Skip Headers

Agile Product Lifecycle Management Agile Configuration Propagation Guide Release 9.3.3 E39285-01 |
| Contents

Previous | Next |

# 8 Configuring the ACP Control File

This chapter is a conceptual overview of the contents of the control file and how its contents are interpreted by ACP. A brief section on XML formatting is included as a baseline of XML syntax when you modify the control file. Each of the main sections of the control file are discussed in this chapter.

## 8.1 ACP Control File

This chapter is a conceptual overview of the contents of the Control File and how it is modified so ACP does what you want it to. This final chapter of the manual is supported by the Appendixes, notably App. A about the ACP Configuration Types and App. B, "Java Regular Expressions."

The ACP Control File is how you tell ACP what to propagate. ACP knows how to propagate objects and which order objects need to be propagated in, but it does not know what to propagate. You must configure the Control File to communicate to ACP what you would like it to do.

By default, the Control File is named config.xml and is located in the project directory. This sample Control File doubles as "online documentation" in that it contains the complete syntax of the tag names, attribute names, and attribute values used by ACP in propagation operations.

The name and location of the Control File can be changed by setting the control.filename property in the Project Properties file (project.properties).

The control file (config.xml) is an XML file whose syntax must adhere to the control file schema, acp_control_file.xsd, located in the <ACP Install Dir>/schema directory. The Control File itself is a valuable source of information: it presents the complete syntax of ACP, listing all the configuration types, business logic attributes, regular expressions, and examples of instructions to ACP, the actions that it will take.

A graphical representation of the schema can also be found in the install directory. The graphical representation is called <ACP Install Dir>/schema/docs/acp_control_file.html. This file can be viewed through any Internet browser.

## 8.2 XML Format

ACP's control file uses basic XML constructs. Please familiarize yourself with these basic constructs before trying to make changes to the control file.

### 8.2.1 Element

XML elements have content (that is, data). This content can be:

- empty,

- simple content (such as text),

- element content, or

- mixed content.

Elements may also have attributes. Attributes are defined as part of the start tag.

All elements have a start tag and an end tag.

The element's content is everything specified from (and including) the element's start tag to (and including) the element's end tag.

The name of the element is defined by its start tag. The start tag and end tag must have matching names. (XML tag names are case-sensitive.)

Here are some examples of XML elements.

#### 8.2.1.1 Empty Element

An empty element is an element with nothing between its start and end tags. Since there is nothing between the start and end tags, there are actually two methods for expressing the element.

- Longhand Example: <middle_name></middle_name>

- Shorthand Example: <middle_name/>

#### 8.2.1.2 Simple-Content Element

An element with simple content is an element with only text between the start and end tags. Carriage returns and tabs that appear between the start and end tag are considered to be part of the text.

- Example: <last_name>Smith</last_name>

- Example with carriage returns:

<last_name>

Smith

</last_name>

#### 8.2.1.3 Element-Content Element

An element with element content is an element with only nested elements between the start and end tags.

- Example:

<name>

<first_name>Jane</first_name>

<last_name>Doe</last_name>

</name>

#### 8.2.1.4 Mixed-Content Element

An element with mixed content has both simple content and element content.

- Example:

<chapter>XML Syntax

<para>Elements must have a closing tag</para>

<para>Elements must be properly nested</para>

</chapter>

#### 8.2.1.5 Element with Attributes

An element with attributes has attributes defined in the start tag. An element can have any number of attributes. The format of an attribute is <attribute name>="<attribute value>".

- Example: <phone type="work">1-888-555-1212</phone>

### 8.2.2 Root Element or Document Element

All XML documents must have a root element; also known as the document element. The < agile > element is the root element for the ACP control file.

### 8.2.3 Element Tags

Element start and end tags are case sensitive and must match each other exactly. All element tags in the ACP control file are lowercase.

### 8.2.4 Element Attributes

XML elements may have attributes which appear as name/value pairs (<name>="<value>"). The value must be surrounded by quotes.

### 8.2.5 Comments in XML

XML allows for comments. You can add comments to the control file that can help during re-use.

The begin comment delimiter is "<!--".

The end comment delimiter is "-->".

Comments may not be nested. In fact, comments may not contain two consecutive dashes (--) within the text.

- Example: <!-- this is a comment -->

### 8.2.6 Special Characters

