About Configuring

Change Process

This section describes the process to follow when changing schema.

Perform all changes using this 2-step process:

Make proposed changes in the test database, with MQL scripting on so you can track all changes.
Create the schema scripts to run in your pre-production and/or production database from copies of the scripts provided with ENOVIA Business Process Services.

If you decide to modify one of the supplied programs, clone the original program and change the name of the cloned program. The names for all ENOVIA product programs are prefixed with "eService[name of install directory]" or "emx". Do not change this prefix and do not create custom programs using the eService prefix.

How the System Identifies Administrative Objects: Symbolic Name Properties

The system identifies administrative objects using symbolic names rather than standard object names.

Symbolic names have this syntax:

[administrative object type name]_[original object name with no 
spaces]

For example, the symbolic name of the Originator attribute is attribute_Originator. The symbolic name of the Product Manager role is role_ProductManager. If you change the name of the Originator attribute to Creator, the symbolic name remains attribute_Originator, allowing the system to identify the attribute even though the name has changed.

Do not change the symbolic name for an administrative object. If you do, objects in the schema will no longer be able to reference the object. Additionally, new software versions will be unable to identify the object for updating.

Whenever you refer to an administrative object within a program (Tcl or JSP program), you must use the object's symbolic name and not the standard name ("policy_Person", not "Person"). You must also use the symbolic name when specifying an administrative object as an input parameter that is to be passed to a program. For example, when specifying the eService Safety Vault, an attribute whose value is passed to the eServicecommonObjectGenerator.tcl program, you must use the symbolic name for the vault.

The symbolic names for all administrative objects are stored as properties of a program object called eServiceSchemaVariableMapping.tcl. Each property assigns a symbolic name to an administrative object. For example, this diagram shows the properties on the program object eServiceSchemaVariableMapping.tcl that assign a symbolic name to an attribute, type, and vault object.

For samples of JSP code that get the symbolic name for an administrative object, see Getting Symbolic Names. For a sample of how to get an administrative object name from a symbolic name, see Getting Administrative Object Names from Symbolic Names.

For instructions on how to view symbolic name properties, see Viewing Administrative Properties.

Tracking administrative objects using fixed symbolic names has several advantages:

You can easily change the name of administrative objects. As long as the symbolic name does not change, the system can identify renamed objects. The only exception is program objects that are installed with ENOVIA Business Process Services and applications. You should not change the name of these program objects, which are prefixed with "eService" or "emx".
When you do change a name, other administrative objects in the schema that reference the object are still able to identify the object. For example, if you change the name of the Originator attribute to Creator, the types that use the attribute called Originator will now use the attribute called Creator because its symbolic name is still attribute_Originator.
Because names can be changed without causing problems, the system changes names to prevent name collisions between objects in your existing database and objects in ENOVIA Business Process Services. If the installation program finds an existing object with the same name as a Business Process Services object, it adds a prefix to the name of the Business Process Services object. The prefix is "eService" and the version number of the installation. For example, if you install the version 10.7.0.0 ENOVIA Business Process Services onto a database that contains a Part type, the installation program renames the Part type within the ENOVIA Business Process Services to "eService10700~Part".
When upgrading to a new version, the system reliably finds the correct object to update, even if you have renamed the object and even if you have replaced the ENOVIA Business Process Services object with your object. As long as the symbolic name is assigned to the object you want to use, the installation program can update the object. For more information, see About Configuring.

Properties of Administrative Objects

Every administrative object has five properties that facilitate upgrades.

installed date-- current date on the system on which the install scripts ran when the object was initially installed; for example, "07-24-2007". This date is not updated when an object is updated in subsequent releases.
installer--the company name that designed the administrative object. For all objects installed with ENOVIA Business Process Services and ENOVIA products, the value is "ENOVIAEngineering".
Never enter "ENOVIAEngineering" for the installer property in any schema that you register without explicit permission from ENOVIA Engineering.
original name--the intended name for the object when it was originally installed. For example, if the standard name for the Part type is changed to avoid a name collision, the original name is still Part and does not include the prefix added to the name.
version--the software version number for the most recent update to the object, such as 10-7-0-0.
application--the name of the application the object is installed with. For administrative objects installed with ENOVIA Business Process Services (a majority of administrative objects), the value for this property is "Framework". For administrative objects installed by an application, the value is the application name with no white space, such as MaterialComplianceCentral.

For instructions on how to view administrative properties, see Viewing Administrative Properties.

The following diagram is the same as the one shown in the previous section, which shows the symbolic name properties for several administrative objects, but the five properties for each administrative object have been added.

How the System Identifies State Names

Like administrative objects, the system identifies policy states using symbolic names. For example, the symbolic name for the Active state of the Person policy is state_Active. Symbolic names for states are stored as properties on the policy object.

This diagram, which shows all the properties for several administrative objects, is the same as the one shown in the previous section except the properties have been added for a policy.

Resolving Schema Similarities

If you have a custom administrative object similar to a ENOVIA Business Process Services object, you must decide which one to use. The objects may have the same name and/or they may have the same symbolic name.

As described in "How the Installation Handles Schema Similarities" in the Live Collaboration BPS Installation Guide, ENOVIA Business Process Services handles these two cases differently when installing. However many of the decisions and procedures for resolving the similarities are the same.

To help find similarities, look in the installation log file. This file lists administrative objects that were renamed due to name collisions, and MQL add and modify commands that were skipped because an object with the same symbolic name already exists in the database.

When ENOVIA Business Process Services has an object that is similar to your custom object, decide whether the objects are really the same. It may be that they serve different functions and are both needed. In that case, you can rename one or both as needed.

If the objects are the same, you must decide which one to use. It is usually most efficient to use ENOVIA Business Process Services's administrative object instead of your object. Using the ENOVIA Business Process Services's object instead of your object usually involves:

Renaming your object and the ENOVIA Business Process Services object so the ENOVIA Business Process Services object has the correct name and there are no name collisions. For example, if the version 9.0.0.0 installation program renamed the Widget type ENOVIA Business Process Services object due to a name collision, you could rename your Widget type to OldWidget and rename the ENOVIA Business Process Services's eService9000~Widget to Widget.
Configuring the ENOVIA Business Process Services object so it has the attributes and other characteristics that your object has.
Making sure any of your existing objects, such as programs and policies, that reference the object you are replacing point to the ENOVIA Business Process Services object.
Migrating data from your administrative object to the ENOVIA Business Process Services's (if the object has been used in production).

Another alternative is to use your object instead of the ENOVIA Business Process Services object. This alternative usually involves more work than using the ENOVIA Business Process Services object. Replacing a ENOVIA Business Process Services object with your own object involves:

Pointing the symbolic name and the five administrative properties to your object instead of the ENOVIA Business Process Services's object. For instructions, see Merging Schema.
Configuring your object so it contains the attributes and other characteristics ENOVIA Business Process Services expects it to have.
Changing all references within ENOVIA Business Process Services to your object instead of the ENOVIA Business Process Services object. For example, if you want to use your Widget type instead of the ENOVIA Business Process Services's Widget type, you would have to make sure all relationships and policies that use the ENOVIA Business Process Services's Widget type now use your Widget type.

Reserved Prefixes, Names, and Characters

This section contains general guidelines for entering data and names.

All Fields

The tilde (~) and pipe (|) characters are reserved for use in the programming code for ENOVIA products. Do not use these characters when entering data for any field in ENOVIA Business Process Services or any ENOVIA product, including fields in application Web pages, ENOVIA Matrix Navigator, and Business Modeler. This restriction includes names, descriptions, comments, and all other attributes and properties.

Administrative Object Names

ENOVIA products are designed to let you use your exact business terminology rather than cryptic words that have been modified to conform to the computer system limitations.

Names are case-sensitive and spaces are allowed. You can use complete names rather than contractions, making the terminology in your system easier for people to understand. Generally, name lengths can be a maximum of 127 characters. Leading and trailing spaces are ignored.

You should avoid using characters that are programmatically significant to the applications. These characters are specified as follows for Administrative Object Names:

@ , * ? [ ] # $ { } \\\" < > | '

These characters are specified as follows for Administrative Object Descriptions, and other related Text fields:

# $ { }

To configure the system to allow the use of the above-listed special characters, see emxSystem.properties.

Also, do not prefix any administrative object (types, relationships, attributes, programs, wizards, etc.) with "eService".

Users should never use special characters for companies, business units, or persons, or for any attribute whose value is used in a Tcl or MQL script.

Program Objects

You need to follow specific rules when naming program objects.

Do not prefix program objects with any of these strings: bid, bom, build, common, draw, engchg, prodcfg, pom, profile, softchg, softrqmt, supplyacc, ui, or eService.
Do not prefix any administrative objects (types, relationships, attributes, programs, wizards, etc.) with "eService".

About Changing Administrative Names

You need to follow specific rules when changing administrative object names.

Keep these points in mind when changing administrative object names:

ENOVIA Business Process Services uses string resource properties to manage internationalization of schema names. The string resource IDs for administrative objects are defined using the actual administrative object name. Therefore, if you change an administrative object name and want the name to be displayed on internationalized versions of applications, you need to update the string resource ID in addition to the value for the ID. For instructions, see Translating Schema.
Do not use underscore _ in administrative object names because that is used in symbolic names and could affect parsing of the string.
Labels and other text for UI components--such as Actions menus, page headings, and tree category labels (items in a Categories menu)--that contain "words" that are the same as administrative object names are NOT updated automatically when schema is renamed. Onscreen text for UI components are defined, like other onscreen text, using string resource properties. Therefore, the string resource value must be changed to change the UI component text. Macros and expressions are not used for UI component text because they cannot be internationalized.

For example, suppose you rename the Part type to Item type. Onscreen text defined by retreiving data from the database, such as a select expression, shows the updated name, Item. If you updated the internationalized string resource ID and value, international versions also display the updated type name. However, a menu with the label "Create Part" will not be updated because the label is defined using a string resource and not using a macro or select expression. To update the menu label, you need to change the value for the string resource from "Create Part" to "Create Item". For instructions on changing onscreen text using string resource properties, see Changing Onscreen Text.

Do not change the names of program objects installed with the ENOVIA products. The names for these programs are prefixed with "eService[name of install directory]". Programs in the Schema directory are prefixed with "eService" or the application name only. Do not change this prefix and do not create custom programs using the eService or emx prefixes. If you need to modify the name of a ENOVIA product program, clone the program and change the name of the cloned program.

If you rename objects that are referenced in policy expression accesses, you must update any expressions that reference the object names. See Administrative Objects Used in Expression (Filter) Accesses.

About Creating Custom Types

You can create custom object types based on existing ENOVIA types by creating a subtype (deriving the new type from an existing type).

By basing the custom type on an existing type, the custom type inherits all triggers from the existing type and you do not need to manually assign them to the custom type.

When doing so, you should carefully consider which type you want to use to derive the custom type from. For example, you may have 2 similar types that have a different combination of triggers. Or, triggers can be assigned at different levels in a type hierearchy. Take this type hierarchy for example.

IEF Family is the parent type of IEF Assembly Family. If you derive your custom type from IEF Family, your type does not inherit the delete trigger. If the user deletes an object of the custom type, any instances of that object would not be deleted (controlled by the delete trigger) and for this type, the user does not have a way to delete instances which would remain in the database. For this example, you would want to use IEF Assembly Family as the derived from type.

See the Business Modeler Guide for details on creating subtypes. To register the new type, refer to Registering Your Own Administrative Objects. You can also add a number generator to the custom type as described in Configuring Automatic Business Object Naming.

Automatic Business Object Naming

When a user creates a business object, it is often convenient and sometimes necessary for the system to create a unique name for the object. For example, when a user creates an ECR, the system creates an ECR object and generates a name automatically. This name becomes a unique ID that distinguishes the ECR from all other ECRs.

Before you configure automatic naming (see Configuring Automatic Business Object Naming), these sections describe how it works.

ENOVIA Business Process Services uses automatic naming for these types of business objects:

Event
Inbox Task
Meeting
Message
Workspace Vault (folders and subfolders)
Workspace Member
Publish Subscribe
Route

The information in this section applies to these types and to automatically-named types used by any of the ENOVIA products.

Naming Conventions

Automatic naming is defined and can be configured per object type. You can use one naming convention for ECRs, and another convention for CAD Drawings. To find out which object types are named automatically, refer to the user guide that accompanies your ENOVIA product(s). The automatic naming conventions for each application are suggestions only. You can configure the naming as appropriate for your business processes.

Automatic names contain a number that increments by 1 for each object that is created. For example, if the number for the first object created is "0000100", the number for the second object created would then be "0000101", and so on. By default, each object name contains a prefix that is an abbreviation of the object type name. The prefix for ECRs is "ECR", so the first object is named "ECR0000100". You can change this prefix and you can add a suffix to the name.

If required by your business process, you can set up automatic naming so that whenever an object of a particular type (called the primary type) is created, additional objects of another type are also created. For example, if your business process requires that each ECR is accompanied by a detailed Specification, you can customize the application so that whenever an ECR is created, a Specification is also created and linked to the ECR by a specific relationship. You can also set up the numbering sequence for the object names so the numbers are the same for the two objects that are created.

Data Model for Automatic Naming

This diagram shows the data model for the automatic naming process.

For help reading the model, see How to Read Data Models.

Every object type that needs automatic naming must have an eService Object Generator object.

Every type that needs a unique numbering sequence requires an eService Number Generator object connected to the eService Object Generator. The Object and Number Generator business object types are governed by the eService Object Generator policy. The business objects are created in the eServiceAdministration vault (symbolic name vault_eServiceAdministration). For example, the automatic naming business objects for ECRs looks like this:

Although not configured out-of-the-box, you can configure a Specification object to be created every time an ECR object is created. In this case, the eService Object Generator for Specifications must be connected to the eService Object Generator for ECRs using the eService Additional Object relationship. Since the Object Generator objects are connected to the same Number Generator object, the numbering sequence is the same. The first ECR created would be called "ECR0000100" and the first Specification would be called "SP0000100".

The primary type is the type whose Object Generator is connected directly to the Number Generator and is on the From end of the Additional Object relationship, ECR in the case described above. Types on the To end of the Additional Object relationship are additional types--Specification in the above example. To define how the additional object connects to the primary object, specify a value for the eService Connect Relation attribute for the eService Additional Object relationship.

Object Generator Program

The program that generates the automatic names is called eServicecommonObjectGenerator.tcl.

The program accepts the following parameters. These parameters are passed by the program that creates the object, which may be a Tcl program or a JavaServer Page (JSP). See About Configuring.

ObjectGeneratorName--Name of the eService Object Generator that contains the attributes for the object type. For example, if the object generator is for ECRs the object generator name would be "type_ECR".
ObjectGeneratorRevision--Revision of the eService Object Generator.
CreateAdditional--Specifies whether to create additional objects. This is a flag with the values Null and Additional. Null means no additional objects are to be created. Default is Null.
ObjectVault--The vault in which to create the object; default is the context vault.
CustomRevisionLevel--Specifies a custom revision for the new object. Default is Null, no custom revision.

The program returns a list of lists. Each item in the list holds the ID, type, name, and revision of the object created. If there is an error, it returns a list with the first item as null and the second item contains the error message.

How Automatic Naming Works

When a user performs a task that calls for an object to be created using the automatic naming process, the eServicecommonObjectGenerator.tcl program performs the steps described in this section.

Makes sure the eService Object Generator object for the object type exists. If the object does not exist, the program returns with a null and an error message.

Gets the attribute values for the eService Object Generator for the type.

Locks the Number Generator object for the object type to avoid creating objects with the same name when more than one user attempts to create a object at the same time. If the object is already locked, the program waits for the time period set for the eService Retry Delay attribute. The program retries for eService Retry Count times. If the program is unable to access the Number Generator, it returns with a null and an error message.

After locking the Number Generator object, gets the next number to be generated from the eService Next Number attribute on the eService Number Generator object for the object type.

Updates the Next Number attribute with the next value to be assigned, which is the current value of the attribute + 1.

Unlocks the Number Generator so it is now accessible when another user needs to create an object.

Generates the name of the object to be created as PrefixNextNumberSuffix.

Makes sure the name is unique. If the object is unique, the program creates the object. If the name is not unique, the program tries to get a unique number until it gets one or until the eService Processing Time Limit (an attribute on the Object Generator) gets exhausted, whichever comes first. If the eService Processing Time Limit gets exhausted, then the program returns with a null and an error message saying that the Number Generator object is busy.

Determines if there are additional objects to be created using the value of the input parameter CreateAdditional. If no additional objects are to be created, the process is complete.

