Get up and running with the Integration Agent

1. Log in to xMatters as a Company Administrator.
2. Click the Users tab, and then click Add Web Service User in the Web Service Users menu.
3. Give your web service user a user ID (the default user ID used by the Integration Agent is "ia_user") and password.
   • Make note of the user ID and password – you need them to configure the Integration Agent. In our examples below, we'll use "ia_user" as the username and "password" as the password.
4. Give the user access to the following web services:
   • Register Integration Agent
   • Receive APXML
   • Submit APXML

1. Log in to the target xMatters system.
2. On the Users tab, click Add.
3. Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how alerts are displayed in the reports and Communication Center, you may want to identify the user as specific to this integration. For example, if you're integrating with the sample workflow, you might set up the user as follows:
   • First Name: Sample
   • Last Name: Integration
   • User ID: sampleplan (we'll use this in our examples below)
4. Assign the user to the REST Web Service User role and set their password (we'll use "password" in our examples below).
   • Depending on your deployment, you might need to add one of the following roles so you can log in as the integration user: Full Access User or Developer.
5. Make a note of these details; you'll need them when configuring other parts of this integration.
6. Click Save.

1. In the extracted Integration Agent archive, locate the integrationservices\applications\sample-plan\SamplePlan.zip file and copy it to your local workstation.
2. Log in to your xMatters system, click the Workflows tab, and then click Import.
3. Browse to the zip file (or drag it onto the Import Workflow screen).
4. Click Import.
   • Once the import is finished, the workflow should be automatically enabled. If it isn't, click Disabled to enable it.
5. Click the edit icon beside the workflow name and select Editor Permissions.
6. Add the integration user you created above, and then click Save.
7. Click the workflow name to open it.
8. On the Forms tab, check that the forms are deployed. If they aren't, click Not Deployed beside the form and select Enable for Web Service.
9. For the Confirmation Message form, in the drop-down list, click the Web Service drop-down list then click Sender Permissions.
10. Add the integration user, and then click Save Changes.
11. Go to the Integration Builder tab and expand the list of inbound integrations.
12. Click the name of the integration to view its details, then select Basic in the Select authentication method drop-down list.
13. Click Update Inbound Integration, then scroll down to the bottom of the page, and click Copy beside the URL field.
14. Paste the URL into a file — you'll need it later to configure the Integration Agent.

1. The first step is to extract the Integration Agent archive (unzip or untar) onto your server or workstation. There are some best practices and recommendations to keep in mind:
   • If you plan to integrate with software you're already using, the simplest (and recommended) approach is to install the Integration Agent onto the same server as that software.
   • We recommend that you install the Integration Agent in C:\xmatters (Windows) or /opt/xmatters (Linux). Extracting the archive into this folder creates a subfolder named integrationagent-#.#.#, where #.#.# is the version number. For example:

C:\xmatters\integrationagent-5.3.0

2. Next, extract the integrationagent-utils.zip archive to the subfolder that was created, and allow the extracted lib and integrationservices folders to merge with the ones already present.
   • If you are using an integration that requires a specific version of the IAUtils, follow the instructions in the integration guide for that integration.

We refer to the installation location (for example, C:\xmatters\integrationagent-5.3.0 in the steps above) as <IAHOME> in our documentation. Also keep in mind that, in most cases, we show the Windows paths and commands — substitute the commands for your operating system wherever appropriate.

As part of the installation process, you need download an Adoptium JDK (formerly known as Adopt OpenJDK) archive for your operating system and copy certain files from that package into a folder in <IAHOME>. For the JVM version, OpenJ9 should also function, but testing was performed using HotSpot.

1. Go to https://adoptium.net/releases.html.
2. For the version, select Temurin 8 (LTS).
3. Select your Operating System and Architecture from the drop-down menus.
   • For all versions of Windows, select the x86 architecture.
   • For Linux, choose x64.
4. For each operating system, there will be a JDK and a JRE option — be sure to choose the JDK file
   1. For Windows, choose the .zip file, and not the .msi installer.
5. Delete your existing <IAHOME>/jre folder.
6. Extract the OpenJDK archive file and copy the jre folder from the extracted archive to <IAHOME>.
7. In the extracted archive, navigate to the lib folder.

8. Find the tools.jar file, and copy it into the <IAHOME>/jre/lib directory.

The steps below provide the basic settings to get you up and running quickly. You can adjust the other settings if needed for your instance.

1. Navigate into your newly installed Integration Agent, and open the <IAHOME>\conf\IAConfig.xml file in a text editor.
2. Edit the following configuration settings (you can leave the other settings as is for now):
   • In the web-services-auth section, replace the value in the user tags with the name of the web service user you created above, and replace the "Default Company" value in the company tags with the name of your company in xMatters. (Leave the password value for now; we'll get to that later.)
   • In the heartbeat section:
     • In the primary-servers section, change the subdomain and domain portion of the url value to point to the IP address (or hostname) of your xMatters hosted instance. For example, change:
       <url>https://xyzcustomer.hosted.xmatters.com/api/services/AlarmPointWebService</url>
       to:
       <url>https://acmeco.hosted.xmatters.com/api/services/AlarmPointWebService</url>
3. Save and close the file.

1. Open a command window, and navigate to the <IAHOME>\bin folder.
2. Run the following command, but replace <new_password> with the actual password of the web service user you created in xMatters:
   iapassword.bat --new "<new_password>" --file conf/.wspasswd

   In our example, this would be iapassword.bat --new "password" --file conf/.wspasswd — this is the password referenced in the IAConfig.xml file configuration. In our example, you don't need to do anything else. Just keep in mind that, if you change the name or location of this file, you'd need to update the IAConfig.xml file.

3. Now run the command for the integration user, replacing <new_password> with the password of the integration user you set up:
   iapassword.bat --new "<new_password>" --file conf/.initiatorpasswd

   In our example, this would be iapassword.bat --new "password" --file conf/.initiatorpasswd

For more information on the IAPassword encryption utility, see IAPassword Utility.

1. Open the <IAHOME>\conf\IAConfig.xml file, find the service-configs section, and check that <path>applications/sample-plan/sample-plan.xml</path> is shown and not commented out.
   • For other integrations, you'd add a <path>applications/integration folder/IntegrationName.xml</path> line to the section to add it to your integration services list.
2. Save and close the file.
3. Open the <IAHOME>integrationservices\applications\sample-plan\configuration.js file in a text editor and locate the following line:
   WEB_SERVICE_URL = "Paste the Inbound Integration URL here"
4. Replace the words in the double quotes with the inbound integration URL you copied from xMatters. (Make sure you keep the double quotes!)
   • We'd show you an example, but it's unique to each xMatters instance and each integration.
5. Now locate the following line:
   INITIATOR = "admin"
6. Replace admin with the name of the sample integration user account you created.
   • In our example, it would be: INITIATOR = "sampleplan"
7. Make sure PASSWORD matches the path and filename of the encrypted password file you created above for the integration user.
8. Save and close the configuration.js file.

You can configure the outbound integrations (or callbacks) and deduplication settings as well.

1. In the command window, run the following command from <IAHOME>\bin:
   start_console.bat

   In a non-Windows systems, run ./start_console.sh (this runs as the current user)

   The console should start (hopefully with no errors), and display the following message:
   "Successfully completed Integration Agent bootstrap process. Integration Agent is running."

2. Now open another command prompt and navigate to <IAHOME>\bin, and run the following command (using the IAdmin tool):
   iadmin get-status

You should see two indications that the connection to xMatters is valid:

• The xMatters server shows "Connectivity status: PRIMARY ACCEPTED"
• The sample workflow integration shows "Status: ACTIVE"

Windows

To run the Integration Agent as a service, you first need to install the service by running <IAHOME>\bin\install_service.bat. After you've done that, do one of the following to start the Integration Agent:

• Open Windows Administrative Tools > Component Services, right-click xMatters Integration Agent, and then click Start.
• Double-click the start_service.bat file (located at: <IAHOME>\bin).
• From a command line, run start_service.bat (located at: <IAHOME>\bin).
• From a command line, run startup.bat (located at: <IAHOME>\bin). This command starts the service and issues a get-status request through IAdmin.

Linux

Run the following from a command line (this needs to be done manually any time the server restarts):

./<IAHOME>/bin/start_daemon.sh

This runs as the current user.

Use RESTClient, cURL, PostMan or a similar utility to send an HTTP POST request to the Integration Agent.

This example sends a message to Bob Smith (bsmith), the Operations group (Operations) and Tara Sanderson's (tsanderson) email and voicemail devices.

URL:

http://127.0.0.1:8081/http/applications_sample-plan

Request body (formatted here for clarity):

<?xml version=\"1.0\" encoding=\"UTF-8\"?>

<event>

<properties>

<building>\"Building A\", \"Building B\"</building>

<city>Victoria</city>

</properties>

<recipients>

<targetName>bsmith</targetName>

<targetName>Operations</targetName>

<targetName>tsanderson, devices: ["\Email\", "\Voice Phone\"]</targetName>

</recipients>

</event>

Replace one of the targeted recipients with a notifiable user, group or device that exists in your xMatters instance.

For example, if you use cURL, the command would be:

curl.exe -i -X POST -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><event><properties><building>\"Building A\", \"Building B\"</building><city>Victoria</city></properties><recipients><targetName>bsmith</targetName><targetName>Operations</targetName><targetName>tsanderson, devices: ["\Email\", "\Voice Phone\"]</targetName></recipients></event>" http://127.0.0.1:8081/http/applications_sample-plan

To create an alert using the command line (APClient.bin), submit a call to your Integration Agent using the following syntax:

APClient.bin --map-data applications|<integrationService> <parameters>

The parameters you include are based on the settings in the mapped-input section in the integration service file. For example, assume you want to create an alert based on the sample workflow with the following properties:

• recipients: bsmith
• xmpriority:high
• form properties:
  • building: Building B
  • city: Vancouver

Your command line entry uses the following syntax and values.

Linux:

apclient.bin --map-data 'applications|sample-plan' '[{"targetName":"bsmith"}]' 'high' '["Building A"]' 'Vancouver'

Windows:

apclient.bin --map-data "applications|sample-plan" "[{\"targetName\":\"bsmith\"}]" high "[\"Building A\"]" "Vancouver"

Once you have identified the types of webhooks you want to receive, you need to configure the integration file (configuration.js) to request them.

You can configure a couple of ways:

• Using the Integration Builder in the web user interface: use this method if you want the webhook to fire based on form alerts.
• Using the integration's configuration file: use this method if you want the outbound integration webhook to fire on the Integration Agent that it came from. Follow the instructions below to configure this method.

If you configure the webhooks in the integration configuration file, these take precedence over those defined in the workflow.

To configure the webhooks in the integration file:

1. Open configuration.js in a text editor.
2. Specify the types of outbound integrations you want in the CALLBACKS parameter.
   1. The following setting illustrates the syntax for the parameter (it requests all available webhook types):

CALLBACKS = ["status", "deliveryStatus", "response", "annotation", "escalation", "targetedRecipientFailure"];

3. Save and close the file.

You may need to add handling to the Javascript file (sample-plan.js) to process the webhooks and parse the information. For more information, see apia_callback(msg).

Each parameter maps to a workflow property or to one of the following top-level message elements:

• recipients: Maps to the Recipients section of a form, which identifies the notification targets.
• xmresponses: Maps to the responses for the form.
• xmconferences: Maps to the Conferences section of a form.
• xmpriority: Sets the priority of the conferences, responses, and notifications. (In the sample workflow integration files, this has been remapped to take a parameter called "priority".)

Example APClient.bin configuration

To configure the mapped input parameters for the sample workflow, open sample-plan.xml in a text editor. The mapped-input section contains the following default parameters:

<mapped-input method="add">

<parameter>recipients</parameter>

<parameter>priority</parameter>

<parameter>building</parameter>

<parameter>city</parameter>

</mapped-input>

If you're creating an alert via the command line, you need to specify the values in the same order as they're listed in the mapped-input section. So, in the sample workflow configuration, the command line input expects to receive four parameters in the following order: first the targeted recipients, then the priority of the notification (as mentioned above, this has been remapped from 'xmpriority'), and finally a building and a city, which are properties on the sample form.

If you had other properties on the form, you could add them as parameters within the mapped-input section. You could also add a reserved parameter to further customize the integration.

This function works similar to apia_response (see the Response action scripting section in the full Integration Agent 5.2 guide for details), but the parameter is a Javascript object that contains the callback information from xMatters.

You can see sample payloads in the Outbound integrations to the Integration Agent topic in the online help.

The sample-plan.js contains the following example of how to use the apia_callback function to access the values within the callback and print it to the Integration Agent log when integration service logging is enabled:

function apia_callback(msg)

{

  var str = "Received message from xMatters:\n";

  str += "Incident: " + msg.incident_id;

  str += "\nEvent Id: " + msg.eventidentifier;

  str += "\nCallback Type: " + msg.xmatters_callback_type;

  IALOG.info(str);

}

You can use the following functions when using APClient.bin injection and mapped-input parameters. The examples assume that you're targeting the sample workflow with the command line you used to send the test message.

apia_event(form)

This function works similar to apia_input (see the Input action scripting section for in the full Integration Agent 5.2 guide details), except that where the apia_input function accepts an APXML parameter, the apia_event function takes a Javascript object that can be serialized to the xMatters post JSON body.

The function uses the map data submissions to set the properties on the workflow, but you can also use the function to set the defaults on the target form.

Any properties set using the apia_event function override any values passed in via the command line.

The function uses the following syntax to refer to form properties:

form.properties.<propertyName>

For example, in the included sample form, you'd refer to the two properties as follows:

form.properties.building

form.properties.city

The different types of properties available on a form have required formatting and quoting rules:

You can also use the apia_event function to specify default recipients. As with properties, any recipients defined within the Javascript file overrides the recipients passed in via the command line. The syntax to set the recipients is:

form.properties.recipients = '[{"targetname": "<User ID>"}]' 

The formatting and quoting rules are also similar, for example:

'[{"targetname": "admin"}, {"targetname": "bsmith"}]'
or, as required on Windows systems:
"[{\"targetname\": \"admin\", \"targetname\": \"bsmith\"}]"

Example

As an example of the apia_event function, you could add the following code to the sample-plan.js file:

function apia_event(form)

{

  // Print this to the IA log:

  // Building is Building A

  ServiceAPI.getLogger().info("Building is " + form.properties.building);

  // Change the city value from Vancouver to Victoria

  form.properties.city = "Victoria";

  return form;

}

The above code would log the name of the building that is passed into APClient.bin in the Integration Agent log file, and would set the value of the city property to "Victoria", overriding anything passed in on the command line.

apia_remapped_data()

This function allows you to reconfigure the reserved keyword mappings, and use a different parameter to target a top-level form attribute. You can use this function to remap one or more of the top level attributes in the post JSON body.

Syntax

function apia_remapped_data() {

  return {

    "<top-level JSON attribute>" : "<mapped-input parameter name>"

  }

}

For an explanation of this syntax, consider the following example of the JSON used to create an alert based on the sample form:

{

  "recipients": [{

"targetName": "bsmith"

},

  ],

  "priority": "high",

  "conferences": [

{"name":"P1M1"}

],

  "responses": [

"a1b73279-465f-4f18-a44b-47993c3f75b9",

"75f789c2-87b2-4c63-91de-ea6e5834e91d"

]

  "properties": {

"Building":["Building A", "Building B"],

"City":"Victoria",

},

}

You can see that the top-level attributes are:

• recipients
• priority (a mapped-input parameter of 'xmpriority' automatically maps to this attribute)
• conferences (a mapped-input parameter of 'xmconferences' automatically maps to this attribute)
• responses (a mapped-input parameter of 'xmresponses' automatically maps to this attribute)
• properties (any mapped-data parameter that is not recipients, xmpriority, xmconferences, or xmresponses is assumed to be a property)

Example

For example, xMatters will always use the 'xmpriority' mapped-input parameter to set the value of the 'priority' attribute in the JSON object. Now, imagine that you're building an integration with a management system and want to pass in a parameter named 'priority' and map it to the priority attribute (instead of passing in an 'xmpriority' parameter). The following code, from the included sample workflow integration service file, shows how this has already been configured for the sample workflow:

<mapped-input method="add">

<parameter>recipients</parameter>

<parameter>priority</parameter>

<parameter>building</parameter>

<parameter>city</parameter>

</mapped-input>

The code included in the sample Javascript file illustrates the syntax used to remap the 'priority' top level attribute to the 'priority' parameter.

function apia_remapped_data() {

return {

"priority" : "priority"

}

}

The top-level attribute on the left is represented by its name in the JSON object, and not the 'xmpriority' parameter.

With these changes in place, xMatters uses the values passed in for the priority parameter to identify the value for the 'priority' attribute in the JSON body.