D ACP Scripts

ACP is command-line driven. The ACP programs are initiated by scripts provided with ACP. All scripts are installed to the bin directory under the ACP Install Directory.

D.1 Working Directory

Run the ACP scripts from the project directory you are working with. Running ACP from the project directory provides ACP with context needed to run. Specifically, ACP looks for the project.properties file in the current directory.

cd <ACP Work Directory>/<project directory>

D.2 Java Home

ACP requires Java 1.6. You are required to install Java 1.6. You can use the ACP_JAVA_HOME environment variable to tell ACP where the JRE is installed. This allows you to use the JAVA_HOME environment variable for other uses if you wish.

Windows: set ACP_JAVA_HOME=<Java JRE 1.6 Directory>

Unix: export ACP_JAVA_HOME=<Java JRE 1.6 Directory>

Add environment variable to login profile (Unix) or to the system environment variables (Windows).

D.3 Running Scripts

All ACP scripts are installed to the bin directory under the ACP Install Directory.

D.3.1 ACP Launcher

For convenience, a special script is installed to the project directory. This script is named acp[.bat]. It allows you to launch an ACP script without having to specify the entire path to the bin directory where the ACP script is located.

• Usage: acp <script name> [<script parameters>]

D.4 Propagation Scripts

ACP provides scripts for propagating data from one Agile PLM instance to another Agile PLM instance via a target ACP XML archive.

D.4.1 export

The export script exports configuration data from a source Agile PLM instance to a target ACP XML archive. This script uses the connection nicknames defined in the Project Properties file. It determines the name of the ACP XML archive by the <nickname>.xml property. Each connection can have its own XML archive.

The export script only needs a single parameter because it has enough information to know how to connect to an Agile PLM instance as well as what the ACP XML archive is called. The -debug option provides stack traces in the error messages. These stack traces are only useful to Agile Customer Care.

• Usage: acp export <source nickname> [-debug]

• Example: acp export dev

D.4.2 import

The import script imports configuration data from a source ACP XML archive to a target Agile PLM instance. This script uses the connection nicknames defined in the Project Properties file. It determines the name of the ACP XML archive by the <nickname>.xml property. Each connection can have its own XML archive. The -debug option provides stack traces in the error messages. These stack traces are only useful to Agile Customer Care.

• Usage: acp import <source nickname> <target nickname> [-debug]

• Example: acp import dev prod

D.5 Version Script

ACP provides a script for determining the version of ACP being run.

D.5.1 version

The version script reports the version of ACP being run and also indicates the required version of the Agile PLM instance it can connect to.

Usage: acp version

Sample Output:

Agile(TM) ACP CopyConfig (Version ACP 9.3.3 (Build 49))

ACP Version: ACP 9.3.3 (Build 49)

Required Agile PLM Version: 9.3.3 (Build 49)

D.6 Project Management Script

ACP provides a script for managing the creation of ACP projects.

D.6.1 create_project

The create_project script creates a clean project. This project will look identical to the sample project created by the installer. The project folder will contain three files: ACP Launcher, Project Properties, and Control File.

1. Choose a name for the new project folder. The folder name cannot already exist.

2. Open a terminal window (Windows: DOS window; Unix: shell)

3. Navigate 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\ACPWork

   • Unix: cd /<user home>/agile/acpwork

4. Run the ACP create_project script. The new project name can be specified on the command line or, if it is not specified, the script prompts you for it.

   • Usage: acp create_project [<project_name>]

D.7 Password Encryption Script

ACP provides scripts for getting the encrypted string for a password. Typically, you will not want clear text passwords stored in text files on your computer. ACP allows you to configure passwords as encrypted passwords.

D.7.1 encryptpwd

The encryptpwd script returns an encrypted string for a clear text password entered. You cannot pass the password you wish to get the encrypted form for on the command-line. The script will prompt you for the clear text password.

Usage: acp encryptpwd

D.8 Object Name Comparison Script

Name Compare provides a script to compare object names. This script is designed to help you ensure your Control File has the proper Rename maps for object names.

Note: The name_compare script compares object names only. Use the deep_compare script to perform a detailed object comparison.

D.8.1 name_compare

The name_compare script compares lists of object names between a source ACP XML archive and a target Agile PLM instance.

This script uses the connection nicknames defined in the Project Properties file. It determines the name of the ACP XML archive by the <nickname>.xml property. Each connection can have its own XML archive.

• Usage: acp name_compare <source nickname> <target nickname> [-debug]

• Example: acp name_compare dev prod

D.9 Object Detail Comparison Script

Deep Compare provides a detailed comparison of an object's definition or configuration.

D.9.1 deep_compare

The deep_compare script compares lists of object attributes between a source ACP XML archive and a target Agile PLM instance.

This script uses the connection nicknames defined in the Project Properties file. It determines the name of the ACP XML archive by the <nickname>.xml property. Each connection can have its own XML archive.

• Usage: acp deep_compare <source nickname> <target nickname> [-debug]

• Example: acp deep_compare dev prod

D.9.2 Generating the Deep Compare Difference Report

This section provides details about how to generate the deep compare difference report.

D.9.2.1 Command

<ACPWorkDir>acp deep_compare     srcName tgtName

Example D-1 Example using command to run the deep compare difference report

