The File Provider

The file provider lets the user test a Python SDK tool independent of Alteryx Designer.

Installation

Perform the steps below to get your environment set up correctly: 1. Activate the base virtual environment 2. Run pip install /path/to/ayx-python-sdk/gitrepo

The -e flag (i.e. pip install -e/path/to/ayx-python-sdk/gitrepo) installs in editable mode so that changes made to the repo are automatically reflected.

Input File Formats

The file provider needs 4 kinds of input files to run.

Tool configuration file

The tool configuration file contains user input information. In Designer, this information would normally be chosen through the SDK’s UI, but in the file provider these values are set in this configuration file. An empty configuration file just contains a Configuration tag, and a configuration file with user input will have a tag corresponding to each value that a user sets. An example tool configuration file can be found here.

Workflow configuration file

Each kind of example tool has it’s own XML configuration file. It contains tool information such as 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 one 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 is the field name, size is the size of each piece of data in that field, and type is the type of each piece of data in that field. type must correspond to one of the values in the FieldType Enum. An example metadata file can be found here.

Record file

The record CSV file contains all of the record information. It looks like a CSV file that Designer might use as input. It’s 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. An example record file can be found here.

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 the following format: 1. tool: This is a dictionary with 2 keys: plugin and path. plugin contains a string corresponding to the class plugin name and path contains a string corresponding to the folder that contains the plugin i.e. {"plugin": "Example", "path": "path/to/ExampleFolder"} 2. tool_config: This is a string corresponding to the absolute path of the tool’s configuration file i.e. path/to/ExampleToolConfig.xml 3. workflow_config: This is a string corresponding to the absolute path of the workflow’s configuration file i.e. path/to/ExampleWorkflowConfig.xml 4. 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, and metadata. anchor_name contains a string corresponding 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 corresponding to the absolute path of the input connection’s record file, and metadata contains a string corresponding to the absolute path of the input connection’s metadata file i.e. {"anchor_name": "AnchorName", "records": "path/to/InputRecords.csv", "metadata": "path/to/InputMetadata.xml"} 5. 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, and metadata. anchor_name contains a string corresponding to the name of the output anchor, which has to match an output anchor name from the associated configuration file. records contains a string corresponding to the absolute path of where the output anchor record information should be stored, and metadata contains a string corresponding to the absolute path of where the output anchor’s metadata file should be stored i.e. {"anchor_name": "AnchorName", "records": "path/to/OutputRecords.csv", "metadata": "path/to/OutputMetadata.xml"} 6. 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 would be an input JSON file for a tool with two input anchors, where the first input anchor has two input connections connected to it and the second input anchor has one input connection connected to it. The tool also has two 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 one 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 one 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 one input anchor and one 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"
}