Introduction: Creating flows for an API (Part 1)

• (If you haven't already connected App Connect to your Salesforce account) The name and password of your Salesforce account.
  Note: 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.

1. On the Dashboard, click New > Flows for an API.
2. At the top of the page, enter a name that identifies the purpose of your API, for example: Customer API

   

   (Click the image to view full size.)

3. In the Model name field, you need to enter a name for your model that reflects the type of object that your API will work with.

   The API flow that we are going to create will create a customer in Salesforce. So, in the Model name field, type Customer

4. Click Create model. The Customer model panel is displayed.

   This panel contains 2 tabs; a Properties tab and an Operations tab.

   First we're going to work with the Properties tab. Properties are required to define the structure of the object that the API will work with.

   1. Our API will create, update, and retrieve a customer so we're going to use the following properties to identify customers.
      • CustomerID
      • FirstName
      • LastName
      • Email

      Add these properties to the Customer model. (To add the first property, type the name in the field provided. To add another property to the list, click Add property (+)).

      

      (Click the image to view full size.)

      A valid property name has the following characteristics:

      • Each property name must be unique.
      • A property name can't contain spaces, but you can use an underscore character (_) to separate words.
      • It must contain only letters, numbers, or the underscore character.
      • It must contain at least 2 characters.
      • It must begin with a letter or an underscore.
      Tip: 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.
   2. By default, the first property that you add (CustomerID) has the ID option selected. Because we want our flow to return a customer ID when we create the customer object, we'll leave this default.
      Note: A property that is set as the ID indicates that your flow must return this property when creating an object or that the property must be sent in a request to update or retrieve an object by using its ID. You can only use ID against one property.

      You can create more models by clicking Create model. To delete a model, select Delete model from the menu.
5. To define how the API will interact with the object, click Operations. You can add operations to:
   • Create an object.
   • Retrieve an object by using its unique ID or by using a filter.
   • Update or create an object (by using its ID or a filter), where the object is updated if it exists, or created if it doesn't.
   1. Add the Create Customer operation to the Customer model. (Click within the Select an operation to add drop-down list, and then select Create Customer.)

      

      Note: You can define your own operations, by clicking Add a custom operation. Note the following restrictions if you decide to use this option:

      • The operation name can't be a keyword.
      • The operation name can't be one of the following keywords: create, updateOrCreate, all, updateAttributes, update, updateAll, upsertWithWhere, replaceOrCreate, replaceById, destroy, destroyAll, executeAssembly.
      • The query parameter can't be the same as the model ID.

      For more information about adding custom operations see, Create your own custom HTTP operations on API flows.

      Next, we're going to create a flow that defines how the Create Customer operation will work.

6. Click Implement flow. You'll see a basic flow in the flow editor, with a Request node, a Response node, and a (+) space to add one or more target applications. Notice the the structure of the Request body example, it is constructed from the properties in your model, with some sample data.

   

7. To add the target application to the flow, click (+).
8. Select Salesforce > Contacts > Create contact.

   (If you haven't already connected App Connect to Salesforce, specify the name and password of your Salesforce account.)

9. Map the fields from the request into the Salesforce 'Create contact' action as follows:
   • Account ID: Click within the field and click Insert a mapping . Then select CustomerID from the Available inputs list.
   • Last Name: Type last and then select LastName from the list.
   • First Name: Type fir and then select FirstName from the list.
   • Email: Type em and then select Email from the list.

   

10. You can also add some conditional logic to your flow. For example, if you want your flow to do different things for different conditions, you can add one or more ‘If’ nodes to your flow. For more information, see Adding conditional logic to a flow.
11. Click the Response node in the flow to define the response that'll be returned when the operation has completed successfully. Map the available fields from 'Salesforce / Create contact' to the response as follows:
    • For the required response field CustomerID, map the Salesforce field Contact ID; optionally, map other fields to return their values in the response.

      

      Note: 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).
12. Click Done to return to your model.
13. From the options menu (⋮), click Start API.

    

If you are using App Connect on IBM Cloud®, you can test the flow for your API in the API portal. Otherwise, you can test the flow for your API in your preferred method for invoking an API, such as by using Postman or curl.

You've created and tested your API!

In flow tiles 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.

If you want to find out how to retrieve and update Salesforce contacts using the same API, see Creating flows for an API (Part 2).