Use a Custom Parameter in an Entity Modification Rule Activation Script

Overview

This guide describes how to use a Custom Parameter of an Entity Copy Task inside the Activation Script of an Entity Modification Rule.

In this example, a Custom Parameter is used to specify if an Entity Modification Rule should be activated or not. This will be defined within the specific Task of an Entity Copy Task Template. A Custom Parameter called activateRule will be created for this purpose, having the default value false. When not changed, this means that the Entity Modification Rule will not be activated by default. Otherwise, if the value of the Custom Parameter is set to true, the Entity Modification Rule will be activated.

This is processed via the Activation Script of the Entity Modification Rule, which checks the value of the Custom Parameter and returns true or false accordingly.

Prerequisites

  • A Domain Model exists, containing at least one Domain Entity. In this example, the Domain Model is called Employee Database, and the Domain Entity is called employees. One of the Domain Entity’s attributes is called last_name. Further attributes are possible but not relevant for this example.

  • One Kafka Topic for source and target each exists, referencing the Domain Model and Domain Entity mentioned above.

  • A Custom Parameter called activateRule of type Boolean exists. The default value is set to false.

Multiple Steps

To reach the predefined goal, multiple steps are necessary. These steps are described in the following.

Step 1: Create the Entity Modification Method

The Entity Modification Method is created first, for subsequent use in the Entity Modification Rule. Since modifying the data is not the main focus of this guide, it will be kept as simple as possible. However, using the Activation Script should control, if the modification is applied or not.

Under the MASKING tab, a new Entity Modification Method is created. This method is named MaskingLastName, and the following code is added to the apply()-method:

def apply() {
    // first, get the value of the column "last_name"
    def value = data.get("last_name")
    // ... then append (copied) to the value
    value = value + " (copied)"
    // ... and replace the original value with the modified
    data.put("last_name", value)
}

Step 2: Create the Entity Modification Rule

On the existing Domain Entity employees of the Domain Model Employee Database, an Entity Modification Rule will be created. This rule will be activated or deactivated based on the value of the Custom Parameter activateRule.

To add the rule to the existing Domain Entity, navigate to the Domain Model Employee Database and then to the Domain Entity employees. Here, add a new Entity Modification Rule named MaskLastNameRule. Select the newly created Entity Modification Method MaskingLastName. Afterward, add the following code to the Activation Script of the Entity Modification Rule:

/*
 * This function decides whether this entity modification rule should be activated or not.
 */
def isActive() {
    // control if the rule should be activated based on the value of the Custom Parameter "activateRule" that is expected to be defined on the corresponding task object.
    return task.activateRule == 'true'
}

Step 3: Create the Entity Copy Task Template

Finally, an Entity Copy Task Template will be created, that we call CopyEmployees. Specify both Source connector type and Target connector type as Kafka Topic. Also, specify both Source kafka topic and Target kafka topic as the Kafka Topics that are existing as prerequisites of this example.

The Custom Parameter activateRule can now be added to the Task Template. Since its default value is false, the Entity Modification Rule will not be activated by default when using this Task Template. This will be overridden in the next step when creating a Task for this Template.

Step 4: Create a Task for the Entity Copy Task Template

To execute the Entity Copy Task Template, a Task must be created. The Task is named CopyEmployeesTaskMod. In the configuration of the Task, override the value of the Custom Parameter activateRule and set it to true. This means that the Entity Modification Rule will be activated when executing this Task, and thus the modification defined in the Entity Modification Method will be applied.

A second Task can be created, which is identical to the first one, except for the value of the Custom Parameter activateRule, which will be set to false. This means that the Entity Modification Rule will not be activated when executing this Task, and thus the modification defined in the Entity Modification Method will not be applied. However, this will not be part of this example, but just shows the possible use case of the Custom Parameter.

Step 5: Execute the Task and verify the results

When executing the Task CopyEmployeesTaskMod, the Entity Modification Rule will be activated, and thus the modification defined in the Entity Modification Method will be applied. This means that the value of the column last_name will be modified by appending " (copied)" to it. Verification is possible by checking the target Kafka Topic after execution of the Task.

Benefits

  • Define flexible XDM Task objects that can adapt their behavior based on Custom Parameters.

  • Avoid the need for multiple similar Task Templates by controlling rule activation via parameters.

Conclusion

This guide showed how to use a Custom Parameter of an Entity Copy Task inside the Activation Script of an Entity Modification Rule. By following the steps described above, the activation of an Entity Modification Rule can be controlled based on the value of a Custom Parameter defined in the Task configuration. This allows for more flexible and adaptable XDM Task objects.