Learn how to configure your App Connect flows to retrieve and process the right data at the right time.

When you add a “retrieve” action to one of your App Connect flows, you can configure your flow to make sure that you’re retrieving the right items:

  • You can retrieve items that match certain criteria.
  • You can retrieve a specified number of records (up to the maximum allowed).
  • You can retrieve items only if a certain condition is met.
  • You can define error handling for when something unexpected happens.
  • You can define how you handle the items that are retrieved.

Here’s an example scenario where you might use a retrieve action in a flow to retrieve a single record. Say you’ve organized an event in Eventbrite. When one of your existing customers signs up for the event, you want your Sales department to contact them with some personalized offers. So you choose the “New attendee” event to begin your flow. You then add the Salesforce “Retrieve contacts” action, mapping the appropriate fields so that you retrieve the contact details and any other salient info from Salesforce for the customer that’s signed up to your Eventbrite event. You can then add the Gmail “Create message” action to the flow to e-mail this important data to your Sales team.

There might be times when you want to retrieve multiple records. Maybe you’re organizing a series of events in Evenbrite. This time, every time a new event is created, you want to retrieve data for all your customers who live in the vicinity so that you can target your marketing campaign at the right people. So you start your flow with the Eventbrite “New event” trigger. You then add the Salesforce “Retrieve leads” action, retrieving all your leads where the city of their address matches the city of the event. You can then add a “For each” node to process all the retrieved records, using the MailChimp “Add subscriber to a list” action to add each lead to the appropriate mailing list for your campaign.

This tutorial takes you through the process of creating a flow that retrieves items from your applications.

First, find or create everything you need:

  • An App Connect subscription.
  • The user names and passwords for the accounts that you want to access (if you haven’t already connected App Connect to your accounts).
    • You can connect to your accounts now from the Applications tab on the Catalog page, or you can connect as you add each application to your flow.
    • Some applications need some extra information to be able to connect to App Connect; if you need help finding this info, see “How to” guides for apps.
  • An application that contains some data that you can retrieve.

    To see which applications support retrieve actions in App Connect, go to the Applications tab on the Catalog page, and then type “retrieve” in the search field.

Next, create your flow:

(App Connect automatically saves your changes as you go. If you move away from the flow at any point, the flow is saved as a draft flow that you can come back to later.)

  1. Log in to App Connect.
  2. From the Dashboard, click New > Event-driven flow.
  3. Enter a name that identifies the purpose of your flow.
  4. Select your first application (source), then select the event that’ll trigger the actions in the rest of your flow.
    For some trigger events, you might have to provide some info, like the name of an event or list that you’re expecting to be updated.
  5. Select a target application, then add a suitable retrieve action to your flow.
  6. Optional: If you want to retrieve records that meet certain criteria, define one or more filters.
    • For example, if you want to retrieve a single item, set the filter to match fields that are likely to be unique, like an email address.
    • To filter against more than one field, click Add condition, and define another filter. For example, if you want to retrieve employees for a particular branch of a company, you could add one condition that matches a company name, and a second condition that matches a particular city.
    • Alternatively, if you want to retrieve all items of a particular type, delete the condition by clicking the X next to the field.
  7. Specify the maximum number of items that you want to retrieve, and what happens if the flow finds more than that number.

    To set the limit to the maximum value allowed, you can click the icon Set the limit to the maximum value for Retrieve action.

    If the flow finds more items than the maximum that you specify, you can choose to exit the flow at that point and issue an error. Or you can continue to process the maximum number of items that are found. The application that you’re retrieving items from decides which items you retrieve.

  8. Define what happens if the flow finds no items that match your criteria.
    You can choose to exit the flow at that point and issue an error, or you can continue through the flow, but issue a response code of “204: No content”. You can use that response code later in the flow. For example, you might add an If node to the flow that says if an action earlier in the flow has resulted in a “204” response code, take a particular action. You might want to send a message to someone to highlight the issue.

    In the following example, we want to retrieve a lead from Insightly that has the same email address as a person who’s signed up for an event in Eventbrite. Email addresses are unique, so we’re expecting to retrieve one lead. So we’ve set the maximum number of items to retrieve to 1, and we’ve said that if more than one lead is found with the same email address, we want to stop processing and issue an error. If no lead is found with the email address, we don’t want to take any further action, so we’ve chosen to exit the flow and issue an error. Screenshot showing settings for retrieving a single record

    Here’s a different example where we’d expect to retrieve more than one item. This time, we want to retrieve all the Salesforce leads who work for a particular company in a particular city. We’ve set the maximum number of items to retrieve to 20. If more than 20 leads are found for this company and city, we just want to process the first 20 that we get back. And if we don’t find any leads that match the criteria, we want to do something about that. So we’ve chosen to continue the flow with an appropriate message. We’ll then add an If node later in the flow to take action for this response code. Screenshot showing the setting to retrieve multiple records

