Retrieve action

A retrieve action gets information from an application so that you can use it to complete a subsequent task in that application or in another application.

Selecting filter conditions for the items to retrieve

When you add an action to your flow to retrieve items (or records), you can configure options to make sure that you're retrieving the correct items.
  • For some applications, you can retrieve all items by ensuring that no conditions are set.
    Figure 1. Example of a retrieve action with no filter conditions
    Example of a retrieve action with no filter conditions

    For others, only a "retrieve all" action is possible, so you won't be able to set any conditions.

    Figure 2. Example of a retrieve all action
    Example of a retrieve all action
  • If you want to retrieve items that match certain criteria, you can define one or more conditions by clicking Add condition, as shown in the following image. In some cases also, only a single Retrieve by ID condition is available; for example, a Box Retrieve file action.
    Figure 3. Example of filter conditions for a retrieve action
    Example of filter conditions for a retrieve action
  • To refine the search conditions that you specify to retrieve items, you can enable conditional filtering. This enables you to apply an only-if precondition to every condition that you add. Each precondition must evaluate to a true or false value that determines whether the associated condition is included in the query to the application that you're retrieving items from. The condition is included in the query if the result of your only-if evaluates to true, but is not added if only-if evaluates to false. When you enable condition filtering, an only-if precondition is added as a nested Boolean field to each condition that you define. The following image shows an example of the only if field. You can enter a value of true or false in this field, or you can specify a mapped field and apply JSONata that evaluates to true or false. If you leave the only if field blank, it resolves to the default value of true.
    Figure 4. Example of a nested 'only if' field
    Example of a nested 'only if' field

    Let's use an example to illustrate how condition filtering works. Suppose that each time a new lead is added to Insightly, we want to query Saleforce to check whether there's an equivalent record for that lead, and possibly take some further action on that lead. Because email addresses are unique per person, we can add a condition to search for a Salesforce lead whose email address matches that of the Insightly lead. But first though, we'd like to check that the Insightly lead record contains an email address since otherwise, the condition will be invalidated.

    1. For the Salesforce 'Retrieve leads' action, click Add condition and then set a condition that queries for a Salesforce lead email address that matches the email address of the new lead in Insightly.
      Figure 5. Adding a condition to retrieve a matching email address
      Adding a condition to retrieve a matching email address
    2. From the options menu [⋮] for the 'Retrieve leads' action, click Enable condition filtering to add the precondition.
      Figure 6. Selecting 'Enable condition filtering
      Selecting 'Enable condition filtering'
    3. Insert a mapped Email address value from Insightly into the nested only if field that is attached to the condition. Then select the mapped value and use Apply a function to apply a JSONata $exists() Boolean function. We are using this precondition to check whether an email address is specified for the new lead that was created in Insightly. If an email address is found, only-if will evaluate to true, and the condition will included in the query to be run to search for a Salesforce lead with a matching email address. If an email address is missing for the new lead in Insightly, only-if will evaluate to false, and the condition will not be added because we've already determined that no match exists.
      Figure 7. Example of an 'only if' condition
      Example of an 'only if' condition

      For more information about applying JSONata expressions in App Connect, see Applying JSONata functions to transform your data.

  • Certain applications have prerequisite values that must be specified before you're allowed to add any filter conditions. These prerequisite values for the retrieve action are presented in drop-down lists, which are populated by the application you're connected to. For example, if you are retrieving interests (or group names) from MailChimp, you need to first specify the list and interest category whose interests you want to retrieve.
    Figure 8. Example of prerequisite values for a retrieve action
    Example of prerequisite values for a retrieve action

    To cater for use cases where you need to specify a dynamic value (which is returned by a previous event or action) instead of a pre-populated static value, you can switch to advanced mode to customize your selections as follows:

    1. From the options menu [⋮] for the action, click Switch to advanced mode. In the following image, we selected a list, but the interest category is blank because we want to add a mapped field for an interest category that was created earlier in the flow.
      Figure 9. Switching to advanced mode
      Switching to advanced mode

      Notice that the drop-down lists are converted to text boxes and that the list name is now shown as an ID value.

    2. Click within the InterestCategories field and then use the Insert a mapping icon Insert a mapping icon to select a mapped field from the list of available inputs.
      Figure 10. Mapped field added in advance mode
      Mapped field added in advance mode
    3. Add any conditions as required. For more information about using the advanced mode, see Switching to advanced mode editing.

Specifying the number of items to retrieve and error handling

After selecting your filter conditions, you can:

  • Define how many items you want to retrieve. In the Maximum number of items to retrieve field, specify a value, or click the arrow icon Set the limit to the maximum value for Retrieve action to set the limit to the maximum value allowed. If you've specified a retrieve by ID condition, the maximum number of items is 1.
  • Indicate what should happen if App Connect finds more than the maximum number of items specified:
    • Choose to exit the flow at that point and issue an error.
    • Process the maximum number of items that are found and continue with the flow. (The application that you're retrieving items from decides which items you retrieve.)
  • Define what should happen if no items are found:
    • Continue processing any remaining nodes in the flow, but issue a response code of '204: No content'. You can use that response code later in the flow.
    • Choose to exit the flow at that point and issue a '404' error.
    Figure 11. Specifying the number of items to retrieve and error handling
    Specifying the number of items to retrieve and error handling

Resolving the Memory limit exceeded for retrieve action message

If you see the message Memory limit exceeded for retrieve action, you have tried to retrieve more object data than can be handled by one flow. Each flow in App Connect comes with a memory limit. If you try to retrieve more object data than this memory limit, you see the error message. You have several techniques to avoid reaching the memory limit, including:

  • Splitting a retrieve action to be processed by two or more flows, with each flow using retrieve actions for a different, smaller subset of the total records to be retrieved.
  • Editing the existing flow to work with a smaller number of retrieved records.
  • Using condition filtering to retrieve items only if a precondition is true.
  • Contacting IBM® to know how this memory cap can be increased to suit your needs.

Ways of processing your retrieved data

You can handle your retrieved items in several ways:

  • You can add a For each node after the retrieve action to perform an action for each of the items that were retrieved.
  • You can add a node that parses the data into a suitable format for subsequent use; for example, a JSON parser node or a CSV parser node.
  • You can add another action after the retrieve action to process the list of retrieved items. This is a single action, no matter how many items are returned – such as creating an email that lists all the retrieved items.

You can also decide what action to take based on the status code that you get in response to the retrieve action. You could use an "If" node to perform different actions for different status codes. The status codes that you're likely to see in response to a retrieve action are:

  • 200: Records that match the search conditions were successfully retrieved
  • 204: No records were found

You can map to the status code that a retrieve action returns by expanding the Response info node in the list of available inputs. The following example shows how you can map to a status code that's returned for a Salesforce "Retrieve leads" action. (The value can be set to 200 or 204 as required.)

Figure 12. Selecting the status code for a retrieve action
Selecting the status code for a retrieve action

Examples

Step-by-step instructions for configuring App Connect to retrieve items

Retrieving items from your applications

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

Learn more