If additional objects are to be created, the program expands on the primary object for the relationship eService Additional Object and gets all the additional objects to be created. For each of these additional objects, the program makes sure the name is unique. If a name already exists, the program tries to get a new number.

The program then connects the newly-created primary object with the newly-created additional object(s). The relationships by which these objects are to be connected are the values of the attribute eService Connect Relation. The program assumes the From type of the relationship is always the primary object.

Calling the Object Generator from a JSP

To use the object generator in a JSP program, you can use the autoName function that is defined in eServiceUtil.jsp.

This file is in the "enovia" directory. You need to include the eServiceUtil.jsp in your JSP using an include directive: <@include file="eServiceUtil.jsp">.

The eServiceUtil.jsp defines two function signatures for overloaded autoName function. The first accepts a revision for the created object and the second does not accept a revision.

static public String autoName(HttpSession session, String type, String revision, String policy) throws MatrixException
To use this autoName function to create an object of type XYZ and revision 1, you would include the below in a JSP page. The example assumes type XYZ is governed by policy ABC.
```
String XYZObjId = autoName(context, session, "type_XYZ", "1", 
"policy_ABC");
```
static public String autoName(HttpSession session, String type, String policy) throws MatrixException
This function signature does not accept a revision. To use it to create an object of type XYZ without specifying a revision, you would include the below in a JSP page. The example assumes type XYZ is governed by policy ABC.
```
String XYZObjId = autoName(context, session, "type_XYZ", 
"policy_ABC");
```

Remember to register the symbolic name for any custom administrative objects (objects that are not supplied with the ENOVIA Business Process Services). If you use an unregistered symbolic name as an input for a program, the program will not work. See Registering Your Own Administrative Objects.

To create an additional object along with the primary object, pass the value "Additional" to the ObjectGenerator for the CreateAdditional parameter by defining a third function signature for autoName and adding the Additional parameter as the last parameter.

Calling the Obejct Generator from Tcl

To use the object generator within a Tcl program, call eServicecommonObjectGenerator.tcl using utLoad. Pass the ObjectGeneratorName, ObjectGeneratorRevision, ObjectPolicy, and CreateAdditional (optional) parameters to the eServiceNumberGenerator procedure.

Remember to register the symbolic name for any custom administrative objects (objects that are not supplied with ENOVIA Business Process Services). If you use an unregistered symbolic name as an input for a program, the program will not work. SeeRegistering Your Own Administrative Objects.

The following example shows how a Tcl program would use the object generator to create objects of type XYZ, revision 1, and policy ABC.

eval [utLoad eServicecommonObjectGenerator.tcl]

set sNewInfo [eServiceNumberGenerator "type_XYZ" "1" "policy_ABC" ""]

set sNewInfoErrorFlag [lindex $sNewInfo 0]

if {[string compare $sNewInfoErrorFlag ""] == 0 } {

set mqlret 1

set outstr [lindex $sNewInfo 1]

} else {

set sNewObjectId [string trim [lindex [lindex $sNewInfo 0] 0]]

set sNewType [string trim [lindex [lindex $sNewInfo 0] 1]]

set sNewName [string trim [lindex [lindex $sNewInfo 0] 2]]

set sNewRev [string trim [lindex [lindex $sNewInfo 0] 3]]

Shadow Agent Passwords

The password is the same for all shadow agent persons, including all of the grant agents. The password is stored in the code section of the emxcommonSessionInfo program object and is "shadowsecret" by default.

If you change this value in the program object, you must also change the password for all of the agents. Also, if you are upgrading and have already changed the password, you must change it again in this new location and change all of the new agents before using the system. You may want to change the password back to shadowsecret for the original User Agent person initially until you know everything is working and then change the password for all of the agents at once.

ENOVIA Business Process Services installs these shadow agent persons:

Shadow Agent Person	Assigned to Group
User Agent	Shadow Agent
Common Access Grantor	Access Grantor
Project Space Access Grantor	Access Grantor
Route Delegation Grantor	Access Grantor
Unmanaged Document Grantor	Access Grantor
Workspace Access Grantor	Access Grantor
Workspace Lead Grantor	Access Grantor
Workspace Member Grantor	Access Grantor