How to use IBM® App Connect with ServiceNow

ServiceNow is a cloud-based platform that supports service management for all departments of your business, including IT, human resources, facilities, field service, and more.

Availability:
  • A connector in IBM App Connect Enterprise as a ServiceApp Connect Enterprise as a Service connector
  • A local connector in a Designer instance of IBM App Connect in containers (Continuous Delivery release)Local connector in containers (Continuous Delivery release)
  • A local connector in a Designer instance of IBM App Connect in containers (Long Term Support)Local connector in containers (Long Term Support release)
  • A local connector in a Designer instance of IBM App Connect in containers (Support Cycle 2)Local connector in containers (Long Term Support Cycle-2 release)

Supported product and API versions

To find out which product and API versions this connector supports, see Detailed System Requirements on the IBM Support page.

Connecting to ServiceNow

Complete the connection fields that you see in the App Connect Designer Connect > Applications and APIs page or flow editor. If necessary, work with your ServiceNow administrator to obtain these values.

To connect App Connect to a ServiceNow account, select your preferred authorization method:
  • Provide a username, password, and client credentials (OAUTH 2.0 PASSWORD)
  • Provide credentials for App Connect to use (BASIC)
Then, specify values in the connection fields for your chosen authorization method:
Table 1. Connection fields for your chosen authorization method. Descriptions of the connection fields are given after this table.
Provide a username, password, and client credentials (OAUTH 2.0 PASSWORD) Provide credentials for App Connect to use (BASIC)
Username Username
Password Password
Client ID Endpoint URL
Client secret  
Endpoint URL  

You must obtain the values for the following connection fields.

Endpoint URL
The URL of the ServiceNow instance that App Connect connects to, in the format https://<servicenow-id>.service-now.com
User name and User password
The username and password that App Connect uses to connect to the ServiceNow instance.
Note: The Endpoint URL and this username and password are for the ServiceNow instance that App Connect connects to. For example, if you're using a Developer instance, the endpoint URL, username, and password are assigned when the instance is created. These values are different from the username and password that you use to sign in to the Developer site.

This user must be assigned the itil and soap roles to allow access to the features and capabilities that App Connect needs. Your ServiceNow administrator can assign these roles to your user account.

Note: If you're using a ServiceNow personal developer instance and access your instance by using the default admin account for the System Administrator profile, you already have the correct access. This account is automatically assigned the admin role, which provides access to all features and capabilities.
Client ID and Client secret
An automatically generated client ID and a client secret (which is user-specified, or can be auto-generated if you leave the field blank). For information about obtaining a client ID and client secret, see Create an endpoint for clients to access the instance in the ServiceNow documentation. You can copy and paste the client ID and client secret values into App Connect when prompted.
Tip: You can use the ServiceNow Application Registries screen to select an OAuth client application and copy its client ID and client secret values. You can also use this screen to create a new OAuth client application for use with App Connect. To go to this screen, type oauth in the filter navigator, then click Application Registry > New > Create an OAuth API endpoint for external clients.

To connect to a ServiceNow endpoint from the App Connect Designer Applications and APIs page for the first time, expand ServiceNow, then click Connect.

The following example shows completed connection fields for a ServiceNow connector.Example of completed fields for connecting from App Connect

Tip:

Before you use the account that is created in App Connect in a flow, rename the account to something meaningful that helps you to identify it. To rename the account on the Applications and APIs page, select the account, open its options menu (⋮), then click Rename Account.

Accessing ServiceNow custom objects

To access more than the static objects that are provided by App Connect (as listed in Events and actions), the user that App Connect uses to connect to the ServiceNow instance must have the soap_query role. Users with this role can access ServiceNow custom properties for any object. Your ServiceNow administrator can assign roles to the user that App Connect uses to connect to the ServiceNow instance.

The following roles are provided for specific functions.
Table 2.
Role Description
incident_manager Manages incident properties and major incident trigger rules. This role is needed to retrieve incident records for a user and to run create, retrieve, update, and delete operations for the Ticket object.
knowledge Creates, updates, and reviews knowledge base articles. For more information, see Accessing and configuring the Knowledge object.
knowledge_admin Manages the knowledge base. For more information, see Accessing and configuring the Knowledge object.
personalize_dictionary To configure dictionary entries and labels.
personalize_choices To configure choices and predefined responses for nonjournal fields that are designated as choice or suggestion fields.
You can also create a custom role with access to particular tables to access custom properties for specific tables.
  1. Create a custom role.
    1. In a web browser, log in to your ServiceNow instance with an ID that has administration access (or ask your ServiceNow administrator to do the following steps for you).
    2. In the filter navigator field of your ServiceNow instance, type Roles and then select Roles when it is displayed.
    3. Click New.
    4. Update the fields as follows.
      Table 3. Custom role values
      Field Value
      Name custom_role_read_only
      Requires Subscription Unspecified
      Description This role is for read access to the following: object - sys_dictionary, sys_db_object and sys_choice
      Application Global
      Elevated privilege Leave cleared
    5. Click Submit.
  2. Provide access to tables.
    1. To get permission to modify the Access Control List, click System Administrator > Elevate role.
    2. In the Elevate Roles pop-up window, select security_admin > OK.
    3. In the Filter navigator field, type ACL and then select Access Control (ACL).
    4. In the Access Controls window, New.
    5. For the purposes of this example, the following tables are used:
      • Table [sys_db_object]
      • Choice [sys_choice]
      • Dictionary Entry [sys_dictionary]
      To create access controls for these tables, update the fields as follows.
      Note: You need to create a record for each table.
      Table 4. ACL configuration
      Access control fields Value
      Type record
      Operation read
      Admin overrides True (checkbox)
      Name Table [sys_db_object]
      Tip: Click the name field and type sys_ in the search field to find the entry.
      None *
      Application Global
      Active True (checkbox)
      Role custom_role_read_only.
      Tip: To add this role, double-click the Insert a new row field and then click the green tick.
    6. Click Submit.
    7. In the 'Verify Security Rules for "sys_xx_xx" ' pop-up window, click Continue.
    8. Repeat steps 2.d - 2.g to create a record for sys_choice and sys_dictionary.
  3. Assign the custom role to a user.
    1. In the Filter navigation panel, go to User Administration > Users and select the user you want to work with.
    2. In the Roles tab, click Edit.
    3. In the Collection list, type custom_role_read_only, select it when it is displayed and then click Add > Save.
    4. The user is now ready to access custom objects when they connect to ServiceNow in App Connect.

