# xmatters/xm-labs-integrationhub architecture

> Architecture diagram of the GitHub repository xmatters/xm-labs-integrationhub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xmatters/xm-labs-integrationhub
- Repository: https://github.com/xmatters/xm-labs-integrationhub

## Overview

#### Purpose and delivery model
This repository packages a no-code/low-code inbound integration from ServiceNow to xMatters. It is primarily a deployable configuration bundle, not an application codebase: ServiceNow detects table-record events, IntegrationHub POSTs event data to an xMatters inbound workflow, and xMatters creates notifications/events. Key artifacts are `ExampleWorkflow.zip`, `UpdateSet.xml`, and `EmailMessageTemplate.html`.

#### Entry points and installation paths
Two provisioning paths establish the integration:
- Import the xMatters plan/workflow from `ExampleWorkflow.zip`; its configured inbound integration exposes the request URL consumed by ServiceNow.
- Either manually create ServiceNow credentials, HTTP connection alias, action, and flow, or import the prebuilt ServiceNow configuration from `UpdateSet.xml`.
The user-facing notification format can be adapted through `EmailMessageTemplate.html`.

#### ServiceNow event trigger stage
A ServiceNow Flow Designer flow is the source-side runtime entry point. It can subscribe to created/updated records from any selected ServiceNow table, with conditions such as assignment-group changes. The packaged example is represented in `UpdateSet.xml`; the README’s example centers on an Incident trigger. This boundary is responsible for deciding which record changes become outbound notifications.

#### IntegrationHub action and payload construction
The flow invokes a reusable IntegrationHub Action containing a REST step. The action maps trigger data into a JSON request body, typically with:
- `recipients`: target xMatters group
- `properties`: arbitrary ServiceNow fields used by the xMatters workflow
The flow/action configuration is distributable in `UpdateSet.xml`; the expected notification/body presentation is exemplified by `EmailMessageTemplate.html`. Payload mapping is configured in ServiceNow’s GUI rather than maintained as source code here.

#### Authentication and HTTP boundary
ServiceNow owns connectivity through a Connection & Credential Alias: HTTP POST, `Content-Type: application/json`, and Basic Auth using an xMatters REST Web Service User. The connection URL is the xMatters inbound-integration URL, ideally held outside the action for reuse across actions. Credentials and instance-specific URLs must be replaced after importing `UpdateSet.xml`; they should not be treated as portable package defaults.

#### xMatters inbound workflow stage
xMatters is the downstream event-processing runtime. Its imported workflow accepts the POST, parses the JSON payload, applies defaults such as recipient groups, creates an xMatters event, and sends email/push notifications with configured response options. The workflow and inbound script/configuration are encapsulated in `ExampleWorkflow.zip`; `EmailMessageTemplate.html` supplies a customizable message template artifact.

#### Operational flow and verification
Control flow is: ServiceNow record mutation → Flow trigger/conditions → IntegrationHub Action → authenticated HTTP POST → xMatters inbound workflow → recipient notification. Operators validate the ServiceNow action/flow with Flow Designer’s test capability, then inspect the xMatters inbound integration Activity Stream for POST success and resulting notifications. The principal external dependencies are a licensed ServiceNow IntegrationHub instance and an xMatters tenant with workflow import and REST-user access.

