Getting Started Guide
---------------------

Prerequisites
~~~~~~~~~~~~~

To get started with the Alteryx Core SDK, You must have a valid
installation of `Alteryx Designer <https://www.alteryx.com/>`__.

Python version 3.6.8 is required for Alteryx Designer plugins.

Setting Up the Development Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creating the Virtual Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To get started, install
`Miniconda3 <https://docs.conda.io/en/latest/miniconda.html>`__ for your
system. Once that is done, open an Anaconda Prompt and create a new
virtual environment:

``conda create -n ayx_plugin_sdk python=3.6.8``

Then you can activate it:

``conda activate ayx_plugin_sdk``

If you are unfamiliar with Anaconda/Miniconda, check out their
`docs <https://docs.anaconda.com/anaconda/user-guide/getting-started/>`__.

Install the Package
^^^^^^^^^^^^^^^^^^^

After creating and activating your virtual environment, pip install the
Alteryx Core SDK pip package.

For more information on pip see the `pip website <https://pypi.org/>`__

Use the following command to install the sdk:

``pip install ayx_plugin_sdk``

Create the *Ayx Plugin Workspace*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now that the Alteryx Python SDK is installed in your virtual environment
packages, we'll create a new `Plugin Tool Workspace*
with default files ready to go. To create a new tool, use the
``create-ayx-plugin`` command.

The command takes the following parameters:
	* ``--name`` (REQUIRED) The name of the new Plugin Tool
	* ``--workspace-directory`` The directory to create the Plugin Workspace
	* ``--tool-type`` The type of tool to create. See the Example Tools for more information.

For this example we'll call our new tool ``MyFirstTool`` and we'll
specify the default directory to ``./tools`` for the Ayx Plugin
Workspace, and we'll use the ``--tool-type passthrough``
parameter to create the new tool with default Input and Output Anchors.

Use the following command:

``ayx_plugin_sdk create-ayx-plugin --name MyFirstTool --tool-type passthrough --workspace-directory tools``

The Workspace Configurations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When a workspace is created, a ``ayx_workspace.json`` file is
generated inside of your workspace directory. This file tracks metadata
related to your workspace. By default you do not need to worry about
this file because it is managed and updated by the CLI commands. For
more advanced workspace users there is customization within the
``ayx_workspace.json`` file that may be useful.

Below is the structure of the configuration file:

.. code:: json

    {
      "tools": [],
      "yxi_name": "",
      "designer_path": null,
      "tool_family_name": "MyTools",
      "requirements_tool": null
    }

Below are descriptions of each field:

``tools``: A list of ``WorkspaceTool`` objects associated with the
project.

Each ``WorkspaceTool`` object contains a name denoting the name of the
tool and looks like this:

``{ name: "MyFirstTool" }``

``yxi_name``: The name of the YXI installer created by the ``create-yxi``
command.

The ``yxi_name`` can include the absolute path to place the yxi file,
however the path must exist.

``designer_path``: This field can be changed to a string to the path of
your designer installation.

If you picked the default User/Admin installation location when you
installed Alteryx Designer, you do not need to worry about populating
that field; the CLI commands will automatically find the default paths
for you.

The ``tool_family_name`` will be used to create the virtual environment and link the
virtual environment to your tools via the tool's
``{tool_name}Config.xml`` file created in each Ayx Plugin Tool
directory.

The ``requirements_tool`` is used to tell the workspace what tool
directory to put the pip wheels and requirements file in. Designer looks
for these wheels and requirements when installing yxi files and linking
your tool's pip dependencies. Generally you shouldn't need to modify the
requirements_tool unless there is a particular Ayx Plugin Tool that you
want to use for the wheels and requirements. If you delete the
requirements_tool using the ``delete-ayx-plugin`` command, the cli will
automatically update the requirements_tool for you.

Build the *Ayx Plugin Tool*
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now you will have a new folder in your current directory called
``tools`` with a sub-directory named ``MyFirstTool``. The Tools
directory is your Ayx Plugin Workspace and is the top
level directory for all of the tools in your YXI
installer package. The ``MyFirstTool`` sub-directory is your Ayx
Plugin Tool directory. This is where all of the files
necessary for Alteryx Designer to integrate with your plugin reside.

Next we're going to build your new Ayx Plugin Tool
into Designer, where you can drag it onto the canvas and connect it to
other Designer Tools. To build ``MyFirstTool`` into the Designer
application use the ``designer-build`` command.

The ``designer-build`` command has the following parameters: -
``--workspace-directory`` - The Ayx Plugin Workspace
directory. - ``--clean`` - removes any previous build files for this
plugin. If you chose the default install location, you do not need to
use this parameter. - ``--force`` - Flag that forces the conda virtual
environment for the Ayx Plugin Tool to be rebuilt. By default, the
``designer-build`` will automatically check for updates to the
environment and rebuild if there are changes.

Use the ``--help`` flag for help using the command.

