Learn how easy it is to create an API flow in App Connect Designer to create OData resources in SAP and perform actions on SaaS apps.

Scenario

As part of a company move to a more-responsive, self-service business model, a travel agency company wants to enable their clients to do more of their own travel arrangements through a mobile or web application (app).

As part of the app capabilities, clients should be able to subscribe to flight details in a SAP backend system so that when flight details are changed they are notified through the app.

Mobile app use for flight subscription. (Click image to view full size.)

Rather than implement the subscription within the app, the app is to consume an API provided by IBM App Connect that uses OData to create subscriptions in SAP.

Also, when a user chooses to subscribe to a flight, App Connect is to add the user details as a contact in Salesforce. This enables the company’s marketing and sales teams to 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. (Click image to view full size.)

Rob, an integration developer, configures an API flow in App Connect Designer to create a flight subscription in SAP and create a contact record in Salesforce. Rob doesn’t need any experience with SAP, only getting required SAP OData configuration details from his SAP admin. Rob exploits App Connect’s “configuration without coding” approach to create and then publish the API in a matter of minutes, and then simply provides the API invocation details to the application developer for use in the app.

Time required:
If you have already connected SAP and Salesforce to App Connect, the steps to create and test the integration flow in this tutorial should take only a few minutes.

First, find or create everything you need:

  • An App Connect subscription (Free or Personal)
  • (If you haven’t already connected App Connect to your Salesforce account) The name and password of your Salesforce account.

    If you want to create a free test account in Salesforce rather than use your business account, make sure that you register for a Developer account from this URL: https://developer.salesforce.com rather than a Trial account. If you connect to App Connect with a Trial account, the Salesforce events do not work.

  • (If you haven’t already connected App Connect Designer to your SAP system) prepare SAP OData connectivity for use with App Connect Designer, as described in What should I know about connecting to SAP?.
  • (If you haven’t already connected App Connect to your Asana account) The email address and password of your Asana account.

Next, create your flow:

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

Creating the flow from the sample flow document

This enables you to create the flow immediately, and then select each node in the flow to validate the node and select the application accounts that you want to use.

Creating the flow from scratch

This helps you to learn the sequence of steps used to create the flow, and to examine the nodes and fields as you go.

  1. Log in to App Connect Designer.
  2. On the Dashboard, click New, then click Create flows for an API.
  3. Enter a name for your model that reflects the type of object that your API will work with, then click Create model.

    For example, FlightSubscription.

  4. Add the properties that are required to define the structure of your object that the API will work with.

    You can 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 in App Connect:
      1. Click Select properties from applications
      2. Expand SubscriptionCollection, and 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 as the app consuming the API must supply a value to be able to create a Salesforce contact.
      • For CustomerID, select ID to specify that this is the property that the flow must return to the app consuming the API.

        The ID property is not marked as required, because the Salesforce Create Contact action used in the API flow automatically generates the ID value when called by the API.

    Properties of an API to create a flight subscription in SAP and a contact in Salesforce. (Click image to view full size.)
  5. Click Operations to define the actions that the API is to perform on objects. In this case, select Create FlightSubscription
  6. Click Implement flow to create a flow that defines how the operation will work.

    You’ll 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’ll see an example of the structure of the request, constructed from the properties in your model, with some sample data.

    API request node showing example request body structure and content. (Click image to view full size.)
  7. 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 the {+) icon, and then select SAP Create SubscriptionCollection
    2. In the *DeliveryAddress field select deliveryAddress from the request. (You can start typing de to be prompted with the Request property.)
    3. In the Collection field, type FlightCollection, as the SAP object being subscribed to
    4. (Optional) In the Select field, type *, to return the FlightCollection content in the payload of the notification sent to the app consuming the API.
      SAP Create SubscriptionCollection node to create a flight subscription. (Click image to view full size.)
    5. Click the {+) icon, and then select Salesforce Create Contact
    6. Populate the Salesforce fields: *Last Name, First name, and Email with corresponding request fields.
    7. (Optional) In the Contact Description field, add the Sub. ID field from SAP / Create SubscriptionCollection; for example: Created for SAP subscription [Sub. ID], where [Sub. ID] is the field selected from SAP
    Salesforce Create Contact node. (Click image to view full size.)
  8. Click the Response in the flow to define the response that’ll be returned when the operation has completed successfully.

    For the *CustomerID field, select the Contact ID from Salesforce.

    API Response node. (Click image to view full size.)

    When you’re creating an object, typically only the ID from the target application will be returned in the response message.

  9. Click Done to return to your model.
  10. Give the API flow a name; for example: Flight Subscription API. This name is useful to identify the API on the App Connect dashboard.
  11. Now that you’ve defined the API’s model and operation, start the API by selecting Start API from the menu.
    Start API menu option
    (Click image to view full size.)

