Using the Syntax Helper
  • 24 Nov 2024
  • 11 Minutes to read
  • Dark
    Light
  • PDF

Using the Syntax Helper

  • Dark
    Light
  • PDF

Article summary

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 (Asset and Relationship 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).
To learn more about field syntax, see Statement Concepts.

Note:
  • Autocomplete shows available options for Enforcement Action fields in the statement (but not for adapter fields - (asset and relationship 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 tab shows under Field Name (UI) 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 / Value Type shows the type of field (such as array, integer, string, bool).
  • An aggregated field or a field in a complex field is always defined as array.
  • 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 using Syntax

  1. Above the Define the statement box, click Syntax.

  2. Determine the Asset fields and/or Relationship fields whose values you want to work with, using the Syntax Helper to get the correct field names and copy them.

  3. Determine the Action Form field you want to populate with values from the Asset and/or Relation fields, using one of the following methods:

  4. With the help of Autocomplete, choose the functions and operators necessary to produce the values that you want in the Action form field.

  5. When you have completed entering the statement, click Validate for the system to automatically verify the statement syntax.

  6. After validating the Dynamic Value Statement, you can click Simulate to debug the statement.

Adding an Asset Field to a Statement

The Syntax Helper enables you to select under the Asset Fields tab the adapter field used in the Dynamic Value statement to configure the field in the configuration dialog (form). This tab provides the following information for each selected asset field:

  • Field Type - The type of field. For example, Single Value, Multiple Values, Single Select, Multiple Select.
  • Value Type - The type of value in the field. For example, bool, integer, float, string, date, array, array (string), number
  • Field Name in Statement - The Axonius database name of the field.

To select and copy an Asset field into the statement

  1. Click Syntax Helper and in the screen that opens, click the Asset Fields tab. In the Asset Fields tab that opens, the Module dropdown is automatically filled with the asset type that you selected in the Enforcement Set query Module dropdown (in the Select Assets tab).
Note:

It is not possible to select or change the asset type from the Module dropdown in the Asset Fields tab of the Syntax Helper. If you have not selected the asset type in the Enforcement Set Query, the Select field dropdown will not show relevant fields.

  1. Under Select Adapter Field, from the Adapters dropdown, select an adapter, and then from the Select Adapter Field dropdown, select one of the adapter fields. The following is displayed for the selected field: Field Type, Value Type, and Field Name in Statement.

SyntaxHelperActionFormFieldsNewB

  1. Click the copy icon to the right, click Close, and then paste the field name into the statement.
Note:
  • The Adapter Connection Label field is not supported. Instead, you can use the Last Fetched From Connection Label field, which is set with the value of the existing connection label of the connection.
    SyntaxHelperLastFetchedIFTTT

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

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

Clicking the Adapter Tags complex field opens the Adapter Tags table with one column per object - Tag Key, Key Value, Tag Source.

AdapterTagsComplexField

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

  1. 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).
  2. 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.
  3. Click Close.
  4. 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.

SyntaxHelperAdapterTagsDropDown

See a detailed example of a dynamic value statetment using the by_key function with complex field path and objects.

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

  1. In the Asset Fields tab, from the adapter dropdown, select the Custom Data adapter.
  2. From the Select Adapter Field dropdown, select and copy the relevant field into the statement.

SyntaxHelperCustomData

Adding a Relationship Field to a Statement

In the Relationship Fields tab of the Syntax Helper, you input the related asset type, relationship, and related asset field, and the system automatically returns the syntax of the Relationship field, i.e., the syntax of the adapter field in the related asset (i.e., an asset that is related to the Enforcement Action asset) based on a Relationship. You can then copy the related asset field directly into the Dynamic Value statement so that its value can be used to configure the field in the configuration dialog (form).

To select and copy a related asset field into the statement

  1. Above the Dynamic Value statement, click Syntax Helper, and in the dialog that opens, click the Relationship Fields tab.
  2. From the Select asset type dropdown, select the type of the related asset from which to fetch the field.
  3. From the Select Relationship dropdown, select a Relationship.
  4. Under Select Field, from the Adapters dropdown, select an adapter, and then from the Select field dropdown, select one of the adapter fields. The following is displayed for the selected field: Field Type, Value Type, and Field Name in Statement.

The following information is provided for the related asset field:

  • Field Type - The type of field. For example, Single Value, Multiple Values, Single Select, Multiple Select.
  • Value Type - The type of value in the field. For example, bool, integer, float, string, date, array, array (string), number
  • Field Name in Statement - The Axonius database name of the field in the format relation.asset type("relationship name").adapter_field
  1. Click the copy icon to the right, click Close, and then paste the field name into the Dynamic Value statement.

In the following example:

  • In Select Asset Type, select Disks as the asset type of the related asset.

  • In Select Relationship, select Has, a defined Relationship.

  • In Select Field, select the Asset Type field from the Axonius adapter.

The Field Type, Value Type, and Database Field Name of the Disk asset type are displayed.

SyntaxHelperRelationshipField

You can copy the related asset field name into the Dynamic Value statement.

device all then form.field_value set_value [relation.disk("Has").specific_data.data.asset_type]

Adding an Action Form Field to a Statement

The Syntax Helper presents under the Action Form Fields tab all the field names used in the configuration dialog (form) available for all Field type, Value type combinations. This tab includes the following information:

  • Field Name (UI) - Field name used in the user interface
  • Type - The field type
  • Field name in statement - The Axonius database name with an adjacent copy icon, enabling you to copy the field directly from the Syntax Helper into the statement.

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 (Field Name (UI), Type, and Field name in statement).

Field type, Value type (in EC)Name in GUITypeField name in statement
Single value, StringField valuestringform.field_value
Single value, DateSet datestringform.field_date.specific
Single value, FloatField valuenumberform.field_number
Single value, IntegerField valueintegerform.field_integer
Single value, BooleanField valueboolform.field_on
Multiple values, StringField valuearrayform.field_list.value
Multiple values, DateField valuearrayform.field_list_date.value
Multiple values, FloatField valuearrayform.field_list_number.value
Multiple values, IntegerField valuearrayform.field_list_integer.value
Note:

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)

  1. Click Syntax Helper. The fields from the selected Enforcement Action configuration dialog are listed in the Action Form Fields section under the Field Name (UI) column.
  2. 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.
  3. Click Close and paste the field name into the statement.

SyntaxHelper-ActionFormField.png

Validating the Dynamic Value Statement

Once you have completed entering a Dynamic Value statement in the Define the statement box, you can click Validate for the system to automatically verify that the statement syntax is valid.

  • If the statement syntax is correct, the following notification appears in green under the Define the statement box: Statement was validated successfully.
  • If the statement syntax is incorrect, the following notification appears in red under the Define the statement box: Statement validation failed at followed by the location of the error and the error. In this case, correct the error and Validate again.




Was this article helpful?