Skip to content

add/apply actions

Introduction

Here follows a list of the following actions described in the page:

  • add field
  • add fields
  • add template
  • add record
  • add category
  • add property
  • add key
  • add instance
  • add instances
  • apply math

add field/add fields

Use add field or add fields to add fields to a record and possibly modify their confidence score.

For example, consider this template:

TEMPLATE(PERSONAL_DATA)
{
    @Name,
    @Age,
    @Date_of_birth,
    @Phone_number,
    @Address,
    @Job,
    @Type_of_job
}

If this rule:

SCOPE SENTENCE
{
    IDENTIFY(PERSONAL_DATA)
    {
        @Name[TYPE(NPH)]
        <>
        @Job[LEMMA("writer")]
        <1:3>
        LEMMA("comic")
    }
}

is applied to the following input text:

Alan Moore is considered as the best writer of comics ever.

you will get this record:

Template: PERSONAL_DATA

Field Value
@Name Alan Moore
@Job writer

With this code:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add field",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["Age", "69", "Phone_number", "0000000000"]
    });
    return result;
}

or with this one:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add fields",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["Age", "69", "Phone_number", "0000000000"]
    });
    return result;
}

you will get this record:

Template: PERSONAL_DATA

Field Value
@Phone_number 0000000000
@Name Alan Moore
@Job writer
@Age 69

As you can see, the Age and Phone_number fields with values of 69 and 0000000000 were added to the PERSONAL_DATA record.

The contents of the values array must be:

field1Name, field1Value [, field2Name, field2Value [, ... fieldnName, fieldnValue]]

where:

  • field#Name is the field name.
  • field#Value is the field value.

The extracted fields have a confidence score of 1.00. With this code:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add field",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["Age", "69", result.match_info.rules.extraction[0].fields[0].instance, "0.40",
                 "Phone_number", "0000000000", result.match_info.rules.extraction[0].fields[0].instance, "0.40"]
    });
    return result;
}

or with this one:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add fields",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["Age", "69", result.match_info.rules.extraction[0].fields[0].instance, "0.40", "Phone_number", "0000000000",
                 result.match_info.rules.extraction[0].fields[0].instance, "0.40"]
    });
    return result;
}

the Age and Phone_number fields will get a confidence score of 0.40.

In this case, the contents of the values array must be:

field1Name, field1Value, instance, <confidence1Score [, field2Name, field2Value, instance, confidence2Score [, ... fieldnName, fieldnValue, instance, confidencenScore]]

where:

  • field#Name is the field name.
  • field#Value is the field value.
  • instance is the instance in the extraction array.
  • confidence#Score is the field confidence score.

add template/add record

Use add template or add record to create a new record of an existing template and possibly modify the confidence score.

For example, consider these templates:

TEMPLATE(PERSONAL_DATA)
{
    @Name,
    @Date_of_birth,
    @Phone_number,
    @Address,
    @Age,
    @Job
}

TEMPLATE(COMPANY)
{
    @Location,
    @Name
}

If the following rule:

SCOPE SENTENCE
{
    IDENTIFY(PERSONAL_DATA)
    {
        @Name[TYPE(NPH)]
        <>
        @Job[LEMMA("knowledge engineer")]
    }
}

is applied to this input text: 

Jonathan works as a knowledge engineer.

you will get this record:

Template: PERSONAL_DATA

Field Value
@Name Jonathan
@Job knowledge engineer

With this code:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add template",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["COMPANY", "Location", "Rovereto", "Name", "Expert.ai"]
    });
    return result;
}

or with this one:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add record",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["COMPANY", "Location", "Rovereto", "Name", "Expert.ai"]
    });
    return result;
}

you will get these records:

Template: PERSONAL_DATA

Field Value
@Name Jonathan
@Job knowledge engineer

Template: COMPANY

Field Value
@Name Expert.ai
@Location Rovereto

As you can see, a new COMPANY record was added, having the Location field set to Rovereto and the Name field set to Expert.ai.

