Datapills

Datapills are output data from a trigger or action step. They serve as variables that enable you to map business logic into recipe steps. For example, when you create a Zendesk organization from a Salesforce account, you can map datapills from the new Salesforce account trigger to fields in the Zendesk organization within your recipe actions.

Datapills appear in the datatree, within the Recipe data section. At any specific recipe step, the Recipe data section holds the output from the trigger and all preceding actions.

Datatree within a recipe step

You can expand the Recipe data menu in the recipe editor.

Expand the Recipe data menu

AUTOMATION INSTITUTE

Try out the hands-on tutorial on working with datapills at Workato's Automation Institute. Complete the course (opens new window) and become a certified Automation Pro.

Default datapills

Every job contains a default set of datapills. You can access them by expanding the Properties datatree.

Default datapills for all Recipes

Datapill	Description
User ID	The unique identifier for the user. In a workspace, this corresponds to the workspace ID.
User name	The name of the user. In a workspace, this corresponds to the workspace name.
User email	The email address of the user. In a workspace, this corresponds to the workspace email.
Recipe ID	The unique identifier for the recipe.
Recipe URL	A URL link to the recipe.
Recipe name	The name of the recipe.
Recipe path	The directory path where the recipe is stored.
Job ID	The unique identifier for the job.
Job URL	A URL link to the job report.
Job created at	The date and time when the job was created.
Master job ID	The initial job ID if the job is repeated.
Calling recipe ID	The ID of the recipe that triggered this job, if applicable.
Calling job ID	The ID of the job that triggered this job, if applicable.
Is repeat	Indicates whether the job is a repeated job.
Is test	Indicates whether the job is a test job.
Repeat count	The number of times the job has been repeated.
Repeated job? deprecated	This field is deprecated. Use Is repeat instead. Indicates whether the job is repeated.
Parent job ID deprecated	This field is deprecated. Use Master job ID instead. The initial job ID if the job is repeated.

On error datapills

When you add a handle errors step to your recipe, Workato generates the following error-related datapills if an error occurs. This enables you to configure your recipe to handle recipe errors differently depending on the error type, message, source (recipe step, action, or app), and more.

Learn more about error handling best practices.

Datapill	Description
Error type	The type of error that occurred.
Error message	A message describing the error.
Retry count	The number of times Workato tried to rerun the actions in the handle errors block.
Error UUID	The Universally Unique Identifier (UUID) of the error. This is a 128-bit label used to identify the error.
Errored step number	The step on which the error occurred.
Errored app	The app that caused the error.
Errored action	The action on which the error occurred.

Data types

Video guide: Data tree, data mapping, and data types

Datapills can be of the following data types:

• String
• Integer or number
• Date or datetime
• Array/hash (list)
• Object
• Boolean

When mapping datapills, ensure they are type-compatible to avoid issues. Workato performs default type conversions when possible, provided there is no ambiguity or loss of information.

You can also transform data by opening the recipe steps in formula mode. This enables you to perform more advanced data manipulation.

Root-level datapills

Root-level datapills are available for all triggers and actions. You can access them after selecting formula mode in a recipe step input field.

Trigger output datapill

These datapills provide the complete output schema of a trigger or action. You can use them with formulas such as .to_json for formatting or with .pluck to extract specific data or keys.

Type conversions

You can convert specific data types using formulas. For example, you can convert a text string of numbers into an integer for arithmetic operations or transform a datetime expressed as a string into a proper datetime type.

Commonly used type conversion formulas include the following:

• to_currency
• to_date
• to_f
• to_i
• to_s
• to_time

Use the formula editor to explore the other type conversions.

Finding type conversions in formula mode

Preview data

Workato displays sample data retrieved from your account alongside datapills to help you better understand the data in your app.

Sample data appears in italic type next to the datapills:

Output datatree for New Salesforce account trigger

Fields mapping

Fields mapping is the assignment of datapills (variables) or absolute values (constants) into action or trigger input fields. This controls the flow of data between apps.

By mapping fields from a Salesforce account (from a trigger) to a Zendesk Create organization action, you can ensure that the Zendesk organization and Salesforce account have the same data.

