.. _bulk-load-sheet-macro-evaluation:

Bulk load sheet macro evaluation
--------------------------------

.. _19.3.4-PB2|EKB-7466:
.. .. _18.1-Patch-Bundle-3|EKB-154:


Bulk load sheets can be configured to allow for 
macro evaluation. 

The first row of a bulk load sheet has
a variable to enable or disable macro evaluation (see :ref:`bulk-load-sheet-layout`.:

::

  evaluate_macros: {True | False}

* If the variable is set to ``True``, macros in a sheet will be evaluated upon loading.
  In this case, it is important that:

  1. The macro be prefixed with ``fn.bulkload_evaluate``.
  #. A named macro must be used, in other words, a ``data/Macros`` instance.
     Macro functions (``fn.<name>``) cannot be used here.
  #. If the named macro that is used evaluates to a boolean or integer value,
     it will be evaluated and the sheet will be processed with that value.

For example:

1. If the sheet is used to update a site at its hierarchy,
   and the ``evaluate_macros:`` value is set to ``True``
   in the first row, then:

   * The macro ``{{ fn.bulkload_evaluate macro.SITENAME }}``
     will be evaluated to the site name when the sheet is loaded, but inserted as plain text.
   * The macro ``{{ fn.evaluate macro.SITENAME }}`` will be *not*
     evaluated to the site name when the sheet is loaded, but inserted as plain text.
   * The macro ``{{ macro.SITENAME }}`` will be *not*
     evaluated to the site name when the sheet is loaded, but inserted as plain text.
   * The macro ``{{ input.sitename }}`` will be *not*
     evaluated to the site name when the sheet is loaded, but inserted as plain text.
   * Rows containing entries with a *combination* of the type ``{{fn.bulkload_evaluate <named macro> }}``
     and other types macros will *only evaluate* the former type and load others as plain text.
   * Macros (in any format above) entered into the Base columns of a sheet will *not* evaluate -
     for details on the Base columns, see :ref:`bulk-load-sheet-layout`.
#. If the sheet is used to update a site at its hierarchy,
   and the ``evaluate_macros:`` value is set to ``False``
   in the first row, then *all* macros entered will be inserted as plain text.


.. note::

   If the named macro needs to be tested with the macro evaluator,
   the format is  {{ fn.evaluate macro.SITENAME }}.


.. rubric: Related topics 

* See the topic on macros in VOSS Automate documentation for named macro examples.
* For further details, also refer to the Advanced Configuration Guide and Named Macro Reference.