File Provider¶
The File Provider lets you test a Python SDK tool independent of Alteryx Designer.
Installation¶
Perform these steps to set up your environment correctly:
Activate the base virtual environment.
Run
pip install /path/to/ayx-sdks/gitrepo
.
The -e flag (for example, pip install -e/path/to/ayx-sdks/gitrepo
)
installs in editable mode so that changes made to the repo are
automatically reflected.
Input File Formats¶
The File Provider needs 4 types of input files to run.
Tool Configuration File¶
The tool configuration file contains user input information. In Designer, this information is normally chosen through the SDK’s UI, but in the File Provider these values are set in this configuration file.
An empty configuration file contains only a Configuration
tag,
and a configuration file with user input has a tag corresponding
to each value that a user sets. See the example below.
<Configuration>
<Value>10</Value>
</Configuration>
Workflow Configuration File¶
Each kind of example tool
has its own XML configuration file. The file contains tool information like name, description, input anchors, and output anchors. The input and
output anchor information is found under the InputConnections
and
OutputConnections
tags respectively. Each Connection
corresponds
to 1 anchor. If the AllowMultiple
flag is True
then there can
be multiple connections attached to that anchor.
Metadata File¶
The metadata XML file contains information about each field of the
incoming data. Each field must have a name
, size
, and type
.
name
: The field name.size
: The size of each piece of data in that field.type
: The type of each piece of data in that field.
type
must correspond to 1 of the values in the
FieldType
enum. See the example below:
<RecordInfo>
<Field name="Name" size="254" type="v_string" />
<Field name="Value" size="254" type="double" scale="2" description="the value" source="internet"/>
</RecordInfo>
Record File¶
The record CSV file contains all of the record information. It looks like a CSV file that Designer might use as input. The first row should contain field names corresponding to the name of each field in the metadata file. The rest of the rows should contain the record data. See the example below:
Name,Value
Ten,10
Twenty,20
Thirty,30
Running the File Provider¶
The file provider is run from a command-line argument. The only argument the user must pass in is a path to a JSON file with this format:
tool
: This is a dictionary with 2 keys:plugin
andpath
.plugin
: Contains a string that corresponds to the class plugin name.path
: Contains a string that corresponds to the folder that contains the plugin, in other words,{"plugin": "Example", "path": "path/to/ExampleFolder"}
.
tool\_config
: This is a string that corresponds to the absolute path of the tool’s configuration file, in other words,path/to/ExampleToolConfig.xml
.workflow\_config
: This is a string that corresponds to the absolute path of the workflow’s configuration file, in other words,path/to/ExampleWorkflowConfig.xml
.inputs
: This is a list of dictionaries that contain information about the tool’s input connections. It is optional since not all tools have input. The user should specify input information for each input connection that is associated with this tool. Each input dictionary has 3 keys:anchor_name
,records
, andmetadata
.anchor_name
: Contains a string that corresponds to the name of the input connection’s anchor, which has to match an input anchor name from the associated configuration file.records
: Contains a string that corresponds to the absolute path of the input connection’s record file.metadata
: Contains a string that corresponds to the absolute path of the input connection’s metadata file, in other words,{"anchor_name": "AnchorName", "records": "path/to/InputRecords.csv", "metadata": "path/to/InputMetadata.xml"}
.
outputs
: This is a list of dictionaries that specify where the tool’s output anchor information should be stored. It is optional since not all tools have output. The user should specify output information for each output anchor that is associated with this tool. Each output dictionary has 3 keys:anchor_name
,records
, andmetadata
.anchor_name
: Contains a string that corresponds to the name of the output anchor, which has to match an output anchor name from the associated configuration file.records
: Contains a string that corresponds to the absolute path of where the output anchor record information should be stored.metadata
: Contains a string that corresponds to the absolute path of where the output anchor’s metadata file should be stored, in other words,{"anchor_name": "AnchorName", "records": "path/to/OutputRecords.csv", "metadata": "path/to/OutputMetadata.xml"}
.
update\_tool\_config
: This is an optional path to the updated tool configuration file. If the tool’s configuration changes as the plugin is running, then the tool configuration file must be updated and sent to an output configuration file. This specifies where the updated configuration file should be stored.
Command Line Options¶
ayx_plugin_sdk run --tool path\to\InputInfo.json
python -m ayx_plugin_sdk run --tool path\to\InputInfo.json
In ayx_plugin_sdk folder:
python __main__.py run --tool path\to\InputInfo.json
JSON File Format for Tools with Input Anchors, Input Connections, and Output Anchors¶
This is an input JSON file for a tool with 2 input anchors,
where the first input anchor has 2 input connections connected to it
and the second input anchor has 1 input connection connected to it.
The tool also has 2 output anchors. Each output anchor always has one
output file associated with it. This must correspond with the anchor
information in WorkflowConfig.xml
. Note that in JSON, backslashes
have to be escaped for any absolute file paths.
{
"tool":{
"plugin":"ComplexExample",
"path":"examples/ComplexExample"
},
"tool_config":"path/to/ToolConfig.xml",
"workflow_config":"path/to/WorkflowConfig.xml",
"inputs":[
{
"anchor_name":"Input1",
"records":"path/to/Input11Records.csv",
"metadata":"path/to/Input11Metadata.xml"
},
{
"anchor_name":"Input1",
"records":"path/to/Input12Records.csv",
"metadata":"path/to/Input12Metadata.xml"
},
{
"anchor_name":"Input2",
"records":"path/to/Input2Records.csv",
"metadata":"path/to/Input2Metadata.xml"
}
],
"outputs":[
{
"anchor_name":"Output1",
"records":"path/to/Output1Records.csv",
"metadata":"path/to/Output1Metadata.xml"
},
{
"anchor_name":"Output2",
"records":"path/to/Output2Records.csv",
"metadata":"path/to/Output2Metadata.xml"
}
]
}
JSON File Format for an Output Tool¶
An output tool should have 1 input anchor and no output anchors.
{
"tool":{
"plugin":"OutputExample",
"path":"examples/OutputExample"
},
"tool_config":"path/to/ToolConfig.xml",
"workflow_config":"path/to/WorkflowConfig.xml",
"inputs":[
{
"anchor_name":"Input",
"records":"path/to/InputRecords.csv",
"metadata":"path/to/InputMetadata.xml"
}
]
}
JSON File Format for an Input Tool¶
An input tool should have 1 output anchor and no input anchors.
{
"tool":{
"plugin":"InputExample",
"path":"examples/InputExample"
},
"tool_config":"path/to/ToolConfig.xml",
"workflow_config":"path/to/WorkflowConfig.xml",
"outputs":[
{
"anchor_name":"Output",
"records":"path/to/OutputRecords.csv",
"metadata":"path/to/OutputMetadata.xml"
}
]
}
JSON File Format with an Updated Tool Configuration File¶
This tool has 1 input anchor and 1 output anchor. It also specifies where an updated tool configuration file should go.
{
"tool":{
"plugin":"InputExample",
"path":"examples/InputExample"
},
"tool_config":"path/to/ToolConfig.xml",
"workflow_config":"path/to/WorkflowConfig.xml",
"inputs":[
{
"anchor_name":"Input",
"records":"path/to/InputRecords.csv",
"metadata":"path/to/InputMetadata.xml"
}
],
"outputs":[
{
"anchor_name":"Output",
"records":"path/to/OutputRecords.csv",
"metadata":"path/to/OutputMetadata.xml"
}
],
"update_tool_config":"path/to/OutputToolConfig.xml"
}