Now, define how you’ll process your retrieved data:

  1. You can handle your retrieved items in two ways:
    • Perform a single action for your list of retrieved items, such as emailing a list of leads to your Sales department
    • Perform an action for each of the retrieved items, such as creating a row in a spreadsheet for details of each lead

    To perform a single action for all the retrieved items, just add an action to your flow after the retrieve action. The following steps describe how to perform an action for each retrieved item.

  2. To process each retrieved item, click the plus (+) after the retrieve action, select the Toolbox tab, and add a For each node to the flow.
  3. In the “For each” dialog box, specify the items that you want to process by clicking in the field Select the collection of items to process, then clicking the Insert a reference icon . Select the appropriate object to process, such as leads or contacts.
  4. Optional: Edit the display name if you want to. This is the name that’s shown on the “For each” node in the flow.
  5. Define whether you want to process the retrieved records sequentially or in parallel.
    If you process items sequentially, they’re processed in the order in which the application provides them. The flow waits until the first item is processed before it starts to process the next. If you process items in parallel, the flow starts to process them in the order that they’re received, but it doesn’t wait until the first one’s finished before it starts to process the next one. So they could finish processing at different times. If you don’t care about the order in which records are processed, parallel processing is typically faster. But if you choose parallel processing, check that the applications that are used in the “For each” node can handle a large number of API calls in a short period.
  6. Specify what you want to do if an error occurs while processing one of the items.
    If you don’t want one error to prevent the other records from being processed, select Process all other items and continue the flow.
    If it’s important that all the records are processed, select Exit the flow with an error. Selecting this option means that the flow stops at that point, and no future actions in the flow are completed.
  7. In the “For each” node in the flow, click the plus (+) and select the action that you want to perform for each retrieved item.
  8. Configure the action in the usual way, mapping any relevant fields from the previous applications in the flow.
    As well as mapping data fields from the previous applications in the flow, you can also map the status code from the retrieve action. For example, you could add a Slack “Create message” action to your “For each” node that posts the status codes for each of your retrieved items to Slack. Then your IT team can follow up any records that can’t be retrieved. You can add more actions to your “For each” node if you want to.

    In the following example, we’re processing some leads that we’ve retrieved from Salesforce. We don’t care about the order in which they’re processed, so we’ve chosen to process them in parallel to optimize performance. We’ve added a Google Sheets “Create row” action to our “For each” node so that for each of the leads that we retrieve from Salesforce, a row will be created in a Google Sheets spreadsheet with the info that we’ve mapped from the event and actions earlier in the flow. So if we’ve retrieved 20 leads, we’ll expect to see 20 rows in our spreadsheet when the flow has finished. A screenshot showing a For each node that's processing Salesforce leads

  9. Optional: You can add more actions to your flow after your “For each” node.
  10. When you’ve finished defining your flow, open the options menu [⋮] in the banner and click Start flow. Then click Dashboard to exit the flow. Your flow is now ready and waiting for the trigger event.

If you can’t find what you want, or have comments about this tutorial, please either add comments to the bottom of this page or .

2 comments on"Retrieving items from your applications"

  1. Karen Cameron October 02, 2017

    Hello Cameron,
    App Connect supports a number of Watson applications, and supports retrieve operations for some of those applications. If you go to the Applications page (https://designer.appconnect.ibmcloud.com/apps) and scroll down to the Watson applications, expand an application to see which retrieve operations are available. We’re adding applications all the time, so if there’s a particular Watson application that you’d like to use but isn’t yet on the list, please let us know.

    If you want to see an example of how to use App Connect in a flow with a Watson application, we have a tutorial that uses Watson Natural Language Classifier to classify some customer service queries: https://developer.ibm.com/integration/docs/app-connect/tutorials-for-ibm-app-connect/create-event-driven-flow-classify-salesforce-customer-service-queries-post-message-slack/


  2. Cameron Scott September 13, 2017

    Is there a way I can use this to help create my flow with my IBM Watson Application?

Join The Discussion

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