Webhooks

BMC Compuware Web Products communicate with BMC Compuware mainframe products, such as ISPW and Abend-AID , by issuing requests and receiving responses to those requests.

BMC Compuware Enterprise Services Webhooks

A webhook allows third-party applications, such as Slack™, to receive notifications when an action has occurred in a BMC Compuware mainframe product. For example, a notification could be sent to Jenkins™ to kick off a build whenever a Promotion occurred in ISPW.

When accessing the Webhooks page in CES, a list of configured webhooks are displayed which show the user-defined name of the webhook, the URL to where the response will be forwarded, and the type of HTTP method that will be used when forwarding the response.

The list of webhooks can be filtered by clicking the filter icon above the list and entering the filter criteria. For example, to filter the list to all POST methods you would click the filter icon and type “POST” (without quotes). If you wanted to further filter the list to all POST methods being sent to a URL containing the domain test.com, you would type “POST test.com” (without quotes) into the filter.

The number of webhooks displayed in the list at a given time can be changed by selecting a different value in the option field below the list. The default is 25 entries per page but can be changed to 10, 25, 50, 100, 500, or all.

If you have management rights then you can also add, edit, and remove webhooks.

To add a webhook

1. Click Add below the list of webhooks. The Webhook Information page appears.

2. Configure a webhook by completing the following fields:

   • Webhook enabled: Toggle On or Off. This specifies whether the webhook is enabled. If it is not enabled then the request to the BMC Compuware mainframe product will not be sent and thus no responses will be received. If the webhook was previously enabled, disabling it will tell the BMC Compuware mainframe product to stop sending any future responses.
   • Name: This is a user-defined name for the webhook so that the webhook is easier to identify when viewing the list of webhooks.
   • URL: This is the URL location where the BMC Compuware mainframe product responses will be sent. For information about the values that can be substituted in the variables, see Variable Substitution.

   Warning

   Important

   The URL entered must begin with http:// or https://.

   • Request method: This is the HTTP method used when the response from a BMC Compuware mainframe product is forwarded to the specified URL. The following methods are available for selection: DELETE, GET, POST, and PUT. If the third-party application follows common conventions, then DELETE will delete a resource, GET will retrieve a resource, POST will create a resource, and PUT will edit or modify, a resource. For example, to create a new item in a third-party application when the response was received, choose the POST option.
   • Request headers: This allows you to define any HTTP headers that need to be sent along with the response to the third-party application. For example, to provide authentication information to a third-party application, click Add Header. In the Header name field type Authorization and in the Header value field type your credential information, such as Basic dXNlcjpwYXNzd29yZA==ik.
   • Request body: This specifies the information that will be sent in the body of the HTTP request to the third-party application. This is a free-form field where any text can be entered, so you can enter JSON, XML, or whatever format is required by the third-party application. For information about the values that can be substituted in the variables, see Variable Substitution.
   • Product: This specifies which BMC Compuware mainframe product is going to receive the request.
   • Expire in days: If you select Abend-AID from the Product list, specify the number of days after which you want the Abend-AID webhook to expire and get automatically deleted. You must specify a value between 0 to 365 days.
   • Event Criteria: The Event Criteria fields are product-specific and dynamically change based on the mainframe product selected.
     • For ISPW, the following fields are used:
       
       • Applications: The names of the applications of an ISPW resource. Each application name must not exceed eight characters with each name separated by a comma.
       • Sub Applications: The names of the subapplications of an ISPW resource. Each subapplication name must not exceed eight characters with each name separated by a comma. If the Sub Application field is left blank when creating or updating webhooks, the default value of Sub Application will be same as Application.
       • Levels: The current levels of an ISPW resource. Each level must not exceed four characters with each level separated by a comma.
       • Event names: The current names of events associated with an ISPW resource. Each event name must be separated by a comma.
       • Operations: The operations for which you want responses. For example, if you want to receive responses when a Deploy or Promote occurs, then you would select Deploy and Promote.
     • For Abend-AID , the following fields are used:
       
       • Program Names: This field contains the name of the abending program associated with an Abend-AID  resource. Each program name must be separated by a comma.
       • User IDs: This field contains the user ID of the abending job associated with an Abend-AID  resource. Each user ID must be separated by a comma. 
       • Abend Codes: This field contains the system or user abnormal termination code, or "SNAP" for a SNAP-AID report, or the PL/I on-code associated with an Abend-AID  resource. Each abend code must be separated by a comma.
       • Job Names: This field contains the job name of the abending job associated with an Abend-AID  resource. Each job name must be separated by a comma.

       • CICS or IMS Regions: This field contains the SYSID of the abending job associated with an Abend-AID  resource. Each region must be separated by a comma.

         Warning

         Important

         You can mask the Event Criteria with asterisks in the fields. For example, Program name: PGM***

         If you enter a single * in the field, that field will be ignored from the criteria list.

