Learn how to use App Connect Designer to create an event-driven flow that when a new Salesforce contact is created, creates a document in IBM Cloudant with data from Salesforce. This tutorial demonstrates how to easily specify your own data properties for an IBM Cloudant document, without needing to write JSON.

Note: This tutorial assumes that you have signed up for free or trial accounts for IBM Cloudant and Salesforce, or that you have business accounts.

Additional reference:

Scenario:

Your company is using Salesforce to manage customer data, and uses IBM Cloudant as a fully managed JSON document store for your web and mobile applications. When a new contact is created in Salesforce, you want to create a new Cloudant document with customer data from the Salesforce contact.

Event-driven flow to update a Cloudant document when a Salesforce contact is updated. (Click image to view full size.)

IBM Cloudant stores JSON formatted documents. Thanks to functionality offered in App Connect, you do not have to write this JSON by hand, but you are able to define the document properties (names and data types) and then map to those properties as you would any other properties in App Connect. This tutorial shows you how to define and use your own document properties.

First, find or create everything you need:

  1. An App Connect subscription.
  2. Obtain account details for connecting App Connect to your applications (If you haven’t already connected App Connect to your applications.):
    • The user name and password for your Salesforce Developer Edition account and your IBM Cloudant account (if you haven’t already connected App Connect to your accounts). You can connect to your accounts now on the Applications tab on the Catalog page, or you can connect as you add each application to your flow.

