In the tutorial Creating flows for an API you created a REST API to create a customer contact in Salesforce. In this tutorial, you’re going to create an API that will retrieve and update contact details in Salesforce.

Watch the video

First, find or create everything you need:

  1. In the App Connect Dashboard, click the Customer API tile.
  2. Click the Operations tab. Notice that you are unable to make any changes. This is because the API is still running. To make changes we have to stop the API.
  3. To stop the API, in the navigation banner, click the options menu (⋮) and then click Stop API.


    Click the image to view full size

  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, for demonstration purposes, you are going to 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.

  6. For the Retrieve Customer by ID operation, click Implement flow.
    1. Notice the Request URL example. When we call this API, we will have to append the customer ID to the end of the URL to retrieve the customer details.

      Next we need to define which customer details we want to receive in the response.

    2. Click (+).
    3. Select Salesforce > Contacts > Retrieve contacts. (If you haven’t already connected App Connect to Salesforce, specify the name and password of your Salesforce account.)
    4. As we want to retrieve contacts whose contact ID is identical to the customer ID that the user of your API enters, we’re going to add a condition and update the Where fields as follows:

    5. Leave the other fields with their default values.
    6. Click Response. Here we define the status code and which fields will be returned in the response body.
    7. Leave the status code as the default and map all the fields to the Salesforce / Retrieve contacts fields as follows:

      Ignore the warning messages. They will not affect the response because only a single contact (that corresponds to the unique ID specified) will be returned.

      Note: When you’re creating an object, typically only the ID from the target application will be returned in the response message. If you’re retrieving an object, the response message will show you all the fields that you’ve requested from the target application.
      Info: 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.

    1. Notice the request URL example and request body example.
    2. Click (+).
    3. Select Salesforce > Contacts > Update or create contact.
    4. We want a way to uniquely identify the contact to be updated, so we’re going to update the Where fields as follows. Select Email from the leftmost field. In the rightmost field, open the list of available inputs and then map to the Email value under Request body parameters.

    5. Configure these Salesforce fields by mapping their values to those from the request body parameters:
      • Last name: LastName
      • First Name: FirstName
      • Email: Note that the value in the Where condition will be used here, so you do not need to manually specify a mapping.
    6. Click Response.
    7. Leave the status code as 200.
    8. Configure the response body fields by mapping their values to those from the Salesforce / Update or create contact fields as follows:

  8. Click Done and then start the API.

Finally, test your flow:

Next you’re going to test the flow to retrieve a customer and then to update the first name of the same customer. You’ll test the flow by using the API portal in App Connect on IBM Cloud. If you’re familiar with using other tools such as Postman or curl to invoke an API, you can also test the flow for your API by using those tools.

Testing in the API portal

  1. Click the Manage tab and then scroll down to the Sharing Outside of Cloud Foundry organization section (at the bottom of the page).

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


    (Click the image to view full size.)

  2. Click the API Portal Link link to open the API in an API portal window. Notice that the Customer.create operation that you created in the earlier tutorial is shown under Operations in the left pane, 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 in the “Creating flows for an API (Part 1)” tutorial. Next, copy the CustomerID value that was returned by Salesforce and paste it into a text editor.

  4. To invoke the operation to retrieve a customer by ID, click Customer.findById in the left pane, and then click Try it.
  5. In the id field, paste the CustomerID value that you copied earlier.
  6. Click Call operation.
  7. Scroll down to the Response section, where you should see the success code 200 OK, and the response body containing 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"
    }
    
  8. 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"
    }
    
  9. To invoke the operation to update the details of an existing a Customer by using a filter, click Customer.upsertWithWhere in the left pane, and then click Try it.
  10. In the data field, paste the contact details that you copied earlier, and then delete the CustomerID line.
  11. Copy the Email value (for example, test1.apiname@email.com) in the data field and then paste it into the Email field.(This value will be used to filter for a Salesforce contact with this identical email address.)
  12. 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.
  13. Click Call operation.
  14. Scroll down to the Response section, where you should see the success code 200 OK, and the response body containing the CustomerID value, as well as 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"
    }
    
  15. You’ve updated your API with two additional operations! Close the API portal tab to return to the API flow. Then, click Dashboard to return to the App Connect Dashboard.
  16. Go to your Salesforce instance, and verify that the contact’s first name has changed.

Testing in Postman

In this example, we test a flow for an API that was created and started in App Connect purchased from IBM Marketplace: https://designer.appconnect.ibmcloud.com/. These instructions are for the retrieve operation only.

Show details…

As in the previous tutorial, we’re going to use Postman, but you can use your preferred utility, for example, the Linux command line and curl, or the HttpRequester add-on for Firefox.

  1. [To retrieve a customer]:
    • Click the Manage tab and make note of the URL, user name, and password. We’re going to use these credentials to invoke the API operations.
    • 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 slightly for different versions.)
    • 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.
      Info: To get a customer ID, open Salesforce and click on 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
    • In the Authorization tab, change the Type to Basic Auth.
    • Add the user name and password that you copied earlier to their respective fields.
    • Click Update Request.
    • Go to the Headers tab and select the following key/value pairs:
      • Key: Content-Type
      • Value: application/json

    • Click Send.
    • The customer details are displayed. Notice that the response contains all the fields that you specified when you created the flow.
    • Copy the response for testing the replace or create operation.
    Postman utility used to call an API GET operation to retrieve a contact from Salesforce (click the image to view full size).

Join The Discussion

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