The purpose of an action template is to convert an event into one or more RESTful API, DXL, and Syslog messages that are sent from the NIOS appliance to the endpoint configured in the notification rule. An action template consists of a series of statements that are interpreted into specific actions. When creating an action template, ensure that it consists of an initial section with some general template settings, followed by one or more steps that are executed in sequence. Steps are constructed for sending messages to the endpoint and for receiving responses. It can also perform specific operations on template variables.

Consider the following guidelines while composing action templates:

• Template error handling is active only if the severity level for logging is set to Debug, otherwise error handling is disabled and the server continues to execute a template even if the template tries to access nonexistent variables or perform invalid operations such as trying to increment a STRING variable. For information about setting the severity level for logging, see Configuring Outbound Notifications. If you have disabled template error handling, then accessing any nonexistent variables will return an empty string and invalid operations are not executed.
• Matching a regular expression is performed un-anchored. If anchoring is required, you must add the characters ^ and/or $ to the respective regular expression.
• For outbound notifications, only template instances are considered. Template instances are constructed from action templates as well as template instance variables in the template. You may configure these variables through Grid Manager when a specific template is associated to an event.

• You can use functions that contain the list of steps to be executed. The FUNCTION operation executes the steps in the function.

• Note that the function steps use step execution limit. Step counters for functions are removed when you return to template steps from function steps.

• You must specify the list of functions in the event template and these functions can be used only by the event template.

• Jumping between functions and template steps is not supported.

• Infoblox supports unused functions and allows execution of a function that is located within a function, including itself.

• You cannot upload or update a template if the function does not exist.

An action template consists of the variables and elements listed in the Action template Variables table blow.

Action Template Variables

Action template Variables

STEP Struct

Each step can perform a different operation, such as SLEEP, CONDITION, NOP, GET, POST, PATCH, DELETE, DXL_EVENT_SEND, or PUT. The STEP Structs table below, lists the step variables.

• SLEEP: Steps with a SLEEP operation will pause the execution for the number of seconds specified in the timeout parameter.
• NOP: Steps with a NOP operation will only parse the text specified in body/body_list without sending it to the endpoint. This can be useful for executing operations on variables to prepare data for subsequent steps.
• CONDITION: Steps with a CONDITION operation will cause a condition specified in statements to be matched. See CONDITION Structs table below, for information about condition variables and STATEMENT Structs table below, for statement variables.

If the condition matches, the execution of the template will do the following:

• • Stop without errors If the stop field is present,
  • Stop with an errors if the error field is present,
  • Jump forward to the specified step if the next field is present,
  • and/or evaluate the text in eval if the field is present.

If the condition does not match, the text in the else_eval field will be evaluated instead, if the field is present.

• GET, POST, PATCH, DELETE, and PUT: These steps will result in an endpoint communication. The request will be sent to an URI composed by the URI configured in the endpoint, plus the path configured in the session management template if present (or replaced by it, depending on its override setting), plus the path configured in the event template if present (same override considerations), plus the path configured in the individual step if present (same override considerations).
  After variable substitution, any data present in the H: namespace will be sent as headers, any parameters listed will be sent as URI parameters, and any data in body/body_list will be sent as the body of the request. Note also that each step can override the endpoint timeout. This is useful when a certain operation is known to require a longer execution time.
  If the result variable is set in the step, the reply from the server will be evaluated and compared against the specified codes and/or REGEX, and the operation specified in the result step will be executed.
  If parse is set in the step, the result from the server will also be parsed and be made available in the P: namespace as described above.

 STEP Structs

VARIABLEOP Struct

Note that all fields are optional, except operation and typeNo schema validation is made for variable combinations. Validation of the schema is performed when you add or modify the action template., no specific JSON schema validation is made for variable combinations as it would be too complex, the validation will be done at template conversion time (which is still done when users upload / edit templates).

VARIABLEOP Struct

Using the COMPOSITE Type

When you use COMPOSITE as the type in the VARIABLE struct, the list of key/value pairs in keys and values is put in an XMLA dictionary with a name set to name and a value set to either the value in composite_value OR to the value in the variable set in source.

Here is an example of using COMPOSITE as the type when you use the following variables and values:

It results in the following:

{

   "<xmla>": true,

   "attrs": {

      "a1": "value is 123",

      "a2": "2",

   },

   "index": {},

   "value": ["123"],

   "name": "varname"

}

Using OPERATION in the VARIABLE Struct

operation ASSIGN

If operation is set to ASSIGN, the value in type will be simply put in the variable identified by destination, overwriting any value it might already have.

The following are several examples of the ASSIGN operation having namespace E as follows:

{

  'some_field': 'some_value',

  'some_list': ['item1', 'item2']

}

(1) When assigning a single value:

{

  'operation': 'ASSIGN',

  'type': 'SINGLE',

  'destination': 'L:var',

  'values': ['value']

}

It returns name space L as follows:

{'var': 'value'}

(2) When assigning a list:

{

  'operation': 'ASSIGN',

  'type': 'LIST',

  'destination': 'L:list',

  'values': ['value', '${E:A:some_field}']

}

It returns the following:

{'list': ['value', 'some_value']}

(3) When assigning a dictionary:

{

  'operation': 'ASSIGN',

  'type': 'DICTIONARY',

  'destination': 'L:dict',

  'keys': ['${E:A:some_field}_1', '${E:A:some_field}_2'],

  'values': ['${E:A:some_list[0]}', '${E:A:some_list[1]}']

}

It returns the following:

{'dict': {'some_value_2': 'item2', 'some_value_1': 'item1'}}

(4) When assigning a composite value, as follows:

{

  'operation': 'ASSIGN',

  'type': 'COMPOSITE',

  'destination': 'L:composite',

  'name': 'tag_name',

  'keys': ['attr_1', 'attr_2'],

  'values': ['${E:A:some_field}', 'another_value'],

  'composite_value': 'tag_content'

}

