Amplify Central Connected Gateway Custom API Subscription Flow – CRM Contact Exists Use Case

In prior posts, we were introduced to API subscriptions in the Amplify Central Unified Catalog and we learned about the basics of how Amplify Central supports custom API subscription approval flows. Finally, we put it all together in a very basic custom subscription approval flow using Axway’s Amplify Integration Builder to automatically approved all subscription requests.

Now let’s look at a more complex API Subscription Approval flow that integrates with your business process systems (e.g. CRM) and incorporates the following facets:

• Automatically approve employees and partners via a whitelist
• For non-whitelist users (e.g. prospects and customers), checks if the subscriber exists in your CRM system
  • If the subscriber does exist in the CRM system, the subscription request is approved, a note is added to the CRM contact with the pertinent subscription details, and an email with API credentials is sent to the subscriber by Amplify Central
  • If the subscriber does not exist in the CRM system, informs the API Approval Team via Microsoft Teams and provides all necessary info to add the user to the CRM (so the request will be approved on the next check)
  • The subscription can be manually rejected by the API approver

Again, we will use Axway’s Amplify Integration Builder for our custom subscription approval flow and we’ll use Salesforce Sales Cloud for our CRM!

This data flow is described in the diagram below:

Note that this flow does not leverage the webhooks we discussed in the prior posts. Instead, the Integration Builder flow runs on a cron job (i.e. scheduled trigger) and uses the Amplify Central subscriptions API to check for subscription requests. The discovery agent should be configured for manual subscription approvals as described in Part 1.

As a reminder of an API Subscription process recall that we have an API consumer who discovers an API in the Axway Unified Catalog and in order to use it, subscribes to the API in order to get credentials (e.g. API Key). This is described in the screenshots below:

When the subscription is approved, the user can get an email with credentials as shown below:

You can view the end-to-end process here.

Amplify Central/Discovery Agent Setup

As described above, the Amplify Central discovery agent should be set up for manual approval and sending the email to the subscriber as described in the discovery_agent.yml fragment below:

.
.
.
subscriptions:
  approval:
    mode: manual

  notifications:
    smtp:
      host: email-smtp.us-east-1.amazonaws.com
      port: 587
      username: xxxxxxxxxxxxxx
      password: yyyyyyyyyyyyyy
      authtype: PLAIN
      fromAddress: noreply-demo@axway.com
      subscribe:
        subject: Subscription Notification
        body: |
           Subscription created for Catalog Item:  <a href= ${catalogItemUrl}> ${catalogItemName} </a> <br/>
           ${authtemplate}<br/>
        oauth: Your API is secured using OAuth token. You can obtain your token using grant_type=client_credentials with the following client_id=<b>${clientID}</b> and client_secret=<b>${clientSecret}</b>
        apikeys: Your API is secured using an APIKey credential:header:<b>${keyHeaderName}</b>/value:<b>${key}</b>
      unsubscribe:
        subject: Subscription Removal Notification
        body: |
           Subscription for Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a> has been unsubscribed
      subscribeFailed:
        subject: Subscription Failed Notification
        body: |
             Could not subscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
      unsubscribeFailed:
        subject: Subscription Removal Failed Notification
        body: |
           Could not unsubscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
.
.
.

the discovery_agent.env fragment below:

.
.
.
CENTRAL_SUBSCRIPTIONS_APPROVAL_MODE=manual
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST=email-smtp.us-east-1.amazonaws.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT=587
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME=xxxxxxx
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD=yyyyyyyy
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE=PLAIN
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_FROMADDRESS=noreply-demo@axway.com
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_SUBJECT=Subscription Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_BODY=Subscription created for Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a> <br/>Your API is secured using an APIKey credential: header:<b>${keyHeaderName}</b> / value:<b>${key}</b><br/>${authtemplate}<br/>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_OAUTH=Your API is secured using OAuth token. You can obtain your token using grant_type=client_credentials with the following client_id=<b>${clientID}</b> and client_secret=<b>${clientSecret}</b>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_APIKEYS=Your API is secured using an APIKey credential:header:<b>${keyHeaderName}</b>/value:<b>${key}</b>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBE_SUBJECT=Subscription Removal Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBE_BODY=Subscription for Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a> has been unsubscribed
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBEFAILED_SUBJECT=Subscription Failed Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBEFAILED_BODY=Could not subscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBEFAILED_SUBJECT=Subscription Removal Failed Notification
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBEFAILED_BODY=Could not unsubscribe to Catalog Item: <a href= ${catalogItemUrl}> ${catalogItemName} </a>
.
.
.

