Plan Metadata References

In the body and header of HTTP tasks in your plans, you can reference the following elements of metadata from the plan run for additional contextual information.

Note

In a task, you can reference metadata for the overall plan and for tasks that are upstream of the current task. If you have deployed a branching structure to your plan, tasks on one branch cannot reference the metadata for tasks on the other branch. All tasks can reference the metadata for the overall plan run.

General Syntax

All plan metadata references follow the following basic syntax:

{{$plan.path.to.reference}}

All references can be entered with $ in Alteryx Analytics Cloud (AAC). These references are turned into {{$ in the code definition. The double-curly braces form the environment for metadata replacement.
Tip
In AAC, you can start by typing $.
Nodes in the tree are separated with a . period.

Reference values that contain whitespace must be listed in the following manner:

{{$plan.path['path with white space in it'].rest.of.path}}

Notes:

In AAC, you can use double quotes when specifying a whitespace value. However, these double quotes get escaped in the actual request. It is safer and more consistent to use single quotes.

Whitespace values typically appear when referencing the display name values for underlying assets.

$plan References

These references apply to the plan definition or current plan run.

Text to enter:

$plan.

Reference	Description
name	Name of the plan that is run.
duration	Length of time that the plan ran or has run so far. Tip To return a more readable form of this duration value, use the following reference: {{$plan.duration\|humanizeDuration}}
id	Internal identifier for the plan.
startTime	Timestamp for when the plan run began.
url	URL to the plan in AAC.
runId	Internal identifier for this run of the plan.
user	Internal identifier of the user who launched this run.
taskCount	Count of tasks in the plan run.

$http References

These references apply to HTTP tasks in the plan run.

Enter the following, after which you can see the two-letter codes for the HTTP tasks that have already been executed in the current plan run:

$http_ax.

Reference	Description
name	Name of the HTTP task.
status	Current status of the task execution.
duration	Length of time that the task ran or has run so far.
startTime	Timestamp for when the task began. A null value if the task has not begun.
endTime	Timestamp for when the task ended. A null value if it has not ended yet.
statusCode	Status code (if any) returned from the receiving endpoint.
response	Response information. See below.

Response references

These references apply to the response returned as part of the task execution.

Enter the following, after which you can see the two-letter codes for the HTTP tasks that have already been executed in the current plan run:

$http_ax.response.

Reference	Description
body	Body of the response
json	JSON-formatted version of the response
headers	Headers returned with the response

$slack References

You can reference metadata from Slack tasks in the current plan run using the following reference types:

$slack_ax.

Supported metadata is identical to the metadata for HTTP tasks. See the previous section for details.

$workflow References

These references apply to workflow tasks in the plan run.

Enter the following, after which you can see the two-letter codes for the workflow tasks that have already been executed in the current plan run:

$wf.

Reference	Description
name	Name of the workflow task.
status	Current status of the task execution.
duration	Length of time that the task ran or has run so far.
startTime	Timestamp for when the task began. A null value if the task has not begun.
endTime	Timestamp for when the task ended. A null value if it has not ended yet.

$desktopworkflow References

These references apply to desktop workflow tasks in the plan run.

Enter the following, after which you can see the two-letter codes for the workflow tasks that have already been executed in the current plan run:

$designer_desktop.

Reference	Description
name	Name of the flow task.
status	Current status of the task execution.
duration	Length of time that the task ran or has run so far.
startTime	Timestamp for when the task began. A null value if the task has not begun.
endTime	Timestamp for when the task ended. A null value if it has not ended yet.
output URL	URL to access your output in Designer Desktop.

$aidataset References

These references apply to Auto Insights tasks in the plan run.

Enter the following, after which you can see a list of the Auto Insights tasks that have already been executed in the current plan run:

$ai.

Reference	Description
name	Name of the Auto Insights task.
status	Current status of the task execution.
duration	Length of time that the task ran or has run so far.
startTime	Timestamp for when the task began. A null value if the task has not begun.
endTime	Timestamp for when the task ended. A null value if it has not ended yet.

$flow References

These references apply to flow tasks in the plan run.

Enter the following, after which you can see the two-letter codes for the flow tasks that have already been executed in the current plan run:

$flow_ax.

Reference	Description
name	Name of the flow task.
status	Current status of the task execution.
duration	Length of time that the task ran or has run so far.
startTime	Timestamp for when the task began. A null value if the task has not begun.
endTime	Timestamp for when the task ended. A null value if it has not ended yet.
jobIds	Internal identifiers for the jobs that were run as part of this flow task
jobUrl	URL to the job in AAC.
flowName	Name of the flow underlying this flow task
output	Metadata from the flow task's output. See below.
params	Parameters created in the flow can be referenced in the task.

Output references

These references apply to the outputs that are generated in the flow tasks of the plan run.

Enter the following for flow task 7p with output My Output Name:

$flow_7p['My Output Name'].

Reference	Description
name	Name of the flow.
status	Current status of the flow.
duration	Length of time that the flow execution ran or has run so far.
startTime	Timestamp for when the flow execution began. A null value if the run has not begun.
endTime	Timestamp for when the flow execution ended. A null value if it has not ended yet.
lastUpdate	Timestamp for when the flow was last modified.
jobIds	Internal identifier(s) for the job that was run or is running for the flow. Can contain multiple identifiers.
user	Internal identifier for the user who executed the job.
jobType	The type of job that was executed. Values: `manual` - executed through AAC. `scheduled` - executed according to a defined schedule `api` - executed via API
fileSize	If the output generates a file or files, this value captures the size in KB of the output.
environment	Running environment where the job was executed.
columnCount	Count of columns generated in the output.
rowCount	Count of rows generated in the output.
dataTypeCount	Count of Alteryx data types detected in the output.
validValuesCount	Count of valid values in the output.
mismatchedValuesCount	Count of mismatched values in the output.
emptyValuesCount	Count of missing or empty values in the output.
columns	Column information from the selected output for the flow. See below.
sources	Source filename and table information from the imported datasets. See below.
publishing actions	Data on the publishing actions defined for the output. See below.

Output column references

Tip

The metrics calculated for output columns may also appear in profiles of your output data.

These references are available for output columns in the following syntax:

$flow_7p['My Output Name'].output.

Reference	Description
name	Column name
type	Data type of column
validValuesCount	Count of valid values in the column
mismatchedValuesCount	Count of mismatched values in the column
emptyValuesCount	Count of empty values in the column
topValues	List of top values in the column
minimumValue	Lowest value in the column
lowerQuartileValue	25th percentile value in the column
medianValue	50th percentile value in the column
upperQuartileValue	75th percentile value in the column
maximumValue	Maximum value in the column

Sources references

These references apply to the datasource files or tables that were used to generate the output.

Reference	Description
name	Name of the datasource file or table.

Publishing actions references

These references apply to the publishing actions defined for the output.

Reference	Description
name	Name of the publishing action.
action	Definition of the publishing action.
location	Location where the publishing action is published.
type	Type of publishing action.

Exploring Metadata

You can use the following functions and techniques to further explore the metadata returned from your plan execution.

Metadata functions

The following functions can be applied to select metadata references to further filter the raw values.

humanizeDuration

In raw form, the duration metadata references return values that look like the following:

PT7.523S

You can apply the HumanizeDuration function to render the above into a more readable format:

{{ $plan.duration | humanizeDuration }}

The output of the above applied to the first value is the following:

7.523 seconds

uuid

You can generate a universally unique identifier, which can be delivered as part of a messaging payload:

{{ uuid() }}

Metadata structure

Some metadata references return complex or nested objects, which may return data that looks like the following:

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

In these cases, the nested data inside the object is not exposed by the basic reference. To explore further, you can use either of the following solutions:

Text: Create a for loop through the returned objects:

{% for value in $flow_6f.Job.columns.MyColumnName.topValues %}[{{value.key}}, {{value.count}}] {% endfor %}

JSON: add the | dumpcommand to the end of your reference. You can modify the following example reference and try to insert in the Body textbox:

{{$flow_6f.Job.columns.MyColumnName.topValues | dump | replace('"', '\"')}}

Tip

When the data is returned, you can use loop structures to retrieve specific values for display.

For more information, go to https://mozilla.github.io/nunjucks/templating.html#dump.

Parameter References

Flow parameters

To reference flow parameters as part of a flow task, use the following pattern:

$plan.params.<myParamName>

Environment parameters

You can reference environment parameters by name in your plan task metadata. For example:

env.MyEnvironmentParameter1

Additional References

Plan metadata reference information leverages the Nunjucks templating language, which provides additional capabilities such as loops, conditions, filters, and helper functions.