Main entry points: [`UpdateSet.xml`](https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml) (IntegrationHub Action), [`ExampleWorkflow.zip`](https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip) (Inbound Workflow), [`EmailMessageTemplate.html`](https://github.com/xmatters/xm-labs-integrationhub/blob/master/EmailMessageTemplate.html) (Email Message Template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_servicenow["ServiceNow"]
  node_update_set["ServiceNow Update Set<br/>package artifact<br/>[UpdateSet.xml]"]
  node_record_change(("Table Record Change<br/>ServiceNow event"))
  node_flow["Flow Designer Flow<br/>trigger and filter<br/>[UpdateSet.xml]"]
  node_integration_action["IntegrationHub Action<br/>reusable REST action<br/>[UpdateSet.xml]"]
  node_payload["JSON Payload<br/>request contract"]
end

subgraph group_transport["HTTP Boundary"]
  node_connection_alias["Connection &amp; Credential Alias<br/>HTTP connection<br/>[UpdateSet.xml]"]
  node_rest_user(("xMatters REST User<br/>credential"))
  node_http_post["Authenticated HTTP POST<br/>integration request"]
end

subgraph group_xmatters["xMatters"]
  node_workflow_package["Workflow Import Package<br/>xMatters package"]
  node_inbound_integration["Inbound Integration<br/>xMatters endpoint"]
  node_inbound_workflow["Inbound Workflow<br/>event processor"]
  node_message_template["Email Message Template<br/>notification template"]
  node_notification["Recipient Notification<br/>email / push delivery"]
  node_activity_stream["Activity Stream<br/>operations visibility"]
end

node_update_set -.->|"provisions"| node_flow
node_update_set -.->|"provisions"| node_integration_action
node_update_set -.->|"provisions"| node_connection_alias
node_record_change -->|"triggers"| node_flow
node_flow -->|"invokes"| node_integration_action
node_integration_action -->|"maps fields to"| node_payload
node_integration_action -->|"uses"| node_connection_alias
node_rest_user -->|"authenticates"| node_connection_alias
node_payload -->|"request body"| node_http_post
node_connection_alias -->|"configures"| node_http_post
node_workflow_package -.->|"installs"| node_inbound_integration
node_workflow_package -.->|"contains"| node_inbound_workflow
node_http_post -->|"delivers to"| node_inbound_integration
node_inbound_integration -->|"starts"| node_inbound_workflow
node_inbound_workflow -->|"creates and sends"| node_notification
node_message_template -->|"formats"| node_notification
node_inbound_workflow -->|"records processing"| node_activity_stream

click node_update_set "https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml"
click node_flow "https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml"
click node_integration_action "https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml"
click node_connection_alias "https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml"
click node_workflow_package "https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip"
click node_inbound_integration "https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip"
click node_inbound_workflow "https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip"
click node_message_template "https://github.com/xmatters/xm-labs-integrationhub/blob/master/EmailMessageTemplate.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_update_set,node_record_change,node_flow,node_integration_action,node_payload toneBlue
class node_connection_alias,node_rest_user,node_http_post toneAmber
class node_workflow_package,node_inbound_integration,node_inbound_workflow,node_message_template,node_notification,node_activity_stream toneMint
```

## Components

### ServiceNow

Source runtime and deployable configuration.

- [ServiceNow Update Set](https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml): package artifact · Prebuilt flow, action, and connection configuration. · `UpdateSet.xml`
- **Table Record Change**: ServiceNow event · Created or updated record from a selected table.
- [Flow Designer Flow](https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml): trigger and filter · Applies record and condition rules before sending. · `UpdateSet.xml`
- [IntegrationHub Action](https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml): reusable REST action · Maps trigger fields into the outbound JSON body. · `UpdateSet.xml`
- **JSON Payload**: request contract · Carries recipients and ServiceNow properties.

### HTTP Boundary

- [Connection & Credential Alias](https://github.com/xmatters/xm-labs-integrationhub/blob/master/UpdateSet.xml): HTTP connection · Holds instance-specific URL and Basic Auth credentials. · `UpdateSet.xml`
- **xMatters REST User**: credential · Basic Auth identity configured after import.
- **Authenticated HTTP POST**: integration request · JSON POST to the xMatters inbound URL.

### xMatters

Inbound event-processing runtime.

- [Workflow Import Package](https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip): xMatters package · Imported plan containing inbound workflow configuration. · `ExampleWorkflow.zip`
- [Inbound Integration](https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip): xMatters endpoint · Accepts the ServiceNow POST and exposes its request URL. · `ExampleWorkflow.zip`
- [Inbound Workflow](https://github.com/xmatters/xm-labs-integrationhub/blob/master/ExampleWorkflow.zip): event processor · Parses payload, applies defaults, and creates an event. · `ExampleWorkflow.zip`
- [Email Message Template](https://github.com/xmatters/xm-labs-integrationhub/blob/master/EmailMessageTemplate.html): notification template · Customizable notification presentation artifact. · `EmailMessageTemplate.html`
- **Recipient Notification**: email / push delivery · xMatters notification with configured response options.
- **Activity Stream**: operations visibility · Used to verify POST processing and resulting notifications.

## Connections

- ServiceNow Update Set → Flow Designer Flow: provisions
- ServiceNow Update Set → IntegrationHub Action: provisions
- ServiceNow Update Set → Connection & Credential Alias: provisions
- Table Record Change → Flow Designer Flow: triggers
- Flow Designer Flow → IntegrationHub Action: invokes
- IntegrationHub Action → JSON Payload: maps fields to
- IntegrationHub Action → Connection & Credential Alias: uses
- xMatters REST User → Connection & Credential Alias: authenticates
- JSON Payload → Authenticated HTTP POST: request body
- Connection & Credential Alias → Authenticated HTTP POST: configures
- Workflow Import Package → Inbound Integration: installs
- Workflow Import Package → Inbound Workflow: contains
- Authenticated HTTP POST → Inbound Integration: delivers to
- Inbound Integration → Inbound Workflow: starts
- Inbound Workflow → Recipient Notification: creates and sends
- Email Message Template → Recipient Notification: formats
- Inbound Workflow → Activity Stream: records processing