Integrate ServiceNow

Integrate with ServiceNow to submit and monitor requests, and take action from any device, intranet, or messenger.

Note

We provide two ServiceNow integration templates for your use. We recommend using the newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure. The set-up process for each integration is identical. For full details of the microapps available in each integration, see Use ServiceNow microapps.

Use the following process to enable the ServiceNow Integration. Ensure you meet the prerequisites, enable API access, and assign a role to the dedicated user. After you complete this process, your existing level of audit logging persists, including any actions carried out by the use of Citrix Microapps.

This integration enables you to:

  • create a task in Workspace Experience. The solution adds an “opened_by” parameter to the API request based on the currently logged-in user. If you explicitly define the “opened_by” parameter in the service action parameters settings, it replaces the default value
  • approve requests within the microapp. The solution adds the sentence Approval state set by the user_name to the comment field to identify who performed the approval
  • create a new Service Catalog Request from the microapp. The solution adds the “requested_for” parameter to the API request based on the currently logged-in user

For a comprehensive list of out-of-the-box ServiceNow microapps, see Use ServiceNow microapps.

Review prerequisites

These prerequisites assume you administer the ServiceNow instance of your organization to set up the integration.

Workspace users need proper roles assigned to complete service actions. Proper roles depend on your ServiceNow configuration.

You must have these details to add the integration in Citrix Workspace Microapps:

  • Instance URL
  • Username
  • Password

For OAuth 2.0:

  • Client ID
  • Client Secret

Note

It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

  • Obtain a new oauth2 client_id and client_secret and define the scope of the client’s application.

  • Configure Citrix Gateway to support single sign-on for ServiceNow so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in ServiceNow Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

New HTTP integration privileges

Your ServiceNow admin account must have read access to all tables that we are fetching in the integration. See the list below:

  • change_request
  • incident
  • problem
  • sc_cat_item
  • sys_user
  • task
  • cmn_location
  • core_company
  • sc_req_item
  • sc_request
  • sys_journal_field
  • sys_user_delegate
  • sys_user_group
  • sys_user_has_role
  • sys_user_role
  • sys_user_role_contains
  • sysapproval_approver
  • sys_choice
  • sc_item_option_mtom

Important

The ServiceNow admin account that administers the HTTP integration must have the timezone set to GMT. This is required to correct time handling in Workspace and in incremental data synchronization. If you see any time mismatch, first check these settings to resolve the issue.

Legacy integration privileges

This ServiceNow admin account must have full data access privileges. If you choose to use a separate ServiceNow account for the Microapps integration, you need to manually add read permissions on restricted tables, such as like sys_journal_field. Specifically, the administrator needs access to the following tables as they include information about the data structure of ServiceNow:

  • sys_db_object
  • sys_dictionary
  • sys_choice

Enable API access for required tables

Most of the ServiceNow tables are enabled for access via web services by default. To confirm if a table you want to synchronize with Workspace is accessible via web services:

  1. Log in to ServiceNow.
  2. Select System Definition > Tables.
  3. Select the Information icon next to the table name that you want to confirm. Select Open record. Select the Application Access tab and ensure that the “Allow access to this table via web services” check box is enabled.
  4. Select the check box if necessary, and click Update to save your settings.

Add Callback URLs

Add a custom URL to your instance configuration to grant access to private data and enable OAuth authenticated user actions. The first callback that is listed does not change. The second callback depends on the target application, and can be found in your URL address bar when creating the integration. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com.

  1. Log in to ServiceNow as an admin.
  2. Navigate to System OAuth > Application Registry, and select New.
  3. Select Create an OAuth API endpoint for external clients.
  4. Enter the following authorized redirect URLs for this integration in the Redirect URL field separated by a comma:

    • https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback
    • https://{yourmicroappserverurl}/admin/api/external-services/com.sapho.services.servicenow.ServiceNowService/auth/serverContext

    Ensure that PKCE required is not selected.

  5. Click Submit.

Filter queries

Most ServiceNow entities support filtering. The sysparm_query URL parameter of the Table API GET method allows filtering. Choose predefined queries or write your own custom queries. For more information, consult the ServiceNow REST API reference and product documentation.

