core.validateInstances

Extend a definition instance viewer capabilities with a custom validator.

Usage:

 core.validateInstances("<definition-name>", function (instance, successCb, failCb) {
   ...
})

 core.validateInstances("<definition-name>", function (oldInstance, instance, successCb, failCb) {
   ...
})

Arguments:

Argument	Description	Required
definition-name	Refers to the name of the specific definition to which you want to apply the customization.	YES
function	callback function that will be invoked to perform the custom validation and that holds the data and contains all logic	YES

Function arguments:

Argument	Description
oldInstance	The initial state of the instance before any changes.
instance	The new instance state reflecting any user changes.
successCb	This is the callback function that will should be invoked if the validation succeeds
failCb([fail1,fail2, ...])	This is the callback function that should be invoked if the validation fails. It has the option to accept an array of objects containing failure information for each instance field.

Function `failCb` failure object structure:

Argument	Description	Required
fieldId	The field id with the error.	YES
localizedMessage	The error message	YES
l10nSource	The custom translation file	NO
l10nArgs	The arguments to use in the translation message	NO

TIP

The displayed errors can be translated. To enable this feature, you need to have the translation dictionary available on your server at server_*/recordm/customUI/i18n/<custom-translation>_<lang>.json. For further details, refer to this link.

### Examples:

The following code snippet ensures that a ticket cannot be closed without assigning a 'Responsible'. Therefore, if a user attempts to change the state to 'Done' and clicks the 'Save' button, the validation will fail.

// recordm/customUI/i18n/tickets_en.json

{
  "required": {
    "done": {
      "responsible-missing": "In order to close the ticket you need to assign a Responsible"
    }
  }
}

cob.custom.customize.push(function(core, utils, ui) {
  const DEFINITION = "Tickets";

  core.validateInstances(DEFINITION, function(instance, successCb, failCb) {
    const stateF = instance.findFields("State")[0];
    const responsibleF = instance.findFields("Responsible")[0];

    if (stateF.value === "Done" && !responsibleF.value) {
      failCb([{ fieldId: responsibleF.id, localizedMessage: "required.done.responsible-missing", l10nSource: "tickets" }]);
      return
    }

    successCb()
  });
});