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

Create the flow for the API

  1. In the App Connect Dashboard, click the Customer API tile.
  2. Click the Operations tab. You can't edit the API because it is still running. To make changes, stop the API.
  3. To stop the API, in the navigation banner, click the options menu (⋮) and then click Stop API.
  4. Click Select an operation to add > Retrieve Customer by ID
  5. 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 first name, last name, and email.
    Figure 1. API operations on Customer records
    API operations on Customer records
  6. 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. (If App Connect isn't already connected to Salesforce, specify the name and password of your Salesforce account.)
    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
  7. 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 (+).
    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
  8. Configure these Salesforce fields by mapping 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.
  9. Click Response.
  10. Leave the status code as 200.
  11. Configure the response body fields by mapping 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.
  12. Click Done and then start the API.

Test your flow

You can test the flow by retrieving a customer and then updating the first name of the same customer. You can test the flow by using the API portal in App Connect. If you're familiar with using other tools such as cURL to invoke an API, you can also test the flow for your API by using those tools.

Testing in the API portal

  1. On the Manage tab, go to the Sharing Outside of Cloud Foundry organization section.

    The API key and associated API documentation link for the API Portal, which you generated to test the Create Customer operation in the Creating flows for an API (Part 1) tutorial, is displayed.

    Figure 7. The 'Sharing Outside of Cloud Foundry organization' section of the API Portal page
    The 'Sharing Outside of Cloud Foundry organization' section of the API Portal page
  2. Copy the API Documentation Link link and paste into your web browser to open the API in an API portal. Notice that the Customer.create operation that you created in the earlier tutorial is shown under Operations, together with the two new operations that you created in this tutorial.
  3. Click the Customer.create operation.

    Then, invoke the Customer.create operation again, as described in the Finally, test the flow for your API section of the part 1 tutorial. Next, copy the CustomerID value that Salesforce returned and paste it into a text editor.

  4. To invoke the operation to retrieve a customer by ID, click Customer.findById, then click Try it.
  5. In the Security / Client ID field, enter or paste the API key that you created in App Connect.
  6. In the ID field, paste the CustomerID value that you copied earlier.
  7. Click Send.
  8. Scroll down to the Response section, where you can see the success code 200 OK, and the response body that contains the contact details that were retrieved from Salesforce; for example: 
    
Response
Code: 200 OK
Headers:
...

{
  "CustomerID": "0034I00001pvaenQAA",
  "Email": "test1.apiname@email.com",
  "FirstName": "Test1",
  "LastName": "APIname"
}
  9. Copy the contact details in the response body and paste it into a text editor; for example: 
    
{
  "CustomerID": "0034I00001pvaenQAA",
  "Email": "test1.apiname@email.com",
  "FirstName": "Test1",
  "LastName": "APIname"
}
  10. To invoke the operation to update the details of an existing a Customer by using a filter, click Customer.upsertWithWhere, then click Try it.
  11. In the data field, paste the contact details that you copied earlier, and then delete the CustomerID line.
  12. Copy the Email value (for example, test1.apiname@email.com) in the data field and then paste it into the Email field. (This value is used to filter for a Salesforce contact with this identical email address.)
  13. In the data field, change the value of the FirstName property to a different name (for example, Test2). You want to update the first name of the Salesforce contact whose email you specified in the previous step.
  14. Click Call operation.
  15. In the Response section, you can see the success code 200 OK, and the response body that contains the CustomerID value. You can also see the updated FirstName value and unchanged Email and LastName values; for example: 
    
Response
Code: 200 OK
Headers:
...

{
  "CustomerID": "0034I00001pvaenQAA",
  "Email": "test1.apiname@email.com",
  "FirstName": "Test2",
  "LastName": "APIname"
}
  16. You updated your API with two more operations. Close the API portal tab to return to the API flow. Then, click Dashboard to return to the App Connect Dashboard.
  17. Go to your Salesforce instance, and verify that the contact's first name changed.
  • As in the previous tutorial, you can use Postman, or you can use your preferred utility, such as the Linux® command line and cURL, or the HttpRequester add-on for Firefox.
    To retrieve a customer, complete the following steps.
    1. Click the Manage tab and make note of the URL, username, and password. You can use these credentials to invoke the API operations.
    2. In the Postman utility, open a new tab and select the GET function. (The following steps use Postman version 5.3.1. Some steps might differ for different versions.)
    3. In the Enter request URL field, paste the API base URL that you copied earlier and append the model name and customer ID to the end. For example, /Customer/0030Y00000X7g6uQAB.
      Note: To get a customer ID, open Salesforce and click a contact record. The customer ID is displayed in the Salesforce URL when you're in the contact record. For instance, it's the string 0030Y00000X7g6uQAB from the URL https://eu11.lightning.force.com/one/one.app#/sObject/0030Y00000X7g6uQAB/view?a:t=1507115352306
    4. In the Authorization tab, change the Type to Basic Auth.
    5. Add the username and password that you copied earlier to their respective fields.
    6. Click Update Request.
    7. Go to the Headers tab and select the following key and value pairs.
      • Key Content-Type and value application/json
    8. Click Send.
    9. The customer details are displayed. Notice that the response contains all the fields that you specified when you created the flow.
    10. Copy the response for testing the replace or create operation.