Note

If the query or any part of it is invalid, then the invalid part is ignored, as specified in the ServiceNow documentation.

Examples:

// Only Active objects:
active=true

// Updated in the last 2 days:
sys_updated_onONLast%20day@javascript:gs.daysAgoStart(1)@javascript:gs.daysAgoEnd(0)

// Updated in the last 3 hours:
sys_updated_onONLast%20hour@javascript:gs.hoursAgoStart(2)@javascript:gs.hoursAgoEnd(0)

// Updated in the last 4 months:
sys_updated_onONLast%20month@javascript:gs.monthsAgoStart(3)@javascript:gs.monthsAgoEnd(0)

Add the integration to Citrix Workspace Microapps

Add the ServiceNow integration to Citrix Workspace Microapps to connect to your application. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace. We provide two ServiceNow integration templates for your use. We recommend using the newer HTTP integration for most use-cases.

Add the ServiceNow HTTP integration

Follow these steps to set up the ServiceNow HTTP integration. The authentication options are preselected. Ensure that these options are selected as you complete the process. We recommend using this newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the ServiceNow tile.
  3. Enter an Integration name for the integration.
  4. Enter Connector parameters.
    • Enter the instance Base URL or simply replace {customer-id} in the example with your customer ID.
    • Select an Icon for the integration from the Icon Library, or leave this as the default ServiceNow icon.

    ServiceNow HTTP parameters

    • Enable the On-premises instance toggle if you are creating an on-premises connection. For more information, see On-premises instance.

    ServiceNow HTTP On-premises

  5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select Resource Owner Password from the Grant type menu. Provide the correct credentials to authorize resource server provision of an access token.
    2. Select Request body from the Token authorization menu.
    3. Enter your Token URL or simply replace {customer-id} in the example with your customer ID. This is the URL of the access authorization token.
    4. Enter your Username and Password. These are the credentials of the service account with access to the full table structure and all tables in ServiceNow.
    5. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server.
    6. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
    7. Enter your Header prefix. (optional) Enter the header prefix if your bearer prefix is different from the default header.

      ServiceNow HTTP service authentication

    8. If you selected OAuth 2.0 authentication method, you can select + Add Parameter to include Access token parameters. Access token parameters define the access token parameters as required by the target application authorization server if necessary.

    ServiceNow HTTP token

  6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level.

    1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
    2. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This will display the Callback URL, which you use when registering your application.
    3. Select Request body from the Token authorization menu.
    4. Enter your Authorization URL or simply replace {customer-id} in the example with your customer ID. This is the authorization server URL provided when setting up the target application integration.
    5. Enter your Token URL or simply replace {customer-id} in the example with your customer ID. This is the URL of the access authorization token.
    6. (Optional) Enter your Scope to define the scope of the access request. This string is defined by the authorization server when setting up your target integration application.
    7. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server.. You collect this and the secret by registering the OAuth client in your ServiceNow account. You need to add the Callback URL you see on the integration configuration page.
    8. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
    9. (Optional) Enter your Header prefix if your bearer prefix is different from the default header.
    10. If you selected OAuth 2.0 authentication method, you can select + Add Parameter to include Access token parameters. Access token parameters define the access token parameters as required by the target application authorization server if necessary.

    ServiceNow HTTP Service Action Authentication

  7. (Optional) If you want to activate rate limiting for this integration, enable the Request rate limiting toggle and set the Number of requests per Time interval.
  8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.

    Rate limiting and logging toggles

  9. Select Save.

Add the legacy integration

Follow these instructions to set up the legacy java-based ServiceNow integration.

