BMC Remedy Change Management (Integration version 5.0)

Contents

Introduction

Prerequisites

Configure xMatters

Configure the Integration Agent

Configure BMC Remedy

How to use the integration

Extend and optimize your integration

Download resources

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

Introduction

This article provides you with the installation and configuration details you need to integrate the xMatters On-Demand service with BMC Remedy Change Management.

This integration uses the communication plan technology within xMatters On-Demand to become the voice and interface of an automation engine. When BMC Remedy detects change requests that require approval or notification, xMatters places phone calls, send emails, or notifies your mobile app.

Integration Version

This version of the integration (5.0) is compatible with BMC Remedy 9.1 Change Management and above, and is designed specifically for xMatters On-Demand. 

How it works

The change management integration service runs in the Integration Agent and handles events and responses associated with change requests in BMC Remedy Change Management and approval requests in BMC Remedy Approval Server.

After BMC Remedy Change Management triggers one of the xMatters filters available as part of this integration, the filter pushes data to a backing form, which sends the request to xMatters On-Demand via the xMatters Integration Agent. xMatters notifies the correct recipients, and then sends response information back to BMC Remedy, allowing users to approve, reject, hold or view the change request from their device.

Features and updates in this version

This version of the integration includes several updates and enhancements:

  • The integration now targets the inbound integrations included in the communication plan rather than the form itself. This provides access to all of the enhancements and options available in the Integration Builder, including the Activity Stream, transformation scripts, and authentication options.

Prerequisites

Before you get started configuring the integration, there are a couple of things you can do ahead of time to make it easier. 

Download the integration archive

The .zip file attached to this article contains all of the components required by xMatters and BMC Remedy Change Management. Download the attached .zip file to a location on your local machine, and extract the contents.

You may also notice that there is another .zip file within the extracted integration archive. This is the communication plan, which contains pre-configured integrations, forms, properties, and messages specifically designed for BMC Remedy. Do NOT extract the contents of the communication plan .zip file! You'll be able to import it directly into xMatters.

Enable and Configure REST API in BMC Remedy

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.

Configure xMatters On-Demand

The first step in configuring this integration is to get your On-Demand environment ready, and set up the components on the xMatters side.

Create an integration user

This integration requires a user who can authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the permissions and capabilities.

Note for trial: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.

To create an integration user:

  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 will affect how messages appear for recipients and how events will be displayed in reports and the Communication Center, you may want to identify the user as specific to this integration; for example:
    • First Name: BMC Remedy Change Management
    • Last Name: Integration
    • User ID: bmcremedycm
  4. Set the password for the user.
    • Make a note of the user ID and password details; you will need them when configuring other parts of the integration.
  5. Assign the user to the REST Web Service User role.
  6. Click Add.

Import the communication plan

The next step is to import the communication plan. You can find this .zip file in the package you downloaded and extracted – look in the components > xmatters folder. 

To import the communication plan:

  1. In xMatters, click the Developer tab, and then click Import Plan.
  2. Click Choose File, and then locate the plan you downloaded from this article (the .zip file).
  3. Click Import Plan.
    • Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.
  4. Click the Edit drop-down list for the plan, and select Access Permissions.
  5. Add the integration user you created above, and then click Save Changes.
  6. In the Edit drop-down list for the plan, select Forms.
  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 you created above, and then click Save Changes.
  9. Repeat steps 7-8 for each of the other forms in the plan.

Configure inbound integrations

You will 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 Update Integration.
  5. Scroll down to the bottom of the page, and click Copy URL beside the field:

CopyURL.jpg

Create a web service user

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.

Determine identifiers

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

APIIcon.png

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 communication plan.
  2. On the Change Request Approval form, click Edit > Responses.
  3. Beside the Approve response, click the API icon.

Configure the xMatters Integration Agent

Now that you've configured xMatters On-Demand, it's time to configure the Integration Agent.

The installation instructions below assume you already have a working xMatters Integration Agent. If this is a new installation and you have not yet deployed the Integration Agent, follow this link to download, deploy and configure it: Integration Agent for xMatters 5.x & xMatters On-Demand

Install the integration files

The installation package contains all that you need to configure the integration.

Note: As usual for our Integration Agent documentation, <IAHOME> refers to the installation folder of the Integration Agent on your system.

To install the integration files:

  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 events