It gives the following:

{'composite': {

  'index': {}, '<xmla>': True,

  'attrs': {

    'attr_2': 'another_value',

    'attr_1': 'some_value'

  },

  'value': ['tag_content'],

  'name': 'tag_name'

}}

This composite value can be serialized to the following XML:

<tag_name attr_1="some_value" attr_2="another_value">tag_content</tagname>

operation PUSH and SHIFT without setting if_exists

If destination_key is set, the assumption is to push or shift to a dictionary; otherwise, it is to push or shift to a list.

For pushing to a list, if the destination variable exists and is a list, the list of values in values will be added to the existing list. With PUSH, it means that the values will be added to the right side of the list (at the end) of the list. With SHIFT however, the values will be added to the left side (at the beginning) of th list.

If the destination variable is a dictionary, it will be converted to a list that contains only one element with the value appended to it. This means that for XML deserializing and JSON values, it is possible to create a list by pushing it on to an existing scalar value.

For pushing to a dictionary, it means that with destination_key set, if the destination variable exists and is anything but a dictionary, it is considered as an error. If it is a dictionary however, the value above will be added with its key set to destination_key overwriting any existing value.

If the variable denoted by destination has a composite value, the COMPOSITE type can be pushed or shifted to it only. If the destination composite value contains text, the text will be replaced with the composite value. In other cases, the PUSH operation using the new value will be added to the right side of the children list. For the SHIFT operation, the new value will be added to the left side of the children list.

The following are several examples of the ASSIGN operation having namespace E:

{'some_field': 'some_value'}

and namespace L as follows:

{

   'some_list': ['item1', 'item2'],

   'some_dict': {'key': 'val'},

   'comp1': {

     'index': {}, '<xmla>': True,

     'attrs': {

        'attr1_b': 'another_value',

        'attr1_a': 'some_value'

     },

     'value': ['tag_1_content'],

     'name': 'tag_1'

   },

   'comp2': {

     'index': {}, '<xmla>': True,

     'attrs': {},

     'value': ['tag_2_content'],

     'name': 'tag_2'

   }

}

(1) When PUSH or SHIFT to a list:

{

   'operation': 'PUSH',

   'type': 'SINGLE',

   'destination': 'L:some_list',

   'values': ['${E:A:some_field}_right'],

},

{

   'operation': 'SHIFT',

   'type': 'LIST',

   'destination': 'L:some_list',

   'values': ['left_${E:A:some_field}']

},

It returns namespace L as the following:

{'some_list': [['left_some_value'], 'item1', 'item2', 'some_value_right']}

(2) When PUSH or SHIFT to a dictionary, it returns the following:

{'some_dict': {

  'push1': 'item',

  'push2': ['item_1', 'item_2'],

  'key': 'val'

}}

Note: There is no difference between PUSH and SHIFT when destination is DICTIONARY.

(3) When PUSH or SHIFT to a composite value:

{

   'operation': 'PUSH',

   'type': 'COMPOSITE',

   'destination': 'L:comp1',

   'name': 'pushed',

   'composite_value': ''

},

{

   'operation': 'SHIFT',

   'type': 'COMPOSITE',

   'destination': 'L:comp1',

   'source': 'L:comp2'

},

It returns the following:

{

   'comp1': {

   'index': {u'pushed': 1, 'tag_2': 0},

   '<xmla>': True,

   'attrs': {'attr1_a': 'some_value', 'attr1_b': 'another_value'},

   'value': [

     {'index': {}, '<xmla>': True, 'attrs': {}, 'value': ['tag_2_content'], 'name': 'tag_2'},

     {'index': {}, '<xmla>': True, 'attrs': {'attr': 'val'}, 'value': [], 'name': 'pushed'}

   ],

   'name': 'tag_1'

  }

}

Note that the first operation (PUSH) overwrites existing value and the second operation (SHIFT) shifts the value to the existing list. This composite value can be serialized to the following XML:

<tag_1 attr1_a="some_value" attr1_b="another_value">

  <tag_2>tag_2_content</tag_2>

  <pushed attr="val"/>

</tag_1>

operation PUSH and SHIFT with if_exist set

If destination_key is set, the assumption is to push or shift to a dictionary. Otherwise it is to push or shift to a list.

If you are pushing to a list, and the variable already exists, the operation specified there will be executed as follows: SKIP will not modify the original value, NEXT will not modify and jump to the step specified in if_exists_next, and ERROR will instead return an error.

If you are pushing to a dictionary, and the variable matches, there is no need to modify the values because they would already be the same. Therefore, SKIP will be a no-operation, NEXT will not modify and jump to the step specified in if_exists_next, and ERROR will instead return an error.

The decision for whether a new value exists or not is a simple comparison with the value/attributes of the existing variables in the list or dictionary in destination_key. They all have to match for if_exists for the operation to be triggered.

If variable denoted by destination has a composite value, the semantics is as above, with additional checks. The check is complete before the value is added to the list of children. During the check, the new composite value is compared one by one with the existing values. If the values are the same, the “if_exists” logic is triggered as above.

The following are a few examples using namespace L as follows:

{

   'some_list': ['item1', 'item2'],

   'some_dict': {'key1': 'val1', 'key2': 'val2'},

   'list_of_lists': [['a', 'b'], ['a', '2'], ['1', '2']],

   'composite': {

     '<xmla>': True,

     'index': {'inner_1': 0, 'inner_2': 1},

     'name': 'outer',

     'attrs': {'outer_attr': 'outer_val'},

     'value': [

       {

          '<xmla>': True,

          'index': {},

          'name': 'inner_1',

          'attrs': {},

          'value': ['inner_1_content']

       },

       {

          '<xmla>': True,

          'index': {},

          'name': 'inner_2',

          'attrs': {'inner_attr': 'inner_val'},

          'value': []

       }

     ]

  }

}

