Zero, Unset, Boolean, Drop, Null and Exists Functions
-----------------------------------------------------


.. index:: Macro function;fn.zero
.. index:: Macro function;fn.unset
.. index:: Macro function;fn.true
.. index:: Macro function;fn.false



+----------------+----------------------------+---------------------------------+--------------------+
| Function       | Description                |  Example                        | Output or Result   |
+================+============================+=================================+====================+
|                |                            | ::                              | ::                 |
|                |                            |                                 |                    |
| fn.zero        | Return a zero value.       |    {{fn.zero}}                  |    0               |
+----------------+----------------------------+---------------------------------+--------------------+
|                |                            | ::                              | ::                 |
|                |                            |                                 |                    |
| fn.unset       | Return an empty string.    |    {{fn.unset}}                 |    ''              |
+----------------+----------------------------+---------------------------------+--------------------+
|                |                            | ::                              | ::                 |
|                |                            |                                 |                    |
| fn.true        | Return a boolean True.     |    {{fn.true}}                  |    true            |
+----------------+----------------------------+---------------------------------+--------------------+
|                |                            | ::                              | ::                 |
|                |                            |                                 |                    |
| fn.false       | Return a boolean False.    |    {{fn.false}}                 |    false           |
+----------------+----------------------------+---------------------------------+--------------------+


Given input context:

1. ``{"input": {"field1": {"key1": "value1"}}}``
2. ``{"input": {"field1": None}}``
3. ``{"input": {"field1": ""}}``



.. index:: Macro function;fn.is_none_or_empty

+---------------------+-------------------------------------------------------------+--------------------------+------------------+
| Function            | Description                                                 |  Example                 | Input and Result |
+=====================+=============================================================+==========================+==================+
| fn.is_none_or_empty | Return a boolean if the argument is None or an empty string | ::                       | input 1.         |
|                     |                                                             |                          |                  |
|                     |                                                             |                          | ::               |
|                     |                                                             |    {{fn.is_none_or_empty |                  |
|                     |                                                             |       input.field1}}     |    false         |
|                     |                                                             |                          |                  |
|                     |                                                             |                          | input 2.         |
|                     |                                                             |                          |                  |
|                     |                                                             |                          | ::               |
|                     |                                                             |                          |                  |
|                     |                                                             |                          |    true          |
|                     |                                                             |                          |                  |
|                     |                                                             |                          | input 3.         |
|                     |                                                             |                          |                  |
|                     |                                                             |                          | ::               |
|                     |                                                             |                          |                  |
|                     |                                                             |                          |    true          |
|                     |                                                             |                          |                  |
+---------------------+-------------------------------------------------------------+--------------------------+------------------+


Given input context:

::

   {
    "input": {
      "test": null
    }
   }


.. index:: Macro function;fn.null

+----------------+----------------------------+---------------------------------+--------------------+
| Function       | Description                |  Example                        | Output or Result   |
+================+============================+=================================+====================+
| fn.null        | Returns Null. Useful in    |  ::                             | ::                 |
|                | comparison tests.          |                                 |                    |
|                |                            |     (( input.test ==            |    true            |
|                |                            |        fn.null ))               |                    |
|                |                            |                                 |                    |
+----------------+----------------------------+---------------------------------+--------------------+

.. index:: Macro function;fn.drop
.. index:: Macro function;fn.force_null

+----------------+----------------------------+----------------------------------+--------------------------------+
| Function       | Description                |  Example                         | Output or Result               |
+================+============================+==================================+================================+
|                |                            | ::                               |                                |
|                |                            |                                  |                                |
| fn.drop        | Removes the attribute from |    {'name':                      | Attribute as in existing data  |
|                | CFT                        |     '{{fn.drop}}'}               |                                |
|                |                            |                                  |                                |
+----------------+----------------------------+----------------------------------+--------------------------------+
|                |                            | ::                               | ::                             |
|                |                            |                                  |                                |
| fn.force_null  | Attribute has Null value   |    {'name':                      |    {'name': None}              |
|                |                            |   '{{fn.force_null}}'}           |                                |
|                |                            |                                  |                                |
+----------------+----------------------------+----------------------------------+--------------------------------+

