BMC Remedy Change Management

Download the .zip or .tar file that contains all of the components required by xMatters and BMC Remedy Change Management. Save the file to a location on your local machine, and extract the contents.

If you navigate through the folders, you will find another .zip file within the extracted integration archive. This is the workflow, which contains pre-configured integrations, forms, properties, and messages specifically designed for BMC Remedy. . Do NOT extract the contents of the workflow .zip file — you'll import it directly into xMatters.

You need to enable and configure REST API in BMC Remedy for this integration to work. For information about enabling REST API in BMC Remedy Action Request System, see the BMC Remedy documentation.

This integration requires a user who can authenticate REST web service calls when working with alerts – these permissions are provided by the "REST Web Service User" role in xMatters. See Create an integration user for more information.

Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration.

The next step is to import the workflow. You can find workflow .zip file in the components > xmatters folder you downloaded and extracted.

To import the workflow:

1. In xMatters, click the Workflows tab, and then click Import.
2. Browse to the BMCRemedyChangeManagement.zip file, or drag it onto the Import Workflow dialog box.
3. Click Import.
   • Once the import is finished, the workflow should be automatically enabled. If it isn't, click the Disabled toggle to enable it.
4. Click the gear icon beside the workflow, and select Editor Permissions.

   

5. Add the integration user, and then click Save.
6. Click the workflow name to open the Forms tab.
7. For the first form in the list (Change Request Approval), click the Web Service Only drop-down list, and then select Sender Permissions.

   

8. Add the integration user, and then click Save Changes.
9. Repeat steps 7-8 for each of the other forms.

You'll need to configure the authentication and retrieve the URLs for the inbound integration.

To configure an inbound integration:

1. In the Integration Builder, expand the list of inbound integrations.
2. Click the name of an integration to view its details.
3. Under the Select authentication method step, select Basic from the drop-down list.
4. Click Save.
5. Scroll down to the bottom of the page, and click Copy beside the field:

   