(1) When PUSH to a list with the item exists:

{

   'operation': 'PUSH',

   'type': 'SINGLE',

   'destination': 'L:some_list',

   'values': ['item2'],

   'if_exists': 'ERROR'

}

It triggers the ‘if_exits’ login. ‘ERROR’ means stopping the template execution with error, ‘SKIP’ means ‘do nothing for this operation’ and ‘NEXT’ will jump to the step with name specified in ‘if_exists_next’.

(2) When PUSH to a dictionary with the item exists:

{

   'operation': 'PUSH',

   'type': 'SINGLE',

   'destination': 'L:some_dict',

   'destination_key': 'key2',

   'values': ['val2'],

   'if_exists': 'ERROR'

}

It triggers an error. Note that both key and value should be the same in order to trigger the ‘if_exists’ logic. If key is the same but value differs, value will be overwritten. If key is different, the new key with value will be added.

(3) When PUSH to a list of list with the item exists:

{

   'operation': 'PUSH',

   'type': 'LIST',

   'destination': 'L:list_of_lists',

   'values': ['a', '2'],

   'if_exists': 'ERROR'

}

It triggers an error.

(4a) When PUSH to a composite value with the item exists, as follows:

{

   'operation': 'PUSH',

   'type': 'COMPOSITE',

   'destination': 'L:composite',

   'name': 'inner_1',

   'composite_value': 'inner_1_content',

   'if_exists': 'ERROR'

}

It triggers an error.

(4b) When PUSH to a composite value with the item exists, as follows:

{

   'operation': 'PUSH',

   'type': 'COMPOSITE',

   'destination': 'L:composite',

   'name': 'inner_2',

   'keys': ['inner_attr'],

   'values': ['inner_val'],

   'composite_value': '',

   'if_exists': 'ERROR'

}

It triggers an error.

operation POP and UNSHIFT

If the source variable is anything but a dictionary, a list, or a composite value, an error is returned. If keys is set, the source value is assumed to be a dictionary. Otherwise, an error is returned.

If the source variable is a list, a single value is removed from the list. If the operation is POP, it is removed from the right side (from the end). If the operation is UNSHIFT, it is removed from the left (at the beginning). The removed value is put in the destination variable.

If the source variable is a composite value, the operation is on the children list of the composite value. Note that it is not possible to POP or UNSHIFT from a composite value, if it has text only.

If the source variable is a dictionary, the specified keys and/or key/value pairs will be removed from the variable in source. If only keys are passed, those keys will be unconditionally removed. If keys and values are passed, the key will be removed from the source variable only if its value matches what is passed in values here. If only one key or key/value pair is passed, the removed value will be put in destination. Otherwise, it will simply be dropped.

For the values match, the value in the list or dictionary will be serialized with quoting specified in the template before being compared to the string value passed in values. This also means that using comparison on large lists would potentially be a slow operation.

In the POP or UNSHIFT case, type is validated to be the same as the type of the popped or unshifted variable (you can validate if they were planning to pop a simple scalar if there is one). If it is not, an error will be raised if debug is turned on.

The following are a few examples using namespace L as follows:

{

   'some_list': ['item1', 'item2'],

   'some_dict': {'key1': 'val1', 'key2': 'val2'},

   'list_of_lists': [['a', 'b'], ['1', '2']],

   'list_of_dicts': [{'a': '1'}, {'b': '2'}],

   'composite': {

     '<xmla>': True,

     'index': {'inner_1': 0, 'inner_2': 1},

     'name': 'outer',

     'attrs': {'outer_attr': 'outer_val'},

     'value': [

          {

              '<xmla>': True,

             'index': {},

             'name': 'inner_1',

             'attrs': {},

             'value': ['inner_1_content']

         },

         {

            '<xmla>': True,

            'index': {},

            'name': 'inner_2',

            'attrs': {'inner_attr': 'inner_val'},

            'value': []

        }

      ]

   }

}

(1) When POP from a list:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_list",

},

It gives the variable as follows:

{"some_list": ["item1"]}

(2) When UNSHIFT from a list:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_list",

}

It returns the following:

{"some_list": ["item2"]}

(3) When UNSHIFT from a dict by key:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key1"]

}

It returns the following:

{"some_dict": {"key2": "val2"}} There is no difference between POP/UNSHIFT fro dictionarries

(4) When POP from a dict by multiple keys:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key1", "key2"]

}

It returns the following:

{"some_dict": {}}

(5) When POP from a dict when a key is absent:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key1", "absent_key"]

}

It returns an error in the DEBUG mode. For non-DEBUG mode, all existing keys are POPed. Note that items are popped one by one, so key1 item is popped before the error is returned.

{"some_dict": {"key2": "val2"}}

(6) When POP from composite value:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:composite",

}

It returns the following:

{

   "composite": {

     "index": {"inner_1": 0},

     "<xmla>": True,

     "name": "outer",

     "value": [{

        "index": {},

        "<xmla>": True,

        "name": "inner_1",

        "value": ["inner_1_content"],

        "attrs": {}

    }],

    "attrs": {"outer_attr": "outer_val"}

  }

}

This can be serialized to the following:

<outer outer_attr="outer_val">

   <inner_1>inner_1_content<inner_1>

</outer>

(7) When conditional POP/UNSHIFT from a list:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_list",

   "values": ["item1"]

}

It returns the following:

{"some_list": ["item2"]}

There is no difference between POP and UNSHIFT when ‘values’ is specified. When source is either LIST or COMPOSITE, all occurrences of a value are deleted.

(8) When conditional POP/UNSHIFT from a dictionary:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key2"],

   "values": ["val2"]

}

It returns the following:

{"some_dict": {"key1": "val1"}}

(9) When conditional POP/UNSHIFT of multiple values:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key2", "key2"],

   "values": ["abc", "val2"]

}

