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:
|
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 | dump
command 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.
Note
These additional capabilities are available through the language, but their implementation in AAC has not been certified. For Nunjucks capabilities not listed on this page, you should experiment with them in a development environment first.
For more information, go to https://mozilla.github.io/nunjucks/templating.html.