Skip to main content

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.

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.