Accessing and configuring the Knowledge object

You can create, update, and delete knowledge management articles with the ServiceNow knowledge object in App Connect.

Figure 1. The ServiceNow knowledge object and actions in App Connect
The ServiceNow knowledge object and actions in App Connect
ServiceNow knowledge articles provide user information such as policy, release notes, and instructions for tasks. To access the knowledge object, you must be assigned the knowledge_admin user role in your ServiceNow instance. To assign this user role, complete the following steps.
  1. In a web browser, log in to your ServiceNow instance with an ID that has administration access (or ask your ServiceNow administrator to do the following steps for you).
  2. In the Filter navigation panel, go to User Administration > Users and select the user you want to work with.
  3. In the Roles tab, click Edit.
  4. In the Collection list, select knowledge_admin, and then click Add > Save.
To use the Get additional knowledge metadata and Download knowledge article attachment action nodes in App Connect, you need to have the Knowledge API plug-in installed in your ServiceNow instance. To install this plug-in, complete the following steps.
  1. In a web browser, log in to your ServiceNow instance with an ID that has administration access (or ask your ServiceNow administrator to do the following steps for you).
  2. Go to System Definition > Plugins.
  3. Search for Knowledge API.
  4. When the result is displayed, click Install.

General considerations for using ServiceNow in App Connect

Before you use App Connect Designer with ServiceNow, take note of the following considerations:

  • (General consideration) You can see lists of the trigger events and actions that are available on the Applications and APIs page of the App Connect Designer.

    For some applications, the events and actions depend on the environment and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

  • (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.

Events and actions

ServiceNow events

These events are for changes in this application that trigger a flow to start completing the actions in the flow.

Note: In containers, only local accounts can be used for these events.
Asset
New asset
Updated asset
Attachment
New attachment
Comments
New comment
Department
New department
Updated department
Incident
New incident
Updated incident
Problem
New problem
Updated problem
System user
New system user
Updated system user
Ticket
New ticket
Updated ticket

ServiceNow actions

Your flow completes these actions on this application.

Asset
Create asset
Update asset
Update assets
Retrieve assets
Delete assets
Update or create asset
Attachment
Create attachment
Retrieve attachments
Download File Attachment Content
Delete attachment
Comments
Create comment
Update comments
Retrieve comments
Delete comment
Update or create comment
Department
Create department
Update departments
Retrieve departments
Delete departments
Update or create department
Incident
Create incident
Update incidents
Retrieve incidents
Delete incidents
Update or create incident
Knowledge
Create knowledge
Download knowledge article attachment
Update knowledge
Get additional knowledge metadata
Retrieve knowledge
Update or create knowledge
Delete knowledge
Problem
Create problem
Update problems
Retrieve problems
Delete problems
Update or create problem
System user
Create system user
Updates system users
Retrieve system users
Delete system users
Update or create system user
Ticket
Create ticket
Update tickets
Retrieve tickets
Delete tickets
Update or create ticket

More items are available after you connect App Connect to ServiceNow.

Examples

Dashboard tile for a template that uses ServiceNow
Dashboard tile for a template that uses ServiceNow
Dashboard tile for a template that uses ServiceNow

Use templates to quickly create flows for ServiceNow

Learn how to use App Connect templates to quickly create flows that complete actions on ServiceNow. For example, open the Templates gallery, and then search for ServiceNow.

Learn more

Dashboard tile for a template that uses ServiceNow

Troubleshooting

ServiceNow personal developer instances go into hibernation and are later reclaimed after a certain period of developer inactivity. If your flows include one or more ServiceNow events or actions, and you haven't accessed your ServiceNow instance in a while, the connection between App Connect and ServiceNow might be lost. The connection might be hibernating or was reclaimed. If you see a related message in your App Connect flow, you can reestablish the connection in one of the following ways:

  • If your instance is in hibernation, either extend your instance, or log in to the ServiceNow console and generate some developer activity.
  • If your instance was reclaimed, use another instance and connect App Connect to that instance.