For this command, we're going to set the following flag: -
``--workspace-directory tools`` - points to the tools folder.

Use this command to build MyFirstTool into Designer:

``ayx_plugin_sdk designer-build --workspace-directory tools``

**Congratulations!**

You just created your first Alteryx Plugin Tool!

You can now open Alteryx Designer and find your new tool in the Tool
Palette.

Removing Tools from Designer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You may create a tool that you did not intend to create or you may have
old tools that you are no longer using. When you want to remove a tool
from your workspace or designer there are a couple of methods available
through the CLI.

You can use the ``delete-ayx-plugin`` command to remove a tool from both
your *Ayx Plugin Workspace* and your Designer Installation.

The following are the arguments for the ``delete-ayx-plugin`` command: -
``--name`` - The name of the tool to be deleted. -
``--workspace-directory`` - The *Ayx Plugin Workspace* directory

You can also use the ``--clean`` flag in the ``designer-build`` to
uninstall all of your tools and your *Tool Family* before rebuilding
them back into designer. That flag is useful if a tool or environment
has been corrupted for any reason.

Create your Production Installer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After you have finished implementing and testing your new *Ayx Plugin
Tool* you may want to distribute it to others. In order to do this, you
must create a YXI installer. The Core SDK CLI provides a
command for packaging your workspace and tools into an installer.

Run the ``create-yxi`` command you'll have a YXI
installer ready for distribution.

The ``create-yxi`` command takes the following arguments: -
``--workspace-directory`` - The *Ayx Plugin Workspace* directory. -
``--yxi-name`` - The name of the yxi installer produced (can also
include a path to another location, as long as the directory exists.)

After you run the ``create-yxi`` command you will have ``.yxi`` file
available for distribution. By default, the name of the yxi produced is
based on the *Ayx Plugin Workspace* directory name but the default can
be overridden using either the ``--yxi-name`` flag or by modifying the
``yxi_name`` field in the ``ayx_workspace.json`` file. (See the
Workspace Configurations section for details)

*Ayx Plugin Tool* Execution in Designer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When Designer runs a tool, it must look for an engine to use. In the
case of our MyFirstTool Python tool, the engine is itself the **python
interpreter**. The interpreter is built out of Anaconda and includes all
of the packages indicated in the ``requirements.txt``.

The *ToolFamily* defined in the Config.xml within the *Ayx Plugin
Workspace* defines the name of the virtual environment created for all
of your *Ayx Plugin Tools*. By default, a *ToolFamily* is set up for
your *Ayx Plugin Workspace* for all of your tools to use. You can use
the ``--standalone-plugin`` flag with the ``create-ayx-plugin`` command
to create a standalone virtual environment specific to the tool. This is
not recommended, particularly if you have multiple tools in your
workspace and will increase your build time significantly.

The YXI installation package includes all of the
interpreter information so the python interpreter can be re-created on
any machine when the tools are installed.

The ``EngineDLLEntryPoint`` within the Config.xml points to the file
that contains a class definition which inherits from ``Plugin``. This
file can be changed at any time to any python file so long as it
contains a ``Plugin`` class that registers with the Alteryx Core SDK.

For a detailed explanation of the Config.xml file, see the
Configuration XML Page.

For information on the ``main.py`` file within your *Ayx Plugin Tool*,
see the Plugin Code Overview Page.

The Configuration Panel GUI
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Alteryx Core SDK examples provide basic Configuration Panel GUIs
however the Core SDK **only** executes the engine (the python side of
the code). Therefore this Getting Started guide will not cover Alteryx
UI development. For more information on Configuration Panel GUI
development, see `Core UI Documenation <https://ayx-ui.pages.git.alteryx.com/ayx-ui/>`__.

**Take Aways:**

If you have come to this guide looking for help on Alteryx GUI
development, then in the famous words of Obi-wan,
``"These are not the droids you're looking for."``

--------------

Glossary
~~~~~~~~

-  ``Ayx Plugin Workspace`` - *YXI* development workspace with
   sub-directories for individual *Ayx Plugin Tools* and plugin tool
   files. The Ayx Plugin Workspace is also used in creating the *YXI*
   installer.
-  ``Ayx Plugin Tool`` - An Alteryx Designer Custom Tool built on the
   Alteryx Core SDK.
-  ``YXI`` - Packaging file and directory system for *Ayx Plugin Tools*.
-  ``Tool Configuration`` - XML configuration file used by both the
   Alteryx Core SDK and Alteryx Designer to read metadata regarding the
   structure of the *Ayx Plugin Tool*.
-  ``Tool Family`` - Shared resources for all *Ayx Plugin Tools* within
   an *Ayx Plugin Workspace*. Tool Families define the name of the
   Virtual Environment, indicates to Designer what virtual environmnet
   interpreter to run for the *Ayx Plugin Tool*, and contains the pip
   installed pip packages defined in the ``requirements.txt`` file.

