Skip Headers

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

Previous | Next |

# 1 Welcome to ACP

This guide describes the purpose, installation, and use of Agile Configuration Propagation (ACP).

## 1.1 Overview

ACP lets you propagate the configuration of one instance of Oracle Agile PLM to another instance of the same version of PLM. The "configuration" can be thought of as the complete or partial content of Java Client Administrator settings in an Agile instance.

It is up to you, the PLM administrator, to specify exactly what you want to propagate. The propagation may consist of the complete Administration data for an instance, or it may consist of a selected subset of Administration data for an instance.

### 1.1.1 Purpose of ACP

- ACP facilitates the management of configuration data across multiple Agile PLM instances.

  Agile PLM is configured by the settings in Administrator. The aggregate of defined settings in Administrator is the configuration data. ACP lets you test your configuration changes or additions outside your production environment so they are fully production-ready before they "go live."

- ACP automates some processes that the Agile administrator had to do manually.

  The ACP utility provides an automated way to apply partial or complete configurations in one Agile instance to another Agile instance.

Although ACP automates the configuration process, ACP only propagates Administrator data that it is directed to propagate. It relies on data in its Control File to dictate what changes in one Agile instance should be propagated to another instance.

You can save your configured Control Files - with descriptive filenames, and in project folders - and re-use them for targeted propagations.

### 1.1.2 Functions of ACP

There are two basic functions that ACP performs: Propagating and Comparing.

- Propagate Function

ACP propagates in two steps, Export and Import: A configurable Control File is used to list the objects for ACP to propagate.

- ACP exports configuration data from Agile instance - the Source instance - to XML files.

- ACP imports configuration data from XML files to Agile instance - the Target instance.

- Compare Function

When you want to discover and report differences between Agile instances, not propagate changes, ACP's Compare function reports object-specific differences.

* ACP compares configuration objects between XML files (from the Source instance) and Agile (the Target instance).

ACP93 enhances its previous level of comparing, called Name Compare, with a deeper level of comparing, called Deep Compare.

See "Name Compare and Deep Compare."

### 1.1.3 Who will use ACP?

ACP is intended for Agile administrators, IT personnel, and Oracle Consulting - Agile Practice consultants. This manual assumes that you have worked in Agile Product Lifecycle Management (Agile PLM) as an Agile administrator. The Administrator module of Agile Java Client is documented in Agile PLM Administrator Guide.

### 1.1.4 Who should not use ACP?

ACP is not intended to be used by Agile end-users.

Because this tool has the potential to completely change how an Agile system functions, ACP should not be used by anyone who does not fully understand the implications of any modifications to a live PLM system.

Chapter 5, "User Requirements" provides more details about appropriate roles and privileges for ACP.

### 1.1.5 Improper Uses of ACP

- ACP is not an upgrade utility. ACP cannot properly complete an upgrade of Agile PLM versions.

- ACP is not a synchronization tool. ACP expects a single source of record, an instance that owns the configuration.

- ACP is not a "mass-update" tool. It is not intended to supersede Java Client behavior.

If you have questions about what ACP may or may not accomplish for your Agile PLM installation, please contact your Oracle Consulting - Agile Practice representative.

### 1.1.6 System Requirements for ACP

This section summarizes the requirements for installation and use of Agile Configuration Propagation.

#### 1.1.6.1 Platform Requirements

- ACP supports all operating systems that are supported by Agile PLM 9.3.x: Windows, Solaris, and Linux. (ACP is not certified on AIX, although it may be used on AIX.)

- ACP is compatible with Oracle and BEA WebLogic application servers.

- ACP requires that the Source and Target instances use the same Agile PLM version; there is now a formal "version check".

- ACP expects that the settings in the Licenses node are the same between Source and Target instances. (This last point is detailed in the next topic.)

#### 1.1.6.2 Licensing Requirements

Since ACP is an extension of the Administrator module in Java Client, implementing ACP requires no additional license from Oracle.

Important: ACP should propagate only Oracle-licensed configuration types, Oracle-licensed configuration objects, and Oracle-licensed class attributes.

