{
  "schema": "aaes/capability-pack/1",
  "provider": "servicenow",
  "version": "1.0.0",
  "description": "ServiceNow Table API on the customer's own instance: read, create and update incidents, read and create change requests, and read catalog items.",
  "notes": "The endpoint host 'servicenow-instance.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the customer's instance host before enabling, in every endpoint, in the resource locator and in every egress allowlist entry. The allowlist matches exactly, so endpoints and allowlist must be substituted together, and substitution is a required deployment step — the reserved host being allowlisted does not make an unsubstituted pack safe to enable.\n\nThe pack does not create the OAuth application or mint tokens: an external deployment process registers the OAuth client with the instance admin, obtains access tokens from the customer's own instance, and stores and renews the complete header value described in the credential note. The Table API enforces the calling user's ACLs and roles, so a capability works only if the token's user (for example an itil user) is permitted the operation; the registration records the endpoint, not the instance's authorization decision.\n\nExcluded operation: servicenow.change_request.approve. Approving a change request by PATCHing the record's approval field was considered and removed — the retrieved Table API documentation establishes PATCH /now/table/{tableName}/{sys_id} as a generic name-value update but does not establish that setting the change_request record's approval field performs a workflow approval; change approvals run through approval records and the Change Management REST API's approval operation, each a different registration requiring its own review, and this pack registers neither.\n\nNothing in this pack approves a change. Further documented exclusions, from the retrieved Table API documentation: DELETE /now/table/{tableName}/{sys_id} exists in the API and is deliberately not registered; incident or change deletion is excluded; PUT /now/table/{tableName}/{sys_id} also exists, and only PATCH is registered for updates; POST inserts one record per call — multiple-record insertion is not supported by the Table API.\n\nThe Attachment API, Stats API, Import Set API and Service Catalog API (order_now) are separate ServiceNow APIs this pack does not register — reading sc_cat_item returns catalog content and orders nothing. AAES has not been certified by ServiceNow; the endpoints here are configuration to review and test; the vendor has not endorsed it.",
  "credential": {
    "secret_ref_id": "secret-ref-servicenow-oauth-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "An OAuth2 access token for the customer's own ServiceNow instance, held in the client's own secret manager. The stored material must be the complete Authorization header value (scheme included): 'Bearer ' followed by the access token. An external deployment process obtains the token from the instance and renews it when it expires — storing the OAuth client credentials under this reference does not make the HTTP injector perform OAuth: the injector injects the stored value verbatim, so refresh ownership (including any refresh-token grant the deployment chooses to use) sits entirely with that external process.\n\nAccess tokens expire and can be revoked at the instance; an expired or revoked value fails closed. The token's access is the token user's access — grant the user the minimum roles (for example itil for the incident and change tables) that make these capabilities work, and nothing more.\n\nExecutor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack."
  },
  "capabilities": [
    {
      "capability_id": "servicenow.incident.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "servicenow-instance.invalid"
      ],
      "endpoint": "https://servicenow-instance.invalid/api/now/table/incident",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-servicenow-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "servicenow-instance",
      "description": "Retrieve incident records from the collection endpoint; this pack registers the collection read only — the Table API's single-record read (GET /now/table/{tableName}/{sys_id}) is not registered. Incident records carry caller, assignee and watch-list user references, so the read is classified as pii (personal data).\n\nThe host is a reserved placeholder: substitute the customer's instance host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "servicenow.incident.create",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R2",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "servicenow-instance.invalid"
      ],
      "endpoint": "https://servicenow-instance.invalid/api/now/table/incident",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-servicenow-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "create"
      ],
      "resource_id": "servicenow-instance",
      "description": "Insert one incident record; the Table API inserts one record per call and does not support multiple-record insertion. The record can name a caller and other users, so the capability registers classified as pii (personal data).\n\nThe host is a reserved placeholder: substitute the customer's instance host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "servicenow.incident.update",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R2",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "servicenow-instance.invalid"
      ],
      "endpoint": "https://servicenow-instance.invalid/api/now/table/incident/SYS_ID",
      "method": "PATCH",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-servicenow-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "update"
      ],
      "resource_id": "servicenow-instance",
      "description": "Update one incident record with the name-value pairs in the request body; fields prefixed sys_ are system-generated and cannot be updated. The Table API also documents PUT for updates; this pack registers PATCH only.\n\nThe host is a reserved placeholder to substitute before enabling, and SYS_ID binds to the target record at call time.",
      "requires_review": true
    },
    {
      "capability_id": "servicenow.change_request.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "servicenow-instance.invalid"
      ],
      "endpoint": "https://servicenow-instance.invalid/api/now/table/change_request",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-servicenow-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "servicenow-instance",
      "description": "Retrieve change request records from the collection endpoint; this pack registers the collection read only — the Table API's single-record read (GET /now/table/{tableName}/{sys_id}) is not registered. Change requests carry requested-by and assigned-to user references, so the read is classified as pii (personal data).\n\nThe host is a reserved placeholder: substitute the customer's instance host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "servicenow.change_request.create",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R2",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "servicenow-instance.invalid"
      ],
      "endpoint": "https://servicenow-instance.invalid/api/now/table/change_request",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-servicenow-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "create"
      ],
      "resource_id": "servicenow-instance",
      "description": "Insert one change request record; the Table API inserts one record per call. The insert accepts the name-value pairs the calling user is permitted to set, subject to the instance's ACLs and business rules — this registration does not restrict which fields a request may carry, so what workflow state a newly inserted record enters, and whether it starts unapproved, is decided by the instance's configuration, not by this pack.\n\nNothing in this pack approves a change: the approval capability was considered and removed (see the pack notes).\n\nThe host is a reserved placeholder: substitute the customer's instance host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "servicenow.catalog_item.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "servicenow-instance.invalid"
      ],
      "endpoint": "https://servicenow-instance.invalid/api/now/table/sc_cat_item",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-servicenow-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "servicenow-instance",
      "description": "Retrieve service catalog item records from the collection endpoint; this pack registers the collection read only. Catalog items are the organization's catalog content, classified as internal data; this reads the catalog only — ordering an item is the Service Catalog API (order_now), which this pack does not register.\n\nThe host is a reserved placeholder: substitute the customer's instance host before enabling.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "servicenow-instance",
      "kind": "api",
      "locator": "https://servicenow-instance.invalid/api/now",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-23",
    "sources": [
      "https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/c_TableAPI.html (retrieved 2026-09-21)",
      "https://www.servicenow.com/docs/api/khub/maps/MVRCUFVyKWd7vUoUukbW6g/topics/bRERdJSjwCv6ACu52tHaCw/content (retrieved 2026-09-23)",
      "https://www.rfc-editor.org/rfc/rfc6750.txt (retrieved 2026-09-23)"
    ],
    "reviewer_id": "aaes-eng"
  }
}