Configuration

Overview

The Extension Platform provides a simple method to configure and adjust Windchill Extensions using a UI. The configuration is a single annotated file that defines variables that hold configuration information: the system will read the annotations within the file and render a user-friendly interface in which WEX Administrators can alter the available values.

Implementation

In order to provide our Windchill Extension with a configuration UI, we need to include the following dependencies in our pom.xml.

<dependency>
    <groupId>com.wincomplm</groupId>
    <artifactId>wex-config</artifactId>
</dependency>
<dependency> <!-- includes helper classes, not mandatory -->  
    <groupId>com.wincomplm</groupId>
    <artifactId>wex-config-aux</artifactId>
 </dependency>

First, we need to create a class that implements IWexConfiguration, Externalizable, Serializable. It will define the fields that will appear in the UI as attributes labeled with the @ConfigOption annotation as seen below:

@WexComponent(uid = "example-config", description = "Example configuration")
public class ExampleConfiguration implements IWexConfiguration<ExampleConfiguration>,Externalizable,Serializable {

    // We need to not fail to serialize, worst case is a reset
    public static final long serialVersionUID = 1L; 

    // An annotate entry
    @ConfigOption(category = "Basic", description = "Simple string", required = false)
    String exampleString = "bad";

Note that the configuration has been registered as a feature, so it will appear in the features list alongside the methods or listener that the Windchill Extension might implement.

For each of the defined fields we must implement a getter and setter method. The name of both methods must match the name of the attribute used to define the field: the kernel will use that name and the Configuration will throw an error if the names do not match.

    public String getExampleString() {
        return exampleString;
    }

    public void setExampleString(String exampleString) {
        this.exampleString = exampleString;
    }

Finally we need to implement the serialization. In the case of a configuration that holds more than one field, the order of the fields in the writeExternal method must be the same as the one in the readExternal one.

    @Override
    public void writeExternal(ObjectOutput out) throws IOException {
        out.writeObject(exampleString);
    }//writeExternal

    @Override
    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
        try {
            this.exampleString = (String) in.readObject();     
        } catch (OptionalDataException ode) {
            System.out.println("Failed to process config [OK] if post install");
        }
    }//readExternal

Result

If the WEX Kernel successfully scans a configuration class, it will show a configuration icon in the Extension Manager for the relevant extension:

A new interface will popup to allow the WEX Admin to set the fields:

Technical Details

Supported Field Types

The following field types are supported:

• All primitive types.
• List.
• Map.

Each will render an appropriate UI to allow the user to input and edit the data.

Hidden field

There are some cases in which the WEX will require sensible information to be inputted in its configuration, for example the credentials of an external server to which it has to connect. There is a way to hide the information in these fields through the optional argument hidden in the @ConfigOption annotation:

@ConfigOption(category = "Credentials", description = "Password", longdesc = "Description", required = false, hidden = true)
    String password = "";

Serialization

The data in the form is serialized into a Windchill document. The system is resilient, but the developer must not alter the sequence of serialization as a newer version of the extension will not load a previous version's configuration.

Error Handing and Assignment

The WEX Framework provides the developer with two methods that allow them to adjust or reject the inputted data:

    public void assign(ExampleConfiguration configuration) throws WexValidationException {
        // Can add code here to adjust assignment
        // for example cross ref the system
    }

    @Override
    public void validate() throws WexValidationException {
        // We ccheck the consistency of the data here
        if (exampleString.equals("bad")) {
            throw new WexValidationException("exampleString","Please change to something that is not bad!");
        }
    }

The validate method also provides the user with feedback about the inputted data in the case it is wrong.

Administration

The configuration is stored as a document in the Site area of Windchill:

The admin can remove it or copy the contents to another system with the same extension installed in order to replicate the configuration.

Example

The Example - Configuration illustrates an implementation of a configuration.