XML uses "<" and ">" to delimit element tags. It also uses quotes ("") to delimit attribute values. For this reason, these characters cannot be used within the data (text) portion of the XML. These characters must be specially encoded to appear as data. The ampersand (&) is used to encode the data. Therefore, the ampersand (&) is also considered a special character. All encodings begin with an ampersand (&) and must end with a semicolon (;).

Here are the proper encodings for the special XML characters:

Characters | Encoding
--- | ---
& | &amp;
< | &lt;
> | &gt;
" | &quot;

## 8.3 Business Logic Attributes in the Control File

In addition to being able to select which objects by configuration type, you can also influence the business logic that ACP uses with regard to configuration types.

The amount of influence on business logic varies by configuration type. For detailed information on attribute names and their allowable values, refer to "ACP Configuration Types."

### 8.3.1 Objects per File

<objects_per_file> attribute is available to all configuration types.

When exporting objects, ACP creates separate XML files for each configuration type exported in the ACP XML archive.

In addition, ACP can limit the number of objects written to an XML file. Once the limit is reached, ACP starts writing to a new XML file for that configuration type.

XML files for a configuration type are sequenced as 001, 002, 003, and so forth.

By default, ACP writes up to 1000 objects to an XML file for each configuration type.

Attribute name | Attribute tag | What it does | Values (default value is in Bold font)
--- | --- | --- | ---
Objects Per File | config_type objects_per_ file | The number of objects ACP writes to a single XML file creating a new XML file for the configuration type. | 1000

### 8.3.2 File Prefix

<file_prefix> attribute is available to all configuration types.

When exporting objects, ACP creates separate XML files for each configuration type exported in the ACP XML archive.

Since ACP may have to create multiple XML files per configuration type, a file prefix must be used for each file. This is the prefix before the sequence number for the file. ACP assigns a reasonable prefix to easily identify the XML files that are exported for each configuration type.

Attribute name | Attribute tag | What it does | Values (default value is in Bold font)
--- | --- | --- | ---
File Prefix | config_type file_ prefix | The prefix to use when naming the XML files generated by export. | Default (if not specified): configuration type-specific

### 8.3.3 Criteria Force Update

<criteria_force_update> attribute is available to the Criteria configuration type.

Typically, criteria should not be updated once in use as this may create an undesirable change to business behavior. Java Client presents a dialog when an in-use criteria is about to be changed and requires you to confirm this change. Similarly, ACP allows you to force in-use criteria to be updated. This setting is applied to all criteria processed.

Attribute name | Attribute tag | What it does | Values (default value is in Bold font)
--- | --- | --- | ---
Criteria Force Update | criteria force_update | Allows you to decide whether in-use criteria can be updated. | No. ACP does not allow an in-use criteria to be updated.

### 8.3.4 Autonumber Force Update

<auto_number force_update> attribute is available to the AutoNumber configuration type.

This attribute is used to control accidental updating of your company's autonumber sequences. When end-users unintentionally "upset" the autonumber sequence, and if the administrator attempts to revert the numbering, PLM may be subject to errors.

As understood by ACP, autonumbers in PLM now have two sets of properties.

- "First set" of properties are updated on a regular propagation - Name, Description, API Name

- "Second set" of properties can be controlled by Autonumber Force Update - Prefix, Suffix, Character Set, Number of Characters, Starting Number

When the "Yes" tag is used, both first and second sets of properties are updated. When the "No" tag is used, only the first set of properties is updated. The default is set to No.

Attribute name | Attribute tag | What it does
--- | --- | ---
AutoNumber Force Update | auto_number force_update | Controls accidental updating of autonumber sequences.

### 8.3.5 Force Delete List Entry

<force_delete_list_entry> attribute is available to the List configuration type.

This parameter addresses the problem of deletion of list entries that belong to lists that are in use by the PLM system. Although you cannot delete a list entry that is part of the configuration (an attribute default value), you can disable the value. If the <force_delete_list_entry> attribute is set to No (the default), then the list entry is disabled instead of deleted. The value remains listed as the default value.

The system issues warnings when "force" behavior is invoked. For instance, the user is prompted whether to wipe out references to the entry being deleted if not used as a default value. The prompt that the user s when deleting a list entry is shown no matter whether the list is in use. If a user creates a list, and immediately adds some values, and then tries to delete one of the values, the confirmation prompt is displayed.

