> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

ServiceNow

Loading version...

Port's ServiceNow integration allows you to model ServiceNow resources in your software catalog and ingest data into them.

Supported resources GroupService CatalogIncidentRelease ManagementVulnerabilityCustom

Core support

Live eventsSee supported resources
Ingesting extra resources

The ServiceNow integration uses the ServiceNow Table API to ingest entities, which means you can ingest any resource that exists in the Table API, not just the ones listed above. Simply specify the table name as a new kind in the Data sources configuration page and the records from the table will be ingested to Port.

Setup​

Authentication methods​

The ServiceNow integration supports two authentication methods:

  1. Basic authentication - Uses a ServiceNow username and password.
  2. OAuth 2.0 client credentials - Uses OAuth client ID and client secret for more secure authentication.
OAuth authentication recommended

OAuth 2.0 is the recommended authentication method as it provides better security and doesn't require sharing user credentials. The integration automatically handles token refresh and expiration.

You can configure the authentication method by providing the appropriate credentials:

  • For basic authentication, provide servicenowUsername and servicenowPassword.
  • For OAuth authentication, provide servicenowClientId and servicenowClientSecret.

The integration will automatically detect and use OAuth authentication if client credentials are provided.

Setting up OAuth in ServiceNow (click to expand)

To use OAuth authentication, you need to create an OAuth application endpoint in ServiceNow:

  1. Log in to your ServiceNow instance as an administrator.
  2. Navigate to System OAuth > Application Registry.
  3. Click New to create a new application.
  4. Select Create an OAuth API endpoint for external clients.
  5. Fill in the following details:
    • Name: Give your application a descriptive name (e.g., "Port Integration").
    • Client ID: This will be auto-generated, or you can specify a custom one.
    • Client Secret: This will be auto-generated. Make sure to copy it securely.
    • Accessible from: Select "All application scopes".
  6. Click Submit to save the configuration.
  7. Use the generated Client ID and Client Secret in your integration configuration.

For detailed information about OAuth client credentials configuration in ServiceNow, refer to the ServiceNow OAuth documentation.

Installation methods​

Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

Live events​

The ServiceNow integration supports live events for real-time catalog updates. When enabled, the integration automatically creates Business Rules in your ServiceNow instance that forward record changes to Port via an Outbound REST Message.

Enabling live events​

To enable live events, set enableTablesLiveEventsWebhooks to true in your integration configuration. When enabled, the integration creates Business Rules for every supported table in your mapping configuration, or only for tables specified in liveEventTables.

For self-hosted installations, you also need to configure liveEvents.baseUrl so that ServiceNow can reach your integration instance. See the installation methods section for network configuration details.

Supported resources​

The following resources support live events. Each resource receives Business Rules for insert, update, and delete operations:

ResourceServiceNow tableSupported events
Incidentincidentinsert, update, delete
Groupsys_user_groupinsert, update, delete
Service Catalogsc_cataloginsert, update, delete
Vulnerabilitysn_vul_vulnerable_iteminsert, update, delete
Release Managementrelease_projectinsert, update, delete
Custom tables

Custom tables added to your mapping configuration that are not in the list above will not receive live events. They will still be ingested during scheduled resyncs.

Delete events and entity identifiers​

For delete events to correctly resolve entities in your catalog, your mapping should use .sys_id as the entity identifier. .sys_id is the primary key for every ServiceNow record and is guaranteed to be present in all webhook payloads across all supported tables.

For example, use .sys_id as the identifier for your resources:

port:
  entity:
    mappings:
      identifier: .sys_id
      title: .short_description
      blueprint: '"servicenowIncident"'

Securing webhooks​

You can secure the webhook endpoint by setting the webhookSecret parameter. When configured, the integration automatically adds an Authorization header to the Outbound REST Message in ServiceNow and validates it on all incoming webhook requests.

Configuration​

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
resources:
- kind: sys_user_group
  selector:
    query: 'true'
    apiQueryParams:
      sysparmDisplayValue: 'true'
      sysparmExcludeReferenceLink: 'false'
  port:
    entity:
      mappings:
        identifier: .sys_id
        title: .name
        blueprint: '"servicenowGroup"'
        properties:
          description: .description
          isActive: .active
          createdOn: '.sys_created_on | (strptime("%Y-%m-%d %H:%M:%S") | strftime("%Y-%m-%dT%H:%M:%SZ"))'
          createdBy: .sys_created_by
- kind: sc_catalog
  selector:
    query: 'true'
    apiQueryParams:
      sysparmDisplayValue: 'true'
      sysparmExcludeReferenceLink: 'false'
  port:
    entity:
      mappings:
        identifier: .sys_id
        title: .title
        blueprint: '"servicenowCatalog"'
        properties:
          description: .description
          isActive: .active
          createdOn: '.sys_created_on | (strptime("%Y-%m-%d %H:%M:%S") | strftime("%Y-%m-%dT%H:%M:%SZ"))'
          createdBy: .sys_created_by
- kind: incident
  selector:
    query: 'true'
    apiQueryParams:
      sysparmDisplayValue: 'true'
      sysparmExcludeReferenceLink: 'false'
  port:
    entity:
      mappings:
        identifier: .sys_id
        title: .short_description
        blueprint: '"servicenowIncident"'
        properties:
          number: .number | tostring
          state: .state
          category: .category
          reopenCount: .reopen_count
          severity: .severity
          assignedTo: .assigned_to.link
          urgency: .urgency
          contactType: .contact_type
          createdOn: '.sys_created_on | (strptime("%Y-%m-%d %H:%M:%S") | strftime("%Y-%m-%dT%H:%M:%SZ"))'
          createdBy: .sys_created_by
          isActive: .active
          priority: .priority

Mapping & selectors per resource​

Set up live events​

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

Filter ServiceNow resources​

Port's ServiceNow integration provides an option to filter the data that is retrieved from the ServiceNow Table API using the following attributes:

  1. sysparmDisplayValue: Determines the type of data returned, either the actual values from the database or the display values of the fields. The default is true

  2. sysparmFields: Comma-separated list of fields to return in the response

  3. sysparmExcludeReferenceLink: Flag that indicates whether to exclude Table API links for reference fields. The default is false

  4. sysparmQuery: Encoded query used to filter the result set. The syntax is <col_name><operator><value>:

    1. <col_name>: Name of the table column to filter against
    2. <operator>: =, !=, ^, ^OR, LIKE, STARTSWITH, ENDSWITH, ORDERBY<col_name>, ORDERBYDESC<col_name>
    3. <value>: Value to match against

    Queries can be chained using ^ or ^OR for AND/OR logic. An example query could be this: active=true^nameLIKEdev^urgency=3 which returns all active incidents with an urgency level of 3 and have a name like dev

The filtering attributes described above can be enabled using the selector.apiQueryParams path, for example:

- kind: <name of table>
  selector:
    query: "true"
    apiQueryParams:
      sysparmDisplayValue: 'true'
      sysparmExcludeReferenceLink: 'false'
      sysparmQuery: active=true^nameLIKEdev^urgency=3
      sysparmFields: sys_id,priority,created_by,state,active

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Relevant Guides​

For relevant guides and examples, see the guides section.