It returns the following:

{"some_dict": {"key1": "val1"}}

(10) When conditional POP/UNSHIFT with list values:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:list_of_lists",

   "values": ["\"['1', '2']\""]

}

It returns the following:

{"list_of_lists": [["a", "b"]]}

For conditional POP/UNSHIFT, non-string values are serialized with the template's quoting. For JSON, quoting is added to value.

(11) When conditional POP/UNSHIFT with dictionary value:

{

   "operation": "POP",

   "type": "DICTIONARY",

   "source": "L:list_of_dicts",

   "values": ["\"{'b': '2'}\""]

}

It returns the following:

{"list_of_dicts": [{"a": "1"}]}

(12a) When conditional POP/UNSHIFT with the following composite values:

{

   "operation": "POP",

   "type": "COMPOSITE",

   "source": "L:composite",

   "values": ["\"{'index': {}, '<xmla>': True, 'name': 'inner_2', 'value': [],

   'attrs': {'inner_attr': 'inner_val'}}\""]

}

It returns the following:

{

   "composite": {

     "index": {"inner_1": 0},

     "<xmla>": True,

     "name": "outer",

     "value": [{

       "index": {},

       "<xmla>": True,

       "name": "inner_1",

       "value": ["inner_1_content"],

       "attrs": {}

     }],

    "attrs": {"outer_attr": "outer_val"}

  }

}

(12b) When conditional POP/UNSHIFT with the following composite values, and with the template quoting set to XMLA:

The example in (12a) can be specified as follows:

{

   "operation": "POP",

   "type": "COMPOSITE",

   "source": "L:composite",

   "values": ["<inner_2 inner_attr=\"inner_val\"/>"]

}

Type check after POP/UNSHIFT:

{

   "operation": "POP",

   "type": "LIST",

   "source": "L:some_dict",

   "keys": ["key2"]

}

It returns an error in the DEBUG mode. Since the type of POPed value is not LIST, the possible values for type are 'SINGLE', 'LIST', 'DICTIONARY', and 'COMPOSITE', where 'SINGLE' means ‘no check’. Note that type check is done after the item is retrieved from source. In the DICTIONARY case, when several keys are specified, there is no type check. Type check is done after value comparison.

(13) When putting the item to ‘destination’:

{

   "operation": "POP",

   "type": "COMPOSITE",

   "source": "L:composite",

   "destination": "L:sub_item"

}

It returns the following:

{

   "composite": {

      "index": {"inner_1": 0},

      "<xmla>": True,

      "name": "outer",

      "value": [

        {"index": {}, "<xmla>": True, "name": "inner_1", "value": ["inner_1_content"],

   "attrs": {}}

      ],

      "attrs": {"outer_attr": "outer_val"}

      },

    "sub_item": {

      "index": {},

      "<xmla>": True,

      "name": "inner_2",

      "value": [],

      "attrs": {"inner_attr": "inner_val"}

   }

}

If the value popped/unshifted from source and destination is specified, the value is written to the destination. The value is written after the type check.

The L:sub_item can be serialized as the following:

<inner_2 inner_attr="inner_val"/>

Constant Specification for values

When you specify the values field inside any variable operation for the VARIABLEOP step type, it is possible to use the constant of a specific type, instead of string.

For example, the following describes three string values:

‘values’: [‘True’, ‘42’, ‘${L::some_var}’]

If you specify values as ‘{X:something}’, ‘something’ is represented as a constant of type X. Note that this is the only allowed syntax. For example, ‘text{X:something}’ is treated as a string, instead of a constant specification.

The following types are supported in constant specification:

• Bool type (B): Both '{B:1}' and '{B:true}' are evaluated as bool true, while '{B:0}' and '{B:false} are evaluated as bool false. Note that both 'true' and 'false' are not case-sensitive. Therefore, True, FALSE or even tRuE are all allowed. Other invalid values such as 'B:' and '{B:anythingelse}' are evaluated as bool=false (the 'default value') without further debugging; and an error is logged in the debug mode.
• Integer type (I): '{I:}' is evaluated to its corresponding integer value. For example, {I:-42} is evaluated as integer -42. The default value is 0.

• Empty type (E): ‘{E:}’ is evaluated as None. ‘{E:[]}’ is evaluated as an empty list. ‘{E:{}}’ is evaluated as an empty dictionary. The default value is None.

• Float type (F): The float type is similar to the integer type. Float numbers can be specified as '{F:0.0}', '{F:-4.2}', '{F:-4E+2}' or '{F:+1.23e-45}. The default value is 0.0.

• String type (S): '{S:}' is evaluated as string ''. For example, '{S:{I:42}}' is string '{I:42}'. There is no default value for string. For the unknown type (e.g. '{U:%^&}'), the default value is an empty string.

The following example illustrates how to use constant specification to define ipv4addr with a DHCP option:

{

   “ipv4addr”: “1.2.3.4”,

   “options”: [

     {

       “name”: 'dhcp-lease-time”,

       “num”: 51,

       “use_option”: true,

       “value': '43200”,

       'vendor_class': “DHCP”

     }

   ]

}

Note that num is an integer (in this string: “num”: “51”) and use_option is bool (in this string: “use_option”:

“true”).

In the action template, you can do the following:

{

   “steps”: [

   {

     “operation': 'VARIABLEOP”,

     “variable_ops”: [

       {

         “operation”: “ASSIGN”,

         “type”: “DICTIONARY”,

         “destination”: “L:addr”,

         “keys”: [“ipv4addr”, “options”],

         “values': [“1.2.3.4”, “{E:[]}”]

      },

      {

         “operation”: “PUSH”,

         “type”: “DICTIONARY”,

         “destination”: “L:addr{options}”,

        “keys”: [ “name”, ”num”, “use_option”, “value”, “vendor_class”],

         “values': [“dhcp-lease-time”, ”{I:51}”, ”{B:true}”, “43200”, “DHCP”]

       }

     ]

   },

   {

   “operation”: “PUT”,

   “transport”: {“path”: “record:host_ipv4addr”},

   “body”: “${L:J:addr}”

   }

  ]

}