Regarding the settings in Administrator > Server Settings > Licenses, ACP expects that the settings in this node are the same between Source and Target instances; that is, ACP does not compare the Licenses node settings nor does it report on any discrepancies between the instances.

However, ACP does observe the settings in the Licenses node of both Source and Target Agile-instances in this way:

- ACP can export data from the Source instance based on the base class/class (to which the data "belongs") being enabled in Licenses node on the Source instance;

- ACP can import data to a Target instance based on the base class/class (to which the data "belongs") being enabled in Licenses node on the Source instance.

Again, the settings in Licenses node for any owned and operating Agile system should conform to the PLM solutions your company purchased from Oracle.

#### 1.1.6.3 Environmental Requirements

The ACP Client - where ACP is installed - must be able to connect via "http(s)" to the Agile-PLM source and target instances. That is, firewalls must not prevent ACP from accessing the PLM source and target.

Note: ACP does not need to be able to connect to both instances at the same time; however, it must be able to connect to either the Source or Target instance based on the ACP function being executed.

## 1.2 Using this Manual

Chapters 1-4 of this manual answer the question "Whatis ACP?"

- ACP's purpose, system requirements, and the new features and changes to the Control File schema that were introduced with PLM 9.3 (Ch. 1);

- Terms used in this manual (Ch. 2);

- Use case for ACP (Ch. 3);

- Chapter 4, "ACP Product Information" gathers information about ACP's product features, business rules, and observations of its behavior. Chapter 4 is essential reading for ACP users. It is also useful to "non-ACP-users" who want to understand how the product works.

Chapters 5-8 answer the question "How do I use ACP?"

- Installation (Ch. 5);

- User requirements (Ch. 6);

- Running ACP (Ch. 7); and

- Configuring the Control File (Ch. 8).

Appendices A-F provide reference material.

The appendices give more detailed information:

- ACP configuration types, match keys, renaming subobjects, and how Deep Compare evaluates the configuration types (App. A);

- Java regular expressions (App. B);

- ACP properties (App. C);