The contents of the values array must be:

templateName, field1Name, field1Value [, field2Name, field2Value [, ... fieldnName, fieldnValue]]

where:

  • templateName is the template name.
  • field#Name is the name of a field.
  • field#Value is the value of that field.

The first three items are mandatory in order to define at least one field. The other items, when present, have to be added in couples to define additional fields and their values.

Note

  • In order to add a new record, jsPathAction must evaluate to an existing element.
  • This means that, if jsPathConditionFlag is set to false and jsPath did not match anything, jsPathAction must be set to $.match_info.rules.extraction. This ensures that a new record will be added successfully.

The fields of the new record have a confidence score of 1.00. With this code:

function onFinalize(result) {
   jsonPlug.jsonPlug(result, {
        action: "add record",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["COMPANY", "Name", "Expert.ai", result.match_info.rules.extraction[0].fields[0].instance, "0.40", "Location", "Rovereto",
                 result.match_info.rules.extraction[0].fields[0].instance, "0.40"]
    });
return result;
}

or with this one:

function onFinalize(result) {
   jsonPlug.jsonPlug(result, {
        action: "add template",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "#this#",
        values: ["COMPANY", "Name", "Expert.ai", result.match_info.rules.extraction[0].fields[0].instance, "0.40", "Location", "Rovereto",
                 result.match_info.rules.extraction[0].fields[0].instance, "0.40"]
    });
return result;
}

the fields will get a score of 0.40.

The contents of the values array must be:

templateName, field1Name, field1Value, instance, confidence1Score [, field2Name, field2Value, instance, confidence2Score [, ... fieldnName, fieldnValue, instance, confidencenScore]]

where:

  • templateName is the template name.
  • field#Name is the name of a field.
  • field#Value is the value of that field.
  • instance is the instance in the extraction array.
  • confidence#Score is the field confidence score.

add category

Use add category to add a new category.

For example, consider this taxonomy:

1   Animals 
    1.1 Cats
    1.2 Dogs

and this template:

TEMPLATE(DOGS_BREED)
{
    @Name
}

If this rule:

SCOPE SENTENCE
{
    IDENTIFY(DOGS_BREED)
    {
        @Name[ANCESTOR(100000144)] //@SYN: #100000144# [dog]
    }
}

is applied to this input text:

Rex is a beautiful 10 year old German Shepherd, and his help was extremely important for the Police.

you will get this record:

Template: DOGS_BREED

Field Value
@Name Gerhamn shepherd

With this code:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add category",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'DOGS_BREED')]",
        jsPathAction: "#this#",
        values: ["1.2", "Dogs", 10, 100.0]
    });
    return result;
}

you will get the same record above plus this categorization output:

Category Label
1.2 Dogs

As you can see, the 1.2 category with the Dogs label was added with a category score and compound score equal to 10 and a frequency equal to 100.0%.

Parameters jsPathAction and recursive are ignored.

The contents of the values array must be:

categoryName, categoryLabel, scoreAndCompound, categoryFrequency, categoryRules

where:

  • categoryName is the category name.
  • categoryLabel is the category label.
  • scoreAndCompound is a non negative integer number used for both the category score and the compound score.
  • categoryFrequency is a non negative decimal number used for the category frequency.
  • categoryRules is an array containing the triggered categorization rules like the standard specification of the rules.

add property/add key

Use the add property or add key actions to add custom properties to categorization or extraction results. This operation can be used to add information for further post-processing activities.

The values array must contain the following elements:

propertyName, propertyValue

where:

  • propertyName is the name of the new property, it must be a string.
  • propertyValue is the value to associate with the new property, it must be a string, a number or a boolean;

For example, the following code will add a jpMatched property with a value of true to each categorization entry:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
            action: "add property",
            jsPathConditionFlag: true,
            jsPath: "$.match_info.rules.categorization[0:]",
            jsPathAction: "#this#",
                values: ["jpMatched", true]
        });
    return result;
}

