Example 17: Custom Validator

Overview

This example demonstrates how to create a custom validator using the Extension Development Kit.

You can find the code for this example in our GitHub repository.

Implementation

The Plus version of the Validator extensions — Promotion Validate Plus and Change Validate Plus — allows users to add their own validators as dynamic Windchill extensions. Unlike static code, which requires a system restart whenever changes are made, Windchill extensions can be added and updated without disrupting the system. This makes the dynamic approach far more flexible and cloud-compliant. Additionally, Windchill extensions are fully manageable through the Extension Manager, allowing for version control and easier deployment. In contrast, static code requires direct access to the Windchill codebase, making it less efficient and harder to manage in modern cloud environments.

The methods for both Extensions must be static and return an Object array with two elements:

Index	Type	Description
`[0]`	`String`	A message describing the reason for any validation failure.
`[1]`	`int`	A status code indicating the result of the validation.

#### Status Code Values

0 – Success: Validation passed successfully.
1 – Error: Validation failed. The process is interrupted.
2 – Warning: Validation did not pass but the error is not critical. The user will be allowed to continue with the process.
3 – Ignore: Validator is not relevant to the current operation. The user will be allowed to continue with the process.

The only difference between the signatures of the custom Promotion Validate Plus and Change Validate Plus Validators are the arguments each of them take. They are detailed below.

Promotion Validate Plus

Signature

public static Object[] validate(Promotable item, List items, String targetState)

Arguments

The arguments of the custom Validator methods for this extension are as follows:

Promotable: The item being checked.
List: A list of the other Promotables that are also part of the Promotion Request.
String: The target state to which the items are being promoted.

Note: We use POJOs (Plain Old Java Objects) for both the parameters and the return value. This is intentional, as it reduces the coupling required when using a shared data model.

@WexComponent(uid = "wex-promote-validators", description = "Wex Promotion Validators")
public class PromoteMethodValidators {

   @WexMethod(name = "validate-OK", description = "Will be ok")
   public static Object[] validateOK(Promotable item, List items, String targetState) {
       Object[] result = new Object[2];
       result[0] = "This is an OK message";
       result[1] = 0;
       return result;
   }

   @WexMethod(name = "validate-error", description = "Will always throw an error")
   public static Object[] validateError(Promotable item, List items, String targetState) {
       Object[] result = new Object[2];
       result[0] = "This is an error message";
       result[1] = 1;
       return result;
   }

   @WexMethod(name = "validate-warn", description = "Will always throw a warning")
   public static Object[] validateWarn(Promotable item, List items, String targetState) {
       Object[] result = new Object[2];
       result[0] = "This is a warning message";
       result[1] = 2;
       return result;
   }
}

Change Validate Plus

Signature

public static Object[] validate(WexChangeItemPlus item, List<WexChangeItemPlus> items)

Parameters

WexChangeItemPlus item: the object being validated at the time. The method will execute once for every object included in the validation process.
List<WexChangeItemPlus> items: all of the objects included in the validation process.

Note: the previous public static Object[] validate(Persistable item, List<Persistable> items) is still supported by the system. This new method signature supports access to WexChangeItemPlus data such as WexChangeItemPlus.getTargetState() and WexChangeItemPlus.isResulting(), so it offers the developer more flexibility in their code. Nevertheless, signature backwards compatibility is ensured.

Examples

public static Object[] validate(WexChangeItemPlus item, List<WexChangeItemPlus> items) {
    Object[] result = new Object[2];
    result[0] = "This is an error message";
    result[1] = 1;  // 1 represents an Error
    return result;
}

For an OK response:

public static Object[] validateTestOK(WexChangeItemPlus item, List<WexChangeItemPlus> items) {
    Object[] result = new Object[2];
    result[0] = "This is an OK message";
    result[1] = 0;  // 0 represents OK
    return result;
}

Requirements

In order to use this signature, the developer needs to add wex-change-validate-adv to their Maven project dependency list. This can be done by adding to their pom.xml the following block, under <dependencies>:

<dependency>
    <groupId>com.wincomplm</groupId>
    <artifactId>wex-change-validate-adv</artifactId>
    <version>2.0-${wex.wt}</version>
    <scope>provided</scope>
</dependency>

The ${wex.wt} variable holds the Windchill version of the target system. The version must be 2.0 or higher.

WexChangeItemPlus

The WexChangeItemPlus class is held in wex-change-validate-adv and holds the following methods:

Persistable getObject(): returns the item.
String getOid(): returns the item's OID.
String getTargetState(): returns the item's Target State, in case the item is listed in the Resulting Objects of the Change Notice.
boolean isResulting(): returns true if the item is in the Resulting Objects of the Change Notice.

Alternative Signature

Alternatively, Change Validate Plus also offers a lightweight signature that does not require adding change-validate-adv as a dependency to your Maven project. The usage of this signature is less flexible and does not allow for usage of the capabilities offered by the WexChangeItemPlus class. The signature is the following:

public static Object[] validate(Persistable item, List<Persistable> items)

And the arguments go like this:

Persistable: The Persistable item being validated at the time.
List: A list of other Persistables that are also part of the Promotion Request.

@WexComponent(uid = "wex-change-validators", description = "Wex Change Validators")
public class ChangeMethodValidators {

   @WexMethod(name = "validate-test-error", description = "Will always throw an error")
    public static Object[] validateTestError(Persistable persistable, List<Persistable> items) {
        Object[] result = new Object[2];
        result[0] = "This is an error message";
        result[1] = 1;
        return result;
    }

    @WexMethod(name = "validate-test-OK", description = "Will always return an OK")
    public static Object[] validateTestOK(Persistable persistable, List<Persistable> items) {
        Object[] result = new Object[2];
        result[0] = "This is an OK message";
        result[1] = 0;
        return result;
    }

    @WexMethod(name = "validate-test-WARN", description = "Will always throw a warning")
    public static Object[] validateTestWarn(Persistable persistable, List<Persistable> items) {
        Object[] result = new Object[2];
        result[0] = "This is a WARN message";
        result[1] = 2;
        return result;
    }

    @WexMethod(name = "validate-test-IGN", description = "Will always throw an ignore")
    public static Object[] validateTestIgnore(Persistable persistable, List<Persistable> items) {
        Object[] result = new Object[2];
        result[0] = "This is a IGNORE message";
        result[1] = 3;
        return result;
    }
}

Configuration

This code can be used in Promotion Validate Plus and Change Validate Plus just by adding the method into the Extension's Configuration as shown below:

Promotion Validator Example

Syntax

The syntax for using the validator methods is as follows:

[extension id]:[uid of class with the promotion methods].[method id]

An example of this syntax using the previous example would be:

com.wincomplm.wex-promote-adv:wex-promote-validators.validate-OK