Page tree

Contents

The appliance uses outbound templates to convert NIOS events into REST API and DXL messages. You use supported variables in the templates to get respective events and define actions you want to take for those events.
The following are outbound templates you can create. You can also export the schema from the appliance and use it to create the outbound templates. For information about how to export template schema, see Exporting Template Schema . Note that the exported schema is in the IETF JSON Schema format. For information about this schema format, see https://tools.ietf.org/html/draft-zyp-json-schema-04 .

  • Session Management Template: A session management template contains specific variables about an endpoint, such as the timeout value and rate limiting information. For more information, see Creating Session Management Templates.
  • Action Template: An action template defines the action(s) to be taken on the selected endpoint for the matching event type(s). It contains scripts the appliance uses to query respective event data from NIOS and to perform actions you want to take in response to the events. For more information, see Creating Action Templates.

After you create your outbound templates, you can do the following to manage them:


Note: To access online resources about this feature, including training videos and sample outbound templates for supported ecosystem partners, visit the Infoblox Community Site at https://community.infoblox.com .


 Creating Session Management Templates

You can use a session management template to specify settings that will be applied to an endpoint. You can define settings such as the timeout value after which the outbound requests are aborted. This template can also contain additional child templates that can be referenced by the configuration. However, you cannot reference other templates in the system from the session management template.
Once you upload a session management template to the Grid, the configuration in the template automatically applies to the specified endpoint, if the connection to the endpoint has been established and if the template is assigned to the endpoint.

Table 45.2 lists the supported variables you can use in a session management template.


Note: Changes made to the variables of the template through Grid Manager overrides the variables in the template. Although the latest template version is 3.0, versions 2.0 and 1.0 templates still work fine with version 2.0 and version 1.0 syntax respectively.



 Table 45.2 Session Management Template Variables

Variable

Type

Mandatory

Description

version

Must be 3.0

Yes

The version number of the template. Note that 3.0 is the latest version. The appliance still fully supports the previous schema version.

type

Must be REST_ENDPOINT
for REST API endpoints
Must be DXL_ENDPOINT
for DXL endpoints

Yes

The template type.

name

String

Yes

The template name.

vendor_identifier

String

Yes

The vendor identifier for an endpoint.

comment

String

No

Additional information.

path

String

No

Path string to append to what the user enters in the GUI.

override_path

Boolean

No

If present, the path above replaces the path the user enters in the GUI.

timeout

Integer

No

The timeout value in seconds. The minimum is 1 and the maximum is 3600. The default is 30.

keepalive

Boolean

No

The value can be True or False. The default is False.

keepalive_timeoutIntegerNoThe keepalive timeout value in seconds. The connection is closed after this timeout. The minimum is 1 and the maximum is 300. The default is 5.

dxl_keepalive_timeout

Integer

No

The keepalive timeout value in seconds with a connected DXL broker. This controls the rate at which the client will send ping
messages to the broker if there is no exchange of other messages. The minimum is 1 and the maximum is 3600. The default is 30.
Note: This field is applicable only for the DXL templates.

dxl_topic

String NoThe DXL topic that is used to send data by DXL.
Note: This variable is applicable only for the DXL templates

retry

Integer

No

The number of attempts to try to connect to the endpoint before considering the connection a failure (this covers only timeout/network errors). The default value is 2.

retry_template

Integer

No

The number of attempts the appliance retries the full template if it returns a failure (this covers a template returning anything but 200). The default value is 0 (no retry).

rate_limit

Float

No

The maximum number of messages (per second) that are sent to an endpoint. The default value is 0 (no rate limiting). You can enter a value less than 1.0 to have lower rate limits. For example, if you set the value to 0.5, the appliance sends less than 1 message in every 2 seconds.

rate_limit_requests

Integer

No

Use this along with rate_limit_interval to define the absolute number of requests for rate limiting. For example, if you set this to 10 and rate_limit_interval to 5000 milliseconds, no further requests are sent until the number of requests falls below 10 in 5000 milliseconds. So if 3 requests are sent at 0 second and 7 requests are sent at the 3rd second, no requests will be sent until the 5th second, where 3 requests are allowed for another 3 seconds. The default is 0 = no rate limiting. You can set this to an integer between 0 and 267840000000.

rate_limit_interval

Integer (in milliseconds)

No

Use this along with rate_limit_requests to define the rate limiting interval . The default is 0 = no rate limiting. You can set this to an integer between 0 and 2678400000 milliseconds.

rate_limit_reset

Integer (in epoch time)

No

Use this together with rate_limit_requests and rate_limit_interval to reset the epoch time for rate limiting. The default is 0 = not resetting the epoch time for rate limiting. You can set this to an integer between 0 and 4102437600 milliseconds.

Example: If rate_limit_requests = 10, rate_limit_interval = 5 seconds, and rate_limit_reset = 3 p.m. on 10 January 2017 (set in epoch time), 10 requests can be sent within 5 seconds after the reset time.

For instance, 3 messages are sent at the 1st second and 7 messages sent at the 3rd second and no more messages can be sent in the next 2 seconds, which is within 5 seconds after 3 p.m. on 10 January 2017.

endpoint_variables

List of VARIABLE structs

No

If specified these will be accessible via the S: namespace in templates.

inactivity_interval

Integer (in milliseconds)

No

A logout request is sent after this time interval, provided no other requests have occurred during this time period. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds.

login_template

String

No

The template that requires user login if there is no active session currently running for the endpoint. Only templates with event_type set to SESSION are supported for this. You must include the template name in the string. Ensure that you upload the login template if you plan to use this variable in the session management template.

logout_any_condition

Boolean

No

Specifies whether a logout request is sent, depending on whether logout_status_code or logout_regexp are set. The value can be True or False. The default is False. If this is set to True, a logout request is triggered if either logout_status_code or logout_regexp is set. If this is set to False, both logout_status_code and logout_regexp must be set.

logout_regexp

String

No

Any response returned by the endpoint that matches the regular expression in this field will trigger a logout request.

logout_status_code

Integer

No

The HTPPS response status code used for the provisional response will trigger a logout request. The default is 0 = “disable.” Valid values are between 0 and 599.

logout_template

String

No

The template that is being executed after steps are executed or after various session duration constraints are met. You must include the template name in the string. Only templates with event_type set to SESSION are supported for this. Ensure that you upload the logout template if you plan to use this variable in the session management template.

requests_per_session

Integer

No

The number of requests that are sent before a logout request is sent. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1.

logout_only_at_template_end

Boolean

No

The value can be True or False. The default is False. If this is set to True, a logout request is sent only after the execution of the template has been completed to ensure that all template requests pertaining to a session are executed if that is required by the API. Therefore, it is possible to set requests_per_session to 1 and have each template call executed in its own session regardless of the number of requests it contains.

session_cooldown

Integer (in milliseconds)

No

When this is set, a login request will be sent only after the amount of time set for this has been elapsed after a logout. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds.

session_duration

Integer (in milliseconds)

No

The time interval after which a logout request is sent unconditionally after a login. For example, if you sent this to 150 milliseconds, after a login, a logout will be sent after 150 milliseconds whether there is current traffic or not. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds.

wapi_rate_limit

Float

No

Independent of the endpoint rate limiting, use this for persistent WAPI requests only. The maximum number of messages (per second) that are sent to an endpoint. The default value is 0 (no rate limiting). You can enter a value less than 1.0 to have lower rate limits. For example, if you set the value to 0.5, the appliance sends less than 1 message in every 2 seconds. The default is 0 = “disable.” You can set this to an integer between 0 and 100000.

wapi_rate_limit_requests

Integer

No

Independent of the endpoint rate limiting, use this for persistent WAPI requests only. Use this along with the wapi_rate_limit_interval field to define the absolute number of requests for rate limiting . For example, if you set this to 10 and rate_limit_interval to 5000 milliseconds, no further requests are sent until the number of requests falls below 10 in 5000 milliseconds. So if 3 requests were sent at 0 second and 7 requests were sent at the 3rd second, no requests will be sent until the 5th second, where 3 requests are allowed for another 3 seconds. The default is 0 = “disable.” You can set this to an integer between 0 and 267840000000.

wapi_rate_limit_interval

Integer (in milliseconds)

No

Independent of the endpoint rate limiting, use this for persistent WAPI requests only. Use this along with the wapi_rate_limit_requests field to define the rate limiting interval . The default is 0 = no rate limiting. The default is 0 = “disable.” You can set this to an integer between 0 and 2678400000 milliseconds.

wapi_rate_limit_reset

Integer (epoch time)

No

Independent of the endpoint rate limiting, use this for persistent WAPI requests only. Use this to reset the epoch time for rate limiting. The default is 0 = not reseting the epoch time for rate limiting. You can set this to an integer between 0 and 4102437600 milliseconds.

 Creating Action Templates

The purpose of an action template is to convert an event into one or more RESTful API and DXL 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.


Note: The steps in an action template are executed sequentially. Some constructs enable steps to be skipped by jumping forward in the list of steps; jumping backwards is not supported.


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 Endpoints. 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.

An action template consists of the variables and elements listed in Figure 45.3 .


Note: When "yes" is indicated in the "Sub" column for a variable, it means that variable substitution (where it is possible to have ${...} variables as part of the value, and have them substituted when the template is executed) is supported for that variable, a * means that the substitution is supported for some of the fields of the struct.



 Table 45.3 Action template Variables

Variable

Type

Mandatory

Sub

Description

version

Must be 3.0

No

No

The version number of the template. Note that 3.0 is the latest version. The appliance still fully supports the previous schema version.

name

String

No

No

The template name.

type

Must be
REST_EVENT for
REST API endpoints
Must be DXL_EVENT
for DXL endpoints

No

No

The template type.

vendor_identifier

String

No

No

The vendor identifier for an endpoint.


event_type

List of ENUM (except for SESSION)


Yes


No

Available 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 for the login and logout events for the session management templates. For information about supported variables for the session management template, see
Session Management Template Variables .

action_type

String

No

No

The action type.

comment

String

No

No

Additional information.

content_type

String

No

No

The content type for the whole template. If not specified, it is set as “application/json”. It can be specified either in the template, inside the transport, or both. If both are specified, then the content type specified in the template takes precedence.

quoting

ENUM

No

No

Sets the default serialization for template variables. The valid value is one of the following: JSON, XML, XMLA, ASIS, or URL. If not specified, this is set to JSON. To use XMLA for serialization, you must specify a valid quoting for variables. Infoblox strongly recommends that you use XMLA as the quoting option (as opposed to XML) when you create new action templates. New operations such as PUSH, POP, SHIFT and others are not officially supported for XML parsed data.

headers

Dictionary of key/value pairs

No

Yes

If specified, it is sent for every request of the template, in addition to any other H: namespace variables.

instance_variables

List of VARIABLE structs

No

No

It must be specified in the GUI to create a template instance.

template_variables

List of VARIABLE structs

No

No

The template_variables are used when there are common settings in various steps. They are specified for maintainability and they are also available in L: namespace. Note that the template variables are evaluated immediately so that they can be used as reference values in other areas of the template.

transport

TRANSPORT struct

No

No

It is the default for steps.





Steps are executed in sequence. You cannot execute them

steps

List of STEP structs

No


Steps are executed in sequence. You cannot execute them in a backward manner.

step_execution_limit

Integer



The maximum number of times a step can be executed. Steps can be executed more than once if using certain template constructs. To avoid possible endless loops, you can limit an individual step to be executed up to a certain number of times. If a step is executed again after the limit is reached, the execution will be interrupted and a failure is logged. The default is 10. The maximum number is 1000.

STEP Struct

Each step can perform a different operation, such as SLEEPCONDITIONNOPGETPOST, PATCHDELETE, DXL_EVENT_SEND, or PUTTable 45.4  lists the step variables.


Note: The name for each step must be unique.


  • 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 Table 45.10 for information about condition variables and Table 45.11 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, PATCHDELETE, 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.

 Table 45.4 STEP Structs


Note: Set the "wapi" field to send WAPI requests to the Grid Master using available event data. For example, you can add or modify extensible attributes of a NIOS object at the time when the object is being synchronized. If you include the "wapi" field in a step, you must enable WAPI integration by entering the WAPI login username and password while configuring the endpoint. Otherwise, the WAPI step will fail due to an authorization error. For information about how to configure endpoints, see Configuring Outbound Endpoints.



Variable

Type

Mandatory

Sub

Description

name

String

Yes

No

Used to refer to the steps used in the execution of the template.

operation

ENUM

Yes

No

The valid value can be one of the following: GET, POST, DELETE, PATCH, PUT, SLEEP, CONDITION, NOP, VARIABLEOP, DXL_EVENT_SEND, or SERIALIZE. If you specify SLEEP, only timeout is supported, where timeout is the sleep length in seconds. If you specify NOP, only variable operations are performed, and only body/body_list is supported. If you specify VARIABLEOP, you must use the VARIABLE struct within your steps that are executed in sequence. See VARIABLE Struct for the supported fields. If you specify SERIALIZE, see SERIALIZE Struct for the supported variables.

condition

CONDITION Struct

No


Applicable only if the operation is set to CONDITION.

timeout

String

No

Yes

If specified, overrides the endpoint configuration value (it is useful if the template is slow during execution). Note that the timeout value is invalid for NOP. Since the timeout variable is a string, you can substitute the variable in individual steps.

transport

TRANSPORT Struct

No

Path only


result

List of RESULT Structs

No

No

If not present, you can assume 200, everything else is a failure. If not specified, the steps are executed sequentially. This is not valid for SLEEP, NOP, or CONDITION variables.

parse

ENUM

No

No

If specified, the output of the server will be parsed. The valid value is one of the following: JSON, REGEXLINE, REGEXMULTILINE, REGEX, XMLA, or XML. Infoblox recommends that you use XMLA instead of XML for parsing. Ensure that you see Result Parsing for details.

parse_regex

String

No

No

You can set one of the following: REGEX, REGEXLINE, or REGEXMULTILINE

parameters

List of PARAMETERS

No

Value only

These are URI parameters.

headers

Dictionary of name/value pairs

No

Yes

This is sent as HTTP headers. The name space substitution is supported only for value. Note that assigning to the H: name space also sends headers.

override_headers

Boolean

No

No

If specified, only these headers and H: name space headers are sent instead of template headers.

body

String

No

Yes

This is applicable only for POST, PATCH, DXL_EVENT_SEND, and PUT requests as well as NOP operations. It will be sent as the body of the request. Note that name space substitution is supported.

body_list

List of strings

No

Yes

This is an alternative to the body. If specified, the strings in the list will be joined before sending it. Any leading or trailing whitespace is removed.

no_connection_debug

Boolean

No

No

The valid value is True or False. If this is set to True even if the endpoint is set to a Debug level logging, only the body, headers, and cookies for the corresponding step will NOT be output to the debug log. Only explicit DEBUG calls will be displayed. This is generally used in login templates to avoid usernames and passwords from being logged to the log files in plain text.

variable_ops

List of VARIABLEOP structs

No

No


serializations

List of SERIALIZE structs

No

No


comment

String

No

No

Adds information about the steps.

wapiStringNoNo

The WAPI version. When this is set, the username and password (auth username and auth password) specified for the endpoint are ignored for WAPI related steps only. Other steps still use the configured auth username and auth password. All WAPI requests are sent to the Grid Master IP. The path of the requests is /wapi/[version]/ with the appended path as specified in the step. The override path option as well as any path configured in the session management template will have no effect.

wapi_quotingENUMNoNo

The valid value is one of the following: JSON or XML. If this is not specified, it is set to JSON. The default is JSON. JSON and XML parsing performs as usual for WAPI.

dxl_topicStringNoPath only

The DXL topic that is used to send data by DXL.
Note: This variable is applicable only for the DXL templates.


 Table 45.5 VARIABLEOP Struct


Note: All variables listed in the following table are applicable only for the VARIALBEOP operation in the STEP struct. The VARIABLEOP struct converts specified keys/values in a complex variable (such as LIST, DICTIONARY, or XML values with attributes) or performs operations on an existing complex variable. No schema validation is made for variable combinations. Validation of the schema is performed when you add or modify the action template.



Variable

Type

Mandatory

Sub

Description

source

String

No

Yes

You must specify the variable name, including the namespace. You can include nested variables. Example: L:DICT{key}{list})

destination

String

No

Yes

You must specify the variable name, including the namespace. You can include nested variables. Example: L:DICT{key}{list})

operation

ENUM

Yes

Yes

Specifies the operation being performed for the value defined or created in type. The valid value is one of the following: PUSH, POP, SHIFT, UNSHIFT, or ASSIGN. Note that both operation and type are mandatory for the struct. For examples, see Using OPERATION in the VARIABLE Struct.


type


ENUM


Yes


Yes

Specifies the type of variables for the operation. Valid value is one of the following: LIST, DICTIONARY, COMPOSITE, or SINGLE. This field defines how the values in keys, values, and composite_value are combined to create a variable while operation defines how the variable is being used. The appliance handles keys, values and composite_value differently based on the type you select, as follows:

  • LIST: keys will be ignored; values will contain the required values and be serialized in a simple list of strings.
  • DICTIONARY: The list of key/value pairs in keys and values will be put in a simple dictionary.
  • COMPOSITE: The list of key/value pairs in keys and values will be put in an XMLA dictionary with a name set to name and a value set to either the value in composite_value OR the value in the variable set in source. See Using the COMPOSITE Type for details about how to use COMPOSITE.
  • SINGLE: keys will be ignored; the value will be the first element in the values list.

name

String

No

Yes

This is applicable only if you select COMPOSITE as the variabletype. Enter the name value for this type.

keys

List of strings

No

Yes

This can contain arbitrary serializable constructs.

values

List of strings

No

Yes

This can contain arbitrary serializable constructs. When you specify this field inside any variable operation for the VARIABLEOP step type, it is possible to use the constant of a specific type, instead of using string. For details about how to  specific type, instead of using string. For details about how to use constant, see Constant Specification for values.

composite_value

String

No

Yes

This can contain arbitrary serializable constructs.

destination_key

String

No

Yes

This can contain arbitrary serializable constructs.

if_exists

ENUM

No

Yes

The action taken if the variable exists. The valid value is one of the following: SKIP, ERROR, or NEXT.

if_exists_next

String

No

Yes

Enter the name for the next step.

conditionCONDITION StructNo
This can be specified for POP and UNSHIFT operations.

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:

FieldValue
typeCOMPOSITE
namevarname
keys["a1", "a2"]
values["value is ${L::SOMEVAR}", "2"]
composite_value"123"

It results in the following:

{

   "<xmla>": true,

   "attrs": {

      "a1": "value is 123",

      "a2": "2",

   },

   "index": {},

   "value": ["123"],

   "name": "varname"

}


Note: If source is set, the value in source is used as is (this can be seen especially for PUSH operations).


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}”

   }

  ]

}

Table 45.6 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.


Field

Type

Mandatory

Sub

Description

content

String

Yes

Yes

Defines what to serialize. This can contain arbitrary variables and text.

destination

String

Yes

Yes

Defines the destination for the serialization.

TRANSPORT Struct


Table 45.7 TRANSPORT Structs

Variable

Type

Mandatory

Sub

Description

path

String

No

Yes, if specified in step.

If present, it is appended to the endpoint URI.

override_path

Boolean

No

No

If this is true, the specified path completely overrides the endpoint URI after the first /.

content_type

String

No

No

If specified, this overrides the endpoint content type.


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: nextstop, or error.


Table 45.8 RESULT Structs

Variable

Type

Mandatory

Sub

Description

codes

comma separated int list

No

No

The http return code

regex

REGEX

No

No

If specified, REGEX is matched against the returned body.

next

id

No

No

The step to execute the next template if the code (and REGEX, if

specified) match. But if the next template is already executed once, the

appliance displays an error.

stop

Boolean

No

No

If set, the execution of the script is stopped. Note that next, error, and stop are mutually exclusive.


error


Boolean


No


No

If set, the execution of the script is stopped and then rerun with an error status if the retry_template is not set to 0. Note that next, error, and stop are mutually exclusive.

PARAMETER Struct


Table 45.9  PARAMETER Structs

Variable

Type

Mandatory

Sub

Description

name

String

Yes

No

Name of the parameter.

value

String

Yes

Yes

Value of the parameter. Note that this value is used as-is, so any strings that are not part of the variables must be URL encoded (%20 for spaces, and etc.)

CONDITION Struct

Table 45.10 CONDITION Structs

Variable

Type

Mandatory

Sub

Description

condition_type

String

Yes

No

This can be one of the following: AND, OR, NAND, or NOR. NAND means not (st1, st2, etc.)

next

String

No

No

The name of the step to jump to if the condition is successful.

eval

String

No

