| Agile Product Lifecycle Management Agile Configuration Propagation Guide Release 9.3.6 E71151-01 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management Agile Configuration Propagation Guide Release 9.3.6 E71151-01 |
|
Previous |
Next |
This chapter discusses the operating components in ACP, which provides a general understanding of how to run ACP. Agile Configuration Propagation consists of the following components: Projects, Properties, Control File, Scripts, Return Codes, and Log Files. Most of these components are described in further detail in succeeding chapters or appendixes.
|
Caution: To prevent the accidental deletion of project directories, the work directory should be kept separate from the install directory. In any case, ACP Project directories should not be under the installed ACP path. |
It is a best practice that you organize your configuration needs into independent configuration projects. Each project is maintained in separate project folders. Project folders are contained in the work directory that is specified when ACP is installed.
A project is defined by its properties file and control file:
The properties file project.properties provides the information that ACP needs for interacting with the environment;
The control file config.xml tells ACP what objects to process.
To help you get started, the ACP installer creates a project named ”sample” for you. You can use this project or create other projects when needed.
sample - a sample project directory created for you by the installer.
<project> or <ACP projects>, for example - a project directory created by you; this directory does not exist until you create it. There may be multiple project directories.
The work directory contains project folders. Projects are defined by the control file stored in the project directory.
For example, you might create projects for List management, for Roles and Privileges, for release-based Agile Classes, and for each new feature that you want to deploy:
| Folder | Description |
|---|---|
| \AgilePLM | Agile PLM home- A directory where AgilePLM is installed |
| \AgilePLM\ACP | ACP home - A directory where ACP client is installed (ACP Project directories should not be under the installed ACP path). Note: ACP home can be a separate directory path and does not have to be under Agile PLM Home. |
| \AgilePLM\ACP Projects | ACP work directory where ACP projects are organized. Note: This directory should not be under the installed ACP home. |
| \ACPProjects\Project_936 | Directory that collects ACP projects oriented to PLM Release 9.3.6. |
| \ACPProjects\Project_936\Roles_Privileges | Directory that contains Agile PLM Release 9.3.6 Admin Roles and Privileges specific propagation (import/export/deep compare) files such as: config.xml, project.properties, acp.bat, export_xxx.agl and logs. |
| \ACPProjects\Project_936\Lists | Directory that contains a control file used to propagate Admin lists |
| \ACPProjects\Project_936\936_Classes | Directory that contains a control file used to propagate Admin classes in PLM Release 9.3.6 |
| \ACPProjects\Project_936\936_Subclasses | Directory that contains a control file used to propagate Admin subclasses in PLM Release 9.3.6 |
| \ACPProjects\Project_936\New Feature_01 | Directory that contains a control file used to propagate a specific new feature |
| \ACPProjects\Project_936\New Feature_02 | Directory that contains a control file used to propagate a specific new feature |
| Important If ACP projects are placed in a work folder, the work directory should not be the same or contained in the Install directory. | |
You can have as many project directories as you like, and you can name them anything you like.
There are two ways in which to create an ACP project:
You can copy an existing project; or,
You can use the create_project script provided by ACP.
This method enables you to start from an existing project. Project folders must be created in the work directory specified when installing ACP.
Identify the existing project folder you want to copy.
Create a copy of the project folder.
Use your favorite method for copying folders:
Windows: Copy/Paste
DOS: copy command
UNIX: cp command.
Rename the copied folder.
Recommendation: Indicate the purpose of the project in the name you choose.
Delete old project files.
Since you are copying a project, you will be copying files that do not apply to the new project.
Here is a list of files that you should consider deleting from the new project folder:
Log Files (*.log, *.err)
ACP archives (*.agl)
Other files you may have created
The new project should only have the launch script (acp.bat), the project properties file (project.properties) and the control file (config.xml).
This method enables you to start with a clean project. Project folders should be created in the work directory specified when installing ACP.
Choose a name for the new project folder. The folder name cannot already exist.
Open a terminal window (Windows: DOS window; UNIX: shell)
Change directory to the work directory specified when ACP was installed.
Here are examples based on the default work directories provided by the ACP Installer.
Windows: cd C:\Agile\ACPWork936
UNIX: cd /<user home>/agile/acpwork936
Of course you will tailor any numbered directory folders to match the specific PLM version, for example, ”93”, ”9301”, ”931”, and so forth.
Run the ACP create project script.
acp create_project <project_name>
ACP uses properties to understand how to interact with the environment it is running in. ACP properties can be set by the program, on the command-line, in the Project Properties file, and common properties files. ACP properties are described in greater detail in "Properties." For now, you should understand how to configure connection information for the Agile PLM instances you want to connect to.
New projects are created with a project.properties file. This property file contains properties specific to the project. The sample project.properties file has a preconfigured list of Agile PLM instances (Golden Config, Development, Quality Analysis, Stage, Training, and Production) listed in it. Each instance is assigned a nickname. For instance, the production instance might be ”prod”.
Here is an example of a connection that is configured in the project.properties file. For example purposes, Acme is the name of the customer. Configure all of your connections in a similar manner.
prod.name = Acme Production
prod.url = http://www.acme.com:7777/Agile
prod.username = propagation
prod.xml = export_prod.agl
In this example, ”prod” is the nickname for the connection. You will specify the nickname as a parameter to the ACP commands. Each of the properties for this particular connection must be prefixed by ”prod.”.
| Property Name | Property Description |
|---|---|
| name | A friendly name for the connection. The application does not actually use this property. You can use this property however you would like. |
| url | The URL to use for accessing the Agile PLM instance. Essentially, this is the URL used to access the Agile PLM Web Client up through "/Agile". |
| username | (optional) The name of the administrator user to connect to the Agile PLM instance with. |
| xml | The name of the ACP archive created when exporting data from this Agile PLM instance. |
Refer to "Properties" for more details.
ACP uses the control file config.xml to tell it what to propagate. The sample control file is configured to select all objects for all configuration types except for users. You can leave the control file configured as is or you can change the configured settings.
The control file is divided into five sections:
<copy> The Copy section tells ACP which objects should be created or updated.
<rename> The Rename section tells ACP which objects whose keys must be renamed in the target.
<delete> The Delete section tells ACP which objects should be deleted from the target.
<ignore_references> The Ignore References section tells ACP which object references can be ignored if they cannot be resolved in the target instance.
<subobject_maps> The Subobject Maps section helps ACP map subobject keys between the source and target.
"Configuring the ACP Control File" for detailed information on how to configure the control file.
Also contained in the control file are Attributes that influence the business logic that ACP uses regarding certain configuration types. These are also covered in the next chapter, in "Business Logic Attributes in the Control File".
ACP is run through a set of scripts. The scripts are initiated from a command-line in either a DOS command window or a UNIX shell. The ACP scripts are installed to the bin directory. When running the ACP scripts, the folder for the project you are currently working with must be your current working directory. Depending on the script you are running, you will need to pass in the nickname for the connection(s) the ACP script will be interacting with.
For convenience, a script launcher was installed to the project directory. You can use this script to launch ACP script you want to run.
Change directory to the project folder for the project you are working with.
Windows: cd /d D:\Agile\AcpWork
UNIX: cd /export/home/joeuser/agile/acpwork
Set the ACP_JAVA_HOME environment variable to where the JRE 1.8 has been installed.
Windows: Set ACP_JAVA_HOME = c:\jre
UNIX: ACP_JAVA_HOME = /u01/app/jre
Launch the desired script. The examples direct ACP to export the Dev instance and to import the Dev instance to the Prod instance:
acp export dev
acp import dev prod
Refer to "ACP Scripts" for a complete list of ACP commands and their parameters.
ACP uses a command-line interface to execute. This allows ACP to be run from background scripts that you develop. Each ACP script runs a specific ACP program. An ACP program will return a code when it exits. This ”exit code” indicates whether the program completed successfully, successfully but with warnings, or with errors. Your background scripts can interrogate the exit code and take the appropriate action based on the code returned.
Refer to "ACP Exit Codes" for a list of the program return codes and corresponding text.
In addition to the data that is propagated to a target instance or exported to an ACP archive, ACP creates log files which describe what ACP did.
The process log tells you what you asked ACP to do, what was processed, and the result for each object processed.
The error log provides detailed information about warnings and errors encountered while processing.
The verbose log provides detailed information about information changed in the target instance.
Refer to "ACP Program Logs" for closer inspections (”anatomy”) and a sample of several of the log files.
ACP is driven from a command-line interface. This allows ACP to be integrated with the configuration management process you are currently using. It does not lend itself to ad-hoc configuration changes.
Managing your configuration through projects will allow you to reuse and perform multiple configuration changes simultaneously.
You interact with ACP through a set of scripts that are installed with ACP.
Use ACP Properties to tell ACP how to interact with your environment.
Use the Control File to tell ACP what objects you want propagated.
Review the work ACP has performed through the log files produced by ACP.
Interrogate the return codes provided by ACP to complete the integration with your configuration management process.
