**************************
Writing a Snippet Argument
**************************
A :ref:`Snippet Argument <glossary_snip_arg>` provides the
:ref:`execution plan <glossary_exec_plan>` to the
:ref:`Snippet Framework <glossary_sf>` and enables low-code/no-code
collections.

Before writing a Snippet Argument, you must first understand
how to collect the required data and ensure that step(s)
exist for the required tasks. If a step does not exist, determine
if you can chain steps together to get the required result.
After you know what steps to use, then you can write the Snippet
Argument for the given :ref:`Syntax <glossary_syntax>`.

The most basic form of writing a Snippet Argument is through
the ``low_code`` :ref:`Syntax <glossary_syntax>` which we will
use for the examples.


Example: Collecting device names from an AIO SL1 System
-------------------------------------------------------
For this example, we will collect device names from a SL1 system.
The required operations for collecting the data will be as follows:

 * Perform a HTTP request to ``/api/device`` on localhost (due
   to this being an AIO we can use localhost instead of an ip
   address or hostname)
 * Interpret the text response as JSON
 * Convert the results to a python dictionary with the following
   structure:

   .. code-block:: python

      {
          "device_uri": "device_name"
      }

After determining how to collect the data, we then need to determine
if our tasks have existing steps around them. For this scenario,
we will use the following steps:

.. list-table:: Steps for collection
   :header-rows: 1

   * - Operation
     - Step
   * - Perform a HTTP request
     - http
   * - Convert response from JSON
     - json
   * - Convert the result to a dictionary
     - jmespath

Now that we know what steps to use, we will need to determine
what arguments, if any, need to be supplied to the step.


Determining Step Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^
http
""""
After reviewing the available parameters for ``http`` and determining
that we will be specifying the entire URL, we only need to provide
the step with the ``url`` parameter. The username / password
will automatically be consumed from the credential.

.. code-block:: yaml

   http:
     url: http://localhost:80/api/device


json
""""
After reviewing the available parameters for ``json``, we notice
that no parameters are required for this step.

.. code-block:: yaml

   json

jmespath
""""""""
After reviewing the available parameters for ``jmespath``, we determine
that we will need to use ``index`` and ``value`` to construct
our dictionary.

.. note::

   This section is not a deep-dive into jmespath. For additional
   documentation around jmespath, refer to the
   `official documentation <https://jmespath.org/>`_.


.. code-block:: yaml

   jmespath:
     index: true
     value: "values(@)|[].{_index: URI, _value: description}"


Creating the Snippet Argument
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now that we have the steps and their parameters to perform the
collection, we need to write our final Snippet Argument using
the ``low_code`` version 2 Syntax. We will add all our steps
under the ``steps`` section, which takes a list of values.

.. code-block:: yaml

   low_code:
     version: 2
     steps:
       - http:
           url: http://localhost:80/api/device
       - json
       - jmespath:
           index: true
           value: "values(@)|[].{_index: URI, _value: description}"


Example: Collecting aligned organization for a device
-----------------------------------------------------
For this example, we will collect the aligned organization for
a given device. Since part of the URI is dynamic, in this case
the device id, we will utilize :ref:`substitution <substitution>`
that will automatically substitute context-aware information
into the Snippet Argument. The required operations for collecting
the data will be as follows:

 * Perform a HTTP request to ``/api/device/<device_id>`` on
   localhost (due to this being an AIO we can use localhost
   instead of an ip address or hostname)
 * Interpret the text response as JSON
 * Select a value from the dictionary

After determining how to collect the data, we then need to determine
if our tasks have existing steps around them. For this scenario,
we will use the following steps:

.. list-table:: Steps for collection
   :header-rows: 1

   * - Operation
     - Step
   * - Perform a HTTP request
     - http
   * - Convert response from JSON
     - json
   * - Convert the result to a dictionary
     - jmespath

Now that we know what steps to use, we will need to determine
what arguments, if any, need to be supplied to the step.


Determining Step Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^
http
""""
After reviewing the available parameters for ``http`` and determining
that we will be specifying the entire URL, we only need to provide
the step with the ``url`` parameter. The username / password
will automatically be consumed from the credential. Since we
need context-aware information, device id, we will use substitution
to get this information. After referring to the available
:ref:`substitution <substitution>` parameters, we determine
that we will need to use ``${silo_did}`` to construct the
url `http://localhost:80/api/device/1`.

.. code-block:: yaml

   http:
     url: http://localhost:80/api/device/${silo_did}


json
""""
After reviewing the available parameters for ``json``, we notice
that no parameters are required for this step.

