Skip to main content

ServiceNow

通过我们的 ServiceNow 集成，您可以根据映射和定义将 sys_user_group、sc_catalog 和 incident 从 ServiceNow 实例导入 Port。

  • 一个 sys_user_group 对应 ServiceNow 中的用户组。
  • 一个 sc_catalog 对应 ServiceNow 中的服务目录。
  • 事件 "代表 ServiceNow 中的事件和票单。

常见被用于情况​

  • 映射 ServiceNow 帐户中的 sys_user_group、sc_catalog 和 incident 。

先决条件​

To install the integration, you need a Kubernetes cluster that the integration's container chart will be deployed to.

Please make sure that you have kubectl and helm installed on your machine, and that your kubectl CLI is connected to the Kubernetes cluster where you plan to install the integration.

安装​

从以下安装方法中选择一种:

使用该安装选项意味着集成将能使用 webhook 实时更新 Port。

本表总结了安装时可用的参数，请在下面的脚本中按自己的需要进行设置，然后复制并在终端运行:

ParameterDescriptionRequired
port.clientIdYour Port client id (How to get the credentials)✅
port.clientSecretYour Port client secret (How to get the credentials)✅
integration.identifierChange the identifier to describe your integration✅
integration.config.servicenowUsernameThe ServiceNow account username✅
integration.secrets.servicenowPasswordThe ServiceNow account password✅
integration.config.servicenowUrlThe ServiceNow instance URL. For example https://example-id.service-now.com✅

Advanced configuration

ParameterDescription
integration.eventListener.typeThe event listener type. Read more about event listeners
integration.typeThe integration to be installed
scheduledResyncIntervalThe number of minutes between each resync. When not set the integration will resync for each event listener resync event. Read more about scheduledResyncInterval
initializePortResourcesDefault true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about initializePortResources

To install the integration using Helm, run the following command:

helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install my-servicenow-integration port-labs/port-ocean \
    --set port.clientId="CLIENT_ID"  \
    --set port.clientSecret="CLIENT_SECRET"  \
    --set initializePortResources=true  \
    --set integration.identifier="my-servicenow-integration"  \
    --set integration.type="servicenow"  \
    --set integration.eventListener.type="POLLING"  \
    --set integration.config.servicenowUsername="<SERVICENOW_USERNAME>"  \
    --set integration.secrets.servicenowPassword="<SERVICENOW_PASSWORD>"  \
    --set integration.config.servicenowUrl="<SERVICENOW_URL>"
高级集成配置

有关代理或自签名证书等高级配置，click here 。

接收 ServiceNow 对象​

ServiceNow 集成使用 YAML 配置来描述将数据加载到开发人员门户的过程。 请参阅下面的examples 。

该集成利用JQ JSON processor 对来自 ServiceNow API 事件的现有字段和 Values 进行选择、修改、连接、转换和其他操作。

配置结构​

集成配置决定从 ServiceNow 查询哪些资源，以及在 Port 中创建哪些实体和属性。

支持的资源及其他 我们的 ServiceNow 集成目前支持以下用于映射配置的资源。可以通过引用ServiceNow Table API 中支持的任何表来扩展当前功能。选择这种方法时，映射配置中的 "kind "键应与 ServiceNow 中的表名相匹配，因为集成会使用 "kind "键的值从表 API 中获取数据。
  • 用户组
  • 服务目录
  • 事件

  • 集成配置的根密钥是 "资源 "密钥:

    resources:
      - kind: sc_catalog
        selector:
        ...

  • 类型 "键是 ServiceNow 对象的指定符:

      resources:
        - kind: sc_catalog
          selector:
          ...

  • 通过 "选择器 "和 "查询 "键，您可以过滤哪些指定 "类型 "的对象将被录入软件目录:

    resources:
      - kind: sc_catalog
        selector:
          query: "true" # JQ boolean expression. If evaluated to false - this object will be skipped.
        port:

  • Port"、"实体 "和 "映射 "键被用来将 ServiceNow 对象字段映射到Port实体。要创建多个同类映射，可在 resources 数组中添加另一项；

    resources:
      - kind: sc_catalog
        selector:
          query: "true"
        port:
          entity:
            mappings: # Mappings between one ServiceNow object to a Port entity. Each value is a JQ query.
              identifier: .sys_id
              title: .title
              blueprint: '"servicenowCatalog"'
              properties:
                description: .description
                isActive: .active
                createdBy: .sys_created_by
      - kind: sc_catalog # In this instance sc_catalog is mapped again with a different filter
        selector:
          query: '.title == "MyServiceCatalogName"'
        port:
          entity:
            mappings: ...
