Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
xmatters-orb: xmatters/xmatters-orb@1.0.4
Use xmatters-orb
elements in your existing workflows and jobs.
Opt-in to use of uncertified orbs on your organization’s Security settings page.
Trigger a build notification to an xMatters recipient.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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
Trigger a build notification to recipients in xMatters using a custom json payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
Generate an xMatters event based on the build status of a job
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
author | The GitHub or Bitbucket username of the user who triggered the build. | No | ${CIRCLE_USERNAME} | string |
branch | The branch the commit is on | No | ${CIRCLE_BRANCH} | string |
build | The number of the CircleCI Build number | No | ${CIRCLE_BUILD_NUM} | string |
build_url | The URL for the current build. | No | ${CIRCLE_BUILD_URL} | string |
commit | The commit hash | No | ${CIRCLE_SHA1} | string |
job | The job name | No | ${CIRCLE_JOB} | string |
project | Project the build is from | No | ${CIRCLE_PROJECT_REPONAME} | string |
recipients | The xMatters group, user or device to target. Can be a comma separated list | Yes | - | string |
workflow_id | A unique identifier for the workflow instance of the current job. | No | ${CIRCLE_WORKFLOW_ID} | string |
xm_url | The inbound integration url. This can be stored in the CircleCI UI as the 'XM_URL' env var | No | ${XM_URL} | string |
Generate an xMatters event with the given JSON payload. See here for details https://help.xmatters.com/xmapi/index.html#trigger-an-event
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
json_payload | The json object to send to xMatters. | No | '' | string |
xm_url | Enter either your inbound integration url or use the CircleCI UI to add your token under the 'XM_URL' env var | No | ${XM_URL} | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
commands:
notify:
description: Generate an xMatters event based on the build status of a job
parameters:
author:
default: ${CIRCLE_USERNAME}
description: The GitHub or Bitbucket username of the user who triggered the build.
type: string
branch:
default: ${CIRCLE_BRANCH}
description: The branch the commit is on
type: string
build:
default: ${CIRCLE_BUILD_NUM}
description: The number of the CircleCI Build number
type: string
build_url:
default: ${CIRCLE_BUILD_URL}
description: The URL for the current build.
type: string
commit:
default: ${CIRCLE_SHA1}
description: The commit hash
type: string
job:
default: ${CIRCLE_JOB}
description: The job name
type: string
project:
default: ${CIRCLE_PROJECT_REPONAME}
description: Project the build is from
type: string
recipients:
description: The xMatters group, user or device to target. Can be a comma separated list
type: string
workflow_id:
default: ${CIRCLE_WORKFLOW_ID}
description: A unique identifier for the workflow instance of the current job.
type: string
xm_url:
default: ${XM_URL}
description: The inbound integration url. This can be stored in the CircleCI UI as the 'XM_URL' env var
type: string
steps:
- run:
command: |
if [ -z "$BASH" ]; then
echo Bash not installed.
exit 1
fi
name: Provide error if non-bash shell
- when:
condition: on_fail
steps:
- run:
command: |
echo 'export XM_BUILD_STATUS="fail"' >> $BASH_ENV
name: xMatters - Setting Failure Condition
- when:
condition: on_success
steps:
- run:
command: |
echo 'export XM_BUILD_STATUS="success"' >> $BASH_ENV
name: xMatters - Setting Success Condition
- run:
command: |
# Provide error if no url is set and error. Otherwise continue
if [ -z "<< parameters.xm_url >>" ]; then
echo "NO XM_URL SET"
echo "Please input your XM_URL value either in the settings for this project, or as a parameter for this orb."
exit 1
fi
# Webhook properly set.
echo Generating event to xMatters
curl -X POST -H 'Content-type: application/json' \
--data \
"{\
\"recipients\": \"<< parameters.recipients >>\",\
\"properties\": {\
\"author\": \"<< parameters.author >>\",\
\"project\": \"<< parameters.project >>\",\
\"workflow_id\": \"<< parameters.workflow_id >>\",\
\"branch\": \"<< parameters.branch >>\",\
\"commit\": \"<< parameters.commit >>\",\
\"build\": \"<< parameters.build >>\",\
\"build_url\": \"<< parameters.build_url >>\",\
\"job\": \"<< parameters.job >>\",\
\"job_status\": \"$XM_BUILD_STATUS\" \
} \
}" "<< parameters.xm_url >>"
name: xMatters Inbound Command
shell: /bin/bash
notify_raw:
description: Generate an xMatters event with the given JSON payload. See here for details https://help.xmatters.com/xmapi/index.html#trigger-an-event
parameters:
json_payload:
default: ""
description: The json object to send to xMatters.
type: string
xm_url:
default: ${XM_URL}
description: Enter either your inbound integration url or use the CircleCI UI to add your token under the 'XM_URL' env var
type: string
steps:
- run:
command: |
if [ -z "$BASH" ]; then
echo Bash not installed.
exit 1
fi
name: Provide error if non-bash shell
- when:
condition: on_fail
steps:
- run:
command: |
echo 'export XM_BUILD_STATUS="fail"' >> $BASH_ENV
name: xMatters - Setting Failure Condition
- when:
condition: on_success
steps:
- run:
command: |
echo 'export XM_BUILD_STATUS="success"' >> $BASH_ENV
name: xMatters - Setting Success Condition
- run:
command: |
# Provide error if no url is set and error. Otherwise continue
if [ -z "<< parameters.xm_url >>" ]; then
echo "NO XM_URL SET"
echo "Please input your XM_URL value either in the settings for this project, or as a parameter for this orb."
exit 1
fi
if [-z "<< parameters.json_payload >>" ]; then
echo "NO json_payload passed"
echo "Enter some json to pass into xMatters. CHECKOUTTHEDOCSHERE"
exit 1
fi
# Webhook properly set.
echo "Generating event to xMatters with payload '" << parameters.json_payload >> "'"
curl -X POST --header 'Content-type: application/json' \
--data '<< parameters.json_payload >>' \
"<< parameters.xm_url >>"
name: xMatters Inbound Command
shell: /bin/bash
description: |
"Generate an xMatters event based on a job build."
display:
home_url: https://www.xmatters.com/docs
source_url: https://www.github.com/xmatters/xmatters-orb-v2
examples:
notify:
description: |
Trigger a build notification to an xMatters recipient.
usage:
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:
description: |
Trigger a build notification to recipients in xMatters using a custom json payload
usage:
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
version: 2.1