.. code-block:: yaml

   json

jmespath
""""""""
After reviewing the available parameters for ``jmespath``, we determine
that we will need to use ``value`` to extract our data.

.. note::

   This section is not a deep-dive into jmespath. For additional
   documentation around jmespath, refer to the
   `official documentation <https://jmespath.org/>`_.


.. code-block:: yaml

   jmespath:
     value: organization


Creating the Snippet Argument
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now that we have the steps and their parameters to perform the
collection, we need to write our final Snippet Argument using
the ``low_code`` version 2 Syntax. We will add all our steps
under the ``steps`` section, which takes a list of values.

.. code-block:: yaml

   low_code:
     version: 2
     steps:
       - http:
           url: http://localhost:80/api/device/${silo_did}
       - json
       - jmespath:
           value: organization

Example: Collection with Custom Substitution
--------------------------------------------
For this example, we will collect the aligned organization for
a given device. Since part of the URI is dynamic, in this case
the device id, we will utilize :ref:`substitution <substitution>`
that will automatically substitute context-aware information
into the Snippet Argument. The required operations for collecting
the data will be as follows:

 * Perform a HTTP request to ``/api/device/<device_id>`` on
   localhost (due to this being an AIO we can use localhost
   instead of an ip address or hostname)
 * Interpret the text response as JSON
 * Select a value from the dictionary

After determining how to collect the data, we then need to determine
if our tasks have existing steps around them. For this scenario,
we will use the following steps:

.. list-table:: Steps for collection
   :header-rows: 1

   * - Operation
     - Step
   * - Perform a HTTP request
     - http
   * - Convert response from JSON
     - json
   * - Convert the result to a dictionary
     - jmespath

Now that we know what steps to use, we will need to determine
what arguments, if any, need to be supplied to the step.

Writing a custom substitution function
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For this example, we want our custom substitution function to
return ``/api/device/<device_id>``. After referring to the
:ref:`Custom Substitution <sub_custom>` document, we can write
a function that returns our string.

.. code-block:: python

   def generate_uri(silo_did):
       return "/api/device/{}".format(silo_did)

We would need to update the default snippet with our new function
too.

.. code-block:: python

  from silo.apps.errors import error_manager
  with error_manager(self):

      from silo.low_code import *
      from silo.apps.collection import create_collections, save_collections

      # =====================================
      # =========== User Editable ===========
      # =====================================
     def generate_uri(silo_did):
         return "/api/device/{}".format(silo_did)

      # List any custom substitutions that need to occur within the snippet arguments
      custom_substitution = {"generate_uri": generate_uri}
      # =====================================
      # ========= End User Editable =========
      # =====================================


      collections = create_collections(self)
      snippet_framework(collections, custom_substitution, snippet_id, app=self)
      save_collections(collections, self)


Determining Step Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^
http
""""
After reviewing the available parameters for ``http`` and determining
that we will be specifying the entire URL, we only need to provide
the step with the ``url`` parameter. The username / password
will automatically be consumed from the credential. Since we
plan on utilizing the custom substitution function to generate
the uri, we will reference that substitution within the ``url``
parameter.

.. code-block:: yaml

   http:
     url: http://localhost:80/${generate_uri}


json
""""
After reviewing the available parameters for ``json``, we notice
that no parameters are required for this step.

.. code-block:: yaml

   json

jmespath
""""""""
After reviewing the available parameters for ``jmespath``, we determine
that we will need to use ``value`` to extract our data.

.. note::

   This section is not a deep-dive into jmespath. For additional
   documentation around jmespath, refer to the
   `official documentation <https://jmespath.org/>`_.


.. code-block:: yaml

   jmespath:
     value: organization


Creating the Snippet Argument
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now that we have the steps and their parameters to perform the
collection, we need to write our final Snippet Argument using
the ``low_code`` version 2 Syntax. We will add all our steps
under the ``steps`` section, which takes a list of values.

.. code-block:: yaml

   low_code:
     version: 2
     steps:
       - http:
           url: http://localhost:80/${generate_uri}
       - json
       - jmespath:
           value: organization