ServiceNow Integration Sketch¶

ServiceNow is the first institutional workflow adapter for the Active Manifest. It turns a needs_review route dispatch into assigned review work instead of leaving an employee blocked with no operational next step.

Shape¶

A tenant policy maps a gated action type to a ServiceNow route, for example servicenow:policy-owner-flow.
POST /law/proposed-action creates a pending route dispatch when the action needs review.
POST /routing/outbox/{dispatch_key}/deliver prepares the REST trigger payload for inspection.
python -m planisphere_api.operator process-outbox --send-external sends the same payload to the configured ServiceNow REST trigger.
The ServiceNow flow creates or updates an approval task, assigns the right owner, and links back to the Planisphere evidence packet metadata.
When review completes, ServiceNow posts a signed review decision callback to Planisphere so the outbox item resolves and the evidence receipt is recorded.

Tenant Integration¶

{
  "enabled": true,
  "config": {
    "url": "https://example.service-now.com/api/x_planisphere/trigger/review",
    "auth_type": "bearer"
  },
  "secret_ref": "env://PLANISPHERE_SERVICENOW_TOKEN"
}

The API stores the secret_ref, not the token. The worker resolves env://... at send time. Tenant configs may also use secret://...; the server resolves those refs from deterministic env vars such as PLANISPHERE_SECRET_PLANISPHERE_TENANT_DEMO_SERVICENOW_TOKEN, or from PLANISPHERE_SECRET_REF_MAP when the full ref is mapped to an env var name. Production deployments can also use optional cloud refs such as aws-sm://..., gcp-sm://..., or azure-kv://...; readiness reports provider/error metadata without returning credential values.

Bearer auth is the default. For inbound REST triggers that prefer request-body signing, configure HMAC mode:

{
  "enabled": true,
  "config": {
    "trigger_url": "https://example.service-now.com/api/x_planisphere/trigger/review",
    "auth_type": "hmac"
  },
  "secret_ref": "env://PLANISPHERE_SERVICENOW_HMAC_SECRET"
}

HMAC mode signs the JSON body with X-Planisphere-Signature.

Review Callback¶

Configure the callback secret separately when the REST trigger credential should not also verify callbacks:

{
  "enabled": true,
  "config": {
    "url": "https://example.service-now.com/api/x_planisphere/trigger/review",
    "callback_secret_ref": "env://PLANISPHERE_SERVICENOW_CALLBACK_SECRET"
  },
  "secret_ref": "env://PLANISPHERE_SERVICENOW_TOKEN"
}

ServiceNow sends a signed JSON body to:

POST /integrations/callbacks/{tenant_id}/servicenow/{target}/review-decision
X-Planisphere-Signature: sha256=<hmac-sha256(body)>

Example body:

{
  "dispatch_key": "route:...",
  "decision": "approved",
  "reviewer": "servicenow:legal-ops",
  "reason": "Policy owner approved the routed AI action.",
  "external_reference": {
    "sys_id": "SN123",
    "number": "TASK001"
  }
}

action_key may be supplied directly; otherwise Planisphere can resolve a known dispatch_key. The callback stores decision metadata and external references, not raw prompt or document content. Law review flows can also submit mirror_version, mirror_digest, and categorical mirror_grades from the raw-safe review_callback_contract included in route-dispatch payloads.

Payload¶

The ServiceNow trigger receives the route-dispatch payload plus active_manifest_item, review_controls, and servicenow objects. The payload includes both review_callback_contract and concrete field mappings so the ServiceNow flow can render categorical review fields without fetching separate setup docs:

{
  "event": "planisphere.route_dispatch.ready",
  "source": "planisphere",
  "tenant": "tenant-demo-law",
  "dispatch_key": "route:...",
  "action_key": "law:...",
  "decision": "needs_review",
  "action_type": "law_gate:proposed_action",
  "review_route": "servicenow:policy-owner-flow",
  "evidence_packet_href": "/law/evidence-packets/law:...",
  "next_step": "Pause execution until review.",
  "raw_content_stored": false,
  "review_controls": {
    "callback": {
      "method": "POST",
      "path": "/integrations/callbacks/tenant-demo-law/servicenow/policy-owner-flow/review-decision",
      "signature_header": "X-Planisphere-Signature",
      "signature_input": "raw request body"
    },
    "fields": [
      {
        "name": "decision",
        "type": "choice",
        "choices": ["approved", "rejected", "escalated"]
      },
      {
        "name": "mirror_grades.citation_support",
        "type": "choice",
        "choices": ["PASS", "PARTIAL", "FAIL", "NA"]
      }
    ]
  },
  "active_manifest_item": {
    "dispatch_key": "route:...",
    "action_key": "law:...",
    "decision": "needs_review",
    "action_type": "law_gate:proposed_action",
    "review_route": "servicenow:policy-owner-flow",
    "target": "policy-owner-flow",
    "evidence_packet_href": "/law/evidence-packets/law:...",
    "next_step": "Pause execution until review.",
    "raw_content_stored": false
  },
  "servicenow": {
    "flow_trigger": {
      "request_body_type": "complex_object",
      "request_body_data_pills": [
        "dispatch_key",
        "action_key",
        "review_controls",
        "servicenow.task_fields",
        "servicenow.review_variables"
      ]
    },
    "task_fields": {
      "table": "task",
      "correlation_id": "route:...",
      "short_description": "Planisphere review needed: law_gate:proposed_action",
      "u_planisphere_callback_path": "/integrations/callbacks/tenant-demo-law/servicenow/policy-owner-flow/review-decision",
      "u_planisphere_raw_content_stored": false
    },
    "review_variables": [
      {
        "name": "u_planisphere_decision",
        "type": "choice",
        "choices": ["approved", "rejected", "escalated"],
        "callback_field": "decision"
      }
    ],
    "outbound_callback_rest_step": {
      "method": "POST",
      "path": "/integrations/callbacks/tenant-demo-law/servicenow/policy-owner-flow/review-decision",
      "headers": [
        {
          "name": "X-Planisphere-Signature",
          "value": "sha256=<hmac-sha256-raw-json-body>"
        }
      ],
      "raw_content_required": false
    }
  }
}

Raw prompt, document, token, and privileged text should not be sent through this payload. ServiceNow should store the workflow task and evidence metadata, then route the human review.

This mirrors ServiceNow's REST API trigger model: the inbound request body is a complex object whose fields can be mapped into flow actions and records. The callback step mirrors ServiceNow's outbound REST step model: send a JSON body, include Content-Type, and add the Planisphere signature header over the raw JSON body.

Current Boundary¶

Implemented: prepared ServiceNow payloads, live REST trigger sending behind --send-external, bearer auth, HMAC signing, token-safe delivery records, and signed review-decision callbacks with test coverage.
Implemented: ServiceNow payloads now render review_controls into task fields, choice variables, and an outbound callback REST step; generic webhook payloads render the same controls into form fields and signed callback templates.
Implemented for the shared route outbox: retry-plan backoff, safe hosted processing, dead-letter quarantine/requeue, and scheduler tick run receipts.
Not implemented yet: production cloud secret-manager/KMS adapters, production notification delivery, and deeper ServiceNow table/state synchronization beyond receipt callbacks.