Attribute name | Attribute tag | What it does | Values (default value is in Bold font)
--- | --- | --- | ---
Force Delete List Entry | force_delete_ list_entry | Determines whether a list entry is to be deleted or disabled | no, false, 0 all mean No = list entry is disabled, not deleted. yes, true, 1 all mean Yes = list entry is deleted, if possible.

### 8.3.6 New User Password

<new_user_password> attribute is available to the User configuration type.

ACP does not propagate user passwords; it would be a "security hole" if it did. Since passwords cannot be propagated, ACP must assign a password when creating new users. By default, ACP assigns the password "agile" to all users that it creates. This password must meet the Account Policy settings in Administrator. The <new user password> attribute allows you to choose the password that ACP assigns to new users.

For security purposes, the <new user password> must be encrypted. You can use the encryptpwd script to get the encrypted version of the password you would like to use; "Password Encryption Script". This setting is applied to all new users created.

Attribute name | Attribute tag | What it does | Value
--- | --- | --- | ---
New User Password | user new_ user_password | Password to assign a new user. This password is used only for new users. Passwords cannot be propagated. This value must meet any account policies you have set in your target instance. The password must be encrypted. | agile

### 8.3.7 Process Extension Association Rule

<px_association_rule> attribute is available to the Base Class, Class, and Subclass configuration types.

ACP works from the premise that Agile PLM configuration information is maintained in one instance and then propagated to other Agile PLM instances after it has been tested. In some situations this may not be the case.

For example, a golden configuration Agile PLM instance will not be used for testing. In this example, process extensions would not be developed and tested in the golden configuration environment.

To facilitate this multiple instance maintenance of configuration data, the propagation rule for process extension associations can be overridden. By default, the associations in the source instance are propagated to the target instance. This setting is applied to all objects of the configuration type it is used with.

Attribute name | Attribute tag | What it does | Values (default value is in Bold font)
--- | --- | --- | ---
Process Extension Association Rule | base_class px_ association_rule; class px_ association_rule; subclass px_ association_rule; | Determines how ACP will handle the process extensions associated with each class. | replace = the class-PX associations in the source are copied to the class in the target. ignore = the class-PX associations in the target are left as is. merge = the class-PX associations in the source are merged with the existing class-PX associations in the target.

### 8.3.8 User Association Rule

<user_association_rule> attribute is available to the Role and User Group configuration types.

ACP works from the premise that Agile PLM configuration information is maintained in one instance and then propagated to other Agile PLM instances after it has been tested. In some situations this may not be the case.

For example, a golden configuration Agile PLM instance will not be used for testing. In this example, a complete set of users would not be updated in the golden configuration environment.

To facilitate this multiple instance maintenance of configuration data, the propagation rule for user associations can be overridden. By default, the associations in the source instance are propagated to the target instance. This setting is applied to all objects of the configuration type it is used with.

Attribute name | Attribute tag | What it does | Values (default value is in Bold font)
--- | --- | --- | ---
User Association Rule | role user_ association_rule; user_group user_ association_rule | Determines how ACP will handle the users associated with each role or with each user group. | replace = the user associations for the role or user group in the source are copied to the role in the target. ignore = the user associations for the role or user group in the target are left as is. merge = the user associations for the role or user group in the source are merged with the existing role-user associations in the target.

## 8.4 Control File Sections

The Control File is divided into named sections. The Copy, Rename, and Delete sections direct ACP what to propagate. The Subobject Maps and Ignore References sections provide additional information and instructions when ACP is processing the Copy section. These are each detailed below.

In addition to the "named sections" of the control file, certain business logic attributes are used to influence the business logic that ACP uses with regard to certain configuration types. This is covered in "Business Logic Attributes in the Control File"

### 8.4.1 Copy (<copy>) Section

The Copy section is marked by the <copy> element, and is used by both Copy and Compare to determine which objects to process.

Each object has a configuration type, for example, List is a configuration type; Country is an object of the configuration type List.

In the Copy section, you tell ACP which configuration types to process. Within each configuration type, you tell ACP which objects to process. The list of objects configured in the Copy section represents a set of objects found in the Source instance.

#### 8.4.1.1 Configuration Types in Copy Section

A complete list of configuration types that support Copy (Create object, Update object, or Replace object) and the XML tags used to denote their elements can be found in "ACP Configuration Types". In the Copy section of the control file, objects to copy can be marked for inclusion or exclusion through regular expressions.

