Syntax and actions

Syntax

The syntax of the jsonPlug method is:

moduleVariable.jsonPlug(result, {
    action: parameterValue,
    jsPathConditionFlag: parameterValue,
    jsPath: parameterValue,
    jsPathAction: parameterValue,
    values: parameterValue [,
    recursive: parameterValue,
    recursiveAction: parameterValue,
    skipNameValidation: parameterValue,
    addIndexToRecords: parameterValue,
    deleteJsPath: parameterValue,
    printMatchedItems: parameterValue]
});

Note

The parts in square brackets are optional.

parameterValue is one of the possible values of the corresponding parameters described below:

moduleVariable is the variable corresponding to the module and set with require().
result is the object containing the analysis results.
action is the action to perform on the results object. The available values for this parameter are:
Note

The following actions can be used interchangeably, producing the same output:
- delete template and delete record.
- clone template and clone record.
- add field and add fields.
- add template and add record.
- add instance and add instances.
- add property and add key.
jsPathConditionFlag is either a boolean or a string:
- true (boolean): the action specified by the action parameter is performed only if the value of jspath selects one or more nodes.
- false (boolean): the action specified by the action parameter is performed only if the value of jspath does not select any nodes.
- count (string): the action specified by the action parameter is performed only if a certain amount of nodes are matched by jspath (see explanation below).
- multiple (string): the action specified by the action parameter is performed only if multiple absolute and relative nodes validations are verified by jspath (see explanation below).
count: In this scenario, the module is designed to verify the number of nodes, referred to as — the count — selected by jspath. The action is executed exclusively when the specified condition is met (as detailed below). The string follows this format:

count operator integer

where:
- operator can be:
  - >
  - <
  - <=
  - >=
  - ==
  - ===
- integer is a non-negative integer number.
For example, if jsPathConditionFlag is:
```
count > 3
```
it means that jsPath must identify at least three nodes for the action to be applied.

multiple: In this context, the multiple option allows the users to implement advanced multiple validations within the jsPath array by sequentially applying multiple JSONPaths, encompassing both absolute and relative paths. You can find an illustrative example in the in the modify paragraph.
jsPath is either a single JSONPath expression or an array of JSONPath expressions that, in combination with jsPathAction (except when also jsPathAction is a full JSONPath expression), determines the nodes to which the action must be applied. The elements of the jsPath parameters are evaluated in couples:
- A boolean that is a flag necessary for the application of the action. If true, the action is performed to the nodes selected by the JSONPath expression.
- A JSONPath expression indicating the nodes where the action must be performed.
Info

Several useful resources are available on the Web to get more information about JSONPath syntax and to test JSONPath expressions.

Warning

It is suggested to avoid using the recursive .. iterator inside a JSONPath expression, as it would process unncessary nodes within the result object.

For example, if you need to match every category, it is preferable to use $.match_info.rules.categorization[0:] instead of $..categorization.

The latter will process every child node starting from the root object, potentially causing unnecessary processing overhead.

By specifying the exact path in the JSONPath expression, you can optimize the matching process and improve the efficiency of your scripting.
jsPathAction is either a special value, a single JSONPath expression or an array of JSONPath expressions (for the array case, see the second example in clone) that, alone or in combination with jsPath, determines where the action must be applied. Its value can be:
- #this# or .: the action is applied to the same nodes selected by jspath.
- ^: the action is applied to the parent nodes of the nodes selected by jspath.
- ^ relativepath: the action is applied to the sibling nodes of the nodes selected by jspath that matches relativepath.
- . relativepath: the action is applied to a child node selected by jspath that matches relativepath.
- a JSONPath expression: the action is applied to the nodes selected by jsPathAction if jspathConditionFlag is satisfied. In case of an array, the elements of the expression are:
  - A boolean that is a flag necessary for the application of the action. If true, the action is performed to the nodes selected by the JSONPath expression.
  - A JSONPath expression indicating the nodes where the action must be performed.

Note

Even though the jsPathAction parameter is usually mandatory, it can be omitted (or passed empty) when one of the following actions is used: add category, add template and add record, clone template and clone record, clone new, clone new multiple

values is an array containing the specification of the action. The meaning of the array items and their order vary according to the action; a few actions do not use it.

Note

When a single string is expected in the array (e.g. in the modify or clone record actions, values can also be directly declared as a single string. This simplifies the syntax and makes it more concise.

recursive (optional) is a boolean that determines whether the action should be applied to only the first node selected by jsPath (false value), or to all the matched nodes (true value). If not explicitly declared, it defaults to true.
recursiveAction (optional) is a boolean that determines whether the action should be applied to only the first node selected by jsPathAction (false value), or to all the matched nodes (true value). If not explicitly declared, it defaults to true.
skipNameValidation (optional, defaulted to false) if set to true, the template and field validation will be skipped. This optional flag is used for:
- modify
- modify regex
- add field and add fields
- add template and add record
- clone
- clone template and clone record
- clone new
- clone new multiple
- clone value
- clone instances
addIndexToRecords (optional, defaulted to false) if set to true, an index property will be temporarily added to each extracted record during the jsonpath validation phase. This property will contain the position of each record within the extraction array and will be automatically deleted after the jsonpath evaluation is applied.
deleteJsPath (optional, defaulted to false) if set to true, the items matched by the jsPath expression will be removed from the output after the main action has been performed. Should the user activate this option while jsPathAction is either equal or directly refers to jsPath, an exception will be raised.
printMatchedItems (optional, defaulted to false) if set to true (boolean) or both (string), the items matched by the jsPath and jsPath expressions will be printed in the console for debugging purposes. The user can also specify either jsPath or jsPathAction (string) to print only the items matched by that specific JSONPath expressions.

Alternatively, you can use this syntax:

moduleVariable.jsonPlug(result, action, jsPathConditionFlag, jsPath, jsPathAction, recursive, values, skipNameValidation, addIndexToRecords, recursiveAction, deleteJsPath, printMatchedItems)

Note

The parameters in the second syntax must be declared in this exact order.
In this case, the recursive parameter MUST be declared.
Both syntaxes can be used interchangeably.

Actions

The following pages will describe the possible values of the action parameter. The value of the values parameter is interpreted based upon the value of action.

Note

All actions changing the categorization results will automatically re-calculate the frequency score of each category.

The example codes will be written according to the first syntax explained above.