ServiceNow

The ServiceNow example solution showcases how to connect a Teneo solution with the ServiceNow REST API. The example flows in the solution demonstrate how incidents can be retrieved as well as how to create, update or delete incidents on ServiceNow.

servicenow 1

Solution contents

ServiceNow integration

The solution contains a ServiceNow backend integration containing methods for authentication, retrieval of incidents, user profiles as well as for creating, updating and deleting incidents. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.

Example flows

For each core method in the ServiceNow integration, the solution contains a corresponding example flow:

User asks to retrieve incidents assigned to someone
User asks to retrieve incidents created by someone
User asks to create a new ServiceNow incident
User asks to delete an incident
User asks to update an existing field of incident
Bot asks an user to login into ServiceNow
User asks to logout from ServiceNow

Authentication flow

ServiceNow provides a support for OAuth authentication and HTTP basic authentication methods which allows a Teneo bot to interact with ServiceNow on the user's behalf. Which authentication method to use depends on factors like use case and channel. This example solution contains flows to demonstrate the basic authentication approach.

For production use cases we would recommend the use of OAuth authentication.

Getting started

Prerequisites

These instructions assume you have a ServiceNow admin account. Alternatively, you can sign up for a free user account on ServiceNow developers page.
These instructions assume you have downloaded and imported the ServiceNow solution. See instructions below.

Create a ServiceNow Personal Developer Instance (PDI)

It's time to create a personal developer instance on ServiceNow developer portal in order to perform and experience some CRUD operations by using the ServiceNow Teneo bot

Using your administrator account, log in to your ServiceNow developer portal.
Select the 'Request instance' button located on topmost right corner of portal.
A popup window appears and will show your PDI url with user access credentials and this should be copied and secured immediately as this requires for you to login to ServiceNow Teneo bot to perform various operations.
Click on 'Open Instance' button appeared on popup window screen.
New PDI setup is completed now.

Configure user profile settings (optional)

It's good to have a look on your user profile settings to track the incidents associated with your account for later reference

Click on the 'Avatar' icon located at the topmost right corner of PDI portal
Select the 'Profile' menu.
You can consider changing your 'First name' and 'Last name' text fields as you wish and click on the 'Update' button.

Add credentials to your solution

The solution contains a global variables ServiceNow_sLoginUserId, ServiceNow_sPassword and ServiceNow_sInstanceEndPointUrl in which various credentials we have collected should be stored. We’re interested in our instance 'userId' and 'password'. The value of the global variable should be a type of String like this:

Variable Name	Example value	Description
ServiceNow_sLoginUserId	'teneoUser'	ServiceNow user account id.
ServiceNow_sPassword	'teneoPassword'	ServiceNow user account password.
ServiceNow_sInstanceEndPointUrl	`https://xxxxxxx.service-now.com`	Base URL of ServiceNow instance end point.

To update the global variables, proceed as follows:

In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
In your ServiceNow solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
Select the 'Variables' tab at the top, select the variables called ServiceNow_sLoginUserId, ServiceNow_sPassword and ServiceNow_sInstanceEndPointUrl.
In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
When done, click 'Save All' in the top right corner.

Test in Try Out

Your solution is now ready. You can test this in Try Out by asking I want to login followed up with I need to retrieve ServiceNow incidents assigned to other user. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the incidents, which are assigned to a user on PDI portal.

Example conversations

User: I want to login
Bot: Hi there! I'm a ServiceNow Connector virtual assistant from Artificial Solutions.
Bot: Please enter your ServiceNow account user id.
User: teneoUser
Bot: Please enter your password.
User: teneoPassword
Bot: Please enter an instance url provided by ServiceNow. Example: https://xxxxxx.service-now.com
User: https://xxxxxx.service-now.com
Bot: Hi teneoUser, Your login has been successful!

User: I want to create a new ServiceNow incident
Bot: Please choose one of the following categories. Inquiry, Software, Hardware, Network, Database
User: Software
Bot: Please enter the short description of incident
User: My first ServiceNow incident via Teneo Bot
Bot: Please enter the description of issue
User: Incident descr via Teneo Bot
Bot: New ServiceNow incident INC0010014 has been created successfully.