Note: The Copy section expects the object name, not the object key.

#### 8.4.1.2 Include Patterns

Include patterns allow you to limit which objects of a specific configuration type to process. If no include pattern is configured, then ACP uses the "select all" pattern (.*) as the include pattern.

#### 8.4.1.3 Exclude Patterns

Exclude patterns offer a second way to limit which objects of a specific configuration type to process. If no exclude pattern is configured, then ACP uses no exclude patterns. In order for an object to be excluded by an exclude pattern, the object matching the exclude pattern must also match one of the include patterns. An object is automatically excluded if it does not match one or more of the include patterns.

#### 8.4.1.4 Regular Expressions

Regular expressions allow you to use "wild cards" in your selection of objects to include or exclude. This prevents you from having to list each object individually. Keep in mind that an object's name can be expressed as a regular expression that matches to itself only.

Regular expressions give special meaning to certain characters. If the special character is used in an object's name, it will need special encoding in the include/exclude pattern to be able to match the object's name exactly.

Therefore, you can list objects individually as using wildcards. Regular expressions use special characters for its matching rules. These special characters may appear in your object names. "Java Regular Expressions" for more detailed information about regular expressions and their special characters.

#### 8.4.1.5 Putting it all together in Copy section

Let's take a look at a short example of the Copy section with some explanation of how ACP interprets what was specified.

    <copy>
    <lists>

<auto_number/>

<base_class>

</base_class>

<class>

<include>

<pattern>.*</pattern>

</include>

</class>

<privilege>

<include>

<pattern>\(Restricted\).*</pattern>

<pattern>Add Phases</pattern>

<pattern>Modify Programs &amp; Gates that I am owner of

</pattern>

<pattern>Admin\. Privilege</pattern>

</include>

</privilege>

<role user_association_rule="replace">

<include>

<pattern>.*</pattern>

</include>

<exclude>

<pattern>\(.*\).*</pattern>

</exclude>

</role>

<user>

<exclude>

<pattern>test.*</pattern>

</exclude>

</user>

    </copy>

In the above example, here is what ACP will process by configuration type.

- Auto Number: This is a shorthand notation. The shorthand notation is an empty element. It tells ACP to process the complete list of auto numbers found in the source data source.

- Base Class: This is similar to the shorthand notation in that it is an empty element. It tells ACP to process the complete list of base classes found in the source data source.

- Class: In this example, we explicitly use the include pattern that matches all objects. It tells ACP to process the complete list of classes found in the source data source.

- Privilege: In this example, we have listed multiple patterns. The pattern "\(Restricted\).*" matches privileges that begin with "(Restricted)". The pattern "\(Propagation\) Administrator" matches a single privilege with the name "(Propagation) Administrator".

Notice the need to escape the parentheses as parentheses are regular expression special characters.

The other three patterns demonstrate that it is possible to match on a specific object name. That is, the pattern can match exactly one object name.

Notice the encoding of the ampersand (&) in "Modify Programs &amp; Gates that I am owner of". This is necessary because the ampersand (&) is an XML special character.

Also, notice the encoding of the period (.) in "Admin\. Privilege". This is necessary because period (.) is a regular expression special character.

- Role: This example demonstrates the use of exclude patterns. In this example, we are asking ACP to process all roles except those that begin with "(…)". For instance, this would exclude the roles that begin with "(Propagation)" and "(Restricted)".

This example also illustrates the use of a business logic attribute. The attribute name is "user_association_rule". The attribute value is "replace". "Replace" instructs ACP to replace the users associated with the role in the target with those users associated with the role in the source.

- User: This example also demonstrates the use of exclude patterns. In this example, we omitted the include patterns. This is perfectly fine since ACP assumes that all objects of a configuration type will be processed when no include patterns are specified.

### 8.4.2 Rename (<rename>) Section

The Rename section is marked by the <rename> element. ACP uses the Source object key (API Name, Name, or User ID) to map it to an object in the Target instance.

If the key of the object changes in the Source, ACP no longer has a way to look up the object in the Target instance. The Rename section of the Control File resolves this dilemma. You can use the Rename section to "re-key" (rename the key) objects in the Target instance.

ACP processes the Rename section of the Control File before it processes the Copy section. This allows Copy to resolve any references to objects whose key has changed. Renames are processed only when the Target is an Agile instance.

