Connector Action Flow Step

Step Inputs

In the Edit Step menu, you can add details about the step configuration as needed for your flow.

Step Detail

• Connector: Select the connector (the third-party system) you want to post the data to. The list of connectors includes all of the third-party systems involved in the integration.

• Action Path: Choose what data you want to post, specific to the connector that you selected. This data is defined in an action path. Action paths are set up when the connector is built and are based on the capabilities of the connector. They all appear in the UI in a common format: [connector module] > [data object] > [action]. Not all connectors will include each or any of these action types, but several common types of connector action may be available:

  • Add/post/create: Create new records or items in the target application. Add actions can apply to specific files.

  • Delete/remove: Delete or remove data.

  • Change/update/patch/put/replace: Change and update generally modify existing data. Patch partially updates existing data. Put and replace usually replace the entire existing record.

  • Upsert: Conditionally update data by adding if the data is new and updating if the data already exists.

  • Get/query: Retrieve data. Many get connector actions indicate different information to fetch, such as get invoices.

  • Send: Transmit data to the target system. Unlike add/post/create, a send action can target an external entity such as an email address.

  • Add row/change row: Create new records or modify records on a table or grid of data.

  • Process payment batch: Process multiple payment batches at once.

  • Refresh cache/refresh many: Refresh cache updates a single entry within a cached data object on the platform. Refresh many updates multiple entries within a cached data object on the platform. For example, in Vista Cost Details, Refresh Cache updates the cost details for a single job, while Refresh Many updates the cost details for multiple individual jobs.

  • Run: Execute a process or task, such as running a change order report.

  • Cancel: Stop a process or task executed by a run step. For example, this can be used to disable auto-posting.

  • Lock/unlock: Control access to resources, preventing concurrent modifications.

Note: You can view the JSON schema definition and OpenAPI documentation for an action path by selecting the links below this field. For some actions, you can disable real-time processing, although in most cases you should keep this enabled.

• Enable Retry Policy: This option is off by default. Toggle this option to set a schedule for retrying failed actions. For example, you can enable the retry policy if an action fails because of a timeout. The retry policy provides this kind of error more time to resolve itself. However, the retry policy is unlikely to help if you suspect a more complex underlying issue like bad data. 

Retry Policy

This section only displays if you toggle on the Enable Retry Policy option. Retry policies run additional attempts in a 24-hour window. If this window passes and the action still fails, the flow will move on to the next step.

The retry action feature allows users to automate retrying an action. This assists with known issues that occur in some target systems. For example, this feature is practical when adding a new batch entry for a batch that is still in use by an end user. With the feature disabled, the action would fail and create a user task. With the feature enabled, we can target that failure and retry automatically. This feature is not intended to replace an immediate retry policy, as it has a minimum wait time of 30 minutes. 

To set up the retry policy, enter values in the following fields:

• Error Condition: These parameters must return as true for the retry policy to run. In this field, enter the values that cause the error you want to resolve with a retry.

• Exponential Backoff: This option is off by default. Toggle this option on to double the interval between each attempt. For example, for an interval of one hour, exponential backoff will retry the action after one hour, two hours, four hours, eight hours, etc.

• Interval: Define how frequently you want to retry the action. Choose an interval between 30 minutes and 24 hours.

• Attempts: Enter the number of times you want to retry the action at the interval you defined. The maximum number of attempts for any time interval is five.

Configuration

Depending on what data you post, you can further refine and customize flow step properties. 

• Wait For Response: This option is on by default. In general, you want to keep Wait For Response enabled, as it pauses the flow and waits for the action to complete before continuing on to the next step. 

• Use Existing Body: This option is off by default. When toggled, this lets you define properties in a previous flow step, and then point to that other step (typically a map step). In other words, you use the existing body of a previous step.

The Configuration section is also where you define action properties. The properties listed depend on the connector and action path you choose in the Step Detail section—the property values are mapped to the system to which you are posting data. For details about property values, see Common Code Examples.

Tip: Avoid adding hardcoded values when defining a property. If you need to translate data between connectors, use a Map JSON List or Object step before the Connector Action Step. 

To include additional properties beyond the ones that are required, select the Include checkbox and enter a value to add the property to the configuration. 

Step Outputs

The output of the connector action varies depending on the type of connector action executed, but it is usually the response from the third-party system. For example, the potential outputs of an add action are that the data is added or the action fails. Similarly, the potential outputs of a delete action are that the data is deleted or the action fails. You can confirm the outcome of a connection action by referencing its step status. These are the possible statuses a step can have:

• ACTION_HANDLED_SUCCESSFUL: Occurs when the action is handled successfully (only occurs when Wait For Response is on).

• ACTION_HANDLED_FAILED: Occurs when any of the following conditions are met.

  • Data is entered in the wrong type, which does not match the required schema for the action. 

  • A string is improperly formatted.

  • A bad request is returned from the API.

  • The action is closed as Failed (only occurs when Wait For Response is on).

• QUEUE_ACTION_SUCCESSFUL: Occurs when the action is queued successfully (only occurs when Wait For Response is off).

Action Output

Connector Action operations may cache write data to ensure the cache stays in sync with data changes instead of waiting for a scheduled cache write. While this is best practice to implement this function, it is the responsibility of the connector developer to program the action outcome to do so. Therefore, it may not be in use for your cached data.

Trigger Other Flows on Action Completion

You can use a completed action to trigger another flow. When setting up the trigger, choose the trigger type based on what you want the flow to do. Trigger types include Cache Write, Action Close Out, and On Demand. For more information about when to choose each trigger type, see Triggers. 

Was this helpful? Give us feedback.