In each recipe step, you can access datapills from all previous steps to configure the input fields of the current step.

Example

In the following example, we map the Account Name datapill from the Salesforce New account trigger into the Message input field in the Send email action.

Mapping the account name datapill into the message input field

Mapping constants versus mapping variables

Workato input fields accept variables (datapills) or constants (fixed values).

Mapping variables

In this example, the variable Account Name is mapped to the Name input field. This means that for each new Salesforce account created, the account name is used as the organization name in Zendesk. For example, if a new Salesforce account named Sattei Winery is created, the recipe creates a Zendesk organization with the same name.

Input field with variable mapping

Mapping constants

In this example, the Notes input field has a constant value mapped to it: Synced over from Salesforce. This means that every Zendesk organization created through Workato has this text in its Notes field.

Input field with constant mapping

The result is a new Zendesk organization created using both variable and constant mapping:

Newly created Zendesk organization Sattei Winery

Mapping both constants and variables

You can also combine constants and variables in input fields to customize the data as needed.

Example

This example recipe sends a welcome email to each Salesforce lead who has signed up for a mailing list.

Recipe that sends a welcome email to new Salesforce leads. Example recipe (opens new window)

In the Send email action, datapills from the New Salesforce lead datatree are mapped into the input fields.

Example of datapills being mapped into an action step

Because datapills are variables, their value depends on a specific trigger event or action. In this example, the value assigned in the To input field depends on the value of Email in each new lead.

The recipe reads the First name (Betty) and Email ([email protected]) from the new lead and sends the following email:

To: [email protected]

Hi Betty,

Thanks for joining our mailing list! We're excited to have you!

Mapping fields not defined as datapills in step output

Some scenarios can require you to access a field that isn't directly available as a datapill in the step's output.

Example

Consider a recipe using the Webhooks connector, triggered by an HTTP webhook that accepts Query params A and B.

In this recipe, a Logger by Workato action logs a message. You plan to map parameter C to the Message field, but C doesn't appear as a datapill in the datatree. This happens when a parameter is included in the step output payload but isn't defined in the webhook schema.

Mapping hidden datapills

Follow these steps to access fields from the step output payload that aren't shown in the datatree:

1

Identify the field you plan to map that isn't shown in the datatree (for example, parameter C).

2

In the input field where you plan to map the parameter, map the parent object datapill (for example, Params).

3

Append the specific field name in brackets to the parent object datapill. For example, use Params['C'] to access parameter C.

Append the specific field name in brackets

Data transformation

Sometimes the data fields from one app don't directly map into a data field for a different app. For example:

• Your sales app stores names in a single field Full name, but your marketing app uses two fields First name and Last name
• Your e-commerce app stores addresses as the individual fields Address line 1, Address line 2, City, State, but your accounting app only accepts a single Billing address field
• The priority levels in your ticketing app are stored as Low, Medium, and High, but in your sales system they are Low, Normal, and Urgent

In such cases, you can take advantage of Workato's data transformation capabilities by using formulas.

Common issues when mapping fields

Common errors you can encounter during fields mapping include the following:

Required fields that have no values at run-time

At design-time (when building the recipe), you must map all required fields. If a required field is left empty, the recipe does not start and throws an error.

However, even if an input field is mapped at design-time, it might not have a value at run-time (when a trigger event occurs and a job is processed). If a required field does not have a value at run-time, the job throws an error and fails.

You must decide on an appropriate response to handle such scenarios. If the missing value represents a business logic error that requires resolution, you might let the job fail and flag the issue for further action. For example, if a recipe attempts to move a new lead from a sales app but finds that the Email address is empty, the recipe should address this according to your business logic.

Datapills from the wrong datatree

When mapping input fields using datapills, you can encounter datapills with identical names in the datatree (for example, Email in Salesforce and Email in Zendesk). Verify that you are mapping the correct datapills from the relevant steps to avoid confusion and ensure accurate data handling.

Datapills from the wrong part of the recipe

If your recipe includes conditional steps, each job can have unprocessed steps. Consequently, the values in the datatree for these steps are likely blank.

When using datapills from these steps, be aware that they can be null.