Integrate ServiceNow

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

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:

• Base URL: This is your instance URL. You must enter your instance Base URL or simply replace {cloud-id} in the example with your customer ID.
• Authorization URL: Replace {customer-id} in the example with your customer ID, https://{customer-id}.service-now.com/oauth_auth.do This is the authorization server URL provided when setting up the target application integration.
• Token URL Replace {customer-id} in the example with your customer ID: https://{customer-id}.service-now.com/oauth_token.do. This is the URL of the access authorization token.
• Username: This and Password are the credentials of the service account with access to the full table structure and all tables in ServiceNow.
• Password: This and Username are the credentials of the service account with access to the full table structure and all tables in ServiceNow.
• Client ID: You collect the Client ID by registering the OAuth client in your ServiceNow account. The Client ID and the Client Secret are the same for both Service authentication and Service action authentication.
• Client Secret: You collect the Client Secret by registering the OAuth client in your ServiceNow account. The Client ID and the Client Secret are the same for both Service authentication and Service action authentication.

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.

ServiceNow roles

We recommend the following ServiceNow roles:

• approval_admin
• itil
• personalize_choices
• snc_read_only

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.

Note

This section of the URL {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}/admin/api/gwsc/auth/serverContext
   • https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback

   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.

   

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

   

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: https://{customer-id}.service-now.com/oauth_token.do. 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.

      

   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.

   

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, https://{customer-id}.service-now.com/oauth_auth.do 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: https://{customer-id}.service-now.com/oauth_token.do. 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.

   

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.

   

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.

   

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

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.

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

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

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

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

Submit Delegate: Submit a new delegate.

Submit Incident: Submit a new incident.

Submit Problem: Submit a new problem.

Java-based 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.

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

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

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

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

Submit Change Request: Submit a new change request.

Submit Delegate: Submit a new delegate.

Submit Incident: Submit a new incident.

Submit Problem: Submit a new problem.