SERIALIZE Struct

SERIALIZE Struct

Note: All variables listed in the following table are applicable only for the SERIALIZE operation in the STEP struct. The SERIALIZE structs inside the step are executed in sequence.

TRANSPORT Struct

TRANSPORT Structs

RESULT Struct

Note the following:

• codes and regex are ignored if the operation is SLEEP or NOP.
• At least one of the following is required: next, stop, or error.

RESULT Structs

PARAMETER Struct

PARAMETER Structs

CONDITION Struct

CONDITION Structs

STATEMENT Struct

STATEMENT Structs

Action Template Variables and Name Spaces

Action templates can access variables in several different name spaces. The following are the available name spaces:

• C: http cookies. It supports only the DEL operation (primarily for logout purposes), but it can be used as a substitution origin.
• Read-Only E: Event data.
• H: http headers. Note that the assigned variables are sent in the next HTTP request and it survives the template execution.
• Read-Only I: Template instance variables. It is set in the GUI during the creation of the filter and it also includes the endpoint variables that are set in the GUI when creating an endpoint. Note that the instance variables can override endpoint variables, if needed.
• L: Local template variables. This name space is empty at name space startup and will not survive the template invocation.
• Read-Only P: Previous endpoint response values (if parsing is enabled for the response.)
• Read-Only R: Previous endpoint request http-specific return values. This includes RC, the http status code of the previous request (Example: 200), BODY, and the body of the response.
• Read-Only RH: Previous endpoint request that returned http headers.
• S: Endpoint session state variables. These variables survive the template invocation (it is used similar to L: name space which is not cleared at the end of the template execution.)
• Read-Only UT: Read-only utility variables. The UT: name space contains the following read-only variables:
  • EPOCH: EPOCH seconds since Jan 1st, 1970 (integer, 1 second resolution.)
  • TIME: UTC time in ISO-8601 format. Example: 2016-04-08T23:09:35Z (1 second resolution).
  • UUID: Random UUID of the form 00000000-0000-0000-0000-000000000000.
  • PROTOCOL: The protocol used for the request.
  • URI: Complete URI used for the request.
  • HOST: The endpoint address.
  • PORT: The port used for the request.
• Read-Only XC: Execute a command on the variable. This results no output.

Action Template Variable Format

The following sequences are substituted with dynamic data:

${<data namespace>:<output format>:<name of the data or operation dependent values>}