RESPONSE_OPTIONS The identifiers for the response options for the xMatters form.
INITIATOR The User ID of the integration (REST) user you created in xMatters.
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 events 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). 
  1. Save and close the file.
  2. Restart the Integration Agent

Set the password files

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:

Note: 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
  1. 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.

Configure deduplication

The integration package includes a filter that engages the Integration Agent's filtering and suppression module to suppress duplicate events (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 events 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 events 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. Save and close the file. 
  5. 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

Configure BMC Remedy

To configure BMC Remedy to integrate with xMatters, you need to:

  • Import workflow definitions into BMC Remedy
  • Add an xMatters user to BMC Remedy

Import the workflow definition files

You need to import a couple of workflow definition files into BMC Remedy. 

To import the workflow definition files:

  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 the 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.

Create xMatters user in BMC Remedy

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:
  4. Click Save.

And that's it! Your integration should be ready to go.

How to use the integration

When the integration is configured, BMC Remedy automatically sends information about any approval request it detects to xMatters via the Integration Agent.

Trigger a notification

To test the incident notification portion of the integration, create a new change request in BMC Remedy that targets a user with a device that you can access (so you can respond to the notification when it arrives) and who exists in both BMC Remedy and xMatters.

The targeted user receives a notification from xMatters.

Respond to a notification

On a device with the xMatters mobile app, you can respond to the message simply by tapping Respond, and then tapping one of the response choices:

BMCRemedyChangeNotification.png

BMCRemedyChangeResponse.png

Other devices use similar methods.

View response results

After you respond to the notification, you can see how the integration automatically updates the event information with the response details in BMC Remedy Change Management.

For approval requests, the notification and response results are recorded on the Work Detail tab of the associated change request:

BMCRemedy_CR_WorkDetail.png

Extend and optimize your integration

You can use the following tips to customize your integration to better suit your deployment.

  • Change the statuses that trigger notifications to be sent.
  • Send change events in addition to approval requests.
  • Disable delivery annotation.
  • Disable alternate approver lookup.
  • Modify the filters in the definition files using BMC Developer Studio.

Change the statuses that send notifications to Change Managers and Change Coordinators

By default, the integration sends notifications to the Change Manager and Change Coordinator when the approval status of a change request is updated. 

xMatters sends notifications for these approval statuses: Cancelled, Closed, Completed, Draft, Implementation In Progress, Pending, Planning In Progress, Rejected, Request For Authorization, Request For Change, Scheduled, Scheduled For Approval, and Scheduled For Review. You can change this functionality, depending on your needs.

To change the statuses that send notifications:

  1. Open the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file and change the values for the following variables to the values you want to trigger these notifications:
    • CHANGE_COORDINATOR_ALERT_ STATUS
    • CHANGE_MANAGER_ALERT_STATUS
  2. Save and close the file.
  3. Restart the Integration Agent.

To send a notification to all managers and coordinators, regardless of the approval status, set the value for these parameters to null.

Send notifications of change events

By default, xMatters only sends notifications for approval requests. You can also configure the integration to send notifications for changes in the status of a change request.

To enable notifications for change events:

  1. Open the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file.
  2. Set the value of the SEND_ACTIVE_APPROVAL_ONLY variable to false.
  3. Save and close the file.
  4. Restart the Integration Agent.

Disable delivery annotation

This integration extensively annotates the originating BMC Remedy change request, but you can disable this behavior if needed for your environment (for example, if there is a large group of approvers).

To disable delivery annotation:

  1. Open the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file.
  2. Set the value of the ANNOTATE_DELIVERY variable to false.
  3. Save and close the file.
  4. Restart the Integration Agent. 

Disable alternate approver lookup

BMC Remedy Change Management lets you set up an alternate approver. By default, xMatters will notify the alternate approver, but you can disable this. 

To disable alternate approver lookup:

  1. Open the <IAHOME>\integrationservices\applications\bmcremedychange50\configuration.js file.
  2. Set the value of the ALTERNATE_APPROVERS_LOOKUP variable to false.
  3. Save and close the file.
  4. Restart the Integration Agent. 

Modify the workflow definition filters

This integration uses filters defined in the workflow definition (.def) files provided in the integration package. You can use BMC Developer Studio to modify those filters to better suite your environment. See the BMC Remedy documentation for details.

Download resources

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk