Integrate ServiceNow

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

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. This admin account must have full data access privileges. 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

Also, 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 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.

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.

  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/external-services/com.sapho.services.servicenow.ServiceNowService/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.

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 and Set data synchronization in the Configure the integration article.

For more details of API endpoints and table entities, see 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.

ServiceNow Microapps

Our 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 Catalogue 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.

Tasks: Search and view tasks including change requests, incidents, and problems.

Notification or Page Use-case workflows
My Open Tasks page Allows users to search for open tasks that are assigned to them.
Task Detail page Provides a read only view of a task with details.