The sequences cannot contain the following characters as variable names: {, }, [, and ]. Therefore, if names contain keys of dictionary/EA variables, they must be quoted with the \ character. Example: *${E::SOME_EA{name with \{ embedded \] braces or brackets}*. But if the \ character is desired, it must be quoted as \. Note that variable substitution happens only once, it is not nested (i.e. if the value contains ${...}, it will not be recursively substituted). Also, the dynamic data is not supported for instance and template variables which are assumed to be immediate values.
The following types of variables allow further qualifiers after the variable name. The qualifiers are always mandatory. Therefore, if a variable is a list or a dictionary, then you must specify [ ] or { }.

• EA (Extensible Attribute) variables or dictionaries. In general, you must specify {EAname} for EA variables or dictionaries. For example, if you specify ${E::NETWORK_EA{City}}, it means the city EA from the network EAs. Note that data specific portion is mandatory for EA variables.
• List variables. You can specify the list index using square brackets. For example, for a list of DNS names if you specify ${E::DNS_NAMES[0]}, this indicates the first DNS name in the list.

You can also use { } or [ ] to signify the full dictionary or list that is supported only in some encodings. Optionally, you can specify the output format. The following output formats are supported:

• J: The output is in the form of JSON formatted variable. It supports deserializing lists as well as dictionaries. Note that strings will have double quotes prepended/appended when serialized with J.
• j: The output is in the form of JSON formatted variable. It supports deserializing lists as well as dictionaries without the leading or trailing double quotes, if the variable is a string.
• X: The output is in the form of XML formatted variable. It supports only deserializing lists, such as < item >..</item > sequence.
• U: The output is in the form of url encoded variable. It supports deserializing lists and the output will be a string (comma separated value.)
• A: The output will be a variable, which is as-is.
• S: The output is in the form of a string. This is the default for JSON if you do not specify any output format. By default, even numbers will be serialized as JSON strings, meaning the output in a JSON quoted template for a numerical value of 1234 will be "1234".
• N: The output is in the form of numbers. For example, if the variable is a boolean, the output will be 0, 1, etc.
• B: The output will be a boolean, that is true/false.
• L: The length of the variable. This is supported only for lists (the length of the list) and dictionaries (the number of keys).
• T: The type of the variable. This can be one of the following characters: 'S' for strings, 'L' for lists, 'D' for dictionaries, 'B' for booleans, 'N' for numbers, and 'O' for otherwise.

The default is set by the template quoting option and by using a variable. If you have not set the template quoting, then JSON will be set, by default. If you have set the template quoting, the output format will be as specified, unless the variable is in the following fields:

• Headers: Any variable inside a headers block is serialized by default, as ASIS.
• Parameters: Any variable inside a parameters block is serialized by default, as URL.
• Path: Any variable inside a path block is serialized by default, as ASIS.

Command Execution

If you use XC: name space, then the value can be one of the following:

Note: The argument will be one or two nested variable specifications separated by ':' but without the '$' symbol.
The variables inside 'XC' do not have an output format, so you must use only one ':'.

• ASSIGN: Assigns the value to the specified variable. Note that the value assigned is in the format I/S/B:value for integer, string, and boolean values. Example: ASSIGN:variable:value.
• DEBUG: Outputs the specified variable to the debug file (if the log level is not set to DEBUG, this will be ignored), if only the name space is used, the whole name space will be printed.
• INC: Increments the variable value. If the value is not a number, NIOS displays an error.
• DEC: Decreases the variable value. If the value is not a number, NIOS displays an error.
• COPY: Copies one variable into another. Example: COPY:destination:source.
• DEL: Removes the variable. This supports only the C:, H:, L:, and S: name spaces.
• FORMAT: Formats the value according to what is specified after the second ':'. Currently, NIOS supports the following formats:
• U: Converts to uppercase value.
• L: Converts to lowercase value.
• DATE_EPOCH: Assuming that the value is a date expressed in UTC ISO 8601 date format. For example, 2016-03-13T04:50:31Z will be converted to EPOCH seconds.
• DATE_ISO8601: Assuming that the value contains EPOCH seconds. The value is converted to a date string expressed in UTC ISO 8601 date format. For example, 1467152565 will be converted to 2016-06-28T22:22:45Z. If the variable contains milliseconds, they will be preserved. For example 1467152565.57 will be converted to 2016-06-28T22:22:45.570Z.
• DATE_STRFTIME: Assuming that the variable contains EPOCH seconds. The value is converted to a date string with the specified format which is passed as the second parameter to the function.
• PUNYCODE_TO_UTF-8: Assuming that the variable contains a punycode encoded domain name. The domain name representation will be converted to UTF-8 characters. Note that there might be a failure if the domain name has non-UTF-8 characters in its wire format.
• TRUNCATE: Assuming that the variable is a string and it will be truncated as specified. The format is a number (positive or negative) followed by the letter 'l' or 'r'. The number is the starting character of the string (positive will be counted from the beginning, negative will be counted from the end) and f/t defines if the characters are from, after, or to that point. For example, if a string is 12345, then 1f will produce 2345, 1t will produce 1, -1f will produce 5 and -1t will produce 1234.

Format operations will function like other operations if an error occurs, but the variable is not modified. However, the error can be ignored if the log setting is not set to Debug. For information about how to set the logging level, see Configuring Outbound Endpoints.

The following are some examples of using XC operations to increment and decrement IP address strings, create a network range, or remove a specific IP address.

Incrementing or Decrementing IP addresses

Use the XC:INC and XC:DEC operations respectively to increment and decrement IP address strings.

Examples:

• For namespace {'L':{'ip_str': '1.2.3.4'}}, an evaluating variable "${XC:DEC:{L:ip_str}}" results in {'L':{'ip_str': '1.2.3.3'}}.
• The same goes for IPv6 addresses. For namespace {'L':{'ip_str': '2001:db8::2'}}, an evaluating variable "${XC:INC:{L:ip_str}}" results in {'L':{'ip_str': 2001:db8::3'}}, and an evaluating "${XC:DEC:{L:ip_str}}" results in {'L':{'ip_str': '2001:db8::1'}}.

The increment of the last address results in the first address. The decrement of the first address results in the last address.
Examples:

INC of ‘255.255.255.255’ results in ‘0.0.0.0’
INC of ‘ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff’ results in ‘::’
DEC of ‘0.0.0.0’ results in ‘255.255.255.255’
DEC of ‘::’ results in ‘fff:ffff:ffff:ffff:ffff:ffff:ffff:ffff’

Creating Network Ranges from Strings

Use the XC:NETWORKTORANGE operation to create a range from a network string. This operation should be specified as the following: ${XC:NETWORKTORANGE:{“var_with_network”}:{“var_for_range”}} where network is a string such as ‘1.2.3.4/16’ or ‘2001:db8:ce4::/48’

The resulting range is an XMLA value such as the following:

{
   '<xmla>': True,
   'name': 'range',
   'attrs': {'from': '1.2.0.0', 'to': '1.2.255.255'},
   'value': [],
   'index': {}
}

or

{
   '<xmla>': True,
   'name': 'range',
   'attrs': {'from': '2001:db8:ce4::', 'to':
 '2001:db8:ce4:ffff:ffff:ffff:ffff:ffff'},
   'value': [],
   'index': {}

}

Note: “var_with_network” must be a top-level variable in a namespace such as E:var, but not L:var{key}[42].

When namespace E is {‘E’: {‘net’: ‘1.2.3.4/16’}} and the response is as follows:

<SiteConfigResponse success="1">
  <Site id="42" name="this_site" description="testing site" riskfactor="1.0" isDynamic="0">
   <Description>testing site</Description>
   <Hosts>
     <host>a.com</host>
   </Hosts>
   <Credentials></Credentials>
   <Alerting></Alerting>
   <ScanConfig configID="21" name="CIS" templateID="cis" engineID="3" configVersion="3">
   <Schedules></Schedules>
   </ScanConfig>
  </Site>
</SiteConfigResponse>

Then using the following steps:

{
     "name": "copy",
     "operation": "NOP",
     "body_list": [
       "${XC:COPY:{L:Site}:{P:PARSE{SiteConfigResponse}}}",
       "${XC:NETWORKTORANGE:{E:net}:{L:range}}"
     ]
},
{

     "name": "add",
     "operation": "VARIABLEOP",
     "variable_ops": [
        {
          "operation": "PUSH",
          "type": "COMPOSITE",
          "destination": "L:Site{Site}{Hosts}",
          "source": "L:range"
         }
     ]
},
{
     "name": "post",
     "operation": "POST",
     "body_list": [
        '<?xml version="1.0" encoding="UTF-8"?>',
        '<SiteSaveRequest session-id="some_sess_id">',
        '${L:x:Site}',
       '</SiteSaveRequest>'
    ]
}

returns the following XML results:

<?xml version="1.0" encoding="UTF-8"?>
<SiteSaveRequest session-id="some_sess_id">
  <Site name="this_site" isDynamic="0" description="testing site" riskfactor="1.0"id="42">
     <Description>testing site</Description>
     <Hosts>
       <host>a.com</host>

       <range from="1.2.0.0" to="1.2.255.255"/>
     </Hosts>
     <Credentials/>
     <Alerting/>
     <ScanConfig configID="21" configVersion="3" name="CIS" templateID="cis" engineID="3">
     <Schedules/>
     </ScanConfig>
  </Site>
</SiteSaveRequest>

Removing Specific IP Addresses from Hosts or Ranges

Use the XC:REMOVEIP operation to remove a specific IP address from a list of hosts or ranges. This operation should be specified as the following: ${XC:REMOVEIP:{“var_with_ip”}:{“var_with_list”}} where IP address is a string such as ‘1.2.3.4’ or ‘2001:db8:ce4::42’.

The list of hosts/ranges is as follows:

[
  {
     '<xmla>': True,
     'name': 'range',
     'attrs': {'from': '1.2.3.1', 'to': '1.2.3.7'},
     'value': [],
     'index': {}
  },
  {
     '<xmla>': True,
     'name': 'host',
     'attrs': {},
     'value': ['a.com'],
     'index': {}
  }
]

Note: “var_with_IP” must be a top-level variable in a namespace such as E:var, but not L:var{key}[42].

Having namespace E as {‘E’: {‘ip’: ‘1.2.3.4’}} and Rapid7 response as follows:

<SiteConfigResponse success="1">
  <Site id="42" name="this_site" description="testing site" riskfactor="1.0"isDynamic="0">
  <Description>testing site</Description>
  <Hosts>
    <host>a.com</host>
    <range from="1.2.3.1" to="1.2.3.7"/>
    <host>b.com</host>
  </Hosts>
  <Credentials></Credentials>
  <Alerting></Alerting>
  <ScanConfig configID="21" name="CIS" templateID="cis" engineID="3" configVersion="3">
  <Schedules></Schedules>
  </ScanConfig>
 </Site>
</SiteConfigResponse>

Use the following steps:

{
     "name": "copy",
     "operation": "NOP",
     "body_list": [

        "${XC:COPY:{L:Site}:{P:PARSE{SiteConfigResponse}}}",
        "${XC:REMOVEIP:{E:ip}:{L:Site{Hosts}}}"
      ]
},
{
     "name": "post",
     "operation": "POST",
     "body_list": [
        '<?xml version="1.0" encoding="UTF-8"?>',
        '<SiteSaveRequest session-id="some_sess_id">',
        '${L:x:Site}',
        '</SiteSaveRequest>'
      ]
}

It returns the following XML results:

<?xml version="1.0" encoding="UTF-8"?>
<SiteSaveRequest session-id="some_sess_id">
     <Site name="this_site" isDynamic="0" description="testing site" riskfactor="1.0"id="42">
     <Description>testing site</Description>
     <Hosts>
        <host>a.com</host>
        <range from="1.2.3.1" to="1.2.3.3"/>
        <range from="1.2.3.5" to="1.2.3.7"/>
        <host>b.com</host>
     </Hosts>
     <Credentials/>
     <Alerting/>
     <ScanConfig configID="21" configVersion="3" name="CIS" templateID="cis" engineID="3">
     <Schedules/>
     </ScanConfig>
  </Site>
</SiteSaveRequest>

XC:Remove* Operations

There are several XC:REMOVE* operations that can be used to remove one or more IP specified addresses from a list of hosts and ranges. Such list is the deserialized representation of the 'Hosts' element of the Rapid7 response or request.

For example,

[
{
'<xmla>': True,
'name': 'host',
'attrs': {},
'value': ['a.com'],
'index': {}
},
{
'<xmla>': True,
'name': 'range',
'attrs': {'from': '1.2.3.1', 'to': '1.2.3.7'},
'value': [],
'index': {}
},
{
'<xmla>': True,
'name': 'host',
'attrs': {},
'value': ['b.com'],
'index': {}
}
]

Represents the following `Hosts` element:

<Hosts>
<host>a.com</host>
<range from="1.2.3.1" to="1.2.3.7"/>
<host>b.com</host>
</Hosts>

Items in the list are iterated one by one upon execution of any REMOVE command. The first argument of the REMOVE* command is the variable specification that contains an IP address. The second argument is the variable with the list of ranges or hosts. If the item is ‘range’, then the specified IP address is deleted from the range. Execution of any REMOVE command may result in no range, one range or two ranges that do not contain any specified IP addresses. The IP addresses specified in non-range items and ranges with different IP addresses are ignored.

• The XC:REMOVEIP command specifies the single IP address as string (for example, ‘1.2.3.4’ or ‘2001:db8:ce4::42’).
• The XC:RMEOVERANGE command specifies the set of IP addresses as Rapid7 range.
• The XC:REMOVENET command specifies the set of IP addresses as network string.

If the first argument denotes an incorrect IP address (range or network respectively), the template execution is stopped and an error is generated for DEBUG mode, and nothing happens for non-DEBUG mode.

XC:Parse* Operations

The XC:PARSE command parses variable data based on the configuration. Some endpoints may return mixed outputs that cannot be parsed using a single parse statement. Hence, Infoblox provides you the flexibility to parse a response or a variable multiple times.

Using the XC:PARSE command to evaluate a string

You can use the ${XC:PARSE:{L:config}:{L:data}} command to parse a variable data based on the configuration. Infoblox supports parsing methods such as REGEX, REGEXSPLIT, XML, and so on. The REGEXSPLIT parsing method can be used to split a string to array of items.

The second argument (L:data) is updated to the result of parsing operation.

Having the L namespace as:

{
"config": {
"parse": "REGEXSPLIT",
"regex": "/"
},
"data": "infoblox.com/contacts"
}
The ${XC:PARSE:{L:config}:{L:data}} variable will update L:data to list ["infoblox.com", "contacts"].

Using the XC:IS_IP_IN command to evaluate a string

You can use the XC:IS_IP_IN command to evaluate if a string is within a range or a network. The ${XC:IS_IP_IN:{L:address}:{L:range}} variable evaluates the string to true. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks or addresses that are separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"address": "1.2.3.4",

"range": "1.2.0.0-1.2.255.255"

}

Using the XC:REMOVEIP command to remove a string

You can remove an IP address from a range as a plain string using the XC:REMOVEIP command. Example: "10.0.0.1-10.0.0.4". In this case, the result format is a plain string with ranges that are separated by a comma. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks, or addresses separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"address": "1.2.3.4",

"range": "1.2.3.1-1.2.3.3,1.2.3.5-1.2.3.20"

}

The ${XC:REMOVEIP:{L:address}:{L:range}} variable updates L:range to string "1.2.3.1-1.2.3.3,1.2.3.5-1.2.3.20".

Using the XC:REMOVENET command to remove a string

You can use the XC:REMOVENET command to remove all the IP addresses of a specified network from the list of ranges. Example: "10.0.0.1-10.0.0.4". In this case, the result format is a plain string with ranges that are separated by a comma. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks, or addresses separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"network": "1.2.3.0/28",

"range": "1.2.3.1-1.2.3.20"

}

