> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# xmatters/xmatters-orb

"Generate an xMatters event based on a job build."


## Commands

### notify

Generate an xMatters event based on the build status of a job

| Parameter | Type | Default | Description |
|---|---|---|---|
| `author` | string | ${CIRCLE_USERNAME} | The GitHub or Bitbucket username of the user who triggered the build. |
| `branch` | string | ${CIRCLE_BRANCH} | The branch the commit is on |
| `build` | string | ${CIRCLE_BUILD_NUM} | The number of the CircleCI Build number |
| `build_url` | string | ${CIRCLE_BUILD_URL} | The URL for the current build. |
| `commit` | string | ${CIRCLE_SHA1} | The commit hash |
| `job` | string | ${CIRCLE_JOB} | The job name |
| `project` | string | ${CIRCLE_PROJECT_REPONAME} | Project the build is from |
| `recipients` | string |  | The xMatters group, user or device to target. Can be a comma separated list |
| `workflow_id` | string | ${CIRCLE_WORKFLOW_ID} | A unique identifier for the workflow instance of the current job. |
| `xm_url` | string | ${XM_URL} | The inbound integration url. This can be stored in the CircleCI UI as the 'XM_URL' env var |

### notify_raw

Generate an xMatters event with the given JSON payload. See here for details https://help.xmatters.com/xmapi/index.html#trigger-an-event

| Parameter | Type | Default | Description |
|---|---|---|---|
| `json_payload` | string |  | The json object to send to xMatters. |
| `xm_url` | string | ${XM_URL} | Enter either your inbound integration url or use the CircleCI UI to add your token under the 'XM_URL' env var |

## Examples

### notify

Trigger a build notification to an xMatters recipient.


```yaml
jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - xmatters/notify:
          author: Deon Sanders
orbs:
  xmatters: xmatters/xmatters-orb@x.y
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build
```

### notify_raw

Trigger a build notification to recipients in xMatters using a custom json payload


```yaml
jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - xmatters/notify_raw:
          json_payload: >-
            { "properties": { "job": "job name here", "author": "Deon Sanders",
            "something": "value" }, "recipients": [{ "id": "dsanders" }] }
          xm_url: ${XM_URL}
orbs:
  xmatters: xmatters/xmatters-orb@x.y
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build
```