Yes

This is executed if the condition is successful. Generally, it will be an XC: set of operations.

else_eval

String

No

Yes

This is executed if the condition is NOT successful. Generally, it will be an XC: set of operations.

else_next

String

No

Yes

The execution will jump to specified step if the condition is NOT successful.

else_stop

String

No

Yes

The template execution will be stopped if the condition is NOT successful.

else_error

String

No

Yes

Generates an error if the condition is NOT successful.

stop

Boolean

No

No

If the condition is successful the execution will be stopped without any error.

error

Boolean

No

No

If the condition is successful the execution will be stopped with an error.

statements

List of STATEMENT
structs

Yes

Yes

The statements to evaluate.

STATEMENT Struct

Table 45.11 STATEMENT Structs

Variable

Type

Mandatory

Sub

Description

leftStringYesYes

The left operand. Note that it is acceptable to include variables that do
not exist on the left side (to test if a variable is set in an event). Any error
during evaluation of the `left` is ignored even if it is run under debug
mode.

opENUMYesNoThe operation to execute. This can be one of the following: =, >, <, >=, <=,
=~, and !~. Note that the >, <, >=, and <= operations try to convert the
operands to numbers before executing the comparison, then = ~, and !~
are REGEX matches and the right side is considered the REGEX.
rightStringYesYesThe right operand.


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: Increments 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.

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.



Variables and Results

Variable: ${E::FQDN}

Result: Substitute the FQDN value from the event.

Variable: ${I::QUARANTINE}

Result: Substitute the quarantine value from the template instance.

Variable: ${XC:COPY:{E:TIMESTAMP}:{L:epoch_timestamp}}${XC:FORMAT:DATE_EPOCH:{L:epoch_timestamp}}

Result: Copy the event TIMESTAMP value into a local epoch_timestamp variable.

Variable: ${XC:COPY:{E:TIMESTAMP}:{L:custom_timestamp}}${XC:FORMAT:DATE_STRFTIME:{L:custom_timestamp}:{%a, %d %b %Y %H:%M:%S}}

Result: Copy the event TIMESTAMP value to a local custom_timestamp variable and format it. In this example, the result might be Wed, 18 Jun 2015 16:13:11.

Variable: ${XC:INC:{S:SERIAL}}${S::SERIAL}

Result: Increment the state 'SERIAL' value and substitute its value

Variable: ${XC:COPY:{S:SERIAL}:{H:X-customheader}}

Result: Copy the state SERIAL value to a custom HTTP header for future requests

Variable: ${XC:DEL:{H:X-loginvalue}}

Result: Removes the specified HTTP header.

Variable: ${XC:DEL:{C:logincookie}}

Result: Removes the specified cookie.

Variable: ${XC:ASSIGN:{L:INT}:{I:123}}

Result: Assign the integer 123 to the value INT in the L name space.

Variable: ${XC:ASSIGN:{L:BOOL}:{B:true}}

Result: Assign true to the value BOOL in the L name space.

Variable: ${XC:ASSIGN:{L:STR}:{S:some } random string}}

Result: Assign the string some } random string to the value STR in the L name space.

Variable: ${XC:DEBUG:{L:INT}}

Result: Output the value of the L name space INT variable to the debug file.

Variable: ${XC:DEBUG:{L:}}

Result: Output the values in the whole L name space to the debug file.

Variable: ${XC:FORMAT:TRUNCATE:{L:VAR}:{-1f}}

Result: Truncate L:VAR to the last character.

 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:


Table 45.12 Variables for RPZ Events

NIOS Field Name

Template Variable Name

Supported Filter(s)

Enriched Data

Comment

Timestamptimestamp (ISO 8601 format)

The timestamp when the event occurred.

Infoblox Member IPmember_ip

Infoblox Member IP (VIP or LAN1) that generated this event.

Infoblox Member Name

member_name


Action Policy

rpz_policy

equals


(PASSTHRU DROP TCP-ONLY NXDOMAIN
NODATA Local-Data CNAME MISS)

RPZ Type

rpz_type

equals


Possible values: BAD, CLIENT-IP, QNAME, IP, NSDNAME, NSIP

Query Name or Query FQDN

query_name

contains, equals, begins with, ends with



Rule Name

rule_name

contains, equals, begins with, ends with



Source IP


source_ip

equals, matches range, matches CIDR

Parent range, Associated objects' DNS Names and EAs, Parent Network, Parent Network EA, Discovered data


Source Port

source_port




Destination IP

destination_ip



The name server that responded to the RPZ rule.

Query Type

query_type



DNS query type: A, AAAA, CNAME, DNAME,
TXT, and other.

Query View Name

query_view_name



Query DNS view name.

Event Type

event_type

equals

RPZ

LEASE

TUNNEL
NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6 HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Enriched from IPv4 or IPv6 Addresses
Source IP User Nameip.username

From IPv4Address and IPv6Address

This field can be empty.

Source IP Associated EA

ip.extattrs

From IPv4Address and IPv6Address pyabs class

Can be empty, EA needs to be stored as "name-value" pair.

Source IP Associated DNS Names

ip.names

From IPv4Address or IPv6Address

List of FQDN
Enriched from Discovered Data

Source IP Attached Device Model

ip.discovered_data.device_model
From discovered data

Source IP Attached Device Name

ip.discovered_data.device_port_name
From discovered data

Source IP Attached Device Port

ip.discovered_data.device_port_type
From discovered data

Source IP Attached Device Type

ip.discovered_data.device_type
From discovered data

Source IP Attached Device Vendor

ip.discovered_data.device_vendor
From discovered data

Source IP Discovered Name

ip.discovered_data.discovered_name
From discovered data

Source IP First Discovered

ip.discovered_data.first_discovered (ISO

8601 format)


From discovered data

Source IP Discovered MAC

ip.discovered_data.mac_address
From discovered data

Source IP NetBIOS Name

ip.discovered_data.netbios_name
From discovered data
Source IP Port Linkip.discovered_data.port_link_status
From discovered data
Source IP Port Speedip.discovered_data.port_speed
From discovered data
Source IP Port Statusip.discovered_data.port_status
From discovered data

Source IP VLAN Description

ip.discovered_data.port_vlan_description
From discovered data
Source IP VLAN Nameip.discovered_data.port_vlan_name
From discovered data
Enriched from Parent Range

Source IP Range Start Address

range.start_addr
From parent range

Source IP Range End Address

range.end_addr
From parent range
Enriched from Parent Network

Source IP Network View Name

network.network_view
From parent network

The network view name in string format.

Source IP Networknetwork.network
From parent network

ip_addr/cidr

Example: 1.2.3.4/24

Source IP Network

Address

network.ipv4addr
From parent networkip_addr
Source IP Network Cidrnetwork.netmask
From parent networkcidr
Source IP Network EAnetwork.extattrs
From parent network

EA name can be any UTF8 characters.

Enriched from Lease Data

Source IP Lease Start Time

lease.starts (ISO 8601 format)
From lease data

Source IP Lease End Time

