Validations

Overview

A record-level validation validates the values of a given entity record against a rule. Several validations may exist on a single entity.

There are two types of validation:

  • SemQL validations express the validation rule in the SemQL language. These validations are executed in the hub’s database.

  • Plug-in validations use a plug-in developed in Java. These validations are executed by Semarchy xDM. Controls that cannot be achieved within the database (e.g., those involving calling an external API) can be created using plug-in validations.

Create a SemQL Validation

To create a SemQL validation:

  1. Expand the entity node, right-click the Validations node and select Add SemQL Validation…. The Create New SemQL Validation wizard opens.

  2. In the Create New SemQL Validation wizard, select the Auto Fill option and then enter the following values:

    • Name: name of the object. During browsing, this name is used to designate errors on business views showing Source Authoring With Errors data.

    • Label: user-friendly label for this object. Note that as the Auto Fill box is selected, the Label is automatically filled in. Modifying this label is optional.

    • Description: (optional) enter a description for the SemQL validation.

    • Condition: enter the SemQL condition that must be true for a valid record. You can use the edit expression button Edit Expression button to open the SemQL Editor.

  3. Error Message: (optional) define a custom error message. This message is displayed on forms during authoring if the validation criteria are not met, replacing the default message.

    • Validation Scope: select whether the SemQL validation should be checked pre- and/or post-consolidation.

  4. Click Finish to close the wizard. The SemQL Validation editor opens.

  5. Press Control+S (or Command+S on macOS) to save the editor.

  6. Close the editor.

Create a Plug-in Validation

  • Semarchy xDM has a large set of built-in plug-ins. For the complete list of built-in plug-ins, see Plug-ins Reference.

  • You can also develop your own plug-ins, as described in Plug-in Development.

  • Before creating validation based on a plug-in not built-into Semarchy xDM, make sure that this plug-in was added to the platform by the administrator as explained in Manage Plug-ins.

To create a plug-in validation:

  1. Expand the entity node, right-click the Validations node and select Add Plug-in Validation. The Create New Plug-in Validation wizard opens.

  2. In the Create New Plug-in Validation wizard, select the Auto Fill option and then enter the following values:

    • Name: name of the object. During browsing, this name is used to designate errors on business views showing Source Authoring With Errors data.

    • Label: user-friendly label for this object. Note that as the Auto Fill box is selected, the Label is automatically filled in. Modifying this label is optional.

    • Plug-in ID: select the plug-in from the list of plug-ins installed in the platform.

    • Validation Scope: select whether the validation should be checked pre- and/or post-consolidation.

  3. Click Finish to close the wizard.
    The Plug-in Validation editor opens. The Plug-in Params and Plug-in Inputs tables show the parameters and inputs for this plug-in.

  4. Only the parameters that are mandatory for the plug-in to work are listed in the Plug-in Params. You can add the parameters you need to set to the list:

    1. In the Plug-in Params table, click the Define Parameters button.

    2. In the Parameters dialog, select the Available Parameters you want to add and click the Add >> button to add them to the Used Parameters.

    3. Click Finish to close the dialog.

  5. Set the values for the parameters:

    1. Click the Value column in the Plug-in Params table in front of a parameter. The cell becomes editable.

    2. Enter the value of the parameter in the cell, and then press Enter.

    3. Repeat the previous steps to set the value for the parameters.

  6. Only the inputs that are mandatory for the plug-in to work are listed in the Plug-in Inputs. You can add the inputs you need to set to the list:

    1. In the Plug-in Inputs table, click the Define Inputs button.

    2. In the Input Bindings dialog, select the Available Inputs you want to add and click the Add >> button to add them to the Used Inputs.

    3. Click Finish to close the dialog.

  7. Set the values for the inputs:

    1. Double-click the Expression column in the Plug-in Inputs table in front of an input. The SemQL editor opens.

    2. Edit the SemQL expression using the attributes to feed the plug-in input and then click OK to close the SemQL Editor.

    3. Repeat the previous steps to set an expression for the inputs.

  8. (Optional) Define a custom Error Message. This message is displayed on forms during authoring if the validation criteria are not met, replacing the default message.

  9. (Optional) You can use Advanced Plug-in Configuration properties to optimize and configure the plug-in execution.

  10. Press Control+S (or Command+S on macOS) to save the editor.

  11. Close the editor.

Advanced Plug-in Configuration

The validations using plug-ins provide options for optimizing and configuring their execution.
The following properties appear in the Advanced Configuration section of the editor:

  • Max Retries: if the execution of the plug-in fails, retries will be executed up to this specified number of times.

  • Behavior on Error: if the execution still fails after the Max Retries have been attempted, the plug-in either skips the current record, skips the entire task, or stops the whole job, depending on this property.

  • Thread Pool Size: this property defines the number of parallel threads used when running the plug-in. This option is taken into account only if the plug-in used is thread-safe and declared as such.