In the previous exercise you used the SAP API Business Hub to explore and use the Workflow API. With the confidence gained in those steps, it's now time to make similar calls, to create a new workflow instance, from a 3rd party API client - Postman.
Postman is a very capable HTTP client with many features. In this exercise you'll use some of them, specifically environments and variables, and make use of the built-in support for OAuth 2.0.
Using these features, you can achieve a semi-automated mechanism for creating new instances of your "orderprocess" workflow definition.
After completing these steps you'll know how to instantiate new workflows from Postman (and, by inference, from other API clients and tools). You'll also have a closer feel to what's going on behind the scenes in the SAP API Business Hub with respect to authentication.
The API call you made in a previous exercise has been encapsulated into a small Postman collection that you can import and use.
👉 Launch Postman and get ready to import a collection using the "Import From Link" feature in this dialog box that you get when you select the "Import" button at the top left of the Postman UI:
👉 In the dialog, specify the URL to this workflowcollection.json resource, and use the "Import" button to complete the process.
Postman offers the facility to manage collections of settings that pertain to different contexts, for example you might have a couple of development contexts and system endpoints, and a production context. These are called "environments" in Postman and in this step you will create one to store the details of your specific SAP Cloud Platform trial account context.
Within environments you can use variables, and the environment-specific values for these are substituted at runtime.
Environments are also separate by design from requests and collections, so that you can share the latter without compromising security by sharing values in the former.
👉 Examine how these variables are used, by expanding the hierarchy of the "Workflow Collection" to reveal and select the POST request "Create new workflow instance", and looking at how the URL of that request is defined.
You should see something like this:
👉 Notice the use of the {{endpoints.workflow_rest_url}} variable in the URL, and the fact also that currently, indicated in the top right of the Postman UI, there is "No Environment" set.
So at this point the request in its skeleton form is ready but you need to supply a value for the root of the URL, and also Postman needs to know how -- or more specifically with what credentials -- to request an OAuth token. It's a good idea to configure this in an environment, which is sort of the equivalent of the API Hub environment you configured in the previous exercise.
👉 First, use the "Manage Environments" button (the cog) in the top right to open up a dialog where you can add an environment. In the form that appears, specify "My Workflow Environment" for the name.
👉 Next, add each of the four properties from the service key data we came across in the previous exercise, as variables in this new environment:
endpoints.workflow_rest_urluaa.clientiduaa.clientsecretuaa.url
You should end up with something like this:
The property names in Postman environments are arbitrary, but it makes sense to use names that mean something to us.
Once you've finished adding this new environment, you should select it for use.
👉 Select the new environment from the drop-down selection that you saw earlier (it was set to "No Environment" at that time). Then notice that the {{endpoints.workflow_rest_url}} variable in the request URL has turned from red, indicating the variable wasn't defined, to a slightly more orange color, and when you hover over it the value is displayed:
The Cloud Foundry (CF) Workflow APIs are protected with OAuth 2.0, and the API Hub handles that for us, specifically using the "Client Credentials" flow. In order to make the call in Postman, using the same authentication approach, we need to take the variable values we specified in our environment and use them in Postman's OAuth 2.0 configuration for retrieving an access token, which is what's requested and used in such a flow.
👉 Switch to the "Authorization" tab of the request and, for the type, ensure that "OAuth 2.0" is selected. This should give you the possibility of setting things up for requesting and using OAuth 2.0 access tokens as employed in the OAuth flow we want to use:
👉 Now use the "Get New Access Token" button to specify details for, and request, an access token. In the dialog box that appears, give a name such as "MyToken", select "Client Credentials" for the grant type, "Send as Basic Auth header" for the client authentication, and specify the values for "Access Token URL", "Client ID" and "Client Secret" using the environment variables you defined earlier. Make sure to add /oauth/token as a suffix to the access token URL:
You may see encoding warnings for the values in the Client ID and Client Secret fields - we can ignore those for the purposes of what we're doing here.
👉 Use the "Request Token" button which will make the OAuth 2.0 call to request an access token, which, if all goes well, will be shown to you and subsequently be available via the "MyToken" name you gave it.
If you're curious to see what actually happened in this request, you can use Postman's console (View -> Show Postman Console) to inspect the HTTP traffic for this access token request call.
👉 Now you need to tell Postman to use this token. Either select the "Use Token" button that's available in the current token dialog, or -- after closing this dialog to get back to the Authorization tab -- or select the token using the "Available Tokens" selection, so that the "Access Token" parameter is filled in, something like this:
In this step you'll take a final look at the request before submitting it.
👉 Switch to the Headers tab now, where you should see an Authorization header with the access token as the value, preceded with the word "Bearer". This is Postman using the access token (that you retrieved just before) to authenticate the actual API call.
👉 Now look at the "Body" tab and you should see something that looks familiar - a request body similar to the one you specified in Exercise 06 when you created a new workflow instance:
{
"definitionId" : "orderprocess",
"context": {
"request": {
"Id": "HT-1003",
"Quantity": 25
}
}
}Now it's finally time to send the request to create a new workflow instance.
👉 Send the request with the "Send" button and examine the response.
If all goes well, you should see something in the response body - similar to what you saw in the response body in the previous exercise when you created a new workflow instance. Note too that the HTTP status code is, as expected, 201.
Great! This is only a very short step, but an important one - it shows that you've set everything up correctly to authenticate with OAuth "Client Credentials" flow.
As a final step in this exercise, you should check the newly created instance in your Fiori launchpad.
👉 Open up your Fiori launchpad and select the "Monitor Workflows - Workflow Instances" app. Make sure that the filter in the master list includes the status "Completed". You should see the instance you have created via Postman - you can identify it by the fact that product with ID "HT-1003" (rather than "HT-1002" or "HT-1001") has been requested.
Nice work!
You've now got a Postman environment set up, with a simple request that can be conveniently run to create new workflow instances. Moreover, you have a better feel for how these requests are authenticated.
-
What's the difference between the "Initial Value" and "Current Value" columns in environment variable definitions?
-
What other HTTP client tools might you have in mind to use instead of (or in addition to) Postman?
-
How often do you think you'll need to fetch a new access token?