3. After configuring the webhook, click OK to submit the request to the selected mainframe product, if the webhook is enabled. The webhook will then appear in the list of webhooks.

To edit a webhook

1. From the Webhook Information page, select a webhook from the list and click Edit. The Webhook Information page appears. The fields will be populated with the values for that webhook.
2. Edit the fields as needed.
3. Click OK to submit the request to the selected mainframe product.

To remove a webhook

1. Select one or more webhooks from the list.
2. Click Remove. The webhook is removed from the list of webhooks and the request is removed from the associated mainframe products.

Variable substitution

Variable substitution is allowed in the URL, request headers, and request body fields. A string enclosed with $$ will be replaced with an associated value. For example, if the mainframe product supplied an ID when a notification was sent, the ID could be dynamically added to the URL by placing a variable in the URL as follows:

http://sample.com/endpoint/$$ID$$

If the ID that was sent was 123-456-789 then the URL would end up looking as follows:

http://sample.com/endpoint/123-456-789

ISPW variables

The following variables are available for substituting values from ISPW:

Variable	Description
$$application$$	The names of the applications in ISPW.
$$subApplication$$	The names of the subapplications in ISPW.
$$assignment$$	The assignment ID to which the task belongs.
$$deployDate$$	The date the resource was deployed in ISPW.
$$deployTime$$	The time the resource was deployed in ISPW.
$$event$$	The event names associated with an ISPW resource.
$$level$$	The current level of an ISPW resource.
$$message$$	A message about the operation that was performed in ISPW.
$$notificationID$$	The ID associated with the notification in ISPW.
$$operation$$	The operations to be performed in ISPW.
$$owner$$	The owner of the resource in ISPW.
$$release$$	The release of ISPW.
$$setID$$	The ID of the set in ISPW.
$$startDate$$	The date the operation was started.
$$startTime$$	The time the operation was started.
$$stream$$	The stream in ISPW.

Abend-AID variables

The following variables are available for substituting values from Abend-AID :

Variable	Description
$$pgName$$	The names of the abending program in Abend-AID .
$$loadMon$$	The name of the load module in Abend-AID .
$$userId$$	The user ID of the abending job in Abend-AID .
$$compDat$$	The compile date of the program being processed in Abend-AID .
$$abndDate$$	The date of the abend dump in Abend-AID .
$$abndTime$$	The time of the abend dump in Abend-AID .
$$abndCode$$	The system or user abnormal termination code in Abend-AID .
$$jobname$$	The name of the abending job in Abend-AID .
$$jobNum$$	The JESID or job number in Abend-AID .
$$region$$	The SYSID of the abending job in Abend-AID .
$$dup$$	This is a duplicate dump and was suppressed during processing in Abend-AID .
$$tran$$	The transaction identifier for the abending transaction in Abend-AID .
$$term$$	The four-character identification number for the terminal at which the abend occurred in Abend-AID .
$$url$$	The URL and PORT number location of the Abend-AID viewer in Abend-AID .
$$notificationId$$	The ID associated with the notification in Abend-AID .

Webhook example

As a company practicing DevOps, you are using BMC Compuware Web Products, BMC Compuware ISPW, and Slack™. You want a notification sent to Slack™ whenever a promote occurs in ISPW. To achieve this, you would create a webhook in BMC Compuware Web Products with the following configuration options:

• Webhook enabled: On
• Name: ISPW Promote Slack Notification
• URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
• Request method: POST
• Request headers: Content-type application/json
• Request body: { “text” : “A promote occurred in ISPW” }
• Product: ISPW
• Event Type: Promote

The “Event Criteria” was left empty so as not to filter the responses to a specific application, level, or event name. As a result, you will receive a message in Slack™ for all promotes that occur in ISPW.

Webhook example with variable substitution

As a company practicing DevOps, you are using BMC Compuware Web Products, BMC Compuware ISPW, and Slack™. You want a notification sent to Slack™ whenever a promote occurs in ISPW. To achieve this, you would create a webhook in BMC Compuware Web Products with the following configuration options:

• Webhook enabled: On
• Name: ISPW Promote Slack Notification
• URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
• Request method: POST
• Request headers: Content-type application/json
• Request body: {"text" : "A promote occurred in ISPW for set: $$setID$$ at level: $$level$$ with a status of: $$eventNames$$"}
• Product: ISPW
• Event Type: Promote

The URL would receive a POST request with the following JSON body looking as follows:

{
 "text" : "A promote occurred in ISPW for set: S000000021 at level: DEV1 with a status of: success"
 }

The “Event Criteria” was left empty so as not to filter the responses to a specific application, level, or event name. As a result, you will receive a message in Slack™ for all promotes that occur in ISPW.