蓝图键 注意 blueprint 键的值 - 如果要使用硬编码字符串，需要用 2 组引号封装，例如使用一对单引号 (')，然后再用一对双引号 ("): :::

将数据输入Port​

要使用integration configuration 引用 ServiceNow 对象，可以按照以下步骤操作:

  1. 转到 DevPortal Builder 页面。
  2. 选择左侧边栏的数据源选项卡。
  3. 点击右上角的 "+ 数据源"。
  4. 选择事件管理类别下的 ServiceNow。
  5. 根据需要修改configuration 。
  6. 运行安装命令。
  7. 单击 "下一步"，即可查看集成配置并根据需要进行更新。

示例​

蓝图和相关集成配置示例:

###组

Group blueprint
{
  "identifier": "servicenowGroup",
  "title": "Servicenow Group",
  "icon": "Service",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string"
      },
      "isActive": {
        "title": "Is active",
        "type": "boolean"
      },
      "createdOn": {
        "title": "Created On",
        "type": "string",
        "format": "date-time"
      },
      "createdBy": {
        "title": "Created By",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}
Integration configuration
resources:
  - kind: sys_user_group
    selector:
      query: "true"
    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

服务目录​

Service catalog blueprint
{
  "identifier": "servicenowCatalog",
  "title": "Servicenow Catalog",
  "icon": "Service",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string"
      },
      "isActive": {
        "title": "Is Active",
        "type": "boolean"
      },
      "createdOn": {
        "title": "Created On",
        "type": "string",
        "format": "date-time"
      },
      "createdBy": {
        "title": "Created By",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}
Integration configuration
resources:
  - kind: sc_catalog
    selector:
      query: "true"
    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

###事件

Incident blueprint
{
  "identifier": "servicenowIncident",
  "title": "Servicenow Incident",
  "icon": "Service",
  "schema": {
    "properties": {
      "category": {
        "title": "Category",
        "type": "string"
      },
      "reopenCount": {
        "title": "Reopen Count",
        "type": "string"
      },
      "severity": {
        "title": "Severity",
        "type": "string"
      },
      "assignedTo": {
        "title": "Assigned To",
        "type": "string",
        "format": "url"
      },
      "urgency": {
        "title": "Urgency",
        "type": "string"
      },
      "contactType": {
        "title": "Contact Type",
        "type": "string"
      },
      "createdOn": {
        "title": "Created On",
        "type": "string",
        "format": "date-time"
      },
      "createdBy": {
        "title": "Created By",
        "type": "string"
      },
      "isActive": {
        "title": "Is Active",
        "type": "boolean"
      },
      "priority": {
        "title": "Priority",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}
Integration configuration
resources:
  - kind: incident
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .number | tostring
          title: .short_description
          blueprint: '"servicenowIncident"'
          properties:
            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

让我们来测试一下​

本节包括 ServiceNow 的响应数据示例。 此外，还包括根据上一节提供的 Ocean 配置从重新同步事件中创建的实体。

有效载荷​

下面是 ServiceNow 提供的有效载荷结构示例:

Group response data
{
  "parent": "",
  "manager": "",
  "roles": "",
  "sys_mod_count": "0",
  "active": "true",
  "description": "\n\t\tGroup for all people who have the Analytics Admin role\n\t",
  "source": "",
  "sys_updated_on": "2020-03-17 11:39:14",
  "sys_tags": "",
  "type": "",
  "sys_id": "019ad92ec7230010393d265c95c260dd",
  "sys_updated_by": "admin",
  "cost_center": "",
  "default_assignee": "",
  "sys_created_on": "2020-03-17 11:39:14",
  "name": "Analytics Settings Managers",
  "exclude_manager": "false",
  "email": "",
  "include_members": "false",
  "sys_created_by": "admin"
}
Service Catalog response data
{
  "manager": {
    "link": "https://dev229583.service-now.com/api/now/table/sys_user/6816f79cc0a8016401c5a33be04be441",
    "value": "6816f79cc0a8016401c5a33be04be441"
  },
  "sys_mod_count": "0",
  "active": "true",
  "description": "Description for service catalog",
  "desktop_continue_shopping": "",
  "enable_wish_list": "false",
  "sys_updated_on": "2023-12-14 15:30:54",
  "sys_tags": "",
  "title": "Test Service Catalog",
  "sys_class_name": "sc_catalog",
  "desktop_image": "",
  "sys_id": "56e48e6a9743311083e6ff0de053af56",
  "sys_package": {
    "link": "https://dev229583.service-now.com/api/now/table/sys_package/global",
    "value": "global"
  },
  "desktop_home_page": "",
  "sys_update_name": "sc_catalog_56e48e6a9743311083e6ff0de053af56",
  "sys_updated_by": "admin",
  "sys_created_on": "2023-12-14 15:30:54",
  "sys_name": "Test Service Catalog",
  "sys_scope": {
    "link": "https://dev229583.service-now.com/api/now/table/sys_scope/global",
    "value": "global"
  },
  "editors": "",
  "sys_created_by": "admin",
  "sys_policy": ""
}
Incident response data
{
  "parent": "",
  "made_sla": "true",
  "caused_by": "",
  "watch_list": "",
  "upon_reject": "cancel",
  "sys_updated_on": "2016-12-14 02:46:44",
  "child_incidents": "0",
  "hold_reason": "",
  "origin_table": "",
  "task_effective_number": "INC0000060",
  "approval_history": "",
  "number": "INC0000060",
  "resolved_by": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user/5137153cc611227c000bbd1bd8cd2007",
    "value": "5137153cc611227c000bbd1bd8cd2007"
  },
  "sys_updated_by": "employee",
  "opened_by": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user/681ccaf9c0a8016400b98a06818d57c7",
    "value": "681ccaf9c0a8016400b98a06818d57c7"
  },
  "user_input": "",
  "sys_created_on": "2016-12-12 15:19:57",
  "sys_domain": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user_group/global",
    "value": "global"
  },
  "state": "7",
  "route_reason": "",
  "sys_created_by": "employee",
  "knowledge": "false",
  "order": "",
  "calendar_stc": "102197",
  "closed_at": "2016-12-14 02:46:44",
  "cmdb_ci": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/cmdb_ci/109562a3c611227500a7b7ff98cc0dc7",
    "value": "109562a3c611227500a7b7ff98cc0dc7"
  },
  "delivery_plan": "",
  "contract": "",
  "impact": "2",
  "active": "false",
  "work_notes_list": "",
  "business_service": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/cmdb_ci_service/27d32778c0a8000b00db970eeaa60f16",
    "value": "27d32778c0a8000b00db970eeaa60f16"
  },
  "business_impact": "",
  "priority": "3",
  "sys_domain_path": "/",
  "rfc": "",
  "time_worked": "",
  "expected_start": "",
  "opened_at": "2016-12-12 15:19:57",
  "business_duration": "1970-01-01 08:00:00",
  "group_list": "",
  "work_end": "",
  "caller_id": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user/681ccaf9c0a8016400b98a06818d57c7",
    "value": "681ccaf9c0a8016400b98a06818d57c7"
  },
  "reopened_time": "",
  "resolved_at": "2016-12-13 21:43:14",
  "approval_set": "",
  "subcategory": "email",
  "work_notes": "",
  "universal_request": "",
  "short_description": "Unable to connect to email",
  "close_code": "Solved (Permanently)",
  "correlation_display": "",
  "delivery_task": "",
  "work_start": "",
  "assignment_group": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user_group/287ebd7da9fe198100f92cc8d1d2154e",
    "value": "287ebd7da9fe198100f92cc8d1d2154e"
  },
  "additional_assignee_list": "",
  "business_stc": "28800",
  "cause": "",
  "description": "I am unable to connect to the email server. It appears to be down.",
  "origin_id": "",
  "calendar_duration": "1970-01-02 04:23:17",
  "close_notes": "This incident is resolved.",
  "notify": "1",
  "service_offering": "",
  "sys_class_name": "incident",
  "closed_by": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user/681ccaf9c0a8016400b98a06818d57c7",
    "value": "681ccaf9c0a8016400b98a06818d57c7"
  },
  "follow_up": "",
  "parent_incident": "",
  "sys_id": "1c741bd70b2322007518478d83673af3",
  "contact_type": "self-service",
  "reopened_by": "",
  "incident_state": "7",
  "urgency": "2",
  "problem_id": "",
  "company": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/core_company/31bea3d53790200044e0bfc8bcbe5dec",
    "value": "31bea3d53790200044e0bfc8bcbe5dec"
  },
  "reassignment_count": "2",
  "activity_due": "2016-12-13 01:26:36",
  "assigned_to": {
    "link": "https://dev229583.service-now.com/api/now/v1/table/sys_user/5137153cc611227c000bbd1bd8cd2007",
    "value": "5137153cc611227c000bbd1bd8cd2007"
  },
  "severity": "3",
  "comments": "",
  "approval": "not requested",
  "sla_due": "",
  "comments_and_work_notes": "",
  "due_date": "",
  "sys_mod_count": "15",
  "reopen_count": "0",
  "sys_tags": "",
  "escalation": "0",
  "upon_approval": "proceed",
  "correlation_id": "",
  "location": "",
  "category": "inquiry"
}