D:\ACPWorkDir\project>acp deep_compare ACP933_SRC ACP933_TRG

D.9.2.2 Console Message:

This message indicates the status of Deep Compare:

ACP DeepCompare SUCCEEDED - Completed with no errors or notes.

====================DEEP-COMPARE REPORT=======================
Report Generation in Progress, Please Wait...
Report Generated Successfully...

Please Check The Report @ D:\ACPWorkDir\project2\deep_compare.xls

Error Level = 0

Note: If you run Deep Compare and open the report in Microsoft Excel, and then you run Deep Compare again, ACP will report an error. The script will not be able to update the report because "it is in use by another application". Simply close the Difference Report before re-running Deep Compare.

D.9.2.3 Deep Compare Difference Report

The Deep Compare Difference Report contains many fields of information. Following the screenshot of a typical report, a table lists all the fields and what information they convey.

Note: There is a valid condition in Java Client criteria in which the Value field is null (is not populated with a value); ACP will report this as "Invalid Criteria Condition: Invalid value specified." You may ignore this error message.

Figure D-1 Sample Output of Deep Compare Report

Important: Because Criteria and Privileges are both "business critical", and small changes to specific criteria and privileges (either general or single-user) in the Production instance can have consequences, a Best Practice is to always compare all Privileges and Criteria when running Deep Compare.

D.9.2.4 Deep Compare Report Sections and Fields

Deep Compare Report Sections and Fields	Explanation
COMPARE RUN SUMMARY INFORMATION High-level and summary information.
Source XML Filename	Name of the Source ( .agl ) file used for Deep Compare, e.g. ACP93_export.agl
Target Agile Connection Info	This information will talk about the URL or Target instance being used for comparison purpose. This field also tells who (User ID) has compared the instances. e.g. URL = http://chandrakantdesk:8888/web; User = admin
Compare Run Date and Time	Date and Time of Deep Compare report being generated, e.g. 3/11/2009 2:34:24 PM
Duration of Compare	How much time is consumed by ACP to compare the SOURCE and TARGET instances? e.g. 00:00:01:5.907
Total Number of Objects Compared	How many objects have been compared? This gives the total number of SOURCE objects being mapped or matched exactly with TARGET objects (including RENAME mapping if it is enabled). Total Number of Objects Compared =∑ Objects Compared (OBJECT COMPARE SUMMARY) of all configurations, e.g. 12
Total Number of Differences	How many differences found? Total number of Differences is calculated based on the attribute level comparison after considering RENAME MAP, SUBOBJECTMAP and IgnoreRef (if you have enabled them in the Control file). Total Number of Differences =∑ Objects With Differences (OBJECT COMPARE SUMMARY) of all configurations, e.g. 120
Total Number of Errors	How many Objects are failed in this comparison? Total Number of Errors =∑ Objects With Errors (OBJECT COMPARE SUMMARY) of all configurations + Processing errors, e.g. 11
OBJECT COMPARE SUMMARY Statistics of the configuration level.
Configuration Type	Type of Configurations being compared. Please refer enabled Configurations List for Deep Compare, e.g. Company Profile
Objects Available At Source	Total number of Objects available at Source. Please note here, this is based on pattern matching at control file (config.xml), e.g. 110
Objects Available At Target	Total number of Objects available at Target. Please note here, this is based on pattern matching at control file (config.xml), e.g. 110
Objects Compared	How many objects have been compared in this configuration? This gives the total number of SOURCE objects being mapped or matched exactly with TARGET objects (including RENAME mapping if it is enabled), e.g. 34
Objects With Differences	How many differences found in this configuration? Total number of Differences is calculated based on the attribute level comparison after considering RENAME MAP, SUBOBJECTMAP and IgnoreRef (if you have enabled them in the Control file), e.g. 23
Objects With Errors	How many Objects are failed in this configuration? Total number of objects failed to compare, e.g. 02
SOURCE ONLY OBJECTS "Source only" objects: not found on Target instance. This is based on pattern matching at control file (config.xml).
Configuration Type	Type of Configuration being compared. Please refer enabled Configurations List for Deep Compare, e.g. Class
Name	Name of the Object, e.g. ECO
TARGET ONLY OBJECTS "Source only" objects: not found on Source instance. This is based on pattern matching at control file (config.xml)
Configuration Type	Type of Configuration being compared. Please refer enabled Configurations List for Deep Compare, e.g. Class
Name	Name of the Object, e.g.ECO1
DIFFERENCES DETAIL INFORMATION Detailed information about attribute values.
Status	Status can be Difference, Source Only, Target Only(Do not confuse with above Source Only and Target only, this difference is at attribute level),Not Comparable etc. This field also talks about Rename Map, Sub Object Map and Ignore References if it is enabled and matched at the both instances, e.g. Difference
Configuration Type	Type of Configuration being compared. Please refer enabled Configurations List for Deep Compare, e.g. Subclass
Object	Name of the Object, e.g. ECO
Context	If Configurations are having UI Tabs and differences are existed in those Tabs, then details of accessing path will be given, e.g. General Information
Attribute	Name of the Attribute, e.g. Date01
Property	Name of the property, e.g. Description
Source Value	Physical value at source instance, e.g. ABC
Target Value	Physical value at target instance, e.g. XYZ