Next, create your flow:

  1. Log in to App Connect Designer; for example, launch App Connect through your IBM Cloud dashboard.
  2. From the Dashboard, click New > Event-driven flow.

    Complete the following steps. As you progress, App Connect automatically saves your changes. If you navigate away from the flow at any stage, the flow is saved as a draft flow that you can complete at another time.

  3. Enter a name that identifies the purpose of your flow; for example: Sync new Salesforce contact to IBM Cloudant document.
  4. Select Salesforce > New contact as the event that is to trigger the flow.

    If you have not connected App Connect to Salesforce, allow App Connect to access your Salesforce account (in a separate tab).

  5. Click the (+) and then scroll down to IBM Cloudant.
    Flow triggered by Salesforce / New contact, with IBM Cloudant / Create document to be the action. (Click image to view full size.)

    Select IBM Cloudant > Create document as the action that App Connect should use to sync Salesforce data to IBM Cloudant documents.

    If you have not connected App Connect to IBM Cloudant, click Connect and then complete and submit the request using the account details that you obtained above.

    Specifying details to connect to IBM Cloudant. (Click image to view full size.)
  6. Select the Cloudant database that you want to use. For this tutorial, I created a new database named businesscard.
  7. Define your Cloudant document data structure specified as data properties.

    The Cloudant documents are to have the following data structure:

    • Name (string)
    • Address
      • Number (number)
      • Name (string)
      • Street (string)
      • City (string)
      • Zip (string)
    • Birthdate (date)
    • Email (string)

    In Cloudant, the documents have the following JSON format:

    {
      "_id": "xxxxxxxxxxxxxxxxxxx",
      "Address": {
        "City": "xxxxx",
        "Number": 123,
        "Street": "xxxxxxxxxxxxxxxxxxx",
        "Zip": "xxxxxxxxxxxxxxxxxxx"
      },
      "Birthdate": "1234-01-23",
      "Email": "xxxxxxxxxxxxxxxxxxx",
      "Name": "xxxxxxxxxxxxxxxxxxx"
    }
    

    Using App Connect, we can define this by data properties (names and data types), without needing to write JSON:

    1. Under the “Document data” heading, click Add property. As a result, a new property field appears and you can set its name and data type. For the example above, enter Name and leave the type as String.
    2. To add another property, click Add property again. This time enter the name Address, but change the type to Object. You should now see a second Add property option appear for the Address object. This allows you to define the properties within the Address object.
    3. Continue to define the other Address properties: Number, Name, Street, City, and Zip. Setting Number to the data type Number means that App Connect will require that a number be mapped to the field for the Number property.
    4. Next, click the outer Add property and then enter the name Birthdate, specifying the type to be Date.
    5. Finally, click the outer Add property, enter the name Email and leave the type as String.

    You should now have your document defined as follows.

    (Click image to view full size.)

    You are now ready to use your document, just as if it had been defined as part of the action all along.

  8. Click Edit mappings to save your changes and show fields for the properties ready to be completed. You can map to these fields from source fields of nodes earlier in the flow, just as you would for other actions in App Connect.

    The IBM Cloudant ‘Document data’ section should now have the data properties fields as shown in the following image:

    (Click image to view full size.)

  9. Map source fields from the Salesforce / New contact into the data properties fields of IBM Cloudant / Create document:
    1. In the Name field, start typing “name” and then select the Full Name field from Salesforce / New Contact.
    2. To map the address number, we extract the number from the street string of the Salesforce / New Contact.

      In Salesforce Contact information, the address number is the first word in the street string (in this example, using the Mailing address fields); for example: 123 Major Oak.
      So we use a JSONata expression to extract the number substring and convert it to a number:
      $number($substringBefore($Trigger.MailingStreet , " ")), shown in Designer as:

      (Click the image to view full size.)

      You can copy and paste the expression into the Number field, or build up the expression as follows:

      1. In the Address / Number field, start typing “street” and then select the Street field from Salesforce / New Contact.
      2. In the Number field, click Street and then select Apply a function.
      3. Scroll down to and then select the string function substringBefore.
      4. Add a space character as the second parameter of substringBefore. The function will extract the Number substring before the first space character in the Street string.
      5. To convert the Number substring into a number, wrap the expression in the Number field with the JSONata $number(...)
    3. In the Address / Street field, start typing “street” and then select the Street field from Salesforce / New Contact.

      To extract the street value from after the number substring, apply the function substringAfter and add a space character as the second parameter. The JSONata expression becomes: {{$substringAfter($Trigger.Street, " ")}}

    4. In the Address / City field, start typing “city” and then select the City field from Salesforce / New Contact.
    5. In the Address / Zip field, start typing “zip” and then select the Zip/Postal Code field from Salesforce / New Contact.
    6. In the Birthdate field, start typing “birth” and then select the Birthdate field from Salesforce / New Contact.
    7. In the Email field, start typing “email” and then select the Email field from Salesforce / New Contact.
  10. From the banner, open the options menu [⋮] and click Start flow. Then click Dashboard to exit the flow. Your flow is displayed on your Dashboard and is listening for your event – the addition of a new contact in Salesforce.
    The flow tile on the Dashboard, showing that the flow is running and listening for events. (Click image to view full size.)

Finally, test your flow:

  1. Log in to IBM Cloudant using the account that you configured in App Connect and verify that no document exists for Robin Hood (or whatever name you want to use for testing).
  2. Create a new Salesforce contact:
    1. Log in to Salesforce using the account that you configured in App Connect.
    2. Create a new contact, specify values for First Name, Last Name, Birthdate, Email, Address (Mailing Street, City, and Zip/Postal Code); for example:
      Creating a new contact in Salesforce. (Click image to view full size.)
    3. Save the new contact.
  3. After a short while, check your IBM Cloudant dashboard for a new document.

    You should see a new document created by IBM App Connect for the new Salesforce contact. If you click the document entry, you will see the data synced from Salesforce:

    IBM Cloudant document created by App Connect for a new Salesforce contact. (Click image to view full size.)
  4. Examine the App Connect Dashboard. If the flow ran successfully, the flow tile shows a green tick
    Flow tile showing the last successful run of the flow. (Click image to view full size.)

Congratulations, you have created a flow that is triggered when a new contact is added to Salesforce, and creates a document in IBM Cloudant with date from the Salesforce contact. You defined the data structure for the Cloudant document by specifying data properties (name and data type) without needing to work with JSON.

Join The Discussion

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