If the same property is added again, the new value will overwrite the previous value.

Warning

  • Trying to add a property with a name already used in the standard data model will trigger an exception.

Custom properties will be automatically discarded by Studio after the result object is returned by the onFinalize function.

add instance/add instances

Consider using the add instance or add instances actions to copy the instance object from one or multiple fields to other field(s) without altering the extracted value.

These actions come in handy when you need to preserve the highlights and debug information for auxiliary fields that are not required in the final output but are useful for explainability purposes.

Note that these actions do not make use of the values array, which can be left undeclared.

For example, suppose you use the same text and rules as in the add field action, and you want to copy the instance from the Name field to each aggregated sibling field named Age. You can achieve this with the following code in your onFinalize function:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "add instance",
        jsPathConditionFlag: true,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'PERSONAL_DATA')].fields[?(@.field == 'Name')]",
        jsPathAction: "^.fields[?(@.field == 'Age')]",
        recursive: true
    });
    return result;
}

apply math

Use apply math to apply mathematical operations to the extracted fields.

For example, consider this template:

TEMPLATE(TAXES)
{
    @TOTAL_MONEY,
    @VALUE_TO_SUBTRACT
}

If these rules:

SCOPE SENTENCE
{
    IDENTIFY(TAXES)
    {
        !LEMMA("tax")
        <1:2>
        @TOTAL_MONEY[TYPE(MON)]
    }

    IDENTIFY(TAXES)
    {
        LEMMA("tax")
        <1:2>
        @VALUE_TO_SUBTRACT[TYPE(MON)]
    }
}

are applied to this input text:

On a total amount of 40000€, your taxes are 5000€

you will get these records:

Template: TAXES

Field Value
@TOTAL_MONEY 40,000 euro

Template: TAXES

Field Value
@VALUE_TO_SUBTRACT 5,000 euro

With this code:

function onFinalize(result) {
    jsonPlug.jsonPlug(result, {
        action: "apply math",
        jsPathConditionFlag: true ,
        jsPath: "$.match_info.rules.extraction[?(@.template == 'TAXES')].fields[?(@.field == 'VALUE_TO_SUBTRACT')].value",
        jsPathAction: "$.match_info.rules.extraction[?(@.template == 'TAXES')].fields[?(@.field == 'TOTAL_MONEY')].value",
        values: ["subtract", "jspath", true, "."]
    });
    return result;
}

you will get these records:

Template: TAXES

Field Value
@TOTAL_MONEY 35,000

Template: TAXES

Field Value
@VALUE_TO_SUBTRACT 5,000 euro

As you can see, the value of the field VALUE_TO_SUBTRACT was subtracted from the value of the field TOTAL_MONEY.

The contents of the values array must be:

mathematicalOperation, dynamicValue, removalFlag, separator, rounder

where:

  • mathematicalOperation is the mathematical operation to apply (case insensitive). It can be:
    • Add: adds the value to the matched jsPathAction.
    • Multiply: multiplies the value by the matched jsPathAction.
    • Subtract: subtracts the value from the matched jsPathAction.
    • Divide: divides the value from the matched jsPathAction
    • Swap divide: divides the matched jsPathAction from the value.
    • Swap subtract: subtracts the matched jsPathAction from the value.
    • Calculate % from digit: calculates the percentage of the static/JSONPath value compared to the jsPathAction value.
    • Calculate digit from %: calculates to which percentage the jsPathAction value corresponds compared to the static/JSONPath value.
  • dynamicValue is either a static numerical value or a special JSONPath keyword in case the value is a variable to be taken from the matched JSONPath.
  • removalFlag is a boolean value, mandatory if you have non-numerical characters like currencies, otherwise optional. If set to true, all non-numerical characters will be removed when parsing the values.
  • separator is the optional thousand separator. It can be left empty (no separator added) or can be:
    • .
    • ,
    • none (no separator added)
  • rounder is the optional number of decimals after which rounding is applied, it can be left empty. If 0, the number is rounded to its closest integer.