User: I need to retrieve ServiceNow incidents assigned to other user
Bot: Please enter an assignee name.
User: teneoUser
Bot: Below are list of incidents assigned to teneoUser. INC0010018, INC0010013, INC0010014

User: Can I retrieve incidents created by someone
Bot: Please enter a reporter name
User: teneoUser
Bot: Below are list of incidents created by teneoUser. INC0010016, INC0010018, INC0010013, INC0010014

User: I need to modify a ServiceNow incident
Bot: Please enter an existing incident id
User: INC0010014
Bot: Please choose one of the following incident fields. Short Description, Category, Description, Impact, Urgency.
User: Category
Bot: Please choose one of the following categories. Database, Hardware, Inquiry, Network, Software
User: Database
Bot: Database field has been updated on incident INC0010014 successfully!

User: I wish to delete a ServiceNow incident
Bot: Please enter an existing incident id
User: INC0010014
Bot: ServiceNow incident INC0010014 has been deleted successfully!

User: I want to logout
Bot: Your logout has been successful!

Note: Combination of impact & urgency levels are determinant factors to decide the Priority level of an incident as per Priority data lookup matrix on ServiceNow PDI (Personal Developer Instance).

For simplicity, the bot answers in this solution are text only. Depending on the channel, interactive cards can be added, for example to add buttons or allow the user to select items from a list.

More on authentication

ServiceNow offers multiple authentication methods including OAuth authentication, Basic authentication by using user id and password that developers can use to allow their users to authenticate with ServiceNow. Which authentication flow to use depends on the type of application and the use case.

This ServiceNow solution contains a flow called 'Bot asks an user to login into ServiceNow'. This flow is responsible to set a value of global variable called ServiceNow_bHasUserLoggedIn which is included at the beginning of each other flows that checks the user's authentication to access the flows. This flow checks if the global variables ServiceNow_sLoginUserId, ServiceNow_sPassword and ServiceNow_sInstanceEndPointUrl contains values which is needed to perform API requests. If the ServiceNow_bHasUserLoggedIn variable is false, this flow answers a user authentication failure message.

By default, the ServiceNow 'Bot asks an user to login into ServiceNow' flow uses the stored credentials from global variables to authenticate the user. This flow uses ServiceNow's basic authentication mechanism, which provides instructions in the getting started section on this page explain how to prepare your solution using this authentication approach.

This authentication uses stored credentials from global variables ServiceNow_sLoginUserId, ServiceNow_sPassword and ServiceNow_sInstanceEndPointUrl to prepare an authentication with ServiceNow and it generates a Base64 encoded authorization header value on another global variable ServiceNow_sBasicAuthToken and checks an access against ServiceNow PDI url stored on ServiceNow_sInstanceEndPointUrl and return a successful authentication. The value generated for global variable ServiceNow_sBasicAuthToken should look like this:

Variable Name	Example value	Description
ServiceNow_sBasicAuthToken	'Basic Vmtrnfsdffh76****='	Basic auth token (Base64 encoded) to access ServiceNow (Table API) resources via REST API.

This Base64 encoded value is then stored in the global variable ServiceNow_sBasicAuthToken, so it can be used for subsequent requests that require authentication across flows in the ServiceNow solution. The global variable is used by the ServiceNow integration for the various REST requests.

The solution uses the stored credentials approach by default, mostly because it is easiest and quickest to get started. However, because this authentication flow passes the user’s credentials back and forth it is advised to use this authentication method for development purposes only. Additionally, using stored credentials means that all objects created by the bot are created by the same user. Therefore, it might be preferred to implement an authentication flow that enables Teneo to interact with ServiceNow on the user's behalf.

The authentication flow for the 'Basic authentication' in combination with Teneo roughly looks like this:

ServiceNow - diagram

For more details on ServiceNow and Basic authentication, see: Digging Deeper into API token in Servicenow

Download

Download the solution here.
Import the solution into Teneo. For more details see: How to import solutions.