Creating an API flow to create SAP OData resources

Learn to create an API flow in IBM® App Connect that creates OData resources in SAP and completes actions on other applications.

Before you begin

Find or create what you need for this tutorial.

Get the name and password of your Salesforce account. To create a free test account in Salesforce instead of using your business account, register for a Developer account from https://developer.salesforce.com. If you connect to App Connect with a Trial account, the Salesforce events don't work.
Connect App Connect to SAP by using OData, as described in How to use IBM App Connect with SAP (via OData).
Get the email address and password of your Asana account.

About this task

This tutorial creates an API for the following scenario. A travel agency is moving to a more responsive, self-service business model. The agency wants to provide a mobile or web application that their clients can use to make their own travel arrangements. As part of the application capabilities, clients can subscribe to flight details in an SAP backend system so that when flight details are changed, clients are notified through the application.

Mobile app use for flight subscription. — Figure 1. Subscribing to flight details in a mobile application.

Rather than implement the subscription in the application, the agency wants the application to use an API that is provided by App Connect that uses OData to create subscriptions in SAP. Also, when a user chooses to subscribe to a flight, App Connect must add the user details as a contact in Salesforce. The marketing and sales teams can then automatically get accurate contact information and other details for use throughout the sales cycle.

When a web/mobile app calls an API, App Connect creates a subscription in SAP and creates a contact in Salesforce. — Figure 2. When a web or mobile application calls an API, App Connect creates a subscription in SAP and creates a contact in Salesforce.

An integration developer configures an API flow in App Connect to create a flight subscription in SAP and create a contact record in Salesforce. The developer doesn't need any experience with SAP, and just needs to get SAP OData configuration details from the SAP administrator. The developer creates and publishes the API. The API call details can then be provided to the application developer to use in the application.

Procedure

You can create your flow either by importing the sample flow document from GitHub, or by creating your flow from scratch.

To use the sample flow, download the Flight Subscription API YAML file from the GitHub sample repository and import it into App Connect. After you import the flow, validate each node in the flow and select the application accounts that you want to use. For more information, see Importing a flow.

To create the flow from scratch, complete the following steps.

On the App Connect Designerdashboard, click Create > Flows for an API.
Enter a name for your model that reflects the type of object for your API to work with, then click Create model.
For example, FlightSubscription.
Add properties that define the structure of the object for your API.
Either type in the name of a property or click Select properties from applications to choose properties from one or more of the applications that you're connected to.
1. To create a subscription, add the property deliveryAddress from SAP SubscriptionCollection.
  1. Click Select properties from applications.
  2. Expand SubscriptionCollection, then select deliveryAddress.
  3. Click Add properties.
2. To create a Salesforce contact, add properties called CustomerID, FirstName, LastName, and EmailAddress (or select the equivalent properties from Salesforce Contact).
  - For LastName, select Required because the application that uses the API must supply a value to create a Salesforce contact.
  - For CustomerID, select ID to specify that the flow must return this property to the application that uses the API. The ID property isn't marked as required. The Salesforce Create contact action that is used in the API flow automatically generates the ID value when the API calls it.
  Figure 3. Creating properties of an API to create a flight subscription in SAP and a contact in Salesforce.
Click Operations to define the actions that the API completes on objects.
In this case, select Create FlightSubscription.
Click Implement flow to create a flow that defines how the operation works.
You see a basic flow in the flow editor, with a request, a response, and a space to add one or more target applications. If you select the Request in the flow, you can see an example of the structure of the request, which is constructed from the properties in your model, with some sample data.
Figure 4. Viewing an example request body structure and content for an API request node.
Add the target applications to the flow between the request and response.
Map the fields from the request into the target applications. This example uses SAP Create SubscriptionCollection and Salesforce Create Contact actions.
1. Click Add node (+), then select SAP Create SubscriptionCollection.
2. Set the DeliveryAddress to the deliveryAddress value from the request. (You can start typing de to be prompted with the request property.)
3. In Collection, type FlightCollection to represent the SAP object to subscribe to.
4. In Select, type *. This value returns the FlightCollection content in the payload of the notification that is sent to the application that uses the API.
  Figure 5. Configuring the SAP Create SubscriptionCollection node to create a flight subscription.