The ${XC:REMOVENET:{L:network}:{L:range}} variable updates L:range to string "1.2.3.15-1.2.3.20".

Using the XC:REMOVERANGE command to remove a string

You can use the XC:REMOVERANGE command to remove all the IP addresses of a specified range from the list of ranges. Example: "10.0.0.1-10.0.0.4". In this case, the result format is a plain string with ranges that are separated by a comma. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks, or addresses separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"range1": "1.2.3.2-1.2.3.10",

"range2": "1.2.3.1-1.2.3.20"

}

The ${XC:REMOVERANGE:{L:range1}:{L:range2}} variable updates L:range2 to string "1.2.3.1,1.2.3.11-1.2.3.20".

Evaluating IP Address in a Range or Network

Use the XC:IS_IP_IN operation to validate if an IP address is in the range and network. This operation should be specified as follows: ${XC:IS_IP_IN:{“var_with_IP”}:{“var_with_net_or_range”}} where IP address is a string such as ‘1.2.3.4’ or ‘2001:db8:ce4::42’.
Having the L namespace as:

{
'ip1': '1.2.3.4',
'ip2': '2001:db8:ce5::42'
'range': {
'<xmla>': True,
'name': 'range',
'attrs': {'from': '1.2.0.0', 'to': '1.2.255.255'},
'value': [],
'index': {}
},
'net': '2001:db8:ce4::/48'
}
The ${XC:IS_IP_IN:{L:ip1}:{L:range}} variable will be evaluated to string as "true".
The ${XC:IS_IP_IN:{L:ip2}:{L:net}} variable will be evaluated to string as "false".