#### 8.4.2.1 Configuration Types in Rename Section

A complete list of configuration types that support Rename and the XML tags used to denote their elements can be found in "ACP Configuration Types."

In the Rename section of the Control File, objects to be renamed are specified by maps. An error is reported if the object being renamed does not exist in the Target instance.

#### 8.4.2.2 Key Maps

A key map maps an object by its key (API Name, Name, or User ID) in the Source instance to an object's key in the Target instance.

In order for the map to have meaning, these two conditions should be met:

- an object should exist in the Source instance with the map's Source key, and

- an object should exist in the Target instance with the map's Target key.

#### 8.4.2.3 Source Key

The Source key is the API Name/Name/User ID of the object being mapped in the Source. Since this is part of a key map, the exact API Name/Name/User ID of the object must be specified.

#### 8.4.2.4 Target Key

The Target key is the API Name/Name/User ID of the object being mapped in the Target. Since this is part of a key map, the exact API Name/Name/User ID of the object must be specified.

#### 8.4.2.5 Putting it all together in Rename section

Let's take a look at a short example of the Rename section with some explanation of how ACP interprets what was specified.

    <rename>

<list>

<map>

<source_apiname>Countries</source_apiname>

<target_apiname>Country</target_apiname>

</map>

<map>

<source_apiname>My Category</source_apiname>

<target_apiname>Category 9 List</target_apiname>

</map>

</list>

<privilege>

<map>

<source_apiname>(Propagation) Configuration Administrator

</source_apiname>

<target_apiname>(Propagation) Administrator</target_apiname>

</map>

<map>

<source_apiname>Modify My Projects &amp; Gates</source_apiname>

<target_apiname>Modify Projects &amp; Gates that I am owner of

</target_apiname>

</map>

<map>

<source_apiname>Administrator Privilege</source_apiname>

<target_apiname>Admin. Privilege</target_apiname>

</map>

</privilege>

<subclass>

<map>

<source_apiname>My ECO</source_apiname>

<target_apiname>ECO</target_apiname>

</map>

</subclass>

    </rename>

In the above example, here is what ACP will process by configuration type.

- List: ACP will attempt the following renames:

- Rename the list "Country" to "Countries";

- Rename the list "Category 9 List" to "My Category".

- Privilege: ACP will attempt the following renames:

- Rename the privilege "(Propagation) Administrator " to "(Propagation)

- Configuration Administrator"; Note that the regular expression special characters for the Open Parenthesis and the Closed Parenthesis are not encoded here: this is because the map contains exact names and not regular expressions.

- Rename the privilege "Modify Projects & Gates that I am owner of " to "Modify My Projects & Gates".

- Rename the privilege "Admin. Privilege" to " Administrator Privilege". Note that the regular expression special character for the Period are not encoded here: this is because the map contains exact names and not regular expressions.

- Subclass: ACP will attempt the following rename:

- Rename the subclass "ECO" to "My ECO"

### 8.4.3 Delete (<delete>) Section

The Delete section is marked by the <delete> element. The Delete section allows you to propagate deletes objects in the target. Deletes only get processed when the target is an Agile instance. Deletes get processed before renames and copies. This allows ACP to report errors where you have asked ACP to delete an object that is being referenced by an object that was also copied.

#### 8.4.3.1 Configuration Types in Delete Section

A complete list of configuration types that support < delete > and the XML tags used to denote their elements can be found in "ACP Configuration Types." In the Delete section, objects to be deleted are specified as a list of names.

#### 8.4.3.2 Name

The Delete section expects object names, not object keys.

The name is the name of the object to be deleted. Deletes must be done by the exact name of the object. This helps to prevent you from deleting objects unintentionally.

#### 8.4.3.3 Putting it all together in Delete section

Let's take a look at a short example of the Delete section with some explanation of how ACP interprets what was specified.

    < delete >

<list>

<name>Category 8 List</name>

<name>Category 9 List</name>

<name>Category 10 List</name>

</list>

<privilege>

<name>(Propagation) Administrator</name>

<name>Modify Programs &amp; Gates that I am owner of</name>

<name>Admin. Privilege</name>

</privilege>

<subclass>

<name>ECO</name>

</subclass>

    </delete>

In the above example, here is what ACP will process by configuration type.

