xMatters connector powered by Jitterbit

Use the BMC Helix iPaaS xMatters connector to easily integrate BMC Helix ITSM and xMatters to sync incidents and events. A specific xMatters connection and its activities together are referred to as an xMatters endpoint. Use the connector to perform the following actions:

• Configure the connector to create an authenticated xMatters connection by entering credentials.
• Configure associated xMatters activities that interact with the connection to be used either as a source to provide data within an operation, or as a target to consume data within an operation.
• Use the connector activities to create, get, and update event status in xMatters.

Supported API versions

The xMatters connector uses the  xMatters REST API version 1 . For more information about the schema fields, see the API documentation.

The xMatters connector requires the use of an agent version  10.1  or later. These agent versions automatically download the latest version of the connector when required.

To configure the xMatters connection

Configure an xMatters connection by using the xMatters connector, to establish access to the xMatters endpoint. You can then configure one or more associated xMatters activities to be used either as a source to provide data to an operation or as a target to consume data in an operation. 

To configure an xMatters connection, complete the following steps:

1. From the design canvas, open the Connectivity tab  of the design component palette.
2. Perform one of the following actions:
   • To configure a new xMatters connection, use the Show list to filter on Connectors, and then click the xMatters connector block:
     
   • To configure an existing xMatters connection, use the Show list to filter on Endpoints, and then double-click the xMatters connector block:
     

