In a prior post, we looked at an API Subscription Approval flow that integrates with your CRM for a business process-based approval mechanism for API subscribers.
In this post, we will look at an API Subscription Approval flow that integrates with your incident management system for an IT-centered API subscription approval process. Again, we’ll use Axway’s Integration Builder to implement the subscription approval flows and Jira for incident management but the principles apply to other incident management applications, such as ServiceNow.
We will actually have two Integration Builder flows, one will be triggered by a subscription event webhook from Amplify Central (e.g. when a new API subscription request is initiated) and the other will be triggered by events in Jira and update the API subscription and add a comment to the incident.
The approval or rejection is handled in the Jira incident itself when an IT stakeholder sets the custom approval field, adds a comment, and closes the incident.
The process is described as follows:
- An API consumer subscribes to an API that initiates a webhook that triggers the first of our two approval flows in Integration Builder
- The first Integration Builder flow will create a new incident in Jira and populate custom fields to contain the Catalog Item ID and Subscription ID for our subscription request since this information will be needed later in order to update our subscription request (via API call)
- This flow will also send a message to Microsoft Teams to let the stakeholders know that a new request is pending
- When the incident is closed and approved/rejected a second Integration Builder flow will detect this event and update the subscription request
- This second flow will also add a comment to the incident once the subscription is updated
This data flow is described in the diagram below:
You can view the end-to-end process here.
Amplify Central/Discovery Agent Setup
As described above and in a prior post, the Amplify Central discovery agent should be set up for webhook approval and sending the email to the subscriber as described in the discovery_agent.yml fragment below:
.
.
.
subscriptions:
approval:
mode: webhook
webhook:
url: https://staging.cloud-elements.com/elements/api-v2/formulas/instances/4.....3/executions
headers:
Header=Authorization,Value=User IPJ.......NW4=, Organization 79......c2a05
notifications:
webhook:
smtp:
host: email-smtp.us-east-1.amazonaws.com
port: 587
.
.
.or the da_env_vars.env fragment below:
. . . CENTRAL_SUBSCRIPTIONS_APPROVAL_MODE=webhook CENTRAL_SUBSCRIPTIONS_APPROVAL_WEBHOOK_URL=https://staging.cloud-elements.com/elements/api-v2/formulas/instances/463433/executions CENTRAL_SUBSCRIPTIONS_APPROVAL_WEBHOOK_HEADERS=Header=Authorization,Value=User IPJ.......NW4=, Organization 79......c2a05 CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=email-smtp.us-east-1.amazonaws.com CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587 . . .
Jira Custom Fields
There are several custom fields that should be added to your Jira instance in order to support this approval flow use case. We need to store the Catalog Item ID and Subscription ID for our subscription request in order to update our subscription request later via API call. I created two custom fields for these: CatalogItemId and SubscriptionId.
I also added two additional custom fields: Approve/Reject which is a picklist to select Approve or Reject for our request, the other is Approve/Reject Comment to store a comment related to the approval. These are shown below:
To summarize, I added four custom fields to Jira:
- CatalogItemId
- SubscriptionId
- Approve/Reject
- Approve/Reject Comment
Refer to the Jira documentation for instructions on how to add and configure custom fields.
Even though we created custom fields with certain names (CatalogItemId, SubscriptionId, …), Jira represents these as customfield_xxxxx internally and in API calls and responses. In the subscription flows, we will need to retrieve a list of all fields and then determine what customfield_xxxxx corresponds to the custom field names provided when we created the custom field. This will make more sense when we review the flows below.
Integration Builder Flow 1
The first flow is a manually triggered Integration Builder flow that is responsible for responding to the Amplify Central subscription webhook call and will create a Jira Incident when a subscription request is detected. The flow is shown below:
Flow Instance
The flow instance is shown below:
The variables are described below:
- jira – this is a connector instance variable for your Jira instance
- apiCentralUrl – the URL for Central API calls. If you are using the default environment (https://apicentral.axway.com), then you can leave this blank. If you are unsure, then please leave this blank
- axwayClientId and axwayClientSecret – client Id and secret for a Central service account. This was described in a prior post
- catalogItemIdJiraCustomFieldName – Name of the Jira custom field created to store the Catalog Item Id related to the subscription request
- jiraBaseAddress – the base address of your Jira instance
- JiraProjectKey – the project key for the Jira project to post incidents to
- msTeamsWebhookURL – this is a variable that contains the webhook for your MS Teams channel that messages should be sent to
- subscriptionIdJiraCustomFieldName – Name of the Jira custom field created to store the Catalog Item Id related to the subscription request
Flow Description
- defineUtils – defines a method that helps determine the custom field name associated with the Jira custom fields described above
- shouldProcess – determines if the flow should execute. The flow should only execute if the subscription event type is “SubscriptionUpdatedEvent” and its state is “REQUESTED“
- prepAxwayAccessTokenRequest and getAxwayAccessToken – a pair of steps to retrieve an access token based on the clientId and clientSecret as described in prior posts
- defineGlobals – defines the Amplify Central API base address and headers for subsequent Central API calls
- prepareGetCatalogItem and getCatalogItem – a pair of steps to retrieve the catalog item (the API) related to the subscription request
- getUser – retrieves the use details (name and email address) for the user that made the subscription request
- getFieldNames – retrieves the field names for your Jira instance
- prepareCreateIncident and createIncident – a pair of steps to create a Jira incident
- prepareSendToTeams and sendToTeams – a pair of steps to post a message to MS Teams notifying the stakeholders that a user subscribed to an API and a link to the Jira incident
An example of the MS Team message is shown below:
The flow can be downloaded from here.
Integration Builder Flow 2
The second flow is a (Jira) connector event-triggered Integration Builder flow that is responsible for responding to Jira events (e.g. incident closed). The flow is shown below:
Flow Instance
The flow instance is shown below:
The variables are described below:
- jira – this is a connector instance variable for your Jira instance
- apiCentralUrl – the URL for Central API calls. If you are using the default environment (https://apicentral.axway.com), or are unsure, then you can leave this blank
- approveRejectCommentJiraCustomFieldName – Name of the Jira custom field created to add a comment to the subscription request approval/rejection
- approveRejectJiraCustomFieldApproveValue – Value of the approveRejectJiraCustomFieldName for “Approve”
- approveRejectJiraCustomFieldName – Name of the Jira custom field created to let the user select “Approve” or “Reject” for the state of the approval
- approveRejectJiraCustomFieldRejectValue – Value of the approveRejectJiraCustomFieldName for “Reject”
- axwayClientId and axwayClientSecret – client Id and client secret for an Amplify Central service account. This was described in a prior post
- catalogItemIdJiraCustomFieldName – Name of the Jira custom field created to store the Catalog Item Id related to the subscription request
- JiraProjectKey – the project key for the Jira project that contains the subscription approvals
- subscriptionIdJiraCustomFieldName – Name of the Jira custom field created to store the Catalog Item Id related to the subscription request
Flow Description
- defineUtils – defines a method that helps determine the custom field name associated with the Jira custom fields described above
- getFieldNames – retrieves the field names for your Jira instance
- shouldProcess – determines if the flow should execute. The flow should only execute if the event is related to the correct Jira project AND the incident is closed (state = Done) AND the Approve/Reject field has been set to “Approve” or “Reject” (i.e. not left empty)
- prepAxwayAccessTokenRequest and getAxwayAccessToken – a pair of steps to retrieve an access token based on the clientId and clientSecret as described in prior posts
- defineGlobals – defines the Amplify Central API base address and headers for subsequent Central API calls
- prepareCheckSubscriptionStillExists and checkSubscriptionStillExists – a pair of steps to check if the subscription still exists
- shouldUpdateSubscription determines if the subscription is still in the “REQUESTED” state (since someone could have manually approved or rejected it)
- prepareUpdateSubscriptionRequest and updateSubscriptionRequest – a pair of steps to update the subscription (to Approved or Rejected)
- prepareAddCommentToIncident and addCommentToIncident – a pair of steps to add a comment to the Jira incident that the subscription has been updated
The flow can be downloaded from here.
Summary
In this Amplify Central API Subscription Approval Flow example, we saw how Integration Builder, with its Helpdesk connectors, enables a robust subscription flow that integrates with your IT-based processes.
Learn more about Amplify Central.