映射结果​

结合样本有效载荷和 Ocean 配置，可生成以下 Port 实体:

Group entity in Port
{
  "identifier": "019ad92ec7230010393d265c95c260dd",
  "title": "Analytics Settings Managers",
  "icon": null,
  "blueprint": "servicenowGroup",
  "team": [],
  "properties": {
    "description": "\n\t\tGroup for all people who have the Analytics Admin role\n\t",
    "isActive": true,
    "createdOn": "2020-03-17T11:39:14Z",
    "createdBy": "admin"
  },
  "relations": {},
  "createdAt": "2023-12-18T08:37:21.637Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-12-18T08:37:21.637Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}
Service catalog entity in Port
{
  "identifier": "56e48e6a9743311083e6ff0de053af56",
  "title": "Test Service Catalog",
  "icon": null,
  "blueprint": "servicenowCatalog",
  "team": [],
  "properties": {
    "description": "Description for service catalog",
    "isActive": true,
    "createdOn": "2023-12-14T15:30:54Z",
    "createdBy": "admin"
  },
  "relations": {},
  "createdAt": "2023-12-18T08:37:28.087Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-12-18T08:37:28.087Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}
Incident entity in Port
{
  "identifier": "INC0000060",
  "title": "Unable to connect to email",
  "icon": null,
  "blueprint": "servicenowIncident",
  "team": [],
  "properties": {
    "category": "inquiry",
    "reopenCount": "0",
    "severity": "3",
    "assignedTo": "https://dev229583.service-now.com/api/now/table/sys_user/5137153cc611227c000bbd1bd8cd2007",
    "urgency": "2",
    "contactType": "self-service",
    "createdOn": "2016-12-12T15:19:57Z",
    "createdBy": "employee",
    "isActive": false,
    "priority": "3"
  },
  "relations": {},
  "createdAt": "2023-12-15T14:52:06.347Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-12-15T15:34:18.248Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}