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 8. You are required to install Java 8. You can use the ACP_JAVA_HOME environment variable to tell ACP where the JRE is installed. This enables you to use the JAVA_HOME environment variable for other uses.

Windows: set ACP_JAVA_HOME=<Java 8 JRE/JDK Directory>

UNIX: export ACP_JAVA_HOME=<Java 8 JRE/JDK Directory>

For convenience, you can add this 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 enables 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 through 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, and also know 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: version

Sample Output:

Agile(TM) ACP CopyConfig (Version ACP 9.3.6 (Build 45))

ACP Version: ACP 9.3.6 (Build 45)

Required Agile PLM Version: 9.3.6 (Build 45)

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.

Choose a name for the new project folder. The folder name cannot already exist.
Open a terminal window (Windows: DOS window; UNIX: shell)
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
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 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.7.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.8 Object Detail Comparison Script

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

D.8.1 deep_compare

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

Usage: acp deep_compare <source nickname> <target nickname> [-debug]
Example: acp deep_compare dev prod

D.8.2 Generating the Deep Compare Difference Report

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

D.8.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 ACP936_SRC ACP936_TRG

D.8.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 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". Close the Difference Report before re-running Deep Compare.

D.8.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.8.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, for example, 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. For example, URL = `http://chandrakantdesk:8888/web`; User = admin
Compare Run Date and Time	Date and Time of Deep Compare report being generated, for example, 3/11/2009 2:34:24 PM
Duration of Compare	How much time does ACP consume to compare the SOURCE and TARGET instances? For example, 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, for example, 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, for example, 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, for example, 11.
OBJECT COMPARE SUMMARY Statistics of the configuration level.
Configuration Type	Type of Configurations being compared. Refer enabled Configurations List for Deep Compare, for example, Company Profile.
Objects Available At Source	Total number of Objects available at Source. This is based on pattern matching at control file (config.xml), for example, 110.
Objects Available At Target	Total number of Objects available at Target. This is based on pattern matching at control file (config.xml), for example, 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), for example, 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), for example, 23.
Objects With Errors	How many Objects are failed in this configuration? Total number of objects failed to compare, for example, 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. Refer to enabled Configurations List for Deep Compare, for example, Class.
Name	Name of the Object, for example, 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. Refer to enabled Configurations List for Deep Compare, for example, Class.
Name	Name of the Object, for example,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, and so on. This field also talks about Rename Map, Sub Object Map and Ignore References if it is enabled and matched at the both instances, for example, Difference.
Configuration Type	Type of Configuration being compared. Refer to enabled Configurations List for Deep Compare, for example, Subclass.
Object	Name of the Object, for example, ECO.
Context	If Configurations are having UI Tabs and differences are existed in those Tabs, then details of accessing path will be given, for example, General Information.
Attribute	Name of the Attribute, for example, Date01.
Property	Name of the property, for example, Description.
Source Value	Physical value at source instance, for example, ABC.
Target Value	Physical value at target instance, for example, XYZ.