| Agile Product Lifecycle Management Agile Configuration Propagation Guide Release 9.3.3 E39285-02 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management Agile Configuration Propagation Guide Release 9.3.3 E39285-02 |
|
Previous |
Next |
This chapter is mandatory reading for the ACP user. The rest of this manual builds on the information in this chapter.
"ACP Product Information" is also written to the general reader who wants an overview of ACP's product features, business rules, and observations of its behavior.
As a client application, ACP may be installed on the same machine as an Agile PLM server, or on a separate machine.
ACP can be installed on the following operating systems: Windows, Linux, Solaris.
ACP can work with the following application servers:
Oracle Application Server (OAS)
WebLogic Application Server (WLS)
The ACP version must match the Agile PLM version it is interacting with. The key factor is this: the APIs that ACP uses must be available and have the same serialization.
ACP can access an Agile instance from the same machine, over a LAN, or over a WAN.
If the source and target instances are separated by a WAN, for better performance it is highly recommended that you copy the .agl file to the local LAN where the target instance is.
ACP is simply a client of Agile PLM.
ACP requires the source and target instance to be the same version of PLM.
ACP does not require that the source and target instances be on the same application server.
To use ACP, an Agile user must have the Administrator privilege mask for that Agile instance. There are specialized roles that can be tailored for users to have less than full access to the Administrator module of an Agile instance.
ACP does not have "super-user" capability: it can access only those Admin objects for which the ACP user has privileges.
ACP adheres to the security policy assigned to the user used to connect to the Agile server. This security policy is managed through privileges. It is possible to have multiple ACP users: each user could be limited to different portions of the Administrator data.
ACP is initiated via the Command-line through an MS-DOS shell on the Windows operating system or one of the various shells available on the Unix operating system.
Several predefined "run" scripts are included with the ACP installation. These run scripts share variables and use command-line parameters to find:
Connection information for connecting to Agile instances;
Location of the Control File;
Location of an ACP XML archive;
Log file information.
ACP is also considered as an Agile-PLM SDK application. As such, ACP adheres to all business rules imposed by the application. ACP interacts with Agile PLM in the same manner that Java Client interacts with the Agile application server.
ACP connects to an Agile instance using the same URL used by any SDK application. This URL is similar to the URL used to access the Agile Web Client (http://<host name>[:<port number>]/Agile).
ACP is susceptible to any existing defects in the Agile server or SDK. It does not work around these defects.
ACP does not access the Agile PLM database directly.
ACP is expressly designed as a propagation tool. ACP's primary purpose is to update or create Administrator objects in a target Agile instance just as they are configured in the source instance. A secondary purpose is to compare Administrator objects between source and target instances so you are certain about what is different between the two. How ACP propagates and compares is discussed below in this chapter.
As a reminder, there are several kinds of operations that cannot be accomplished by ACP:
ACP is not an upgrade utility. ACP cannot properly complete an upgrade of Agile PLM versions.
ACP is not a synchronization tool. ACP considers only one Agile instance, the source instance, as the source of record for the configuration data: the source instance owns the configuration. It is also expected that the source Agile instance and target Agile instance are at the same product level (version).
ACP is not a "mass-update" tool. It is not intended to supersede the Java Client behavior.
ACP uses a "best-it-can-do" strategy: its goal is to make the propagated objects look the same in the target as it does in the source. Because PLM business rules, or unforeseen errors, can prevent ACP from fully propagating an object, sometimes this goal is not achieved; some objects may be partially propagated, or some objects may not be propagated at all.
ACP does not propagate with an "all-or-nothing" strategy.
If any errors are reported during the propagation, ACP cannot 'guarantee' that the propagation worked correctly.
ACP uses a two-step propagation method:
Export - ACP first exports the objects to propagate from one Agile instance to an Agile XML archive;
Import - ACP's second step is to import objects in an Agile XML archive to an Agile instance.
This method allows you to place the Agile XML archive under source control.
This method can be used to overcome any performance issues ACP may have when used over a WAN.
The Control File tells ACP what specific configuration types it should examine when it is run. A Control File can be run as a "compare" - using Name Compare or Deep Compare scripts - where configuration types are specified for informational and reporting purposes. A Control File can be run as a propagation where configuration types are specified for altering the target instance using Delete, Rename, or Copy (Create, Update, Replace) actions.
The Control File has a defined schema, which allows you to use tools like XMLSpy to edit the Control File.
The Control File allows you to be as general or specific with the objects you want ACP to propagate through the use of regular expressions.
ACP does not track anything from propagation to propagation. Because it is not possible for ACP to determine what has been deleted in the source instance, the Control File must explicitly direct ACP to delete configuration items.
ACP does not automatically propagate dependent objects. All propagated objects must explicitly match one of the include patterns and none of the exclude patterns in the Control File.
Using Compare reports as a guide, you can determine which configuration items can be included in the propagation and which ones can be excluded from the propagation.
There is a shorthand notation for specifying all objects of an Administrator node.
There is no limit on the number of include or exclude regular expressions that may be entered.
Name maps must use exact names.
Delete names must use exact names.
The Control File Schema allows tools like XMLSpy to help in configuring the control file.
The order in which Administrator nodes are configured has no bearing on the processing order.
ACP does not propagate by a change list; Agile PLM Administrator does not support the notion of a change list.
ACP does automatically propagate the relationships between objects if both objects exist in the target. If only one of the objects in the relationship changed, it is only necessary to propagate that object. For example, if a role is added to a privilege, only the privilege needs to be propagated unless the role did not previously exist.
The API Name attribute has been added to all Administrator nodes (with some exceptions). API Name is now the preferred identifier (key) for mapping Administrator nodes between Agile instances.
Renames and Subobject Mapping are now based on the API Name attribute. This change should require fewer rename actions to be performed, as well as fewer subobject maps, as API Names will not be changed.
The API Name attribute is supported in ACP (for all PLM objects that support API names) with the tags <source_apiname> and <target_apiname>.
Users are renamed with the tag <source_userid>. This is only used when the User ID is changed.
There are also Administrator objects where <source_name> and <target_name> are used.
ACP supports these actions or operations: Copy, Rename, and Delete. The actions performed by ACP correspond to named sections in the Control File.
The Copy action allows you to propagate an object's configuration from a Source instance to the Target instance using a Create, Update, or Replace operation;
The Rename action allows you to rename objects in the Target instance;
The Delete action allows you to delete objects in the Target instance.
There are two additional sections of the Control File that do not instruct propagation changes:
Ignore References directs ACP to ignore references to certain objects that will not be propagated.
Subobject Maps allows ACP to match subobjects with different names between the Source and Target instances;
These three propagation actions and two (non-propagating) sets of instructions are briefly described below, and are more fully detailed in "Configuring the ACP Control File".
The two compare scripts, Name Compare and Deep Compare, are also introduced below.
The Copy action uses regular expressions to identify the objects to copy.
The regular expressions come in two forms: include and exclude. If an object matches an include regular expression and does not match an exclude regular expression, then it is copied.
There is no limit to the number of expressions that can be specified. An object's name can be (or can be encoded to be) a valid regular expression itself. Therefore, you can list each object individually.
Copy contains these three "subactions": Create, Update, and Replace.
Create, Update, and Replace are implicit operations, that is, ACP decides which subaction will be performed, based on the existence of the object in the target instance, as described below.
Create the configuration object if it is not found by object key in the target instance. (The object key is the API Name if the Administrator node supports it, or the Name if the node does not support API Name; in the case of Users, the object key is User ID.)
If the source configuration object does not exist in the target instance by name, then the configuration object is inserted into target instance.
Update the configuration object if it is found by name in the target instance.
If a match on name is found in both the source and the target instances, then the target configuration object is updated with the information on the source configuration object.
Replace the configuration object if it is found by name in the target and its type in the source instance is different.
If the object's type differs in the target instance from the type in the source instance, Replace finds the configuration object in the target instance and deletes the object, then creates a new object in its place, thereby changing the type or meaning of an object.
Replace is used when the object being propagated is "strongly typed". Some Administrator nodes are strongly typed, that is, in order to change the object's type, it must be deleted and re-created. An example of a strongly typed Administrator node is Lists. In order to change a regular list to a cascading list, the list must be deleted and re-created.
Copy is fully detailed in "Copy (<copy>) Section."
The Rename action directs ACP to rename an object's key (that is, the value of the object key for that object). Renaming is now based on the API Name attribute, which has been added to most kinds of objects in PLM.
The Control File uses the XML term <map> to rename objects whose key was changed in the Source instance. Name maps have a Source name (key) - which is the "new" name because the ACP user has changed it in the Source instance - and a Target name (key) - which is the "old" name because it has not yet been changed in the Target instance.
To make it more self-evident, these tag names have been introduced:
<source_apiname>
<source_name>
<source_userid>
<target_apiname>
<target_name>
<target_userid>
A name map exists for the configuration object in the Control File.
If a configuration object is not found by its new name in the Target instance, and it is found by its old name in the Target instance, then the Target configuration is updated with the new name.
|
Note: If an object cannot be renamed, an error is issued. |
The names specified in the map must match the object's name exactly. Regular expressions cannot be used here.
There is no need to escape (or encode) regular expression special characters, for example, the asterisk ("*").
Rename is not a kind of "update". Rename can only give an object a new name.
Rename is an explicit operation, that is, ACP must be directed to take the Rename action.
Rename is fully detailed in "Rename (<rename>) Section."
The Delete action allows objects to be deleted in the Target.
As a protective measure, the object name specified must exactly match the name of the object-to-be-deleted.
A Delete directive exists for the configuration object in the Control File.
Delete is an explicit operation, that is, ACP must be directed to take the Delete action.
|
Note: If an object cannot be deleted, an error is issued. |
Not all configuration types support the Delete operation.
The configuration object is found by name in the Target instance. The names specified in the map must match the object's name exactly. Regular expressions cannot be used here.
If the user has configured a configuration item to be deleted in the Control File, the configuration item is deleted from the Target instance if it exists. If the configuration item does not exist in the Target instance, an error is issued.
Delete is fully detailed in "Delete (<delete>) Section."
The Subobject Maps section of the Control File is used to map the keys for subobjects. Subobject mapping is now based on the API Name attribute, which has been added to most kinds of Administrator objects.
Some Administrator objects include a set of subordinate objects. Subordinate objects ("subobjects") cannot exist by themselves, they exist only in relationship to a parent object. An example of an object/subordinate object relationship is:
List (object) and
List Entry (subordinate object).
The point is that a specific List Entry object does not exist independently, it must belong to a List.
Subobject mapping can be applied to the following configuration types:
Base Class
Class
Subclass
List
Unit of Measure
Workflow
My Assignments
Subobject mapping is fully detailed in "Subobject Maps (<subobject_maps>) Section."
Object mapping is introduced in "Object Matching (Mapping)."
The Ignore References section of the Control File is for references to objects that will not be propagated by the ACP actions.
"Ignore References" is not an ACP action. The usefulness of Ignore References is apparent when "test Admin nodes" are created in a development environment (although these objects have a place in a Development environment, they have no place in the Production environment).
The "ignorable" references are limited to Admin nodes where test objects are likely to be created:
Users
User groups
Roles
Privileges
Regular expressions may be used to specify which objects should be ignored.
Ignore References is fully detailed in "Ignore References (<ignore_references>) Section."
ACP has always distinguished differences in names of Administrator objects between instances of Agile. ACP could use the Copy operations to make actual changes to object names (in the Target, based on what ACP perceived in the Source); ACP could also simply report the differences, through the Compare function.
ACP still supports the comparison of configuration objects based on their name, which is now called Name Compare.
ACP can now compare object attributes, both on the level of the Attribute names, and further on the names of the Properties of the Attributes. This comparison is called Deep Compare. With Deep Compare, each and every attribute of an object in the Source is compared with the ones in the Target to reveal all differences in properties of the attributes.
The Compare function supports these data sources:
in the Source instance: XML (the XML archive that is the first step to a potential propagation);
in the Target instance: Agile (the PLM data that stands to be altered in a potential propagation).
Name Compare and Deep Compare are driven by the Control File against which they are run; only objects and configuration types specified in the Control File are compared. All other objects and configuration types are ignored regardless of whether they are present in the "XML archive" (Source) or "Agile" (Target).
Sections of the Control File that Deep Compare pays attention to:
Copy
Rename
Subobject Maps
Ignore References
Section of the Control File that Deep Compare does not pay attention to:
Delete
A Deep Compare Report is generated through BI Publisher, and the supporting output format is a modified Microsoft Excel spreadsheet.
ACP propagates the data contents of Configuration Types, which are roughly the same as the Administrator "nodes". Admin nodes are simply the named elements under Java Client's Admin tab. The Admin nodes are collectively called the "Admin tree."
Not all propagation operations are supported by each Administrator node. "ACP Configuration Types" shows the complete list of ACP-supported configuration types and the propagation actions that are supported by each type. This list is meant to be complete for this specific release only.
|
Important: An ACP user must have the appropriate Administrator privilege (privilege mask) to a given Administrator node for that node to be responsive to ACP's operations. |
The following Administrator objects (listed in alphabetical order) cannot be propagated.
| Non-propagating Administrator objects | Where found (Java Client unless noted) | Comment |
|---|---|---|
| Attachments on User and User Group objects | User Settings > Users, User Groups | NA |
| Cache Health Monitor | Web Client > Administration | Web Client--only Admin data and Monitors are not propagated. |
| Character Sets that are "out of the box" | Data Settings | NA |
| Currency Exchange Rates | System Settings | NA |
| Deleted Users | User Settings | ACP must be explicitly directed to delete users. |
| Deleted User Groups | User Settings | ACP must be explicitly directed to delete users. |
| Event Handler Monitor | System Settings > Event Management | Monitors are not propagated. |
| Example Criteria, Example Privileges, Example Roles | Examples | "Read only" out-of-the-box data |
| Languages on User and User Group objects tab | Server Settings > Preferences | NA |
| LDAP | Server Settings | NA |
| Licenses | Server Settings | NA |
| Lists with duplicate list entry names.
Dynamic/Criteria-based lists. |
Data Settings | NA |
| Logging Configuration | Web Client > Administration | Web Client--only Admin data and Monitors are not propagated. |
| Personal User Groups | (created by users, stored as Admin objects) | NA |
| Relationships on User and User Group objects | User Settings > Users, User Groups | NA |
| Report Templates | Web Client > Administration | NA |
| "(Restricted)" users | Roles > "(Restricted) ___" users are not propagated | NA |
| Sites | Classes > Sites base class | NA |
| Task Monitor | Server Settings | Monitors are not propagated. |
| Unit Of Measure families with duplicate UOMs | System Settings | NA |
| User Monitor | User Settings | Monitors are not propagated. |
| Visual Themes | Web Client > Administration | Web Client--only Admin data is not propagated. |
ACP only propagates Administrator data from Java Client, and it does not distinguish Admin data that happened to be generated from Web Client. Therefore, users and user groups that are generated from Web Client can be propagated.
|
Note: Dashboard Configuration in Web Client corresponds to Dashboard Management in Java Client. |
|
Note: The word "type" in the new feature "Type Filter" refers to filtering by Administrator nodes sub[ordinate]-types. It is pertinent to some Admin nodes, not all, as elaborated below. Do not confuse "type filtering" with either "configuration types" in ACP nor the "object types" in PLM. |
The Type Filtering feature is introduced to permit more flexible object selection. For example, in the table below, the configuration type "Privilege Mask" can be filtered by "Privilege". Therefore, you could specify that ACP look at only those privilege masks that are based on the Create privilege (in an instance of Agile PLM).
The enhancement is that you are no longer constrained to filtering by name alone.
The Type Filtering tag is <type name="xx"/>, where xx is the specific filter (in the previous example: Create).
In this table, where the possible values are too numerous to list, you can look at the appropriate node in Administrator to know exactly what the choice of specific Filters are.
| Configuration Type | Type Filter | Possible Values |
|---|---|---|
| (ACS) Destination | Protocol | Agile, File, FTP, HTTP, HTTPS, JMS |
| (ACS) Event | (ACS) Event Type | Scheduled, Workflow |
| AutoNumber | Type | Standard, Custom |
| Class | Base Class | any base class, for example: Items, Changes, Customers |
| Subclass | Base Class or Class | any base class (see above) or class, e.g., Parts, Change Orders, customers |
| Criteria | Object Type | any base class, class, or subclass |
| (Event Mgt.) Event | (EM) Event Type | see Event Management > Event Types |
| Event Handler | Event Handler Type | Java PX, Script PX |
| Event Subscriber | (EM) Event | any Event defined in Event Management > Events |
| Privilege Mask | Privilege | see User Settings > Privileges |
| Process Extension | (PX) Type | Internal Custom Action, URL |
| User Group | Subclass | any User Group subclass, e.g., User Group |
| Workflow | Object Type = Routable Base Class | Changes, Declarations, File Folders, Packages, PSRs, Projects, QCRs, ATOs |
| Notification | Object Type | NA |
Examples of Filtering
Example 4-1 To filler all ACS Destinations where the protocol is HTTP
<acs_destination>
<include>
<tyoe name="HTTP"/>
</include>
</acs_destination>
The following example filters all subclasses in the Items base class; all subclasses in the Change Orders class; and all subclasses that belong to the Suppliers class with the word "Manufacturer" in the name.
ACP now uses a public key, API Name, where available. ACP93 has reduced the likelihood that an object's key will change by using the more static key API Name.
ACP recognizes User ID for users.
ACP still uses Name as the key in a few cases. "Configuration Types and Match Fields" (in Appx. A) lists the configuration types and whether the match field is the external, changeable name of the object or the internal, unchangeable, identification number.
ACP uses an object's name for matching where the customer can create or delete objects of the Administrator node.
ACP uses an object's internal ID for matching where the customer may not create or delete objects of the Administrator node.
If an object is renamed and ACP uses the name for matching objects of that Administrator node, then a mapping must be specified in the control file for ACP to take the correct action.
ACP matches subobjects by name.
Subobject renames require a name map in the control file.
Admin objects do not have a public key (see definition of public key in Object Mapping above).
The following sets of Processing Order Rules stem from these two facts about ACP:
ACP controls the processing order.
ACP may process an Administrator node in multiple passes. These passes are listed separately in the Log file.
ACP controls the order in which Administrator nodes are processed. This order is dictated by the dependencies between each of the Administrator nodes. ACP performs "Deletes" first, then "Renames", then "Copies". Deletes are processed in reverse dependency order. Renames and Copies are processed in forward dependency order.
Due to some dependencies between Administrator objects, ACP may have to process the configuration type in multiple passes when Copying.
For example, in PLM, Users can belong to User Groups, and User Groups are populated with Users. In order for ACP to process the objects in these two configuration types, it first creates Users in the Target system, then it creates User Groups are created. Only when all "new" users and user groups have been created in the Target does ACP make the necessary associations.
ACP defines the processing order of the configuration types based on application rules. The order is not influenced by the order the configuration types appear in the control file.
By default, all configuration objects for a configured configuration type will be copied.
Copy selects objects by name; users are selected by UserID.
Include patterns match object names using Java regular expression rules.
Java regular expressions have special characters that may need to be encoded. Direct them where to go for the list of special characters.
XML special characters need to be encoded.
Zero or more include patterns may be specified. There is no limit to the number of patterns you may specify.
Exclude patterns match using Java regular expression rules.
One or more exclude patterns may be specified. There is no limit to the number of patterns you may specify.
Rename selects objects by object key; users are selected by UserID.
Zero or more key mappings may be specified.
Name mappings use an exact match for both the old and new keys.
Regular expressions are not allowed.
XML special characters must be encoded.
Regular expression special characters do not need to be encoded.
By default, no configuration objects for a configured configuration type will be deleted.
Delete by object name: The delete names action requires an exact match to be deleted.
Regular expressions are not allowed.
XML special characters must be encoded.
Regular expression special characters do not need to be encoded.
ACP does not propagate History information. However, since ACP uses the PLM application to propagate, a History record is created as the data is propagated. Since History items always apply to the specific user who created or modified Admin objects, it is helpful to assign propagation roles to Agile users, which simplifies tracking how the data was modified in the target instance.
ACP can be run once to propagate all language versions of the configuration data. This is true regardless of the language preference of the administrator who connects to the Agile instance during the ACP run. The target instance must have all of the languages enabled that are enabled in the source instance.
Supported languages are:
English
French
German
Japanese
Simplified Chinese
Traditional Chinese
Russian
Korean
ACP can be run to propagate global configuration types. These include Tab Display Configuration, Global Views, Global Searches, out-of-box Searches, Global Reports, and Standard Reports.
The following sections provide more information about these configuration types. Some of the sections include usage examples, however, you should refer to the config.xml file that is provided out-of-box for general guidelines and examples.
You can use ACP to propagate tab display configuration from one environment to another. The short hand notation used in config.xml is <tab_display_configuration/>. For more information about the propagation actions available for this configuration type, see "ACP Configuration Types."
You can use ACP to propagate all global views from one environment to another. The short hand notation used in config.xml is <global_views/>.
The following are examples of how to use the global views notation.
Example 4-3 To propagate all global views on the Relationships tab of Change Orders, except the one with name "Complete"
<copy>
<global_views>
<include>
<pattern>Change Orders\.Relationships\.*</pattern>
</include>
<exclude>
<pattern>Change Orders.Relationships.Complete</ pattern >
<exclude>
</global_views>
</copy>
Example 4-4 To delete the global view named "Complete" on the Relationships tab of Change Orders
<delete>
<global_views>
<name>Change Orders.Relationships.Complete</name>
</global_views>
</delete>
For more information about the propagation actions available for this configuration type, see "ACP Configuration Types."
You can use ACP to propagate all global and out-of-box searches from one system to another. Recycle Bin searches, Personal Searches and folders under personal searches cannot be propagated.
The short hand notation used in config.xml is <searches/>. The searches configuration type supports further refining using <Include>, <exclude> and type filtering. Folder names are used as filter criteria in type filtering. Any level folder names are valid for type filtering.
ACP creates folder structures in the target automatically, if they are not already available, to support the organization of searches and to make the target look like the source. For example, if the folder name specified is two levels deep under global searches, while propagating to the target, the same two-level deep folder organization is created in the target and then searches are placed inside it.
The following are examples of how to propagate searches.
Example 4-5 To propagate all global and out-of-box searches, except those that start with "All Items"
<searches>
<include>
<pattern>.*</pattern>
</include>
<exclude>
<pattern> All Items.*</pattern>
</exclude>
</searches>
Example 4-6 To use type filtering to limit what is propagated
<searches>
<include>
<type name='Workflow Searches'/>
<type name='Item Searches'>
<pattern>Items that.*</pattern>
</type>
</include>
<exclude>
<type name='Quality Seaches'/>
<type name='Item Searches'>
<pattern>Scorpion Productline Items</pattern>
</type>
</exclude>
</searches>
For more information about the propagation actions available for this configuration type, see "ACP Configuration Types."
You can use ACP to propagate all global and standard reports from one system to another.
|
Note: Only General Info, Layout and Schedule tab information are supported for propagation. Historical Report tab is transactional data and is not supported. On Administrative Reports, only General Info is supported. Personal Reports and folders under Personal Reports are not supported. |
The short hand notation used in config.xml is <reports/>. The reports configuration type supports further refining using <Include>, <exclude> and type filtering. Folder names are used as filter criteria in type filtering. Any level folder names are valid for type filtering.
ACP creates folder structures in the target automatically, if they are not already available, to support the organization of reports and to make the target look like the source. For example, if the folder name specified is two levels deep under global reports, while propagating to the target, the same two-level deep folder organization is created in the target and then reports are placed inside it.
The following are examples of how to propagate reports.
Example 4-8 To propagate all reports that have "BOM" somewhere in the name, except the "Manufacturer BOM Report"
<reports>
<include>
<pattern>.* BOM .*</pattern>
</include>
<exclude>
<pattern>Manufacturer BOM Report</pattern>
</exclude>
</reports>
Example 4-9 To use type filtering to limit what is propagated
<reports>
<include>
<type name='Product Reports'/>
<type name='Compliance Reports'>
<pattern>.* Compliance</pattern>
</type>
</include>
<exclude>
<type name='Quality Reports'/>
<type name='Compliance Reports'>
<pattern>Part Compliance</pattern>
</type>
</exclude>
</reports>
For more information about the propagation actions available for this configuration type, see "ACP Configuration Types."
|
 Copyright © 2010, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|