Creating flows for an API (Part 2)

In the preceding tutorial about creating flows for an API, you created a REST API to create a customer contact in Salesforce. This tutorial describes how to create an API that retrieves and updates contact details in Salesforce.

Before you start

  • Complete the preceding tutorial Creating flows for an API.
  • If the API flow is running, you must stop it before you can edit it. On the App Connect Designer dashboard, click the action menu (⋮) on the Customer API tile and click Stop API.

Create the flow for the API

  1. In the App Connect Designer dashboard, click the Customer API tile to open the API.
  2. Click the Operations tab.
  3. Click Select an operation to add > Retrieve Customer by ID
  4. Click Select an operation to add > Replace or create Customer with filter
    Note: In this tutorial, you retrieve a customer by using an ID, and update a customer by using a filter that is based on the properties that you added for the model. In this case, the available filters are FirstName, LastName, and Email.
    Figure 1. API operations on Customer records
    API operations on Customer records
  5. For the Retrieve Customer by ID operation, click Implement flow.
    1. Notice the Request URL example. When you call this API, you must append the customer ID to the end of the URL to retrieve the customer details.

      Next, define which customer details you want to receive in the response.

    2. Click Add node Icon that adds a node to the flow to add a node to the flow.
    3. Select Salesforce > Contacts > Retrieve contacts.
    4. You want to retrieve contacts whose contact ID is identical to the customer ID that the user of your API enters. Therefore, add a condition and update the Where fields as follows.
      Figure 2. A condition added to the Where field of the Retrieve contacts action
      The image shows that the "where" clause is set to Salesforce Contact ID equals the Customer ID from the request.
    5. Leave the other fields with their default values.
    6. Click Response to define the status code and which fields to return in the response body.
    7. Leave the status code as the default and map all the fields to the Salesforce Retrieve contacts fields.
      Figure 3. Field mappings in the Response node
      The image shows that CustomerID is mapped to the Salesforce Contact ID, FirstName is mapped to the Salesforce First Name field, LastName is mapped to the Salesforce Last Name field, and Email is mapped to the Salesforce Email field.

      Ignore the warning messages. They don't affect the response because only a single contact (that corresponds to the unique ID that is specified) is returned.

      Note: When you're creating an object, typically the response message includes only the ID from the target application. If you're retrieving an object, the response message shows all the fields that you requested from the target application.
      In the Response header section, you can choose your own response code mapping. The following response codes are returned for the different operations:
      • Create operations return a response code of 201 (record created).
      • Retrieve operations return a response code of 200 (record retrieved).
      • Replace or create operations return a response code of 200 (record replaced) or 201 (record created).
    8. Click Done
  6. For the Replace or create Customer with filter operation, click FirstName and LastName to deselect these properties as filters. Then, click Implement flow.
    Figure 4. Filter properties for the Replace or create Customer with filter operation
    Filter properties for the 'Replace or create Customer with filter' operation
    1. Notice the request URL example and request body example.
    2. Click Add node (+).
    3. Select Salesforce > Contacts > Update or create contact.
    4. You want to uniquely identify the contact to be updated. Therefore, update the Where fields as follows. Select Email in the first field. In the last field, open the list of available inputs and map to the Email value under Request body parameters.
      Figure 5. Mapping the Salesforce Email value to the Request Email value
      Mapping the Salesforce Email value to the Request Email value
  7. To configure these Salesforce fields, map their values to the corresponding values from the request body parameters.
    • Map Last name to LastName
    • Map First name to FirstName
    • For Email, the value in the where condition is used. Therefore, you don't need to specify a mapping manually.
  8. Click Response.
  9. Leave the status code as 200.
  10. To configure the response body fields, map their values to the values from the Salesforce Update or create contact fields as follows.
    Figure 6. Response body fields mapped to the Salesforce Update or create contact fields
    The image shows that the CustomerID field is mapped to the Salesforce Contact ID. The FirstName field is mapped to the Salesforce First Name field. The LastName field is mapped to the Salesforce Last Name field. The Email field is mapped to the Salesforce Email field.
  11. Click Done.

Conclusion

You added more operations to your API. You can test the API by clicking Test API. For more information, see Testing flows during development. You can start and stop an API flow on the App Connect Designer dashboard in the same way as any other flow. You can open an API while it's running, but you must stop it before you can edit it.

Figure 7. The flow tile on the App Connect Designer dashboard
The tile for the running API flow.