WCM Integration with a Change Management System

You can integrate Workload Change Manager (WCM) with a change management system that manages the request tickets for the following actions:

  • Create a Ticket: Creates a ticket automatically after the Web user sends the request, or the Web user creates the ticket from the change management system manually.

  • Change a Ticket State: Changes a ticket state after the Web user or the Control-M Scheduler changes the request state.

  • Show Ticket State: Shows the state of a ticket after a request from the Web user, or the Control-M Scheduler.

To enable the REST API communication between WCM and the change management system, you must implement one of the following:

  • Dedicated REST Server: The REST server exposes the API according to the WCM requests and sends API requests for the change management system to create and update tickets. This integration requires you to create and maintain the REST server.

  • Directly: Some change management systems, such as Service Now, enables you to create and implement new APIs for integration with their external systems. WCM sends API requests directly to the change management system to create and update tickets and the dedicated REST server is not required. This integration requires you to create and implement the WCM API in your change management system.

BMC Software provides an example REST Service for Integrating Remedy with Control-M Workload Change Manager.

Integrating Workload Change Manager with a Change Management System

This procedure describes how to integrate Workload Change Manager with a change management system.

Begin

  1. Prepare the dedicated REST server or the change management system to receive the API endpoints, as described in Workload Change Manager API Endpoints.

  2. Test the API endpoints with Postman or any HTTP connector.

  3. (Optional) Configuring Secure Communication between Control-M Workload Change Manager and a Change Manager System.

  4. Configure Control-M with the new endpoint parameters, as described in Control-M Workload Change Manager System Parameters.

Workload Change Manager API Endpoints

The following table describes the API endpoints that the change management system receives from the Control-M Workload Change Manager:

URL

Response

POST validateChangeState

Responds with one of the following:

  • Automatic Ticket Creation: If the call does not include the changeID, the change management system creates the ticket and returns a 200 code, the new changeID, and a message back to the WCM.

  • Manual Ticket Creation: If the call includes the changeID but does not include oldstate or newstate, the change management system returns a 200 code, the new changeID, and a message to the WCM.

  • Change of State: If the call includes the oldState and newState parameters, the change management system changes the state and returns a 200 code, the changeID, and a message to the WCM.

POST stateChanged

Confirms the state of the ticket.

POST getChangeStatus

Returns the state of the ticket with a 200 code, the changeID, and a message, when the Change Management Status option is enabled, as described in Control-M Workload Change Manager System Parameters.

The following table describes the parameters of the API endpoints:

Parameter

Description

changeID

Defines the ticket ID of the change management system. If a request does not contain a ChangeID, the workload change manager retrieves one and assigns it to the request.

ctmRequestID

Defines the ID of the Workspace that the Web user submits.

Name

Defines the name that the Web user gives to the request.

newState

Defines the new status of the request.

OldState

Defines the old status of the request.

creationTime

Determines the creation time of the request. UTC time in the following format:

YYYYMMDDhhmmssUTC

lastTransferSideTimestamp

Determines the last transfer side timestamp. UTC time in the following format:

YYYMMDDhhmmssUTC

endUser

Defines the Web user that submitted the request.

scheduler

Defines the Control-M Scheduler of the Request.

The following table describes the parameters of the response from the change management system:

Parameter

Description

message

Defines the returned message that appears to the Web user or the Control-M Scheduler.

changeID

Determines the ticket ID of the change management system.

For examples, REST Service API Examples

Configuring Secure Communication between Control-M Workload Change Manager and a Change Manager System

This procedure describes how to configure a secure SSL connection between Control-M Workload Change Manager and an external change management system.

Before you begin

Ensure that the CN field of the SSL certificate for the external change manager contains the host name of the external server.

Begin

  1. From the JRE bin directory of the EM, run the following command to verify that your CA certificate is trusted by BMC Software:

    • Windows: keytool -list -keystore ..\lib\security\cacerts

    • UNIX: ./keytool -list -keystore ../lib/security/cacerts

    The default password of the keystore is changeit unless you are using external Java.

  2. If your CA certificate is not trusted by BMC Software, import your CA certificate from the JRE bin directory of the EM, as follows:

    • Windows: keytool -importcert -file <path to certificate> -keystore ..\lib\security\cacerts -alias <certificate name>

    • UNIX: ./keytool -importcert -file <path to certificate> -keystore ../lib/security/cacerts -alias <certificate name>

REST Service API Examples

