Help
Webhooks
Compuware Web Products communicate with Compuware mainframe products, such as ISPW, by issuing requests and receiving responses to those requests. For example, a Deploy request can be made through Compuware Web Products to an instance of ISPW running on a mainframe. That instance of ISPW will return a response to that request, at a future time, indicating the success or failure of the Deploy action. As part of a DevOps environment, you might be interested in having a third-party application notified when ISPW actions have occurred from either Compuware Web Products or any other source. This type of integration can be achieved through the use of webhooks.
Compuware Enterprise Services Webhooks
A webhook allows third-party applications, such as Slack™, to receive notifications when an action has occurred in a Compuware mainframe product. For instance, a notification could be sent to Jenkins™ to kick off a build whenever a Promotion occurred in ISPW.
When accessing the Webhooks page in Compuware Enterprise Services, 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.
ISPW must be configured to push notifications to your CES installation. The CES installation that ISPW will use can be configured in the CMSC.
ISPW does not persist notifications across restarts. Therefore, CES must be running before ISPW starts in order for ISPW to register any older webhooks previously created in CES.
To add a webhook
Click Add below the list of webhooks. The Webhook Information page appears.
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 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 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 Compuware mainframe product responses will be sent.
The URL entered must begin with http:// or https://.
Request method: This is the HTTP method used when the response from a 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.
Product: This specifies which Compuware mainframe product is going to receive the request.
Product specific fields: The remaining fields are specific to the Compuware mainframe product selected, and will dynamically change based upon that selection. For ISPW, the following fields are used:
- Applications: The names of the applications of an ISPW resource. Each application name must not exceed four characters with each name separated by a comma.
- 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.
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 like this:
http://sample.com/endpoint/$$ID$$
If the ID that was sent was 123-456-789 then the URL would end up looking like this:
http://sample.com/endpoint/123-456-789
The following variables are available for substituting values from ISPW:
- $$application$$ (The names of the applications 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)
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
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.
Edit the fields as needed.
Click OK to submit the request to the selected mainframe product.
To remove a webhook
Select one or more webhooks from the list.
Click Remove. The webhook is removed from the list of webhooks and the request is removed from the associated mainframe products.
Webhook Example
As a company practicing DevOps, you are using Compuware Web Products, 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 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 Compuware Web Products, 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 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 like this:
{
"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.