lease.ends (ISO 8601 format)
From lease data
Source IP Lease Statelease.binding_state
From lease data

Possible values: UNKNOWN, ABANDONED, ACTIVE, BACKUP, DECLINED, EXPIRED, FREE, OFFERED, RELEASED, RESET, STATIC

Source IP Lease Client Host Name

lease.client_hostname
From lease data

Source IP Lease MAC Address

lease.hardware
From lease data
Source IP Lease DUIDlease.ipv6_duid
From lease data
Source IP Fingerprintlease.fingerprint
From lease data


Table 45.13 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.

NIOS Field Name

Template Variable Name

Supported
Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip


.

Infoblox member IP (VIP or LAN1) that has generated the event

Infoblox Member Name

member_name




Lease Binding State

binding_state

equals


This can be either UNKNOWN, ABANDONED, ACTIVE, BACKUP, DECLINED, EXPIRED, FREE, OFFERED, RELEASED, RESET, or STATIC.

Lease IP address

address

equals, matches range, matches CIDR

Parent Network EA, Parent Range, DNS Names and EA of associated objects

Some information from parent network is already in the DHCP lease data.

Lease Protocol

protocol



Possible values are IPv4 or IPv6.

Lease Start Time

starts




Lease End Time

ends




Client MAC address

hardware




Client IPv6 DUID

ipv6_duid




Client Host Name

client_hostname




Fingerprint


contains, equals, begins with, ends with



Lease Network View Name

network_view

contains, equals, begins with, ends with



Lease Network

network



ip_addr/cidr

Example: 1.2.3.4/24

Lease Network Address


network_ipaddr



ip_addr

Lease Network CIDR

network_netmask



CIDR

Lease IP Range Start Address

range_start_addr




Lease IP Range

End Address

range_end_addr


Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Enriched from Network EA
Lease Network EAnetwork.extattrs

From parent network EA

EA name can be any UTF-8 characters.

Enriched from IPv4 Address and IPv6 Address
Lease IP Usernameip.username

From IPv4 Address and IPv6 Address


Lease IP Associated EAp.extattrs

From IPv4 Address and IPv6 Address pyabs class

EA must be stored as “<EA name>-<EA value>” pair.

Lease IP Associated DNS Names

ip.names

From IPv4 Address and IPv6 Address

List of FQDN
Enriched from Discovery Data

Lease IP Attached Device Model

ip.discovered_data.device_model
From discovered data

Lease IP Attached Device Name

ip.discovered_data.device_port_name
From discovered data

Lease IP Attached Device Port

ip.discovered_data.device_port_type
From discovered data

Lease IP Attached Device Type

ip.discovered_data.device_type
From discovered data

Lease IP Attached Device Vendor

ip.discovered_data.device_vendor
From discovered data

Lease IP Discovered Name

ip.discovered_data.discovered_name
From discovered data

Lease IP First Discovered

ip.discovered_data.first_discovered (ISO 8601 format)


From discovered data

Lease IP Discovered MAC

ip.discovered_data.mac_address
From discovered data

Lease IP NetBIOS Name

ip.discovered_data.netbios_name
From discovered data
Lease IP Port Linkip.discovered_data.port_link_status
From discovered data
Lease IP Port Speedip.discovered_data.port_speed
From discovered data
Lease IP Port Statusip.discovered_data.port_status
From discovered data

Lease IP VLAN Description

ip.discovered_data.port_vlan_description
From discovered data
Lease IP VLAN Nameip.discovered_data.port_vlan_name
From discovered data


Table 45.14 Variables for Analytics DNS Tunneling Events

NIOS Field Name

Template Variable Name

Supported Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




Source IP

source_ip

equals, matches range, matches CIDR

Parent Network, Parent Network EA, Discovery


Domain Name

domain_name



Domain name that was determined as DNS tunneling domain.

RPZ Rule Policy

rpz_policy



RPZ rule policy that was created.

Event Type

event_type

equals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Comment

comment



Comment generated from the event by the Analytics system.

Enriched from IPv4 Address or IPv6 Address

Source IP Username

ip.username


From IPv4 Address and IPv6 Address


Source IP Associated EA

ip.extattrs


From IPv4 Address and IPv6 Address pyabs class

EA must be stored as “<EA name>-<EA value>” pair.

Source IP Associated DNS Names

ip.names


From IPv4 Address and IPv6 Address

List of FQDN.

Enriched from Discovery Data

Source IP Attached Device Model

ip.discovered_data.device_model


From discovered data


Source IP Attached Device Name

ip.discovered_data.device_port_name
From discovered data

Source IP Attached Device Port

ip.discovered_data.device_port_type
From discovered data

Source IP Attached Device Type

ip.discovered_data.device_type
From discovered data

Source IP Attached Device Vendor

ip.discovered_data.device_vendor
From discovered data

Source IP Discovered Name

ip.discovered_data.discovered_name
From discovered data

Source IP First Discovered

ip.discovered_data.first_discovered (ISO

8601 format)


From discovered data

Source IP Discovered MAC

ip.discovered_data.mac_address
From discovered data

Source IP NetBIOS Name

ip.discovered_data.netbios_name
From discovered data
Source IP Port Linkip.discovered_data.port_link_status
From discovered data
Source IP Port Speedip.discovered_data.port_speed
From discovered data
Source IP Port Statusip.discovered_data.port_status
From discovered data

Source IP VLAN Description

ip.discovered_data.port_vlan_description
From discovered data
Source IP VLAN Nameip.discovered_data.port_vlan_name
From discovered data
Enriched from Parent Range

Source IP Range Start Address

range.start_addr
From Parent Range

Source IP Range End Address

range.end_addr
From Parent Range
Enriched from Parent Network

Source IP Network View Name

network.network_view
From Parent Network

Network view name in string format.

Source IP Networknetwork.network
From Parent Network

ip_addr/cidr

Example: 1.2.3.4/24

Source IP Network Address

network.ipv4addr
From Parent Networkip_addr
Source IP Network Cidrnetwork.netmask
From Parent NetworkCIDR
Source IP Network EAnetwork.extattrs

From Parent Network EA

EA name can be any UTF-8 characters.

Enriched from Lease Data

Source IP Lease Start Time

lease.starts (ISO 8601 format)
From Lease Data

Source IP Lease End Time

lease.ends (ISO 8601 format)
From Lease Data
Source IP Lease Statelease.binding_state
From Lease Data

Source IP Lease Client Host Name

lease.client_hostname
From Lease Data

Source IP Lease MAC Address

lease.hardware
From Lease Data
Source IP Lease DUIDlease.ipv6_duid
From Lease Data
Source IP Fingerprintlease.fingerprint
From Lease Data


Table 45.15 Variables for DB Object Change Event - DHCP Network IPv4

NIOS Field Name

Template Variable Name

Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

Members

members




MS AD User Data

ms_ad_user_data




Comment

comment




network_container

network_container




options

options




unmanaged

unmanaged




Event Type

event_type

equals

RPZ

LEASE

TUNNEL
NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6 FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6
SESSION

SESSION is used for the login and logout events for the session management templates.


