How steps work
==============

Every step is a Python class extending ``ipaascore.BaseStep``. HTTP steps go
through :ref:`step-HTTPBaseStep` first, which supplies authentication,
pagination, SSL/mTLS and retry behaviour.

A step declares its configuration parameters in ``__init__`` and implements
``execute()``:

.. code-block:: python

   class MyStep(BaseStep):
       def __init__(self):
           super().__init__()
           self.friendly_name = "My Step"
           self.description = "What this step does"
           self.version = "1.0.0"
           self.add_step_parameter_from_object(some_param)

       def execute(self):
           value = self.get_parameter("param_name")
           upstream = self.get_data_from_step_by_name("step_id")
           self.save_data_for_next_step(result)

Steps communicate through a data pipeline. A step reads its own configuration
with ``get_parameter(...)``, optionally reads a previous step's output, and hands
results downstream with ``save_data_for_next_step(...)``. The "Outputs" section
on each step page describes what that step puts into the pipeline.

For the platform's own account of the step model and the full set of data-passing
functions, see `Creating a Step
<https://docs.sciencelogic.com/skylar_automation/latest/Content/Manuals/Skylar_Automation_Dev/skylar_auto_dev_steps.htm#transferring-data-between-steps>`_
in the Skylar Automation developer documentation. This reference does not repeat
it; it documents what each individual step accepts and returns.

Parameters
----------

Parameters are not declared in the class body or in a method signature -- they
are registered at runtime, either from a shared parameter object or inline:

.. code-block:: python

   # shared, defined once in util/request_params.py and reused across steps
   self.add_step_parameter_from_object(prefix_url_param)

   # step-specific
   self.new_step_parameter(
       name="bearer_token",
       description="Token for authorization",
       required=False,
       param_type=parameter_types.StringParameterShort(password=True),
   )

Never hardcode a parameter name in step logic; reference the parameter object's
``.name`` instead.

Parameter types
---------------

The platform's ``parameter_types`` classes are normalised in this reference as
follows.

.. list-table::
   :header-rows: 1
   :widths: 42 58

   * - Source ``param_type``
     - Documented type
   * - ``StringParameterShort``, ``StringParameterMedium``
     - string
   * - ``StringParameterLong``
     - string (long)
   * - ``NumberParameter``
     - number
   * - ``BoolParameterToggle``, ``BoolParameterCheckbox``
     - boolean
   * - ``JSONParameter``
     - json
   * - ``ArrayParameterString``
     - array of strings
   * - ``SelectStaticDropdownParameter``
     - enum -- allowed values are listed inline
   * - ``JINJA2Parameter``
     - jinja2 template
   * - ``password=True`` on any string type
     - annotated ``(masked)``

Three tiers of parameter
------------------------

Any given step accepts parameters from three places, and each step page shows
only the first:

**Its own**
   What the step registers in its own ``__init__``. This is the table on the step
   page.

**Inherited from its base class**
   For the REST and GraphQL steps, the 30-odd shared HTTP parameters from
   :ref:`step-HTTPBaseStep`. Linked rather than repeated -- otherwise the same
   table would appear on seven pages.

**Platform parameters**
   The ten registered by the platform's ``BaseStep`` itself (``name``, ``file``,
   ``queue``, ``output_to``, ``data_from`` and the five ``retry_*``). Identical on
   every step in every SyncPack, so they live on one page:
   :ref:`platform-parameters`.

So configuring a REST step means reading its own table, plus
:ref:`step-HTTPBaseStep`, plus :ref:`platform-parameters`.

Version introduced
------------------

Two different version numbers appear on each page, and they are not the same
thing:

**Step version**
   The ``self.version`` attribute inside the step class. It is maintained by hand
   and tracks changes to that individual step.

**Introduced in** (the ``versionadded`` marker)
   The SyncPack release the step first shipped in, derived from git history: the
   earliest release tag whose tree contains the step's file. This is the number
   that matters when pinning a SyncPack dependency.

   **This is not a step class attribute.** It exists only in this documentation,
   computed at build time -- you will not find it anywhere in the source, and
   there is nothing to keep up to date.