C Properties

ACP provides a set of properties for you to communicate to ACP how you would like ACP to interact with your environment. These properties include information for connecting to Agile PLM instances, log file names, and behavior manipulation. ACP offers great flexibility with setting properties. The primary use of this flexibility is to allow you to share properties across projects. This is especially useful for connections since chances are all of your projects will use the same connections.

C.1 Property Sources

Since ACP enables you to set properties in multiple places, it is important that you understand the precedence order ACP uses for deciding which value to use if the property is set in multiple places. If the same property is defined multiple times in the same source, the first occurrence is used.

Order	Property Source	Description
1.	Program Defined	These are properties set by the program that cannot be overridden.
2.	Command Line Property	These are -D options specified on the command line and passed to the program through the ACP script used.
3.	Command Line Property File	These are names of property files specified on the command line and passed to the program through the ACP script used.
4.	Project Property File	This is the property file specific to your project. It is the project.properties file located in your project folder.
5.	Common Property File	This is a property file which can be shared across all ACP projects for a single version. The name of this property file must be set in your project.properties file. This file can be located anywhere.
6.	Global Property File	This is a property file which can be shared across all ACP projects for all versions. The name of this property file must be set in your project.properties file. This file can be located anywhere.
7.	Program Default	These are properties set by the program that can be overridden.

C.2 Defining Properties

ACP uses Java-style properties. As mentioned before, ACP provides great flexibility with its properties. Properties can be defined in terms of other properties. You can create your own properties. And finally, properties can be referenced through indirection.

C.2.1 Java-style Property

Java-style properties syntax:

<property name> = <property value>

Example:

prod.name = Acme Production

C.2.2 Property References

Properties can be defined in terms of other properties. This is very powerful as it allows for ease of automation. ACP uses the Ant-style property reference.

Reference Syntax:

${<property name>}

Example:

acp.method = export
acp.run.datetime = 20090603_142442
log.process.name = ${acp.method}_${acp.run.datetime}.log

result: log.process.name = export_20090603_142442.log

C.2.3 Indirect References

To extend the power of defining properties in terms of others, ACP supports the use of indirection. This power is usually not warranted. It exists to support the specification of connections. ACP refers to connections as src or tgt. If ACP required you to use these names, you would need to remember to modify the project.properties file each you wanted to use a different connection. To keep things simple, ACP enables you to define all of your connections once and give each connection a nickname.

Indirect Reference Syntax:

${${<property name>}}

Example:

src.ref = prod
prod.name = Acme Production
log.process.name = ${${src.ref}.name}.log
 
result: log.process.name = Acme Production.log

C.3 Properties

Here are the properties known by ACP. You can also create your own properties. The properties you create would only be useful if used in the definition of other properties. You can find detailed information regarding the properties known to ACP in the file <ACP Install Directory>/templates/properties.txt.

C.3.1 Agile-owned Properties

The properties listed here are set by the program and cannot be overridden. These properties are made available to you so that you may use them in the definition of other properties.

Property Name	Description
acp.program.name	The name of the ACP program being run.
acp.program.version	The version of the ACP program being run.
acp.program.date	The date the ACP program was started (YYYYMMDD).
acp.program.time	The time the ACP program was started (HH24MISS).
acp.program.datetime	The date and time the ACP program was started (YYYYMMDD_HH24MISS).
acp.method	The method (export, import, name_compare, deep_compare) that ACP will use. The method determines the type of the source and target connections. Possible Values: export - source is Agile; target is XML import - source is XML; target is Agile name_compare and deep_compare - source is XML; target is Agile
src.ref	Provides a level of indirection for the propagation source. This allows the actual source to be determined on the command line. Refers to a nickname for a connection.
tgt.ref	Provides a level of indirection for the propagation target. This allows the actual target to be determined on the command line. Refers to a nickname for a connection.

C.3.2 Agile-defaulted Properties

The properties listed here are set by the program; however, their values can be overridden.

Property Name	Description
acp.debug	Indicates if stack traces should be included with error messages. Stack traces are useful for Agile Customer Care to solve issues. Possible Values: false - stack traces are included (default) true - stack traces are not included
acp.verbose	Indicates if detailed propagation information should be written to the verbose log. Possible Values: false - no verbose information is logged (default) true - verbose information is logged
objects.suppress.skipped	Indicates if the names of objects which do not match the selection regular expressions should be logged. Possible Values: false - skipped objects are logged (default) true - skipped objects are not logged
control.filename	The name of the control file. (format: [<file path>/]<file name>.xml. Default: config.xml
log.process.filename	The name of the process log file (format: [<file path>/]<file name>). If no path is specified, the log file is created in the current project directory. Default: ${acp.method}.log
log.process.open.mode	Indicates how ACP should open the process log file when it already exists. Possible Values: append - appends to the file if already exists overwrite - overwrites the file if already exists
log.error.filename	The name of the error log file (format: [<file path>/]<file name>). If no path is specified, the log file is created in the current project directory. Default: ${acp.method}.err
log.error.open.mode	Indicates how ACP should open the error log file when it already exists. Possible Values: append - appends to the file if already exists overwrite - overwrites the file if already exists
log.verbose.filename	The name of the verbose log file (format: [<file path>/]<file name>). If no path is specified, the log file is created in the current project directory. Default: ${acp.method}Verbose.log
log.verbose.open.mode	Indicates how ACP should open the verbose log file when it already exists. Possible Values: append - appends to the file if already exists overwrite - overwrites the file if already exists

C.3.3 Customer-owned Properties

The properties listed here are set by the program, however, their values can be overridden.

Note: Connection nicknames are a concept, not a property. ACP uses the nickname to qualify a connection property (use <nickname>.name; for example, prod.name for a connection nicknamed ”prod”).

Property Name	Description
global.properties.filename	The path and name to an optional global properties file. This properties file is intended to allow you to share properties across all projects for all versions of ACP. An example of this file can be found at <ACP Install Dir>/templates/global.properties. Note: Use forward slashes (/) as the path separator.
common.properties.filename	The path and name to an optional common properties file. This properties file is intended to allow you to share properties across all projects for a single version of ACP. This is especially useful for maintaining connection information. An example of this file can be found at <ACP Install Dir>/templates/common.properties. Note: Use forward slashes (/) as the path separator.
<nickname>.name	This is used as a descriptive name for the connection. It is provided for you to use in the definition of other properties.
<nickname>.url	The Agile PLM URL for the connection. Format: http://<hostname>[:<port number>]/Agile. Essentially, this is the URL used to connect to the Agile PLM web client through ”/Agile”.
<nickname>.username	(optional) The login name for a valid Agile user which has Administrator privileges to connect to the Agile PLM instance referenced by this connection. Default: propagation.
<nickname>.xml	The name to use for the XML archive when exporting from or importing from this Agile PLM instance (format: [<absolute path>/]<Agile XML archive name>.agl).

Here are some complete examples for defining a connection, using "Acme" as the customer name.

dev.name=Acme Development
dev.username=propagation
dev.xml=export_dev.agl
 
prod.name=Acme Production
prod.url=http://agileplm-prod.acme.com:7777/Agile
prod.xml=export_prod.agl