This integration requires a web service user with specific permissions in xMatters to receive user responses and notifications about event status changes for the Integration Agent. ("Web service users" are a specific type of user in xMatters that can work with the SOAP web services used by the Integration Agent; this means you can't just use a regular user and assign them a specific role or permission – you have to create a dedicated user.)

To set up a web service user:

1. In xMatters, click the Users tab, and then, in the menu on the left side of the page, click Add Web Service User.
2. On the Add Web Service User page, enter a User ID.
   • This user should match the xMatters user created in BMC Remedy.
3. In the Denied Web Services list, locate and select the following web services, and then click Add:
   • Query Incident
   • Query User
   • Receive APXML
   • Register Integration Agent
   • Submit APXML
4. Enter a Password for the new web service user.
5. Click Save.

Some configuration fields require a UUID (Universal Unique Identifier) for a specific component or property - usually the responses. To retrieve the identifier for an element, look for the API icon in the xMatters user interface:

Clicking this button will display the identifier for the component in a dialog box; you can copy and paste the string to the appropriate location in the configuration file.

As an example, the following instructions describe how to retrieve the UUID for a specific response choice; the process is similar for any identifier you want to determine.

To retrieve the identifier for a response choice:

1. In xMatters, open the BMC Remedy Change Management workflow.
2. On the Change Request Approval form, click Edit > Responses.
3. Beside the Approve response, click the API icon.

1. Within the extracted integration archive, navigate to components\integration-agent\integrationservices, and copy the entire contents of the folder to the <IAHOME>\integrationservices directory.
2. Open the <IAHOME>\conf\IAConfig.xml file and add the following line to the "service-configs" section:<path>bmcremedychange50/bmcremedychange.xml</path>
3. Save and close the file.
4. Open the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file and add or set the values for the following variables:

   REMEDY_SERVER_HOSTNAME	BMC Remedy server URL that can be resolved to an IP address.
   REMEDY_AR_SERVER_NAME	BMC Remedy Action Request (AR) server name.
   XMATTERS_COMPANY_NAME	The company name to display in the notification email.
   REMEDY_WS_USERNAME	User name of the account used to access the BMC Remedy web services that support the integration.
   REMEDY_WS_PASSWORD_FILE	Location of the file containing the web services user's password.
   XMATTERS_REMEDY_CHANGE_APPROVAL_URL	URL of inbound integration used to handle incoming alerts
   RESPONSE_OPTIONS	The identifiers for the response options for the xMatters form.
   INITIATOR	The User ID of the integration (REST) user.
   PASSWORD	Path and filename of the password file containing the encrypted password of the xMatters initiator user.
   DELETE_EXISTING_EVENTS	When set to true, sends a 'delete' prior to creating the new event to clear any existing alerts for this Change Request ID.
   TIME_TO_SLEEP_BEFORE_ PROCESSING_DEL_FOR_REJECTED_APPOVALS	Defines how long (in milliseconds) xMatters should wait for BMC Remedy to finish updating approval records before deleting associated notifications in xMatters. The default is 2000 (2 seconds).

5. Save and close the file.
6. Restart the Integration Agent.

This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the integration user and the BMC Remedy web services user. You will need to update (or create) the files with the correct passwords for these users.

Password files:

• initiatorpasswd stores the password for the integration user
• xm_chg_ws.pwd stores the password for the BMC Remedy web services user

If you store the passwords with a different file name or in a different location, you must update the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file with the correct name and path.

To configure the REST API user password:

1. Open a command prompt and navigate to <IAHOME>\bin
2. Run the following command, where <new_password> is the password for the INITIATOR (the integration user) specified in the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file, and <old_password> is the existing password (the default password for a newly installed integration is "password"):
   iapassword.bat --new <new_password> --old <old_password> --file conf/.initiatorpasswd
3. Now run the command again, but where <new_password> is the password for the REMEDY_WS_USERNAME (the BMC Remedy web service user) specified in the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file, and <old_password> is the existing password (the default password for a newly installed integration is "password"):
   iapassword.bat --new <new_password> --old <old_password> --file conf/xm_chg_ws.pwd

For more information about working with the iapassword command, and creating password files, refer to the xMatters Integration Agent Guide.

The integration package includes a filter that engages the Integration Agent's filtering and suppression module to suppress duplicate alerts (also known as deduplication). This can help to avoid disruption of traffic due to event floods (a potential hazard with improperly configured management systems).

The deduplicator is installed into the <IAHOME>\conf folder, and is configured by default to suppress up to 100 duplicate alerts for two minutes. You can configure the filter to extend the time period in which an event is considered to be a duplicate, the number of alerts within that period, and the tokens or properties that xMatters uses to determine what makes the event unique.

To enable deduplication:

1. Navigate to the <IAHOME>\conf directory.
2. If you have an existing deduplicator-filter.xml file in this folder, create a backup version in a separate location.
3. Copy the deduplicator-filter.xml file from the integration-agent\conf folder in the extracted integration archive into the <IAHOME>\conf directory.
4. If you backed up an existing deduplicator file, merge the contents of your backup with the newly installed <IAHOME>\conf\deduplicator-filter.xml file: open both files in a text editor, and then copy the <filter> node from the backup file into the new deduplicator file after the last </filter> node.
5. Save and close the file.
6. Restart the Integration Agent.

For more information about the deduplication filter and the available settings, refer to the "Filtering and Suppression" section in the xMatters Integration Agent Guide.

To import the workflow definition files into BMC Remedy:

1. Log in to the BMC Remedy Developer Studio, and then select File > Import.
2. Select BMC Remedy Developer Studio > Object Definitions, and then click Next.
3. Select the AR System server into which you want to upload the integration objects, and then click Next.
4. Do one of the following:
   • Type in the location of the xm_foundation_9_1.def file.
   • Click the Browse button to the right of the text field and navigate to the location of the xm_foundation_9_1.def file. Select the file, and then click Open.
5. Click Next.
   • If you have already imported a workflow definition file, ensure that you select Replace Objects on the Destination Server check box (do not select the other check boxes), but note that any changes you have made to those objects will be lost. If you are sure the changes you made are necessary for your installation, you will be required to re-apply those changes to the new version of the files being imported unless you applied those changes to overlay objects.
6. Repeat the above steps to import the xm_change_9_1.def file.
   • This file must be imported after the foundation file.
7. Click Finish.

You need to create a new user in BMC Remedy for the xMatters integration so that xMatters can write to any ticket. To create the xmchange user:

1. Go to Applications > Quick Links > Approval Administration Console.
2. On the Administrator tab, click Create.
3. On the Process Administrator tab, fill in the following information:
   • Individual: Match the user ID for the xMatters web services user
   • Authority: Full Admin
4. Click Save.