- List: ACP will attempt to delete lists with the following names:

  - "Category 8 List";

  - "Category 9 List";

  - "Category 10 List".

- Privilege: ACP will attempt to delete privileges with the following names:

  - "(Propagation) Administrator";

  - "Modify Programs &amp; Gates that I am owner of ";

  - "Admin. Privilege".

- Subclass: ACP will attempt to delete the subclass named "ECO".

### 8.4.4 Ignore References (<ignore_references>) Section

The Ignore References section is marked by the <ignore_references> element.

The Ignore References section does not propagate any information. Since data may be propagated from a Development instance to a Production instance, there may be test data that will not get propagated. However, there may be configuration data that does get propagated but refers to test data. Since the test data does not get propagated, any references to test data will generate errors because the test data it references will not be present in the Production instance. This is undesirable as it is writing "OK" errors to the Error log, which amounts to a lot of noise.

A common example where this is useful is Roles. You may have created test users in your development instance. You assigned several roles to the test users. You will want to propagate the roles, but not the test users. The Ignore References section allows you to specify "ignore references" to test users. Then, when ACP cannot resolve a user, the error message that ACP would normally issue is suppressed.

The Ignore Reference section expects object names, not object keys.

#### 8.4.4.1 Configuration Types in Ignore References Section

The "ignorable" references are limited to configuration types of those Administrator nodes where test objects are likely to be created:

- Users

- User groups

- Roles

- Privileges

In the Ignore References section of the Control File, object references to ignore can be accomplished through regular expressions. This promotes the use of naming conventions. For instance, test users could have user logins that begin with "test".

#### 8.4.4.2 Patterns

Patterns allow you to specify one or more object names to be ignored. Given that this is a pattern, you can use regular expressions to select multiple objects with a single pattern.

#### 8.4.4.3 Regular Expressions

Regular expressions allow you to use wildcards in your selection of objects to include or exclude. This prevents you from having to list each object individually. Keep in mind that an object's name can be a regular expression itself. Therefore, you can list objects individually as using wildcards. Regular expressions use special characters for its matching rules. These special characters may appear in your object names. Please see "Java Regular Expressions" for more detailed information about regular expressions and their special characters.

#### 8.4.4.4 Putting it all together in Ignore References section

Let's take a look at a short example of the Ignore References section with some explanation of how ACP interprets what was specified. The Ignore References section of the Control File is honored by Copy and Deep Compare.

    <ignore_references>

<user>

<pattern>test.*</pattern>

<pattern>dev.*</pattern>

<pattern>demo1</pattern>

</user>

<role>

<name>test.*</pattern>

</role>

    </ignore_references>

In the above example, ACP will suppress error messages for objects that cannot be resolved that also match the patterns listed.

- User: Ignore user references to users whose user ID starts with "test" or "dev" as well as the specific user ID "demo1".

- Role: Ignore user references to roles whose name starts with "test".

### 8.4.5 Subobject Maps (<subobject_maps>) Section

The Subobject Maps section is marked by the <subobject_maps> element. A subobject is contained by an object. For example, lists contain list entries. Therefore, a list entry is a subobject of a list. Just as ACP uses an object key (API Name/Name/User ID) to map an object between the source and the target, ACP uses a subobject's key to map subobjects between the source and target. If the key of the subobject changes in the source, ACP no longer has a way to look up the subobject in the target instance.

The Subobject Maps section resolves this dilemma. You can use the <subobject_maps> section to map subobject keys between the source instance and target instance. ACP uses the contents of the Subobject Maps section when it is processing the Copy section. Subobject maps only have meaning when the target is an Agile instance.

#### 8.4.5.1 Configuration Types in Subobject Maps Section

The configuration types that support subobject maps are: <base_class>, <class>, <subclass>, <list>, <workflow>, <unit_of_measure_family>, and <column_assignments>.

In the Subobject Maps section of the Control File, subobjects whose names have changed are documented by maps. Some configuration types may have more than one subobject type. For example, <class> has LifeCycle Phases and Attributes. A table that lists the corresponding subobject maps and the methods for renaming can be found in "Renaming Subobjects."

#### 8.4.5.2 Object Reference

As the name subobject implies, a subobject is subordinate to an object. Therefore, in order for ACP to match by the subobject key, it must also have the name of the object that the subobject belongs to. What if the object name and the subobject key are changing at the same time? Since ACP dictates the processing order that configuration types are copied, the referenced object name is assumed to have been changed in the target already. Therefore, the subobject maps must always use the new name of the object.