The following are examples of API change requests between the WCM and a change management system:

  • In this implementation, WCM sends validateChangeState to the change management system to create or update a ticket:

    • WCM sends this validateChangeState request:

      Copy 
      POST validateChangeState
      ctmRequestID=”Workspace22”
      name=”please review my workspace”
      newState=”Submitted”
      creationTime=” 20211027123500”
      endUser=”James”

    • The change management system sends one of the following:

      • After recording the change request:

        200 HTTP code

        changeID=”request222”

      • If the change management system rejects the change request, it returns the following:

        400 HTTP code

        changeID=”request222”

  • In this implementation, WCM sends validateChangeState to the change management system before creating or updating the change state, and stateChanged afterwards:

    • WCM sends this validateChangeState request:

      Copy 
      POST validateChangeState
      ctmRequestID=”Workspace22”
      name=”please review my workspace”
      newState=”Submitted”
      creationTime=” 20211027123500”
      endUser=”James”

    • The change management system identifies the change request, and returns the following:

      • 200 HTTP code

      • changeID=”request222”

    • WCM sends this stateChanged request:

      Copy 
      POST stateChanged
      changeID=”request222”
      ctmRequestID=”Workspace22”
      name=”please review my workspace”
      newState=”Submitted”
      creationTime=” 20211027123500”
      endUser=”James”

    • The change management system records the change request, and returns the following:

      • 200 HTTP code

      • changeID=”request222”

  • The Web user wants to check the status in the change management system of one of his tickets:

    • The change management system sends this getChangeStatus request:

      Copy 
      POST getChangeStatus
      changeID=”request222”
      ctmRequestID=”Workspace22”
      name=”please review my workspace”
      newState=”Submitted”
      oldState=”Rejected”
      creationTime=” 20211027123500”
      endUser=”James”
      scheduler=”Frank”

    • The change management system records the change request, and returns the following:

      • 200 HTTP code

      • changeID=”request222”

      • message=”The change is approved”

Integrating Remedy with Control-M Workload Change Manager

This procedure describes how to integrate Remedy with Control-M Workload Change Manager through a REST Service. This procedure contains example code which can be modified to fit your specific criteria.

The Remedy example provides two actions:

  • Creates and verifies a Change Ticket ID and verifies the approval of a submitted request.

  • Adds more properties for the different Control-M Workload Change Manager request statuses; such as returned, or rejected.

You can modify and add properties that are relevant to your organization and use the Remedy example as a basis to create your own Rest Service for a different change management system.

Before you begin

Ensure that you have the following installed:

  • Java JDK 1.8

  • Apache MAEVEN build utility

Begin

  1. Navigate to the following directory:

    • Windows:<em_InstallFolder>\WCMRemedyIntegration\src\main\webapp\WEB-INF\classes

    • UNIX: <em_InstallFolder>/WCMRemedyIntegration/src/main/webapp/WEB-INF/classes

  2. Open the RemedyIntegration.properties file to configure the settings of your Remedy properties, as described in Remedy Integration File Properties.

  3. In the same directory, open the NewTicketFields.properties file to configure the field ID values that are used to create a Change Ticket ID. You can modify the values to reflect your Remedy environment values.

    The values of the fields can contain values for the REST Service request such as: Control-M Request ${name} by ${endUser} performed by ${scheduler}.

  4. Navigate to the following directory:

    <em_InstallFolder>/WCMRemedyIntegration

  5. To create a WAR package, type the commands, as follows:

    • Windows:

      • SET JAVA_HOME= your java home path

      • SET M2_HOME= your M2 home path

      • SET PATH=%JAVA_HOME%\bin;%M2_HOME%\bin;%PATH%

      • mvn package

    • UNIX:

      • setenv JAVA_HOME

      • setenv M2_HOME

      • set path = ($JAVA_HOME/bin $M2_HOME/bin $PATH)

      • mvn package

    The MAEVEN build utility creates a WAR and JAR file in the target directory.

  6. Deploy the WAR file to a Web Server. You can use a Control-M/EM Web Server by copying the WAR file into the following directory:

    • Windows:<em_InstallFolder>\emweb\tomcat\webapps

    • UNIX: <em_InstallFolder>/etc/emweb/tomcat/webapps

Remedy Integration File Properties

The following table describes the RemedyIntegration.properties file definitions that are used to configure your Remedy environment settings, which integrates it with Control-M Workload Change Manager:

Property

Description
ServerName Defines the name of your Remedy server.
UserName Defines the username in Remedy.
IsUserPasswordEncrypted

Determines whether the user password is encrypted, as described in Encrypting the User Password.

Valid Values:

  • yes

  • no

Default: no
UserPassword

Defines the password of the Remedy user. If you have created an encrypted password, you can define the password in this property.
CreateForm

Creates a new change management entry in the Remedy form.
ModifyForm

Determines an existing change management entry to modify in the Remedy form.
ChangeIdFieldId

Defines the field ID number that contains the Change Ticket ID in Remedy. If the Change Ticket ID is not defined in the submitted request, it is created automatically and is assigned to the request. If a Change Ticket ID is defined, it is verified in Remedy.

TicketApprovedFieldId

Defines the field ID number that contains the status of the request.

TicketApprovedFieldValue

Defines the field value which determines if the status is approved.

After a request is submitted for approval, the integration process checks if the TicketApprovedFieldId of the change ticket is in the value of TicketApprovedFieldValue. If it is, the request is approved and the status is changed.

Encrypting the User Password

This procedure describes how to encrypt the user password.

Begin

  1. Complete Integrating Remedy with Control-M Workload Change Manager and build the MAEVEN package.

  2. Run the following command:

    java -cp target\WCMRemedyIntegration-9.jar com.bmc.ctmem.wcminteg.changemanagment.AESCrypt abcd1234 /li>

  3. Update the encrypted password in the UserPassword property.

  4. Build the MAEVEN package again.