Creating Keys

Use the XC:KEYS operation to create keys. This operation should be specified as follows: ${XC:KEYS:{“var_with_dict”}:{“var_for_key_list”}}. It creates a list from the keys of the `var_with_dict` variable and includes it in the `var_for_key_list` variable.
Having L namespace as

{
'some_dict': {
'key1': 'value',
'key2': 42,
'key3': ['item1', 'item2']
}
}
After evaluating the ${XC:KEYS:{L:some_dict}:{L:key_list}} variable, the L namespace will contain new variable key_list with the following values:
[
'key1,
'key2,
'key3'
]

 Variable Examples

The following are variable examples.

Note: The XC: examples refer to the operations discussed in the Command Execution section.

 Event Variables

The E: event name space is populated with variables from the event. For performance reasons, only the variables referred in the template will be available in the name space. This means that if the template is changed and if a new variable is added, it might take some time for the changes to be propagated to all the Grid members and the new variable to be available in future template executions.
You can use event_type in an action template to specify the following supported event types: RPZ, LEASE, TUNNEL, NETWORK_IPV4, NETWORK_IPV6, RANGE_IPV4, RANGE_IPV6, FIXED_ADDRESS_IPV4, FIXED_ADDRESS_IPV6, HOST_ADDRESS_IPV4, HOST_ADDRESS_IPV6, and SESSION. Note that SESSION is used only for the login and logout events for the session management templates. For information about action templates, see Creating Action Templates; and for information about session management templates, see Creating Session Management Templates.
The following tables list the supported variables by event type:

Variables for RPZ Events

 45.12 Variables for RPZ Events

Variables for DHCP Lease Events

When searching for DHCP lease events with associated discovered data, both the "address" and "hardware" or "duid" must match the discovered data. If there is no hardware or DUID, the lease event cannot be associated with any discovered data.
For leases, same IP addresses may be used by multiple systems, so the IP address must match the MAC address or DUID to ensure that the discovered data has the most likely correct value.

Variables for DHCP Lease Events

Variables for Object Change Discovery Data

Note: Infoblox supports insert and update operations from Network Insight and Cloud Discovery for object change discovery data in the NIOS 8.3.0 release version.

Variables for Object Change Discovery Data

Variables for Security ADP Events

Variables for Security ADP Events

Variables for Analytics DNS Tunneling Events

Variables for Analytics DNS Tunneling Events

Variables for DB Object Change Event - DHCP Network IPv4

Variables for DB Object Change Event - DHCP Network/Network Container IPv4

Variables for DB Object Change Event - DHCP Network IPv6

Variables for DB Object Change Event - DHCP Network/Network Container IPv6 

Variables for DB Object Change Event - DHCP Range IPv4

Variables for DB Object Change Event - DHCP Range IPv4

Variables for DB Object Change Event - DHCP Range IPv6

Variables for DB Object Change Event - DHCP Range IPv6