3. On the configuration screen for the xMatters connection, enter the following configuration values:
   

   Tip

   Fields with a variable icon  support using  global variables ,  project variables , and Jitterbit variables . Begin either by typing an open square bracket [ into the field or by clicking the variable icon to display a list of the existing variables to choose from.

   Field name	Action
   Endpoint Name	Enter a name to identify the xMatters connection. The name must be unique for each xMatters connection and must not contain forward slashes (/) or colons (:). This name is also used to identify the xMatters endpoint, which refers to both a specific connection and its activities. For example, xMatters.
   Client ID	Enter the client ID for your instance of xMatters. For example, 3f57df8a9-f099-4ec6-a313-36y840986ef0. For more information about finding or creating the client ID, see OAuth authentication .
   Username	Enter the user ID to log on to your instance of xMatters. For example, jodoe@bmc.com.
   Password	Enter the password for the user to log on to your instance of xMatters.
   xMatters Host URL	Enter the URL of your xMatters instance. For example, https://xmatters122.xmatters.com

   Important

   If you click Delete when creating a new connection, an error is displayed. For more information, see  Component Dependencies, Deletion, and Removal .

4. Click Save Changes.
   After configuring an xMatters connection, configure one or more associated xMatters activities with that connection. For more information about creating an activity, see Creating an xMatters activity.

To create an xMatters activity 

1. From the design canvas, open the Connectivity tab  of the design component palette.

2. Use the Show list to filter on Endpoints, and then click the xMatters connection block to display activities that are available to be used with an xMatters connection:
   
   The following activities are available. For more information about configuring these activities, see the specific activity sections.

   Activity name	Description
   Create Event	Inserts details of a new event record into an xMatters endpoint and is intended to be used as a target in an operation.
   Get Event	Retrieves an existing event record based on the Event ID and details, from the xMatters endpoint and is intended to be used as a source in an operation.
   Get All Events	Retrieves all existing event records based on the search criteria from an xMatters endpoint and is intended to be used as a source in an operation.
   Update Event Status	Updates an existing event record at an xMatters endpoint and is intended to be used as a target to consume data in an operation.
   Add Event Comment	Adds a comment into the xMatters endpoint and is intended to be used as a target to consume data in an operation.

3. To create an activity that can be configured, drag the activity block  from the palette to the operation.

For more information about the parts of an operation and adding activities to operations, see  Operation Creation and Configuration . 

To configure an xMatters Create Event activity 

An xMatters Create Event activity places details of a new event record into an xMatters endpoint and is intended to be used as a target to consume data in an operation. After configuring an xMatters connection, you can configure as many xMatters activities as you like for each connection. 

To configure an xMatters Create Event activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name, select a form and specify the activity settings.
   

   Field name	Action
   Name	Enter a name to identify the xMatters Create Event activity. The name must be unique for each xMatters Create Event activity and must not contain forward slashes (/) or colons (:).
   Select a Form	This section displays the forms available in the xMatters endpoint. When reopening an existing activity configuration, only the selected form is displayed instead of reloading the entire form list. Selected Form: After you select a form, it is listed here. Search: Enter any part of the form name into the search box to filter the list of forms. The search is not case-sensitive. If forms are already displayed within the table, the table results are filtered in real time with each keystroke. Refresh: Click the refresh icon   or the word Refresh to reload form names from the xMatters endpoint. This may be useful if you have recently added forms. This action refreshes all metadata used to build the table of issue types displayed in the configuration. Selected form name: Within the table, click anywhere on a row to select a form name. Only one issue class can be selected. The information available for each issue type is fetched from the xMatters endpoint: Form Name: Name of the xMatters form. Form UUID: The UUID of the form. Workflow Name: Name of the workflow that includes the selected form. Important:  If the table does not populate with available issue types, the xMatters connection might not be successful. Make sure the xMatters connection is configured correctly by reopening the connection and retesting the credentials. The selected form should contain only fields available in the transformation, and should not contain any custom xMatters fields.
   Recipients	Enter the user names of the recipients who should get the notification when the event is created. The selected users must have a valid xMatters account. Use comma separated values for multiple users.
   Priority	Enter the priority for the event to create.

3. Click Next.

4. Select the event values. 
   
   

   Field name	Action
   Event Status	Enter the status for the event to create.
   Event Severity	Enter the severity of the event to create.
   Additional fields for event creation	To add fields for the event, click Add. Select the following values: Name: Select a field from the list. Value: Enter a value for the selected field.
   Optional Settings	Click to expand additional optional settings: JSON input (This event definition overrides the prior selections): Enter the Key-Value pair for the event fields to add for the event to create. Use the {"Key": "Value"} or [{"Key": "Value"}] format. For example, { "properties": { "summary": "This is an event", "incidentID": "INC-123", "description": "This is an event", "status": "OPEN", "severity": "Low", "reporter": "jitterbituser", "created time": "3:00" }, "priority": "HIGH", "recipients": [ { "targetName": "jitterbituser" } ], "conferences": [ { "name": "82777271" } ], "responses": [], "callbacks": [ { "url": "https://mydomain.com/path/to/my/service/event/status", "type": "status", "authType": "basic", "authUserName": "mmcbride", "authPassword": "password123" }, { "url": "http://mydomain.com/path/to/my/service/event/deliveryStatus", "type": "deliveryStatus" } ] }

5. Review the request and response data schemas displayed for your instance of xMatters. 
   

6. Click Finished. 
   After an xMatters activity has been created, you can access the menu actions for that activity from the project pane in either the Workflows or the Components tabs, and from the design canvas. For more information, see Activity Actions Menu .

Next steps

After configuring an xMatters Create Event activity, complete the configuration of the operation by adding and configuring other activities, transformations, or scripts as operation steps. You can also configure the operation settings, which include the ability to chain together operations from the same or different workflows.

xMatters Create Event activity can be used as a target with the following operation patterns:

• Transformation Pattern

• Two-Transformation Pattern  (as the first or second source)

Other patterns are not valid by using xMatters Create Event activity. For more information about the validation patterns, see the  Operation Validity  page.

A typical workflow uses an xMatters Create Event activity in the Two-Transformation Pattern. In this example, the first transformation (xMatters Create Event Request) creates a request structure that is passed to the xMatters Create Event activity. The second transformation (xMatters Create Event Response) receives the response structure, which is then written to a variable by a Variable Write activity (Write  xMatters Create Event Response) and a message is then logged by the Write to Operations Log script.

To use the activity with scripting functions, write the data to a temporary location and then use that location in the scripting function. When the workflow is ready, deploy and run the operation and validate behavior by checking the  operation logs . 

To configure an xMatters Get Event activity 

An xMatters Get Event activity retrieves an event record based on the event details into an xMatters endpoint and is intended to be used as a source to consume data in an operation. After configuring an xMatters connection, you can configure as many xMatters activities as you like for each xMatters connection. 

To configure an xMatters Get Event activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specify the activity settings.

   

   Field name	Action
   Name	Enter a name to identify the xMatters Get Event activity. The name must be unique for each xMatters Get Event activity and must not contain forward slashes (/) or colons (:).
   Event ID	Enter the Event ID or select the variable for the Event ID that you want to retrieve.
   Embed	Enter a comma-separated list of the objects to embed in the event. Valid values include: Annotations: Comments added to the event when responding to the event or in the tracking report Properties: Form properties that allow you to extract message details from the event ResponseOptions: Response options included in the event Suppressions: Events that are suppressed as a result of an event flood control rule targetedRecipients: List of targeted users, devices, groups, or dynamic teams
   Targeted	To get a list of directly targeted recipients, set to true. To get the list of resolved recipients only, set to false or leave blank.
   At	Enter the date and time in the UTC format of the time at which you want to see the status of the event in the system. For example, 2021-06-01T19:00:00.000Z

3. Click Next. 

4. Review the request and response data schemas displayed for your instance of xMatters.

   If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.

   The xMatters connector uses the  xMatters REST API version 1 . For more information about the schema fields, see the API documentation.

   

5. Click Finished. 
   After an xMatters activity has been created, you can access the menu actions for that activity from the project pane on either the Workflows or the Components tabs, and from the design canvas. For more information, see Activity Actions Menu .

Next steps

After configuring an xMatters Get Event activity, complete the configuration of the operation by adding and configuring other activities, transformations, or scripts as operation steps. You can also configure the operation settings, which include the ability to chain together operations from the same or different workflows.

xMatters Get Event activities can be used as a target with the following operation patterns:

• Transformation Pattern

• Two-Transformation Pattern  (as the first or second source)

Other patterns are not valid by using xMatters Get Event activities. For more information about the validation patterns, see the  Operation Validity  page.

A typical workflow uses an xMatters Get Event activity in the Two-Transformation Pattern. In this example, the first transformation (xMatters Get Event Request) creates a request structure that is passed to the xMatters Get Event Details activity. The second transformation (xMatters Get Event Response) receives the response structure, which is then written to a variable by a Variable Write activity (Write xMatters Get Event Response) and a message is then logged by the Write to Operation Log script.

To use the activity with scripting functions, write the data to a temporary location and then use that location in the scripting function. When the workflow is ready, deploy and run the operation and validate behavior by checking the  operation logs . 

To configure an xMatters Get All Events activity 

An xMatters Get All Events activity retrieves event records into an xMatters endpoint and is intended to be used as a source to consume data in an operation. After configuring an xMatters connection, you can configure as many xMatters activities as you like for each xMatters connection.

To configure an xMatters Get All Events activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specify the activity settings.
   

   Field name	Action
   Name	Enter a name to identify the xMatters Get All Events activity. The name must be unique for each xMatters Get All Events activity and must not contain forward slashes (/) or colons (:).
   Optional Settings	Click to expand additional optional settings: optional parameters JSON input: Enter the Key-Value pair for details of the event records to retrieve. Use the {"Key": "Value"} or [{"Key": "Value"}] format. For example, {     "propertyName":"customerAffected",     "propertyValue":"false",     "status":"ACTIVE,SUSPENDED",     "priority":"HIGH,MEDIUM,LOW",     "embed": "properties,annotations,responseOptions,suppressions",     "sortBy":"START_TIME",     "sortOrder":"ASCENDING",     "requestId":"3423560-6b87-4662-9a2f-107d3bb233bf",     "plan":"c56730a9-1435-4ae2-8c7e-b2539e635ac6",     "form":"8824b5b3-5875-4f04-adbc-e60fb108bef6",     "submitterid":"aUser",     "search":"Database",     "fields":"name",     "eventType":"SYSTEM,USER",     "from":"2017-05-01T14:00:00.000Z",     "to":"2017-05-01T19:00:00.000Z",     "propertyValueOperator":"EQUALS,CONTAINS",     "targetedRecipients":"c56730a9-1435-4ae2-8c7e-b2539e635ac6",     "resolvedUsers":"mmcbride,tsmith",     "at":"2018-11-02T08:00:00.000Z" }

3. Click Next.

4. Review the request and response data schemas displayed for your instance of xMatters.

   If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.

   The xMatters connector uses the  xMatters REST API version 1 . For more information about the schema fields, see the API documentation.

   

5. Click Finished.
   After an xMatters activity has been created, you can access the menu actions for that activity from the project pane on either the Workflows or the Components tabs, and from the design canvas. For more information, see Activity Actions Menu .

Next steps

After configuring an xMatters Get All Events activity, complete the configuration of the operation by adding and configuring other activities, transformations, or scripts as operation steps. You can also configure the operation settings, which include the ability to chain together operations from the same or different workflows.

xMatters Get All Events activities can be used as a target with the following operation patterns:

• Transformation Pattern

• Two-Transformation Pattern  (as the first or second source)

Other patterns are not valid by using xMatters Get All Events activities. For more information about the validation patterns, see the  Operation Validity  page.

A typical workflow uses an xMatters Get All Events activity in the Two-Transformation Pattern. In this example, the first transformation (xMatters Get All Events Request) creates a request structure that is passed to the xMatters Get All Events activity. The second transformation (xMatters Get All Events Response) receives the response structure, which is then written to a variable by a Variable Write activity (xMatters Get All Events Write ) and a message is then logged by the Write to Operations Log script:

To use the activity with scripting functions, write the data to a temporary location and then use that temporary location in the scripting function.

When ready, deploy and run the operation and validate behavior by checking the  operation logs . 

To configure an xMatters Update Event Status activity 

an xMatters Update Event Status activity updates an existing event record at the xMatters endpoint and is intended to be used as a target to consume data in an operation. After configuring an xMatters connection, you can configure as many xMatters activities as you like for each xMatters connection.

To configure an xMatters Update Event Status activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specify the activity settings. 
   

   Field name	Action
   Name	Enter a name to use to identify the xMatters Update Event Status activity. The name must be unique for each xMatters Update Event Status activity and must not contain forward slashes (/) or colons (:).
   Event ID	Enter the Event ID or select the Event ID variable to close.
   Status	Enter the status of the event. Valid values include: Active Suspended Terminated

3. Click Next.

4. Review the request and response data schemas displayed for your instance of xMatters.

   If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.

   The xMatters connector uses the  xMatters REST API version 1 . For more information about the schema fields, see the API documentation.

   

5. Click Finished.
   After an xMatters activity has been created, you can access the menu actions for that activity from the project pane on either the Workflows or the Components tabs, and from the design canvas. For more information, see Activity Actions Menu .

Next steps

After configuring an xMatters Update Event Status activity, complete the configuration of the operation by adding and configuring other activities, transformations, or scripts as operation steps. You can also configure the operation settings, which include the ability to chain together operations from the same or different workflows.

xMatters Update Event Status activities can be used as a target with the following operation patterns:

• Transformation Pattern

• Two-Transformation Pattern  (as the first or second source)

Other patterns are not valid by using xMatters Update Event Status activities. For more information about the validation patterns, see the  Operation Validity  page.

A typical workflow uses an xMatters Update Event Status activity in the Two-Transformation Pattern. In this example, the first transformation (xMatters Update Event Status Request) creates a request structure that is passed to the xMatters Update Event Status activity. The second transformation (xMatters Update Event Status Response) receives the response structure, which is then written to a variable by a Variable Write activity (xMatters Write Update Event Status Response) and a message is then logged by the Write to Operations Log script.

To use the activity with scripting functions, write the data to a temporary location and then use that temporary location in the scripting function.

When ready, deploy and run the operation and validate behavior by checking the  operation logs . 

To configure an xMatters Add Event Comment activity 

An xMatters Add Event Comment activity updates an existing event record at the xMatters endpoint and is intended to be used as a target to consume data in an operation. After configuring an xMatters connection, you can configure as many xMatters activities as you like for each xMatters connection.

To configure an xMatters Add Event Comment activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specify the activity settings. 

   

   Field name	Action
   Name	Enter a name to identify the xMatters Update Event Status activity. The name must be unique for each xMatters Update Event Status activity and must not contain forward slashes (/) or colons (:).
   Event ID	Enter the Event ID or select the variable for the Event ID to which you want to add a comment.
   Comment	Enter the comment to add to the event.

3. Click Next.

4. Review the request and response data schemas displayed for your instance of xMatters.

   If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.

   The xMatters connector uses the  xMatters REST API version 1 . For more information about the schema fields, see the API documentation.
   

5. Click Finished.
   After an xMatters activity has been created, you can access the menu actions for that activity from the project pane on either the Workflows or the Components tabs, and from the design canvas. For more information, see Activity Actions Menu .

Next steps

After configuring an xMatters Add Event Comment activity, complete the configuration of the operation by adding and configuring other activities, transformations, or scripts as operation steps. You can also configure the operation settings, which include the ability to chain together operations from the same or different workflows.

xMatters Add Event Comment activities can be used as a target with the following operation patterns:

• Transformation Pattern

• Two-Transformation Pattern  (as the first or second source)

Other patterns are not valid by using xMatters Add Event Comment activities. For more information about the validation patterns, see the  Operation Validity  page.

A typical workflow uses an xMatters Add Event Comment activity in the Two-Transformation Pattern. In this example, the first transformation (xMatters Add Event Comment Request) creates a request structure that is passed to the xMatters Add Event Comment activity. The second transformation (xMatters Add Event Comment Response) receives the response structure, which is then written to a variable by a Variable Write activity (xMatters Write Add Event Comment Response) and a message is then logged by the Write to Operations Log script.

To use the activity with scripting functions, write the data to a temporary location and then use that temporary location in the scripting function.

When ready, deploy and run the operation and validate behavior by checking the  operation logs .