Rules engine / Execute Rules

Execute rules of the rules engine.

Json

Example

Mode=ALLMode=USER_SELECTIONMode=REQUESTOnly rule computation, no items import

json

{
  "name": "rules-engine-execute-rules",
  "taskReferenceName": "execute_mapping_rules",
  "description": "The business description of the task",
  "type": "SUB_WORKFLOW",
  "optional": false,
  "inputParameters": {
    "mode": "ALL",
    "tableKey": "PRODUCTS",
    "accountKey": "",
    "partitions": [
        "active"
    ]
  }
}

json

{
  "name": "rules-engine-execute-rules",
  "taskReferenceName": "execute_mapping_rules",
  "description": "The business description of the task",
  "type": "SUB_WORKFLOW",
  "optional": false,
  "inputParameters": {
    "mode": "USER_SELECTION",
    "tableKey": "PRODUCTS",
    "accountKey": "",
    "partitions": [
        "active"
    ]
  }
}

json

{
  "name": "rules-engine-execute-rules",
  "taskReferenceName": "execute_mapping_rules",
  "description": "The business description of the task",
  "type": "SUB_WORKFLOW",
  "optional": false,
  "inputParameters": {
    "mode": "REQUEST",
    "request": "${previousTask.output.file}"
  }
}

json

{
  "name": "rules-engine-execute-rules",
  "taskReferenceName": "execute_mapping_rules",
  "description": "The business description of the task",
  "type": "SUB_WORKFLOW",
  "optional": false,
  "inputParameters": {
    "mode": "ALL",
    "tableKey": "PRODUCTS",
    "accountKey": "",
    "partitions": [
        "active"
    ],
    "importComputedItems": "NO"
  }
}

Definition

Property	Type	Required	Description
			The name (or type) of the task
			The unique name of the task in your job. It is used to reference this task in the workflow.
			The functional description of this task in your job.
			The type of the task. It must be `SUB_WORKFLOW`.
	:		`true`: the job continues if there is an error on this task. `false`: the job fails.
			Input parameters of the task. See below

Inputs

Property	Type	Required	Description
	:
			The target table key.
			The account key of the partner owning the shared table.
			To limit the execution to some specific partitions.
			An XML file containing the request to select the items to execute the rules on. The expected format is the same as the export items task request parameter.
	:		`YES`: The computed items will be imported. `NO`: The computed items will not be imported, but will be available in the output of the task. Default to `YES`
	:		Default: `false` When set to `true`, the report generation is skipped and thus the report is not available in the output parameters.
	:		Default: `info` It defines the log level to be recorded in the report. `error` < `warning` < `info` < `debug`

Best practice

Limit the execution to only active items.

Outputs

Property	Type	Description
		Items in the same format as the export items task.
		`YES`: at least one warning. `NO`: no warnings.
		`YES`: at least one error. `NO`: no errors.
		An XML file containing the log of each warnings/errors.

How the rules are applied

Rules update items, they never create them

Executing mapping rules only ever updates existing items. It never creates one, whatever the rules say.

A few consequences worth knowing before you look for a bug:

Running the task on a table that carries no rule at all is not an error. A warning appears in the job execution detail and the task completes.
A rule whose target element already has a formula is ignored: the rule is not executed, and a message is added to the report.
Applying rules has the same effect as editing an attribute by hand, so it triggers a recalculation of the conditional formatting of every item it touched.
Classification rules run before field rules, so a field rule may rely on a classification another rule has just set.

Emptying the source empties the target

When a rule copies field B into field A and B is empty for a given item - the rule's conditions being otherwise met - A is emptied. This is deliberate, and it produces no log at all: neither error nor warning. An unexpectedly blank column after an execution is usually this, not a failure.

Archived elements

Archiving is not neutral, and it does not behave the same way on the source side and the target side:

Element	As a rule target	As a rule source
Table	The rules of an archived target table are not applied	No effect - rules still apply
Identifier	Rules targeting it are not applied	Its value is treated as empty
Classification	Rules targeting it are not applied	No effect - rules still apply
Field	Rules targeting it are not applied	No effect - rules still apply
Field whose `matrix` link is archived	Rules targeting it are not applied	Its value is treated as empty

Note the asymmetry on fields: archiving the field leaves rules working, while archiving its link in the matrix does not.

Which items a rule can read

Matching two items across tables relies on the source tables declared when the rules are imported. Only one link may exist between two given levels of two tables, and a level has exactly one parent.

To find the item of the source table that corresponds to an item of the target table, the engine starts at the target level and:

follows the link to the source table if there is one;
otherwise moves up to the parent level and tries again.

Every level crossed this way counts as linked. A rule set on a given target level may therefore use any field, classification or identifier belonging to a level linked to it by that walk - not just those of its own level.

When no link can be reached, the rule is not applied and the report says so.

`NUMBER` fields

Operations built with the TEMPLATE action are bounded:

at most 3 decimal places;
no value outside the double-precision range (±1.7976931348623157e+308);
NaN is not accepted;
no line break inside an operation;
scientific notation is accepted.

The suffix applied to the result depends on the field's default suffix:

Field has a default suffix	Suffix given by the rule	Result
Yes	valid	The rule's suffix is applied
Yes	invalid	The default suffix is applied
No	valid	The rule's suffix is applied
No	invalid	No suffix is applied

An invalid suffix therefore never fails the rule - it silently falls back.

`DATE` and `DATE-TIME` fields

With the COPY action, the value is truncated or padded according to the pair of types:

Source	Target	Result
`DATE`	`DATE`	Copied as-is - `2022-04-25` → `2022-04-25`
`DATE-TIME`	`DATE-TIME`	Copied as-is - `2022-04-25 14:34:00.000Z` → `2022-04-25 14:34:00.000Z`
`DATE`	`DATE-TIME`	Time set to midnight - `2022-04-25` → `2022-04-25 00:00:00.000Z`
`DATE-TIME`	`DATE`	Time dropped - `2022-04-25 14:34:00.000Z` → `2022-04-25`

With the SET_TEXT action the value is validated against the accepted date formats, exactly as on item import. An invalid format is not applied and a log is added to the report.

Report log codes

Code	Severity	Raised when
`DATE_INVALID_VALUE`	warning	A `SET_TEXT` value on a `DATE` field is not a valid date and was not applied.
`DATE_TIME_INVALID_VALUE`	warning	Same, on a `DATE-TIME` field.
`ACTION_EXECUTION_ERROR`	error	An action could not be executed - no matching source item, for instance. The log carries the identifiers, the action type and the field key.

Limits and additional notes

These limits apply to one mapping - the rules of a single target table, for your account.

Element	Limit
Fields with rules	20 000
Rules by field	1 000
Source tables	500
Rules by table	20 000

Rules engine / Execute Rules ​

Json ​

Example ​

Definition ​

Inputs ​

Outputs ​

How the rules are applied ​

Rules update items, they never create them ​

Emptying the source empties the target ​

Archived elements ​

Which items a rule can read ​

NUMBER fields ​

DATE and DATE-TIME fields ​

Report log codes ​

Limits and additional notes ​

Rules engine / Execute Rules

Json

Example

Definition

Inputs

Outputs

How the rules are applied

Rules update items, they never create them

Emptying the source empties the target

Archived elements

Which items a rule can read

`NUMBER` fields

`DATE` and `DATE-TIME` fields

Report log codes

Limits and additional notes