Congratulations, you’ve created and started your API! On the App Connect dashboard, flows for APIs are identified by the API icon. You can start and stop them in the same way as any other flow. You can open an API while it’s running, but you have to stop it before you can edit it.
API flow tile on dashboard
(Click image to view full size.)

To test your API, you can complete the following steps:

  1. To test your API, click the Manage tab, then use the URL, Username, and password with your preferred technique to invoke API operations; for example, the Linux command line and curl, the HttpRequester add-on for Firefox, or another utility like Postman.
    Postman utility used to call an API POST operation to create a subscription in SAP and a contact in Salesforce. (Click the image to view full size.)

    Note that the username and password are set in the request header, and that the request body does not include the API ID property (CustomerID) because that is set by Salesforce.
API test results: SAP SubscriptionCollection and Salesforce Contact created. (Click image to view full size.)

Rob could provide the API URL and request details to the app developer for use by the app, but it is better to publish the API to an API management tool, such as IBM API Connect – the end-to-end API lifecycle management solution to publish and secure APIs in a hybrid cloud environment.

To manage your API, you can import it into IBM API Connect:

  1. From the menu of the API tile on the dashboard, select Open API.
  2. Click the Manage tab

    This tab provides a button for you to download your API document, which you can import into your API management tool. We’ve provided the URL, user name, and password that your API management tool will need.

    If you don’t have a subscription for API Connect, you can click Manage API with IBM API Connect to obtain a subscription.

  3. Click Download API to download your API document. Save the swagger.json file somewhere convenient.
  4. Copy the values for the URL, user name, and password.
  5. In API Connect, complete the steps to add the API; for example, using the Getting Started guide:
    1. Click 01 Import API.
    2. Click Import API from a file or URL.
    3. Click Import from file, and then locate and select the swagger.json file that you downloaded for the API.
    4. Click Import. A new REST API definition is created, including Paths and HTTP operations. (You can edit your API definition as you would any other REST API definition.)
    5. Click 02 Generate and Publish
      1. Click Generate a default product. The New Product pane provides details of the product, and the catalog to be used to publish the API.
      2. Click Create product

        Note the success message:

        Success   Swagger flightsubscription product (version 0.0.1) has been published to Sandbox 

    6. Click 03 Explore

      Optionally, click Drafts or Sandbox to explore further. For example, in Sandbox, you will see the API Swagger flightsubscription 0.0.1

    7. Click 04 Test, to test the POST operation to create a new subscription.
      1. Click Drafts in the UI navigation pane
      2. On the APIs tab, click Swagger flightsubscription
      3. Click the Assemble tab.
      4. If there is no assembly already, add an Invoke policy to call the URL of the API in App Connect.
      5. Click the Test icon
      6. Select the Sandbox catalog
      7. Click Republish product
      8. Select the post /flightsubscription operation to invoke
      9. For Authorization, specify the Username and Password values from the API in App Connect
      10. In the Model instance data, specify JSON data appropriate for a new subscription; for example:
        {
        "FirstName": "TestB",
        "LastName": "SAPnameb",
        "Email_Address": "testb.sapname@email.com",
        "deliveryAddress": "http://host:port/GWC/SUPNotification/ApplicationConnectionId/SAPnameb/Application/Domain"
        }

        Note that CustomerID is not specified, because it is generated by Salesforce.

      11. Click Invoke.

        You should see a 200 OK success response; for example:

        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
        
      API test results through API Connect: SAP SubscriptionCollection and Salesforce Contact created. (Click image to view full size.)

    Join The Discussion

    Your email address will not be published. Required fields are marked *