- 12 Nov 2023
- 8 Minutes to read
Using the Syntax Helper
- Updated on 12 Nov 2023
- 8 Minutes to read
You can create a Dynamic Value statement (also referred to as "statement") to add dynamic values to the fields in an Enforcement Action configuration from the assets themselves. The Syntax Helper makes it easy to find the Enforcement Action fields that you want to populate, as well as the adapter fields that determine the values in the Enforcement Action fields.
Enforcement Action statements must include field names used in the Axonius database (and not the names displayed in the Axonius application). The Syntax Helper presents the Axonius database names for each field in the selected Enforcement Action with an adjacent copy icon, enabling you to copy the field directly from the Syntax Helper into the statement.
To learn more about field syntax, see Statement Concepts.
- Autocomplete shows available options for Enforcement Action fields in the statement (but not for adapter fields). You can choose a relevant action field name from the Autocomplete options instead of going into the Syntax Helper to find and copy the field name.
- Action form refers to the Enforcement action configuration dialog. The Syntax Helper Action Form Fields section shows under Name in GUI the list of required and Additional Fields by their User Interface names in the configuration dialog of the selected Enforcement Action. Each Enforcement Action has its own set of fields, and only those field names appear in the Syntax Helper and in the Autocomplete options.
- Field name in statement shows the corresponding field name in the Axonius database, and Type shows the type of field (such as array, integer, string, bool).
- When you use the Dynamic Value Statement Wizard to construct Dynamic Value statements, you choose the adapter and enforcement action fields from dropdowns, and do not need to use the Syntax Helper.
The following procedure describes how to construct a statement in the Define the statement text box using Syntax Helper and Autocomplete.
To construct a statement
Determine the Adapter fields whose values you want to work with, using the Syntax Helper to get the correct field names and copy them. See below how to add an adapter field to the statement.
Determine the Action form field you want to populate with values from the Adapter fields, using one of the following methods:
- Choose from the Autocomplete suggestions.
- Use the Syntax Helper to get the correct field names and copy them. See below how to add an action form field to the statement.
With the help of Autocomplete, choose the functions and operators necessary to produce the values that you want in the Action form field.
Adding an Adapter Field to a Statement
To copy an Adapter field into the statement
- Click Syntax Helper. In the Syntax Helper that opens, the Module dropdown is automatically filled with the asset type that you selected in the Enforcement Set query Module dropdown.
It is not possible to select or change the asset type from the Module dropdown in the Syntax Helper. If you have not selected the asset type in the Enforcement Set Query, the following message appears: Select entity type in enforcement set query to get relevant fields.
In the Adapter Fields section, from the Adapters dropdown, select an adapter, and then from the Select Adapter Field dropdown, select one of the adapter fields.
Click the copy icon to the right, click Close, and then paste the field name into the statement.
The Adapter Connection Label field is not supported. You can use the following workaround: Create a custom data field, copy the Adapter Connection Label value to that field, and then use the custom field in the Dynamic Value statement.
The following Custom Enrichment fields are supported in dynamic value statements:
- Adapter Enriched fields - Fields enriched based on a specific adapter; labeled with Enrichment.
- Common Enrichment fields - Fields enriched based on an Aggregated field; labeled with Common Enrichment.
Aggregated and Preferred Fields in the Syntax Helper
An Aggregated field contains data fetched from different adapters. For example, it can contain several Host Names, each one collected from a different adapter. As an Aggregated field can contain a list of values, it is defined as a list (array).
A Preferred field displays the most authoritative value for a specific piece of information when there are multiple values for a given asset. For example, the Preferred Host Name field has the most common host name value out of all the Host Name field values fetched for any given device. The Preferred fields values are calculated as part of each global discovery cycle and also every number of hours as specified.
When creating a statement with concat, join, or other operators, it is important to choose the correct type of field (single value, list of values).
Complex Fields in the Syntax Helper
A Complex field contains objects (subfields, keys), which can be of any data type, and can be complex fields themselves. You can include in a Dynamic Value statement a complex field path, as well as its objects.
For example, in the following screen, the asset profile of a device shows the Adapter Tags complex field in All Fields.
Clicking the Adapter Tags complex field opens the Adapter Tags table with one column per object - Tag Key, Key Value, Tag Source.
You can copy a complex field path and its objects into a Dynamic Value Statement using the Syntax Helper.
To copy a complex field and its objects into a Dynamic Value statement
- In the Syntax Helper, select an adapter from the Adapters list, and in Select Adapter Field, search for or select the complex field (in this example, Adapter Tags).
- Copy the field for use in the statement, as follows:
- To copy a complex field path: Select the complex field required for the statement and then click the adjacent Copy icon. The complex field's Axonius database full path name is copied.
- To copy an object of a complex field: Selecting a complex field shows all its objects (screen below). Select the object required for the statement and then click the adjacent Copy icon. The object's Axonius database full name - path followed by object, is copied.
- Click Close.
- In the Enforcement Action configuration dialog, paste the copied field into the statement.
- For the complex field path (as in [adapter_complex_field_path] in the by_key function), use the name from the syntax helper as is.
- For an object of a complex field (as in key_to_search_by and key_to_pick in the by_key function), you can remove the full path preceding the object name in the statement. For example, for Adapter Tags: Tag Key, instead of using the full syntax device.adapters_data.aws_adapter.tags.tag_key, you can use tag_key in the statement.
Custom Data Fields in the Syntax Helper
You can add custom data fields to selected assets on an Asset page from the Actions menu, or to all assets returned by a query using the Axonius - Add Custom Data to Assets enforcement action.
To learn more about using existing custom data fields and creating new ones, see Working with Custom Data.
When you create a Custom Data field, the field name assigned to it depends on the selected field type.
You can use a Custom Data field in a Dynamic Value statement.
To select a Custom Data field from the Syntax Helper
- In the Adapter Fields section, from the adapter dropdown, select Custom Data.
- From the Select Adapter Field dropdown, select and copy the relevant field into the statement.
Adding an Action Form Field to a Statement
The Syntax Helper presents under Action Form Fields all the field names (under Field name in statement) available for all Field type, Value type combinations. The Dynamic Value Statement Wizard and Autocomplete also present all possible choices. From this list, you should choose a field name that corresponds to the Field type, Value type combination configured in the Enforcement Action.
The following table includes the field names for some Field type, Value type combinations (first column in the table) in the Add Custom Data EC, followed by the three columns as they appear in the Syntax Helper under Action Form Fields (Name in GUI, Type, and Field name in statement).
|Field type, Value type (in EC)||Name in GUI||Type||Field name in statement|
|Single value, String||Field value||string||form.field_value|
|Single value, Date||Set date||string||form.field_date.specific|
|Single value, Float||Field value||number||form.field_number|
|Single value, Integer||Field value||integer||form.field_integer|
|Single value, Boolean||Field value||bool||form.field_on|
|Multiple values, String||Field value||array||form.field_list.value|
|Multiple values, Date||Field value||array||form.field_list_date.value|
|Multiple values, Float||Field value||array||form.field_list_number.value|
|Multiple values, Integer||Field value||array||form.field_list_integer.value|
When you create a Dynamic Value Statement for adding a custom date field, make sure to use form.field_date.specific with Date type set to Specific date, as a dynamic date can be written only to this type of Date field. Do not use form.field_date.now or a field with Date type set to Now, as this type of field cannot accept dynamic input and regardless of the statement, its value is always the action runtime.
To copy an Action form field into the statement (using Syntax Helper)
- Click Syntax Helper. The fields from the selected Enforcement Action configuration dialog are listed in the Action Form Fields section under the Name in GUI column.
- Hover over one of the Action form fields and click the copy icon that appears to the right of the Field name in statement entry. The field name is copied to the system clipboard.
- Click Close and paste the field name into the statement.
For more information about working with Enforcement Sets see the following:
Enforcement Center Overview
Using the Enforcement Center Page
Managing Enforcement Sets
Creating Enforcement Sets
Testing an Enforcement Set
Creating Enforcement Action Dynamic Value Statements
Scheduling Enforcement Set Runs
Running Enforcement Sets
Viewing Enforcement Set Run History
Terminating an Enforcement Set Run
Duplicating Enforcement Sets
Editing and Deleting Enforcement Sets