Useful in Configuration Templates (CFT):

Function ``fn.drop`` in a CFT will drop a value from the input data 
when it is processed through a CFT. Input data without the dropped field is then
overlaid onto the existing model data by the workflow code. 
The final payload data for the value will thus *remain the same* as in the
existing model data.

Example of ``fn.drop`` in an if-then-else test from a CFT of a workflow:

::
  
   "ldapDirectoryName": "(( input.cucm_user_ldapDirectoryName != '' )) 
     <{{ input.cucm_user_ldapDirectoryName }}> 
     <{{ fn.drop }}"



.. index:: Macro function;fn.drop_from_payload

+----------------------+------------------------------------+---------------------------------+-------------------+
| Function             | Description                        |  Example                        | Output or Result  |
+======================+====================================+=================================+===================+
|                      |                                    | ::                              |                   |
|                      |                                    |                                 |                   |
| fn.drop_from_payload | Removes the attribute from payload |    {'name':                     | Attribute "blank" |
|                      |                                    |     '{{fn.drop_from_payload}}'} |                   |
|                      |                                    |                                 |                   |
+----------------------+------------------------------------+---------------------------------+-------------------+

Useful in Configuration Templates (CFT): 

Function `fn.drop_from_payload` forces a field to not be present in the final payload data.
Used in a CFT, it will drop a value from the existing model data *after*
the input data is overlaid onto the existing model data. The value is then not present,
i.e. "blanked".

Example of ``fn.drop_from_payload`` in a CFT so that attributes
are blanked:

::

   {
     "meta": {},
     "resources": [
       {
         "data": {
           "name": "ConvertCUCUserCFT",
           "target_model_type": "device/cuc/User",
           "template": {
             "LdapType": "0",
             "LdapCcmUserId": "{{ fn.drop_from_payload }}",
             "LdapCcmPkid": "{{ fn.drop_from_payload }}"
           }
         },
         "meta": {
           "model_type": "data/ConfigurationTemplate",
           "system_resource": true,
           "tags": [
             "convertusertype"
           ]
         }
       }
     ]
   }
   

.. index:: Macro function;fn.exists


Given input context:

1. ``{"input": {"field1": {"key1": "value1"}}}``
2. ``{"input": {"field1": {"key1": null}}}``
3. ``{"input": {"field1": ""}}``


+-----------+---------------------------------------+----------------------------+------------------+
| Function  | Description                           |  Example                   | Input and Result |
+===========+=======================================+============================+==================+
| fn.exists | Return a boolean true if the argument | ::                         | input 1.         |
|           | is exits and has a non-null value.    |                            |                  |
|           |                                       |                            | ::               |
|           |                                       |    {{ fn.exists            |                  |
|           |                                       |       input.field1.key1 }} |    true          |
|           |                                       |                            |                  |
|           |                                       |                            | input 2.         |
|           |                                       |                            |                  |
|           |                                       |                            | ::               |
|           |                                       |                            |                  |
|           |                                       |                            |    false         |
|           |                                       |                            |                  |
|           |                                       |                            | input 3.         |
|           |                                       |                            |                  |
|           |                                       |                            | ::               |
|           |                                       |                            |                  |
|           |                                       |                            |    false         |
|           |                                       |                            |                  |
+-----------+---------------------------------------+----------------------------+------------------+
|           |                                       |                            | input 1, 2, 3    |
|           |                                       |                            |                  |
| fn.exists | If the *argument does not exist*, it  | ::                         | ::               |
|           | is interpreted as a string  - which   |                            |                  |
|           | is interpretable, so the function     |    {{ fn.exists            |    true          |
|           | returns true.                         |       field.key }}         |                  |
|           |                                       |                            |                  |
+-----------+---------------------------------------+----------------------------+------------------+




.. |VOSS-4-UC| replace:: VOSS-4-UC
.. |Unified CM| replace:: Unified CM