Table 45.16 Variables for DB Object Change Event - DHCP Network IPv6 

NIOS Field Name

Template Variable Name

Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes


Network


network

equals, contained in



ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String

Members

members




MS AD User Data

ms_ad_user_data




Comment

comment




network_container

network_container




options

options




unmanaged

unmanaged




Event Type

event_type

equals

RPZ

LEASE

TUNNEL
NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6 FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6
SESSION

SESSION is used for the login and logout events

for the session management templates.


Table 45.17 Variables for DB Object Change Event - DHCP Range IPv4

NIOS Field Name

Template Variable Name

Supported
Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox Member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

 network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String

Member

member




Boot File

bootfile




Start Address

start_addr




End Address

end_addr




MAC Filter Rules

mac_filter_rules




MS AD User Data

ms_ad_user_data




Next Server

nextserver




Server Association Type

server_association_type

contains, equals, begins with, ends with



Event Type

event_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Table 45.18 Variables for DB Object Change Event - DHCP Range IPv6

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



Timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox Member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals

Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String

Member

member




Boot File

bootfile




Start Address

start_addr




End Address

end_addr




MAC Filter Rules

mac_filter_rules




MS AD User Data

ms_ad_user_data




Next Server

nextserver




Server Association Type

server_association_type

contains, equals, begins with, ends with



Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV6

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Table 45.19 Variables for DB Object Change Event - DHCP Fixed Address IPv4

NIOS Field Name

Template Variable Name

Supported
Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data




Name

name

contains, equals, begins with, ends with



MAC Address

mac

contains, equals, begins with, ends with



IPv4 Address

ipv4addr

equals, matches range, matches CIDR



Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.


Table 45.20 Variables for DB Object Change Event - DHCP Fixed Address IPv6

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals

Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data




Name

name

contains, equals, begins with, ends with



IPv6 DUID

duid

contains, equals, begins with, ends with



Address Type

address_type

equals

Address, Prefix, or Both

IPv6 Address

ipv6addr

equals, matches range, matches CIDR



IPv6 Address Prefixipv6prefix

equals, matches range, matches CIDR



IPv6 Address Prefix bitsipv6prefix_bitsequals

Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.


Table 45.21 Variables for DB Object Change Event - DHCP Host Address IPv4

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Extensible Attributes

extattrs



Dictionary of extensible attributes from parent host record

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data




Host

host

contains, equals, begins with, ends with



MAC Address

mac

contains, equals, begins with, ends with



IPv4 Address

ipv4addr

equals, matches range, matches CIDR



Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.


Table 45.22 Variables for DB Object Change Event - DHCP Host Address IPv6

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Extensible Attributes

extattrs



Dictionary of extensible attributes from parent host record

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data

contains, equals, begins with, ends with


Host

host

contains, equals, begins with, ends with



IPv6 DUID

duid

contains, equals, begins with, ends with



Address Type

address_type

equals

Address, Prefix, or Both

IPv6 Address

ipv6addr

equals, matches range, matches CIDR



IPv6 Address Prefixipv6prefix

equals, matches range, matches CIDR



IPv6 Address Prefix bitsipv6prefix_bitsequals

Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Result Parsing

Besides the R: name space, which is always initialized, if a template step includes the parse setting, then the result returned by the server is interpreted and will be available in the P: name space. Result parsing is extremely naive and supports only the following:

  • JSON: In this case, the returned JSON will be available in the P name space if it is a dictionary, otherwise it will be as-is in the P:PARSE variable. If JSON is malformed, an error will be logged and P:PARSE will be set to an empty dictionary.
  • REGEX: The supplied REGEX is applied to the whole body and it will be available in P:PARSE[0] to P:PARSE[N], if you have specified more than one groupings. In this case, P:PARSE[0] contains the full match, and P:PARSE[1..N] contains each individual grouping match. If no groupings are parsed, then P:PARSE will be a string with the matched expression. If one grouping is parsed, then P:PARSE will be a string with the matched grouping result. Note that ^ and $ anchors are the anchors for the whole output to be parsed.
  • REGEXLINE: The supplied REGEX is applied to every line returned by the server, and each match is assigned to P:PARSE[0] to P:PARSE[N] depending on how many lines match. The REGEX must contain only one grouping. If there are many groupings then the last matched grouping is put in the PARSE value, but if there are no groupings provided then the full match is put in each line. Note that ^ and $ anchors in this case are the anchors for each line.
  • REGEXMULTILINE: REGEXMULTILINE can be used when multiple groupings are required to be matched in multiple lines. Each match will be in P:PARSE[0..n] and each individual match is a list where the first value is the full REGEX match, and each subsequent value is a grouping match. The first grouping match of the first match can be accessed via ${P:PARSE[0][1]}. Note that ^ and $ anchors in this case are the anchors for each line.

For all REGEX cases, if there are no matches, P:PARSE is set to an empty string.

  • CONDITION: In some cases, when a condition on a REGEX match is required, it is recommended to use a CONDITION step with the :L (length) format specifier applied to PARSE. So when ${P:L:PARSE} is matched with = 0, it would create a condition evaluating to true if there was a regular expression match.
  • XML: For XML, the XML data is converted into a dictionary of dictionaries/lists depending on the XML present. Similar to JSON, this will be available in the P name space if it is a dictionary, otherwise it will be as-is in the P:PARSE variable. If the XML is malformed or not parseable, then an error is logged and P:PARSE is set to an empty dictionary.

Parsing does not support DTDs, schemas, or XML attributes. It simply converts the XML document as-is. This also means that if the schema defines a particular element to be a list, it might not be deserialized as a list depending on how many members are present (if there is only one, then the parent is not considered a list.) When serializing XML, any variable composed of a dictionary with an '<xmla>' member set to True will be serialized as an XML element with attributes.

If an XMLA element is serialized under JSON/XML, the attributes will be ignored and the appliance returns a meaningful result (a list of XMLA variables will be serialized in JSON as a list of the values of these elements, assuming the values are simple strings/numbers).

For example, consider the following XML:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_list_
output.dtd">
<APPLIANCE_LIST_OUTPUT>
   <RESPONSE>
     <DATETIME>2014-01-02T09:26:01Z</DATETIME>
     <APPLIANCE_LIST>
       <APPLIANCE>
          <ID>777</ID>
          <NAME>scanner1</NAME>
          <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
          <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
          <STATUS>Online</STATUS><S2>Online</S2>
      </APPLIANCE>
      <APPLIANCE>
          <ID>1127</ID>
          <NAME>scanner2</NAME>
          <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
          <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
          <STATUS>Online</STATUS><S2>Online</S2>
      </APPLIANCE>
      <APPLIANCE>
          <ID>1131</ID>
          <NAME>scanner3</NAME>
          <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
          <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
          <STATUS>Offline</STATUS><S2>Online</S2>
      </APPLIANCE>
    </APPLIANCE_LIST>
    <LICENSE_INFO>
      <QVSA_LICENSES_COUNT>10</QVSA_LICENSES_COUNT>
      <QVSA_LICENSES_USED>3</QVSA_LICENSES_USED>
    </LICENSE_INFO>
  </RESPONSE>
