The following sections should be used in conjunction with the Security Labels Configuration Steps. One or all of these customizations can be completed.

To enable custom security labels, you must complete the following steps. See the Security Labels Configuration Steps for more information about each of these steps.

A custom Java evaluator class can be used to determine if a participant is restricted by the security label value specified and to determine if the participant is able to modify the security label value. To do this, the class must extend the wt.access.UnrestrictedPrincipalEvaluator class.

The wt.access.UnrestrictedPrincipalEvaluator class contains four methods. Any of these methods can be overridden, depending on whether the default behavior is sufficient:

An example custom Java evaluator class can be found in the <Windchill>/prog_examples/access directory. For more information about the use case and setting up Windchill to use the example, refer to the Javadoc for the custom Java evaluator class for each of the implemented methods.

For more information about working with class files, see Managing Customizations.

When Windchill access control service methods are called to evaluate a user's access rights to information, the methods may be given a persistable object or a wt.access.AccessControlSurrogate. The AccessControlSurrogate acts as a stand-in for a persistable object, to evaluate access rights for the information returned when a database query is performed requesting specific attributes of an object rather than a full persistable. The surrogate contains attributes from the class it is representing and includes all possible attributes necessary for making the access control decision.

The boolean isRestrictedBySecurityLabelValue(WTPrincipal principal, SecurityLabeled object, String label_name, String label_value) method defined by the wt.access.UnrestrictedPrincipalEvaluator class could be given an AccessControlSurrogate object. If you override this method in a custom Java evaluator class, your custom code should check if the object is an instance of AccessControlSurrogate before trying to check various attributes.

The wt.fc.ObjectIdentifier method getId() can be used to get the unique identifier of the represented persistable object. The class name in the ObjectIdentifier is wt.access.AccessControlSurrogate. The surrogate has a getTargetClassName method which can be used to get the class name of the represented persistable object. For example:

The attributes that are available on the AccessControlSurrogate depend on the type of the represented persistable object and whether Agreements are enabled on your system.

The following attributes are available and have supported APIs to access them.:

If Agreements are enabled on your system in addition to the SecurityLabeled interface being a superinterface of the target class:

For custom security labels a custom Java translator class can be used to convert the internal form of the security label value into the external form of the security label value or back again. To do this, the class must extend the wt.access.CustomSecurityLabelValueTranslator class. The internal form is used by Windchill during access evaluations and is stored in the database. The external form is what is displayed in the Windchill interface and what users will enter when specifying a security label value. If no translator class is defined, the external form is the same as the internal form and is what is stored in the database.

There are certain restrictions on what can be included in the internal form. The equals (=) and comma (,) characters cannot be stored in the database. If your user-entered security label values will use either of these characters, you must use a translator class to remove them from the internal name. Similarly, the string NULL cannot be stored in the database. Using a custom Java translator class also allows you to have longer security label value names. The security label attribute is limited to 4000 characters in the database, so having lengthy security label values can cause a storage issue. By specifying a custom translator class, you can have descriptive label values in the Windchill user interface using an external form and less user-friendly values stored in the database using an internal form. A custom translator class can also be used to validate custom security label values, particularly in cases where there is no user interface to validate the user-specified label values.

The wt.access.CustomSecurityLabelValueTranslator class contains two methods:

The following simple example removes the restricted comma character (,) and replaces it with an unrestricted plus character (+). This example assumes that the external value never contains a plus character (+).

Each method must always return the same answer when given the same input. If you anticipate the internal value changing over time, consider putting a version number in the string. For example, if a custom security label represents third party companies with whom you work, you may need to add the countries in which each third party has offices at some point in the future. Initially, one external value could be “Company A”, with the internal value of “1:A”. In the future, when office locations of Company A need to be represented, the external value could change to “Company A (US)” and “Company A (UK)”. The corresponding internal values could change to “2:A-US” and “2:A-UK”. The version number can be used to let the custom translator class know how to translate each version individually since the database might have both versions stored.

For more information about working with class files, see Managing Customizations.

This information relates to the Edit the Security Labels Configuration File - Required step of the Security Labels Configuration Steps.

To enable custom security labels, add a CustomSecurityLabel element and its subelements for each custom security label. When you are finished, save and close the file.

The CustomSecurityLabel element contains the data for defining a custom security label, the authorized participant for the custom security label values (if not all users), the agreement type (if any) associated with the custom security label values, and various mappings used by applications and services to process custom security labels. There should be one CustomSecurityLabel element for each custom security label you configure. For example:

The name attribute of the CustomSecurityLabel element is the string that is stored in the database for this security label, in this case, THIRD_PARTY_PROPRIETARY. For this custom security label to be available in your Windchill solution, the enabled attribute must be set to true. This name value does not generally show in the user interface; the display name for this security label was defined in the <Windchill>/wtcustom/wt/access/accessModelRB.rbinfo file previously.

The SecurityLabelResourceKey element represents the resource key for the label, and is specified in the following format:

where <SECURITY_LABEL> is the value of the name attribute on the CustomSecurityLabel element. This resource key must be present in the accessModelRB.rbinfo resource file edited previously.

The CustomSecurityLabelValues element can have a single UnrestrictedPrincipal subelement, which specifies the authorized participant for the security label values. If the UnrestrictedPrincipal subelement is omitted, all users are cleared for access to objects with the custom label values.

The UnrestrictedPrincipal element can have a ufid subelement. The UFID, or Unique Federation Identifier, specifies a participant, which can be a user, user-defined group, or organization. The UnrestrictedPrincipal element can also have an evaluatorClass subelement, which specifies the evaluator class created in Create a Custom Java Evaluator Class. The ufid subelement and the evaluatorClass subelement can either be used together or individually under the UnrestrictedPrincipal element. For more information about the differences between using a ufid subelement, an evaluatorClass subelement, or both, see Specifying Authorized Participants for Custom Security Labels.

The UnrestrictedPrincipal element can optionally have an AgreementType subelement. An agreement can be used to grant temporary clearance to users who are not authorized participants for the security label values. The content for the AgreementType element is specified in the following format:

where <AGREEMENT_NAME> is the internal name of the agreement type or subtype.

The optional TranslatorClass element specifies the class created in section Create a Custom Java Translator Class. The TranslatorClass element converts the internal name of the security label values into the external names, which appear throughout Windchill, and back again. If the TranslatorClass element is not specified, the internal and external values for the custom security label values are the same.

The optional SecurityLabelParameter element contains the parameter name used by various authoring applications as a file attribute to map to this custom security label. SecurityLabelParameter is always the last element within the CustomSecurityLabel element. The parameter name must follow any restrictions for parameter names that exist for the authoring applications.