Follow these steps:

  1. From the overview page, select Get Started.

    The Manage Integrations page opens.

  2. Select Add New Integration, and Add a new integration from Citrix-provided templates.
  3. Choose the ServiceNow tile.
  4. Enter a name for the integration.

    ServiceNow connector parameters, URL, Username, Password, Authentication Method, Number of Connections

  5. Enter the Connector parameters that you collected as prerequisites.
    • Enter your URL.
    • Enter the Username and Password.
    • Select an Authentication Method. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access.
    • For Oauth 2.0, enter the OAuth Client ID and OAuth Client Secret that you collected in the prerequisites procedure.
    • Enter a quantity for Number of ServiceNow Connections. This value determines the number of strings the data sync initiates.

      Note: The default number of connections is three. Opening more connections reduces the time for data synchronization, but increases the load on the Microapps server and can influence its performance. If you require, we recommend no more than 10.

    • Select the radio button to Download Inactive Data if you want to have a list of closed requests, for example, or other data that is set to active = false.
  6. Select Add.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see ServiceNow HTTP connector specifications or ServiceNow connector specifications.

Use ServiceNow microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Note

We provide two ServiceNow integration templates for your use. We recommend using the newer HTTP integration for most use-cases over the older java-based integration. The microapps that they contain differ slightly.

HTTP ServiceNow microapps

ServiceNow HTTP Microapps

Our HTTP ServiceNow integration comes with the following preconfigured out-of-the-box microapps:

Change Requests: Search for change requests, view their details, add comments, and update them.

Notification or Page Use-case workflows
Change Request Assigned notification When an existing change request is assigned to a user, they receive a notification.
Change Request Assignee Change (opened by) notification When the assignee for a change request is changed, the user for whom the request was created receives a notification.
Change Request Assignee Change (requested by) notification When the assignee for a change request is changed, the user who made the request receives a notification.
Change Request State Change (assigned to) notification When the state of a change request is modified, the user who the request is assigned to receives a notification.
Change Request State Change (opened by) notification When the state of a change request is modified, the user who opened the request receives a notification.
Change Request State Change (requested by) notification When the state of a change request is modified, the user for whom the request was created receives a notification.
New Change Request Assigned notification When a new change request is assigned to a user, they receive a notification.
Change Request Detail page Provides a read only view of a change request with details.
Comment Change Request page Provides a form for commenting on a change request.
My Open Change Requests page Allows users to search for open change requests that are assigned to them, requested by them, or opened by them.
Update Change Request page Provides a form for updating a change request.

Incidents: Search incidents, view their details, add comments, and update them.

Notification or Page Use-case workflows
Incident Assigned notification When an existing incident is assigned to a user, they receive a notification.
Incident Assignee Change (caller) notification When the assignee for an incident is changed, the user who reported the incident receives a notification.
Incident Assignee Change (opened by) notification When the assignee for an incident is changed, the user who opened the incident receives a notification.
Incident State Change (assigned to) notification When the state of an incident is modified, the user who the incident is assigned to receives a notification.
Incident State Change (caller) notification When the state of an incident is modified, the user who reported the incident receives a notification.
Incident State Change (opened by) notification When the state of an incident is modified, the user who opened the incident receives a notification.
New Incident Assigned notification When a new incident is assigned to a user, they receive a notification.
Comment Incident Form page Provides a form for commenting on an incident.
Incident Detail page Provides a read only view of an incident with details.
My Open Incidents page Allows users to search for open incidents that are assigned to them, requested by them, or reported by them.
Update Incident page Provides a form for updating an incident.

Problems: Search for problems, view their details, add comments, and update them.

Notification or Page Use-case workflows
New Problem Assigned notification When a new problem is assigned to a user, they receive a notification.
Problem Assigned notification When an existing problem is assigned to a user, they receive a notification.
Problem Assignee Change (opened by) notification When the assignee for a problem is changed, the user who opened the problem receives a notification.
Problem State Change (assigned to) notification When the state of a problem is modified, the user who the problem is assigned to receives a notification.
Problem State Change (opened by) notification When the state of a problem is modified, the user who opened the problem receives a notification.
Comment Problem page Provides a form for commenting on a problem.
My Open Problems page Allows users to search for open problems that are assigned to them or opened by them.
Problem Detail page Provides a read only view of a problem with details.
Update Problem page Provides a form for updating a problem.

Request Approval: Search and view pending approvals, and approve or reject them.

