Retrieving items from your applications

Consider this example scenario where you might use a retrieve action in a flow to retrieve a single record. Imagine that you 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. You map the appropriate fields so that you retrieve the contact details and any other salient information from Salesforce for the customer who is 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.

In some circumstances, you might want to retrieve multiple records. Maybe you're organizing a series of events in Eventbrite. This time, every time a new event is created, you want to retrieve data for all your customers who live in the vicinity. You can then target your marketing campaign at the correct 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 by using the Mailchimp Add subscriber to a list action. This action adds each lead to the appropriate mailing list for your campaign.

• An App Connect subscription.
• The credentials for the accounts that you want to access (if App Connect isn't yet connected to your accounts).
  • You can connect to your accounts now from the Applications and APIs 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 with finding this information, 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 and APIs page and type retrieve in the search field.

By using App Connect Designer, you can create your flow from scratch.

To create your flow, complete the following steps.

1. On the in App Connect Designer dashboard, click Create > Event-driven flow.

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

2. Enter a name that identifies the purpose of your flow.
3. Select your first application (source), then the event to trigger the actions in the rest of your flow.

   For some trigger events, you might have to provide some information, like the name of an event or a list that you're expecting to be updated.

4. Click Add node (+) and select a target application and a suitable retrieve action.
5. To retrieve records that meet certain criteria, define one or more filters.
   • For example, 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, to retrieve employees for a particular branch of a company, add one condition that matches a company name, and a second condition that matches a city.
   • Alternatively, to retrieve all items of a particular type, delete the condition.
6. 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 .

   If App Connect finds more items than the specified maximum limit, you can 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.

7. 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 results 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, you want to retrieve a lead from Insightly that has the same email address as a person who signed up for an event in Eventbrite. Email addresses are unique, so you're expecting to retrieve one lead. So, set the maximum number of items to retrieve to 1. The example also shows that if more than one lead is found with the same email address, you stop processing and issue an error. If no lead is found with the email address, you don't want to take any further action, so you want to exit the flow and issue an error.

   

   In the next example, you expect to retrieve more than one item. This time, you want to retrieve all the Salesforce leads who work for a particular company in a particular city. You set the maximum number of items to retrieve to 20. If more than 20 leads are found for this company and city, you want to process the first 20 that you get back. And if you don't find any leads that match the criteria, you want to do something about it. So, you can continue the flow with an appropriate message. You can then add an If node later in the flow to handle this response code.

   

8. Now, define how to process your retrieved data.
   You can handle your retrieved items in two ways.

   • Complete a single action for your list of retrieved items, such as emailing a list of leads to your Sales department
   • Complete an action for each of the retrieved items, such as creating a row in a spreadsheet for details of each lead
   To complete a single action for all the retrieved items, add an action to your flow after the retrieve action. The following steps describe how to complete an action for each retrieved item.

   1. To process each retrieved item, click the plus (+) after the retrieve action, select the Toolbox tab, then add a For each node to the flow.
   2. 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 mapping icon . Select the appropriate object to process, such as leads or contacts.
   3. Edit the display name if you want to. This name is shown on the "For each" node in the flow.
   4. 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. The flow doesn't wait until the first item is finished before it starts to process the next one. So, the items might 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 many API calls in a short period.

   5. Specify what you want to do if an error occurs while the flow is 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.

   6. In the "For each" node in the flow, click the plus (+) and select the action that you want to complete for each retrieved item.
   7. Configure the action in the usual way, mapping any relevant fields from the previous applications in the flow. In addition to mapping data fields from the previous applications in the flow, you can also map the status code from the retrieve action. For example, you can 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, you process some leads that you retrieved from Salesforce. If you don't care about the order in which they're processed, process them in parallel to optimize performance. A For each node contains a Google Sheets "Create row" action. So, for each lead that you retrieve from Salesforce, the action creates a row in a Google Sheets spreadsheet with the information that you mapped from the event and actions earlier in the flow. Therefore, if you retrieved 20 leads, you expect to see 20 rows in the spreadsheet when the flow finishes.

      

9. You can add more actions to your flow after your "For each" node.
10. To test your flow, click Test flow, then select the option to use sample data or real data. For more information, see Testing flows during development.
    Warning: Make sure that your connected applications are appropriate to use for testing. Your applications are updated with the real or sample data when the flow is triggered.