Integration Builder Flow

The Integration Builder flow is shown below:

Before we go into the flow description, let’s look at the Flow Instance below:

The variables are:

• crm – this is a connector instance variable for your CRM instance. In this example, I am using Salesforce
• msTeamsWebhookURL – this is a variable that contains the Webhook for your MS Teams channel that messages should be sent to
• cron – a cron quartz expression that defines the frequency that our flow will run on (e.g. every 30 minutes)
• 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
• orgId – The ID of your Amplify Platform Organization
• whitelist – an array of domains that will get automatic approval. In the screenshot above, the whitelist contains one domain, axway.com. This means that any Axway employee with the xxxx@axway.com email address can subscribe and be automatically approved
• axwayClientId and axwayClientSecret – client Id and secret for a Central service account. This was described in Part 2

Retrieve clientId and clientSecret

If you don’t already have a service account and clientId and clientSecret, follow the instructions below.

We will make the following CLI commands in order to:

• Authenticate with the Amplify platform using your platform credentials
• Create a service account in the platform for API access (this will get you the clientId and clientSecret)

Note that you will need jq installed on your environment for the authentication curl command shown below

Enter your Organization ID (e.g. 100000142) and the serviceAccountName (e.g. catalog-integration) in the CLI command below and execute the following two commands manually. This is a one-time activity to create a service account and retrieve the clientId and clientSecret.

axway auth logout --all

axway auth login

ORG_ID=100000142 && TOKEN=$(axway auth list --json | jq -r ".[] | select( .org.id == $ORG_ID ) | .auth.tokens.access_token") && curl -vv 'https://apicentral.axway.com/api/v1/serviceAccounts' --header "Authorization: Bearer ${TOKEN}" --header "X-Axway-Tenant-Id: ${ORG_ID}" --header 'Content-Type: application/json' --data-raw '{
  "serviceAccountType": "DOSA",
  "serviceAccountName": "catalog-integration",
  "clientAuthType": "SECRET"
}'

Flow Description

• The first few steps: prepAxwayAccessTokenRequest, getAxwayAccessToken, and defineGlobals retrieve the access_token and define URLs and Headers for subsequent Amplify API calls
• The next two steps, prepareGetRequestedSubscriptions and getRequestedSubscriptions retrieve all subscription requests that are in the REQUESTED state using the https://apicentral.axway.com/api/unifiedCatalog/v1/subscriptions?query=state==REQUESTED API call
• Then we enter a loop for each subscription
  • The next two steps: prepareGetCatalogItem and getCatalogItem retrieve the details for the API that the subscriber is trying to subscribe to using the https://apicentral.axway.com/api/unifiedCatalog/v1/catalogItems/{{catalogItemId}} API call
  • The next two steps: prepareGetUser and getUser retrieve the subscriber details using the https://platform.axway.com/api/v1/user/{{userId}} API call
  • The next two steps: prepareGetCRMUser and getCRMUser look to see if the subscriber is also a contact in the CRM system using the Salesforce connector resource: /contacts?where=Email={{susbcriberEmail}}
  • The flow then checks to see if the subscriber is in the whitelist OR exists as a contact in the CRM
    • In this example, the whitelist is simply an array of domains stored as a variable in the Integration Builder flow instance. In a production environment, the whitelist will most likely be stored in a database or other application.
  • If either is true then the flow continues along the left leg and performs the following in order to approve the subscription:
    • The next two steps: prepareUpdateSubscriptionRequest and updateSubscriptionRequest approve the subscription request using the https://apicentral.axway.com/api/unifiedCatalog/v1/catalogItems/{{catalogItemId}}/subscriptions/{{subscriptionId}}/states API call with an approval payload in the body
    • The next step, contactExists makes sure the contact exists in the CRM, if so, continue
    • The next two steps: prepareAddCRMUserNote and addCRMUserNote add a note to the contact in the CRM system using the Salesforce connector resource: /contacts/{{contactId}}/notes with the note contents in the body. A sample is shown below:

• • If both are false then the flow continues along the right leg and sends a message to MS Teams. A sample is shown below:

You can download the flow here.

Summary

In this API Subscription Flow example, we saw how Integration Builder, with its CRM connectors, enables a robust subscription flow that integrates with your CRM-based business processes for customers and prospects and also enables you to handle employee and partner subscription requests.