</APPLIANCE_LIST_OUTPUT>

The XML will be deserialized as follows:

{

    "APPLIANCE_LIST_OUTPUT":

    {

         "RESPONSE": {

            "APPLIANCE_LIST": [

               {

                  "ID": "777",

                  "NAME": "scanner1",

                  "RUNNING_SCAN_COUNT": "0",

                  "S2": "Online",

                  "SOFTWARE_VERSION": "2.6",

                  "STATUS": "Online"

               },

               {

                  "ID": "1127",

                  "NAME": "scanner2",

                  "RUNNING_SCAN_COUNT": "0",

                  "S2": "Online",

                  "SOFTWARE_VERSION": "2.6",

                  "STATUS": "Online"

               },

               {

                  "ID": "1131",

                  "NAME": "scanner3",

                  "RUNNING_SCAN_COUNT": "0",

                  "S2": "Online",

                  "SOFTWARE_VERSION": "2.6",

                  "STATUS": "Offline"

               },
        ],
        "DATETIME": "2014-01-02T09:26:01Z",
        "LICENSE_INFO": {
            "QVSA_LICENSES_COUNT": "10",
            "QVSA_LICENSES_USED": "3"
        }
      },
   }
}

But the following will be deserialized differently:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_list_ output.dtd">

<APPLIANCE_LIST_OUTPUT>

      <RESPONSE>

         <DATETIME>2014-01-02T09:26:01Z</DATETIME>

         <APPLIANCE_LIST>

            <APPLIANCE>

               <ID>777</ID>

               <NAME>scanner1</NAME>

               <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>

               <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>

               <STATUS>Online</STATUS><S2>Online</S2>

           </APPLIANCE>

        </APPLIANCE_LIST>

        <LICENSE_INFO>

            <QVSA_LICENSES_COUNT>10</QVSA_LICENSES_COUNT>

            <QVSA_LICENSES_USED>3</QVSA_LICENSES_USED>

        </LICENSE_INFO>

    </RESPONSE>

</APPLIANCE_LIST_OUTPUT>

The XML will be deserialized as follows (note the difference in the appliance_list):

{

       "APPLIANCE_LIST_OUTPUT":

       {

           "RESPONSE": {

              "APPLIANCE_LIST": {

                  "APPLIANCE": {

                  {

                      "ID": "777",

                      "NAME": "scanner1",

                      "RUNNING_SCAN_COUNT": "0",

                      "S2": "Online",

                      "SOFTWARE_VERSION": "2.6",

                      "STATUS": "Online"

                 }

        },

        "DATETIME": "2014-01-02T09:26:01Z",

        "LICENSE_INFO": {

             "QVSA_LICENSES_COUNT": "10",

             "QVSA_LICENSES_USED": "3"

        }

     },

  }

}

  • XMLA: Infoblox strongly recommends that you use XMLA as the quoting option (as opposed to XML) when you create new action templates. New operations such as PUSH, POP, SHIFT and others are not officially supported for XML parsed data.

    XMLA parsing strips all white spaces (horizontal tab, line feed, vertical tab, form feed, carriage return, and space). To keep all white spaces, XMLA_WHITESPACE enum is added. The parsing is the same as XMLA except that there is no white space stripping.

    If you set parse to XMLA, the XML parsing supports XML attributes, and the XML document is put in the P:PARSE namespace variable, as illustrated in the following example. This example contains a mixed-attribute XML message with some values that contain attributes and some do not.

<?xml version="1.0" encoding="utf-8"?>
<SiteConfigResponse success="1">
   <Site id="27" name="SOAPUI13006925d-7dac-428d-aaf1-4038a98838a1" description="" riskfactor="1.0" isDynamic="0">
     <Description/>
     <Hosts a0="123">
         <host a1="123">server1.example.com</host>
         <host>server2.example.com</host>
         <host>server3.example.com</host>
         <host>server4.example.com</host>
         <host>server5.example.com</host>
     </Hosts>
     <Credentials></Credentials>
       <Alerting>
          <Alert name="test" enabled="1" maxAlerts="2">
          <scanFilter scanStart="1" scanStop="1" scanFailed="1" scanResumed="1" scanPaused="1"/>
          <vulnFilter severityThreshold="1" confirmed="1" unconfirmed="1" potential="1"/>
          <smtpAlert sender="user1@example.com" server="server6.example.com" limitText="0">
          <recipient>user2@example.com</recipient>
         </smtpAlert>
        </Alert>
       </Alerting>
     <ScanConfig configID="28" name="Full audit" templateID="full-audit" engineID="3" configVersion="3">
       <Schedules></Schedules>
     </ScanConfig>
   </Site>
</SiteConfigResponse>

The following is the deserialized response in P:PARSE when using XMLA parsing:

[

     {

         "<xmla>": true,

         "attrs": {

              "success": "1"

         },

         "index": {

              "Site": 0

         },

         "name": "SiteConfigResponse",

         "value": [

            {

               "<xmla>": true,

               "attrs": {

                  "description": "",

                  "id": "27",
                  "isDynamic": "0",
                  "name": "SOAPUI13006925d-7dac-428d-aaf1-4038a98838a1",
                  "riskfactor": "1.0"
                },
                "index": {
                  "Alerting": 3,
                  "Credentials": 2,
                  "Description": 0,
                  "Hosts": 1,
                  "ScanConfig": 4
                },
                "name": "Site",
                "value": [
                   {
                      "<xmla>": true,
                      "attrs": {},
                      "index": {},
                      "name": "Description",
                      "value": []
                   },
                   {
                      "<xmla>": true,
                      "attrs": {
                          "a0": "123"
                      },
                      "index": {
                          "host": 4
                      },
                      "name": "Hosts",
                      "value": [
                          {
                              "<xmla>": true,
                              "attrs": {
                                  "a1": "123"
                               },
                               "index": {},
                               "name": "host",
                               "value": ["server1.example.com"]
                          },
                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server2.example.com"]
                          },
                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server3.example.com"]

                          },
                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server4.example.com"]
                          },

                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server5.example.com"]
                           }
                       ]
                    },
                    {
                       "<xmla>": true,
                       "attrs": {},
                       "index": {},
                       "name": "Credentials",
                       "value": []
                    },
                    {
                       "<xmla>": true,
                       "attrs": {},
                       "index": {
                           "Alert": 0
                       },
                       "name": "Alerting",
                       "value": [
                          {
                               "<xmla>": true,
                               "attrs": {
                                   "enabled": "1",
                                   "maxAlerts": "2",
                                   "name": "test"
                               },
                               "index": {
                                  "scanFilter": 0,
                                  "smtpAlert": 2,
                                  "vulnFilter": 1
                               },
                               "name": "Alert",
                               "value": [
                                  {
                                      "<xmla>": true,
                                      "attrs": {
                                           "scanFailed": "1",
                                           "scanPaused": "1",
                                           "scanResumed": "1",
                                           "scanStart": "1",
                                           "scanStop": "1"
                                       },
                                       "index": {},
                                       "name": "scanFilter",
                                       "value": []

                                  },

                                  {

                                       "<xmla>": true,

                                       "attrs": {

                                          "confirmed": "1",

                                          "potential": "1",

                                          "severityThreshold": "1",

                                          "unconfirmed": "1"

                                        },

                                        "index": {},

                                        "name": "vulnFilter",

                                        "value": []
                                  },
                                  {
                                        "<xmla>": true,
                                        "attrs": {
                                             "limitText": "0",
                                             "sender": "user1@example.com",
                                             "server": "server6.example.com"
                                        },
                                        "index": {
                                             "recipient": 0
                                        },
                                        "name": "smtpAlert",
                                        "value": [
                                             {
                                                 "<xmla>": true,
                                                 "attrs": {},
                                                 "index": {},
                                                 "name": "recipient",
                                                 "value": ["user2@example.com"]
                                              }
                                         ]
                                      }
                                   ]
                                 }
                               ]
                            },
                            {
                               "<xmla>": true,
                               "attrs": {
                                  "configID": "28",
                                  "configVersion": "3",
                                  "engineID": "3",
                                  "name": "Full audit",
                                  "templateID": "full-audit"
                               },
                               "index": {
                                  "Schedules": 0
                               },
                               "name": "ScanConfig",
                               "value": [
                                  {
                                        "<xmla>": true,
                                        "attrs": {},
                                        "index": {},
                                        "name": "Schedules",
                                        "value": []

                                  }

                               ]

                           }

                       ]

                  }

             ]

      }

]