Notification or Page Use-case workflows
New Approve Request (Requested Item) notification When an approval for a request or change request is assigned to a user, they receive an actionable notification that they can approve or reject.
New Approve Request (Problem) notification When an approval for a problem is assigned to a user, they receive an actionable notification that they can approve or reject.
Pending Request Approval page Allows users to search for pending approvals that are assigned to them.
Request Approval Detail page Provides an actionable view of a pending approval with details that they can approve or reject.

Submit Change Request: Select items and submit a new change request.

Notification or Page Use-case workflows
Submit Change Request page Provides a form for submitting a change request.

Submit Delegate: Submit a new delegate.

Notification or Page Use-case workflows
Submit Delegate page Provides a form for submitting a new delegate.

Submit Incident: Submit a new incident.

Notification or Page Use-case workflows
Submit Incident page Provides a form for submitting a new incident.

Submit Problem: Submit a new problem.

Notification or Page Use-case workflows
Submit Problem page Provides a form for submitting a new problem.

Java-based ServiceNow microapps

ServiceNow Microapps

Our java-based ServiceNow integration comes with the following preconfigured out-of-the-box microapps:

Approvals: Search and view pending approvals, and approve or reject them.

Notification or Page Use-case workflows
New Approve Request notification When a new request for approval is assigned to a user, they receive an actionable notification that they can approve or reject.
Approval Request Detail page Provides an actionable view of a pending approval with details that they can approve or reject.
Pending Requests page Allows users to search for pending approvals that are assigned to them.

Change Requests: Search for change requests, view their details, add comments, and update them.

Notification or Page Use-case workflows
Change Request Assigned notification When an existing change request is assigned to a user, they receive a notification.
Change Request Assignee Change notification When the assignee for a change request is changed, the user who opened the request receives a notification.
Change Request State Change notification When the state of a change request is modified, the user who opened the request receives a notification.
New Change Request Assigned notification When a new change request is assigned to a user, they receive a notification.
Change Request Detail page Provides a read only view of a change request with details.
Comment Change Request Form page Provides a form for commenting on a change request.
My Open Change Requests page Allows users to search for open change requests that are assigned to them.
Update Change Request Form page Provides a form for updating a change request.

Incidents: Search incidents, view their details, add comments, and update them.

Notification or Page Use-case workflows
Incident Assigned notification When an existing incident is assigned to a user, they receive a notification.
Incident Assignee Change notification When the assignee for an incident is changed, the user who opened the incident receives a notification.
Incident State Change notification When the state of an incident is modified, the user who opened the incident receives a notification.
New Incident Assigned notification When a new incident is assigned to a user, they receive a notification.
Comment Incident Form page Provides a form for commenting on an incident.
Incident Detail page Provides a read only view of an incident with details.
My Open Incidents page Allows users to search for open incidents that are assigned to them.
Update Incident Form page Provides a form for updating an incident.

Problems: Search for problems, view their details, add comments, and update them.

Notification or Page Use-case workflows
New Problem Assigned notification When a new problem is assigned to a user, they receive a notification.
Problem Assigned notification When the assignee of a problem is changed, the assignee receives a notification.
Problem Assignee Change notification When the assignee for a problem is changed, the user who opened the problem receives a notification.
Problem State Change notification When the state of a problem is modified, the user who opened the problem receives a notification.
Comment Problem Form page Provides a form for commenting on a problem.
My Open Problems page Allows users to search for open problems that are assigned to them.
Problem Detail page Provides a read only view of a problem with details.
Update Problem Form page Provides a form for updating a problem.

Submit Catalog Request: Select items and submit a new catalog request.

Notification or Page Use-case workflows
Select Item page Allows users to search the catalog and select available items.
Submit Catalog Request page Provides a form for submitting a catalog request.

Submit Change Request: Submit a new change request.

Notification or Page Use-case workflows
Submit Change Request page Provides a form for submitting a change request.

Submit Delegate: Submit a new delegate.

Notification or Page Use-case workflows
Submit Delegate page Provides a form for submitting a new delegate.

Submit Incident: Submit a new incident.

Notification or Page Use-case workflows
Submit Incident page Provides a form for submitting a new incident.

Submit Problem: Submit a new problem.

Notification or Page Use-case workflows
Submit Problem page Provides a form for submitting a new problem.

Integrate ServiceNow