#### 8.4.5.3 Subobject Type

Some objects may have multiple types of subobjects. In order for ACP to interpret the subobject name map correctly, it must know the type of subobject being mapped.

#### 8.4.5.4 Flex Attribute Rename

A Subobject Map has been introduced that allows ACP to rename user-defined flex-field attributes. The XML tags are given below:

Class

    <classes>

<class name="Items">

<attributes>

<map>

<source_apiname>Mass</source_apiname>

<target_apiname>Flex01</target_apiname>

</map>

</attributes>

</class>

    </classes>
    <subclasses>

Subclass

<subclass name="Part">

<attributes>

<map>

<source_apiname>Weight</source_apiname>

<target_apiname>Flex02</target_apiname>

</map>

</attributes>

</subclass>

    </subclasses>

#### 8.4.5.5 Key Maps

A key map maps a subobject key (API Name/Name) in the Source instance to a subobject key in the Target instance.

#### 8.4.5.6 Source Key

The Source key is the API Name/Name of the subobject being mapped in the Source. Since this is part of a key map, the exact API Name/Name of the subobject must be specified.

#### 8.4.5.7 Target Key

The Target key is the API Name/Name of the subobject being mapped in the Target. Since this is part of a key map, the exact API Name/Name of the subobject must be specified.

#### 8.4.5.8 Putting it all together in Subobject Maps section

Let's take a look at a short example of the Subobject Maps section with some explanation of how ACP interprets what was specified. The Subobject Maps section of the Control File is honored by Copy and Deep Compare. Subobject maps only come into play when the key of the object matches the object key being Copied or Deep-compared.

    <subobject_maps>
        <list apiname="ReasonCode">
          <list_entries>
            <map>
              <source_apiname>Enhancement</source_apiname>
              <target_apiname>Product Enhancement</target_apiname>
            </map>
            <map>
              <source_apiname>Improvement</source_apiname>
              <target_apiname>Reliability Improvement</target_apiname>
            </map>
          </list_entries>
        </list name>
        <list name="Location||Europe">
          <list_entries>
            <map>
              <source_apiname>Czech Republic</source_apiname>
              <target_apiname>Czechoslovakia</target_apiname>
            </map>
          </list_entries>
        </list name>
      </lists>
      <subclasses>
        <subclass apiname="Customer">
          <life_cycle_phases>
            <map>
              <source_apiname>Current</source_apiname>
              <target_apiname>Active</target_apiname>
            </map>
          </life_cycle_phases>
          <attributes>
            <map>
              <source_apiname>Customer Details</source_apiname>
              <target_apiname>Page Three</target_apiname>
            </map>
          </user_interface_tabs>
        </subclass>
        <subclass apiname="ECR">
          <attributes>
            <map>
              <source_apiname>Page Three||Origination Date
               </source_apiname>
              <target_apiname>Page Three||Flex Date01</target_apiname>
            </map>
          </user_interface_tabs>
        </subclass>
      </subclasses>
    <subobject_maps>

In the above example, ACP will be able to map the following subobjects.

- List (Reason Code): The list entry "Enhancement" and "Product Enhancement" are mapped as the same. The result will be the list entry will be renamed to "Enhancement". The list entry "Improvement" and "Reliability Improvement" are mapped as the same. The result will be the list entry will be renamed to "Improvement".

- List (Location||Europe): This is an example of renaming a list entry in a cascade list. Note the way the cascade sub-list is specified. A list entry belongs to a specific list. With cascade lists, the specific list is a sub-list. The sub-list names are separated with a double pipe (||) (period could not be used since a period is valid within a list name). The list entry "Czech Republic" and "Czechoslovakia" are mapped as the same. The result will be the list entry will be renamed to "Czech Republic".

- Subclass (Customer): This example illustrates specifying multiple subobject types for a single object. In this example, the life cycle phase "Current" is mapped to "Active". The result will be the life cycle phase will be renamed to "Current". In addition, the user interface tab "Customer Details" is mapped to "Page Three". The result will be the user interface page will be renamed to "Customer Details".

- Subclass (ECR): The user interface tab "ECR Details" is mapped to "Page Three". The result will be the user interface page will be renamed to "ECR Details".