As shown in the example above, any XML value will become an internal dictionary that contains separate 'attrs' and 'value' members representing the XML attributes (if exist) and the XML values (if exist) of the element respectively, as well as the single "" boolean (set to True) to qualify this particular field as an XML attribute field (this is used when serializing, as well as for user-created XMLA values, see below).

You typically address the XMLA variable by using VAR{tag}{subtag}, which uses the VALUES of the tag (its value or its subtag(s)). To access the attributes of a tag, you use VAR{tag}{{attributename}}. Example: P::PARSE{SiteConfigResponse}{{success}}

If you need to access the name of a tag instead (for example if the remote server can return different tags depending on the status), use the [[name]] syntax. For example, you can use P::PARSE[[name]].

Adding Outbound Templates

Before you configure notification rules, you must add or upload outbound templates to the Grid. The appliance uses the scripts in these templates to process and sends outbound notifications to the endpoints. You can either modify existing templates or create new ones through Grid Manager. For information about how to create a template, see Creating Action Templates.


Note: When you add an outbound template or make changes to an existing one, it may take a few seconds to a few minutes until the changes are propagated to all the members.


Complete the following to upload an outbound template:

  1. From the Grid tab, select the Ecosystem tab -> Templates tab, and then click the Add icon. 
    or
    From the Grid tab, select the Ecosystem tab, and click Add Template from the Toolbar.
  2. In the Add Template wizard, complete the following:
    • Click Select to upload an outbound template. In the Upload dialog box, click Select and navigate to the template, and then click Upload. Select the Overwrite the existing template check box to overwrite an existing template.

3. Click Add to add an outbound template.

4. Optionally, click ViewResults to open the Syslog Preview dialog and view all the syslog messages. For more information, see Previewing Syslog Events.

Modifying Outbound Templates

To modify an outbound template:

  1. From the Grid tab, select the Ecosystem tab -> Templates tab -> template check box, and then click the Edit icon.
    or
    From the Grid tab, select the Ecosystem tab, select the template that you want to modify, click the Action icon  and select Edit.
  2. The <Template Name>Template editor contains the following tabs from which you can modify information:
    • General: You can modify the Name and Comment fields. All other fields are automatically propagated with available information, such as the template type, vendor type, event type, and action type.
    • Contents: This tab displays the content of the uploaded template file. You can modify the template contents and the appliance validates the content for proper JSON format when you save the configuration. For more information about the format of the templates, see Creating Session Management Templates and Creating Action Templates.
  3. Save the configuration.

Viewing All Outbound Templates

To view the list of outbound templates:

  1. From the Grid tab, select the Ecosystem tab, and then click the Templates tab.
  2. Grid Manager displays the following information:
    • Name: The outbound template name.
    • Vendor Type: The vendor type.
    • Event Type: The event type specified in the template.
    • Template Type: Displays the template type, such as Session Management or Action template.
    • Outbound Type: The endpoint type. This can be REST or DXL.
    • Comment: Comments that were entered for the outbound template.
    • Added On: Displays the timestamp when the template was uploaded to the Grid Master in this format: YYYY-MM-DD HH:MM:SS, plus time zone.

You can do the following in this tab:

  • You can select the Action icon  and do the following:
    • Edit: Select this to modify the outbound template information.
    • Delete: Select this to delete a template.
    • Export: Select this to export a template.
  • Edit the outbound template information.
    • Select the outbound template, and then click the Edit icon.
  • Delete an outbound template.
    • Select the template, and then click the Delete icon.
  • Export the list of outbound templates.
    • Click the Export icon.
  • Print the list of outbound templates.
    • Click the Print icon.
  • Use filters and the Go to function to narrow down the list. With the autocomplete feature, you can just enter the first few characters of an object name in the Go to field and select the object from the possible matches.
  • Create a quick filter to save frequently used filter criteria:
    1. In the filter section, click Show Filter and define filter criteria for the quick filter.
    2. Click Save and complete the configuration In the Save Quick Filter dialog box.

      The appliance adds the quick filter to the quick filter drop-down list in the panel. Note that global filters are prefixed with [G], local filters with [L], and system filters with [S].

  • Sort the outbound templates in ascending or descending order by column.

Deleting Outbound Templates

You can delete a template anytime after you have created it.


Note: Before you delete a template, ensure that it is not in use.


To delete a template:

  1. From the Grid tab, select the Ecosystem tab, and then click the Templates tab.
  2. Select the template that you want to delete, and click the Delete icon.
  3. Click Yes in the Delete Confirmation dialog.

Exporting Template Schema

The Export Template Schema feature allows you to export the session management and action template schema. You can use the exported schema to valid the templates before uploading them. The exported schema is in IETF JSON Schema format. It is a JSON file that is used to define and validate outbound templates you plan to upload to the appliance. If you want to create your own templates, you must follow this schema format. For information about this format, see https://tools.ietf.org/html/draft-zyp-json-schema-04.
Complete the following to export the outbound template schema:

  1. From the Grid tab, select the Ecosystem tab -> select the Templates tab.
  2. Expand the Toolbar, click ExportTemplateSchema -> select ActionTemplateSchema to export the action template schema or select SessionTemplateSchema to export the session management template schema.
  3. If there is only one template version, the appliance downloads the schema to your local system. If there are multiple template versions, the appliance displays the Export Action Template Schema or Export Session Template Schema dialog. In the dialog, select the template version that you want to export. The template schema is downloaded to your local system.




  • No labels

This page has no comments.