5. Click Add node (+), then select Salesforce Create Contact.
6. Populate the Salesforce Last name, First name, and Email fields with corresponding request fields.
7. In the Contact Description, add the Sub. ID field from the SAP Create SubscriptionCollectionaction. You can type Created for SAP subscription [Sub. ID], where [Sub. ID] is the field that is selected from SAP.
  Figure 6. Salesforce Create Contact node.
Click the Response in the flow to define the response to return when the operation completes successfully.
Set the CustomerID to the Salesforce Contact ID. (When you're creating an object, typically only the ID from the target application is returned in the response message.)
Figure 7. Configuring the API Response node.
Click Done to return to your model.
Give the API flow a name, such as Flight Subscription API.
This name is useful so that you can identify the API on the App Connect dashboard.
To test the API model and operation, start the API by clicking Start API.

Results

On the App Connect Designer dashboard, flows for APIs have an API icon. You can start and stop them in the same way as any other flow to test them. You can open an API while it is running, but you must stop it before you can edit it. To provide your API to applications, you must deploy the API flow.

What to do next

To test your API, click the Manage tab, then use the URL, username, and password with your preferred technique to call API operations. For example, you can use the Linux® command line and cURL or the HttpRequester add-on for Firefox.

The integration developer can provide the API URL and request details to the application developer for the application to use. However, you can take advantage of powerful features by publishing the API to an API management tool like IBM API Connect. The following steps describe how to manage your API by importing it into API Connect.

From the menu of the API tile on the dashboard, select Open API.
From the Manage tab, download your API document, which you can import into your API management tool. The URL, username, and password that your API management tool needs are provided. If you don't have a subscription for API Connect, you can click Manage API with IBM API Connect to obtain a subscription.
Click Download API to download your API document, then save the swagger.json file.
Copy the values for the URL, username, and password.
In API Connect, complete the steps to add the API.
1. Click 01 Import API, then Import API from a file or URL, then Import from file.
2. Select the swagger.json file that you downloaded for the API, then click Import. A new REST API definition is created that includes Paths and HTTP operations. (You can edit your API definition in the same way as any other REST API definition.)
3. Click 02 Generate and Publish, then Generate a default product. The New Product pane provides details of the product, and the catalog to be used to publish the API.
4. Click Create product. You see the following success message.
```
Success   Swagger flightsubscription product (version 0.0.1) has been published to Sandbox
```
5. Click 03 Explore.
6. Click Drafts or Sandbox to explore further. For example, in Sandbox, you can see the API Swagger flightsubscription 0.0.1.
7. Click 04 Test to test the POST operation to create a new subscription.
8. In the navigation pane, click Drafts.
9. On the APIs tab, click Swagger flightsubscription.
10. On the Assemble tab, if no assembly exists, add an Invoke policy to call the URL of the API in App Connect.
11. Click Test, then select the Sandbox catalog.
12. Click Republish product, select the post /flightsubscription operation to call.
13. For authorization, specify the username and password values from the API in App Connect.
14. In the Model instance data, specify JSON data that is appropriate for a new subscription, as shown in the following example.
```
{
"FirstName": "TestB",
"LastName": "SAPnameb",
"Email_Address": "testb.sapname@email.com",
"deliveryAddress": "http://host:port/GWC/SUPNotification/ApplicationConnectionId/SAPnameb/Application/Domain"
}
```
  The CustomerID is not specified because it is generated by Salesforce.
15. Click Invoke. If the test is successful, you see a 200 OK success response.
```
Status code:
200 OK
Response time:
131ms
Headers:
content-type: application/json
x-global-transaction-id: 180155511
apim-debug-trans-id: 10.113.132.144-1d5a0ad3-e9d0-428b-94ee-9458c4d4613f
```
Figure 8. Viewing API test results through API Connect.