- ACP scripts, including propagation scripts and comparison scripts (App. D;

- ACP exit codes (App. E); and

- ACP program log file samples (App. G).

## 1.3 What's New in ACP

The following sections list new features from the current release, as well as the past few releases.

### 1.3.1 New Features in ACP933

This list summarizes the changes made to ACP in Release 9.3.3:

- The <InstanceName>.username property has been deprecated. This property is in the project.properties file. When this entry does not exist in this property file, ACP prompts the user to input Login User Name during run time.

- The <InstanceName>.password property has been retired. This property is in the project.properties file. During run time, ACP prompts the user to input Login User Password.

- The <InstanceName>.password.mode property has been retired. This property is in the project.properties file, but is no longer required and will be ignored even if it is set in the file.

### 1.3.2 New Features in ACP93

This list summarizes the enhancements to ACP in Release 9.3:

- API Name-based Rename and Subobject Maps - "API Name-based Rename and Subobject Maps."

- Object Matching - "Object Matching (Mapping)."

- Type Filtering on Configuration Types - "Type Filtering on Configuration Types."

- Name Compare, Deep Compare, and the Deep Compare Difference Report - these topics:

"Name Compare and Deep Compare";

"Deep Compare Difference Report";

"Log and Report Files for Deep Compare"

- Autonumber Force Update - "Autonumber Force Update."

- Event Management, including Create/Delete of event-based notifications - the main feature introduced in PLM 9.3, Event Management, is completely supported by ACP 9.3. This includes propagating event-based notifications (i.e., those created as Notification masks, not the out-of-box default notifications)

- New Error Message Header - "Error Messages."

  - Error Message on:

    - Unmatched Regular Expressions

    - Unused Subobject Maps

ACP supports propagating data in all languages that are supported by Agile PLM.

### 1.3.3 New Features in ACP932

Agile Configuration Propagation 9.3.2 introduces support for the propagation of several new configuration types including:

- Tab Configuration

- Global Searches

- Global Views

- Global Reports

- PG&C External Rollups scheduling and rule setting

- Reference Object Application

For more information about propagating Personalization configuration for searches, tab configuration, views, and reports, "Personalization."

For more information about the configuration types, "ACP Configuration Types."

### 1.3.4 ACP931/9301/9302

No new features were added to ACP931, ACP9301, or ACP9302.

## 1.4 Changes to the Control File Schema (for previous ACP users)

There were no changes to the Control File schema in PLM Releases 9.3.1, 9.3.0.1, or 9.3.0.2.

There were numerous changes to the Control File schema in PLM Release 9.3.

Some elements of the old schema syntax will no longer work. This section lists those elements of the Control File that have been removed or are no longer supported or have otherwise changed since ACP 9.2.x.

These are important if you are a previous user of ACP and have customized Control Files that are still useful. The elements below should be properly changed. If any of these are present, the Control File will throw an error and not complete.

You may disregard this list of changes if:

- You are a new customer to Agile PLM, or

- You are a customer of Agile PLM 9.2.x and you did not use ACP, or

- You have used ACP 9.2.x but are not going to use old Control Files with ACP 9.3.x.

### 1.4.1 Server Portals not supported (Copy, Rename, Delete)

Agile PLM no longer supports Portlets (Agile Portlet Services). The administrator could go to Server Settings > Locations > Portals tab to create and manage portals. The corresponding ACP tag was <server_portal>.

Therefore, <server_portal> is no longer supported in the Copy, Rename, or Delete sections of the Control File. You should remove the tag from your existing Control Files.

Error Message: "cvc-complex-type.2.4.a: Invalid content was found starting with element 'server_portal'."

### 1.4.2 Case Sensitive List Entries attribute removed (Copy)

The <case_sensitive_list_entries> attribute tag has been removed from List (<list>) in the Copy section of the Control File.

Functional Replacement: List Entries are now matched by their API Name instead of their Name. The attribute provided an alternative to the Subobject Maps for List Entries when only the case of the List Entry name changed. Now a Subobject Map is required if any part of the API Name for the List Entry has changed, even if only the case changed.

Error Message: "cvc-complex-type.3.2.2: Attribute 'case_sensitive_list_entries' is not allowed to appear in element 'list'."

### 1.4.3 Changes in Rename section due to API Name/User ID

The following changes all apply to the Rename section of the Control File.

#### 1.4.3.1 Rename by API Name

With the introduction of API Name to Administrator nodes, API Name is now the preferred identifier (key) for mapping Administrator nodes between Agile instances. This change should require fewer rename actions to be performed as it is expected that API Names will tend not to be changed.

The following Administrator nodes are affected by this change in the Rename section of the Control File:

- ACS Destination (<acs_destination>)

- ACS Event (<acs_event>)

- ACS Filter (<acs_filter>)

- ACS Package Service (<acs_package_service>)

- ACS Response Service (<acs_response_service>)

- ACS Subscriber (<acs_subscriber>)

- Auto Number (<auto_number>)

- Character Set (<character_set>)

- Criteria (<criteria>)

- List (<list>)

- PPM Dashboard Management (<ppm_dashboard_management>)

- Privilege (<privilege>)

- Process Extension (<process_extension>)

- Role (<role>)

- Server File Manager (<server_file_manager>)

- Subclass (<subclass>)

- Unit of Measure Family (<unit_of_measure_family>)

- Workflow (<workflow>)

Functional Replacement: The rename functionality still exists; it is just that the API Name is being renamed rather than the Name. This requires two changes to the Control File on your part:

1. Use different tag names (source_apiname and target_apiname instead of source_name and target_name);

2. Specify the new and old API Name instead of the new and old Name.

Error Message: cvc-complex-type.2.4.a: Invalid content was found starting with element 'source_name'. One of '{"":source_apiname}' is expected.

#### 1.4.3.2 Rename by User ID

With the introduction of API Name to Administrator nodes and since Users are identified by their login ID for mapping Users between Agile instances, the XML attribute name reflects what is mapped.

The Users (<user>) Administrator node is affected by this change in the Rename section of the Control File.

Functional Replacement: The rename functionality still exists. This requires one change to the Control File on your part: use different tag names (source_userid and target_userid instead of source_name and target_name).

Error Message: cvc-complex-type.2.4.a: Invalid content was found starting with element 'source_name'. One of '{"":source_userid}' is expected.

#### 1.4.3.3 Rename no longer supported

With the introduction of API Name to Administrator nodes, API Name is the preferred identifier (key) for mapping Admin nodes between Agile instances. For Administrator nodes that are entirely owned by Agile, the API Name cannot be changed. In these cases, there is no longer a need to have a rename for the Administrator node.

The following Administrator nodes are affected by this change in the Rename section of the Control File:

- Base Class (<base_class>)

- Class (<class>)

- Cost Status (<ppm_cost_status>)

- Quality Status (<ppm_quality_status>)

- Resource Status (<ppm_resource_status>)

- Schedule Status (<ppm_schedule_status>)

- Database (<server_database>)

  Functional Replacement: The replacement is that ACP will map these objects by their API Names. Since the API Name cannot be changed, the functionality for this feature is complete without any assistance from the Control File.

  Error Message: cvc-complex-type.2.4.a: Invalid content was found starting with element '<admin node tag name>'.

### 1.4.4 Changes to Subobject Maps section due to API Name

The following changes all apply to the Subobject Maps section of the Control File.

#### 1.4.4.1 Subobject Map object reference by API Name

With the introduction of API Name to Administrator nodes, API Name is now the preferred identifier (key) for mapping Administrator nodes between Agile instances. This change should require fewer subobject maps as it is expected that API Names will tend not to be changed.

The following Administrator nodes are affected by this change in the Subobject Maps section of the Control File:

- Base Class (<base_class>)

- Class (<class>)

- List (<list>

- Subclass (<subclass>)

- Unit of Measure (<unit_of_measure_family>)

- Workflow (<workflow>)

Functional Replacement: The subobject map functionality still exists; it is just that the API Name is being used to identify the object rather than the Name. This requires two changes to the Control File on your part:

1. Use different attribute name (apiname instead of name);

2. Specify the object's API Name as its identifier.

Error Message: cvc-complex-type.3.2.2: Attribute 'name' is not allowed to appear in element '<Admin Node tag name>'.

#### 1.4.4.2 Subobject Map subobject identified by API Name

With the introduction of API Name to Administrator nodes, API Name is now the preferred identifier (key) for mapping Subobject nodes between Agile instances. This change should require fewer subobject maps as it is expected that API Names will tend not to be changed.

The following Subobject nodes are affected by this change in the Subobject Maps section of the Control File:

- Base Class (<base_class>) à Life Cycle Phases (<life_cycle_phases>)

- Class (<class>) à Life Cycle Phases (<life_cycle_phases>)

- List (<list>) à List Entries (<list_entries>)

- Subclass (<subclass>) à Life Cycle Phases (<life_cycle_phases>)

- Unit of Measure (<unit_of_measure_family>) à Units of Measure (<unit_of_measures>)

- Workflow (<workflow>) à Workflow Statuses (<workflow_statuses>)

Functional Replacement: The subobject map functionality still exists; it is just that the API Name is being renamed rather than the Name. This requires two changes to the Control File on your part: 1) use different tag names (source_apiname and target_apiname instead of source_name and target_name; 2) specify the new and old API Name instead of the new and old Name for the subobject being referenced.

Error Message: cvc-complex-type.2.4.a: Invalid content was found starting with element 'source_name'. One of '{"":source_apiname}' is expected.

#### 1.4.4.3 Subobject Map no longer supported

With the introduction of API Name to Administrator nodes, API Name is now the preferred identifier (key) for mapping Subobject nodes between Agile instances. For Subobject nodes that are entirely owned by Agile, the API Name cannot be changed. In these cases, there is no longer a need to have a subobject map for the Subobject node.

The following Subobject nodes are affected by this change in the Subobject Maps section of the Control File:

- Class (<class>) à User Interface Tabs (<user_interface_tabs>)

- Subclass (<subclass>) à User Interface Tabs (<user_interface_tabs>)

Functional Replacement: The replacement is that ACP will map these subobjects by their API Names. Since the API Name cannot be changed, the functionality for this feature is complete without any assistance from the Control File.

Error Message: cvc-complex-type.2.4.a: Invalid content was found starting with element 'user_interface_tabs'. One of '{"":attributes, "":life_cycle_phases}' is expected.