exportBuildDefinition

Edit online

The exportBuildDefinition task exports build definitions from an EWM repository into an executable Ant build script as a createBuildDefinition or updateBuidlDefinition task embedded in a Build.Definitions target.

The exportBuildDfinition task can be used to export a single build definition, or a series of build definitions, into a fully formatted Ant build script. The generated build script can be used for build definition recovery, backup, and restore of the build definition, moving the build definition to another repository, and/or ongoing maintenance of the build definition.

The following table describes exportBuildDefinition attributes.

Attribute	Description	Required
repositoryAddress	Address of the team repository to use. The value of this attribute is typically ${repositoryAddress} because that property is built-in when the Jazz® Build Engine is used.	Yes
userId	User ID for authentication to the repository. Requires password or passwordFile to be set.	Yes
certificateFile	The path to the file that contains the user's login certificate for authentication. Requires password or passwordFile to be set. You can specify certificateFile or repositoriesFile, but not both.	No
password	Password for the user ID for authentication to the repository. Either password or passwordFile can be provided, but not both.	No
passwordFile	The password file to use for authentication to the connection. You can create a suitable password file by invoking the Jazz Build Engine with the `-createPasswordFile` argument. Only one password file can be specified. Either password or passwordFile can be provided, but not both.	No
smartCard	Use of the connected smart card for authentication (`true` or `false`). Requires userId to be set. For more information about smart card authentication, see Connecting to repositories and project areas.	No
failOnError	If `true` (default value), the task fails if it encounters an error. If `false`, some errors are ignored and the task is completed.	No
verbose	More message output. The default value is `false`.	No
buildId	The ID for the build that is to be created.	Yes
buildWorkspace	The name of the workspace to use as a reference for streams, components, projects and files used by the build and included in the build definition. This does not have to be the workspace that is used by the build, but it can be. It must be a workspace that is attached to the same streams, components, projects, and files used by the build. This workspace is used as the prototype for any workspace defined to the build that is created by the creatBuildDefinition task.	Yes
commaSeparated	This option controls how list items for build properties are specified. Valid values are `true` and `false`. If the value is `true`, a build definition report is generated. If `false`, list items must be separated by a space. The default value is `true`.	No
createReport	This option controls whether or not a build definition report is generated. Valid values are `true` and `false`. If the value is `true`, a build definition report is generated. If `false`, no report is generated. If other reporte attributes are specified and createReport is set to `false`, no report is generated and the other report attributes are ignored. The default is `true`.	No
exportAsis	Specify `true` to have build property values exported "asis" and to have the asis attribute added to the build property elements. An"asis" property value means that the value is already in its' resolved form. For example, if a build property specifies a workspace name, the unresolved form of the value is the name of the workspace and the resolved form of the value is a workspace UUID string. When the asis attribute is set to `true`, it signifies that the workspace value is already in UUID form. This attribute is optional. The default value is `false`.	No
exportCreate	Specify `true` to have a createBuildDfinition task created by the export. Specify `false` to have an updateBuildDefinition task created by the export. The default value is `true`.	No
exportFile	The name of the export file. This is the file where the Ant script with exported build definition is written. Since the export file is also an Ant build script, the file extension typically used for this file is "xml".	Yes
exportFolder	The name of the export file folder. This is the location for the export file. A fully qualified path is required.	Yes
exportFormat	This option controls whether or not the resulting export file, and the XML it contains, is formatted for human consumption. Specify `true` to have the XML formatted into a more readable form. Specify `false` to create a standard,compact XML file. The default is `true`.	No
exportInternal	This option controls whether or not internal properties are exported. Valide values are `true` and `false`. Specify `true` to export internal build properties. Specify `false` to skip the export of internal build properties. The default value is `false`.	No
exportLog	This option controls whether the resulting export file is written to the console as well as the file. Specify `true` to write the XML to the console, or build log, in addition to the file. Specify `false` to write the XML only to the xexport file. The default value is `false`.	No
exportReportAppend	This option controls the contents of the reportAppend attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportAppend="true" attribute added to the task. Specify `false` to have the reportAppend="false" attribute added to the task. If this attribute is omitted, the reportAppend attribute will be omitted from the task in the export.	No
exportReportCondensed	This option controls the contents of the reportCondensed attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportCondensed="true" attribute added to the task. Specify `false` to have the reportCondensed="false" attribute added to the task. if this attribute is omitted, the reportCondensed attribute will be omitted from the task in the export.	No
exportReportFile	This option controls the contents of the reportFile adttribute on the exported createBuildDefinition or updateBuildDefinition task. Specify a file_name to have the reportFile="file_name"attribute added to the task. If this attribute is omitted, the reportFolder attribute will be omitted from the task in the export.	No
exportReportFolder	This option controls the contents of the reportFolder attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify a folder_path to have the reportFolder="folder_path" attribute added to the task. If this attribute is omitted, the reportFolder attribute will be omitted from the task in the export.	No
exportReportNoUuid	This option controls the contents of the reportNoUuid attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportNoUuid="true" attribute added to the task. Specify `false` to have the reportNoUuid="false" attribute added to the task. If this attribute is omitted, the reportNoUuid attribute will be omitted from the task in the export.	No
exportReportOnly	This option controls the contents of the reportONly attribute on the exported createBuildDefinition task. Specify `true` to have the reportOnly="true" attribute added to the task. Specify `false` to have the reportOnly="false" attribute added to the task. If this attribute is omitted, the reportOnly attribute will be omitted from the task in the export. This option is recognized only if exportCreate is set to `true`.	No
exportReportSorted	This option controls the contents of the reportSorted attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportSorted="true" attribute added to the task. Specify `false` to have the reportSorted="false" attribute added to the task. If this attribute is omitted, the reportSorted attribute will be omitted from the task in the export.	No
processAreaName	The name of the EWM process area where the builds are defined. When the process area is a child of a parent process area, like a team area, specify the process area name in a path format starting with the project area name ( /project_area_name/team_area_name/subteam_area_name for example).	Yes
processAreaNameDefinitions	The name of the EWM process area where Enterprise Extensions resource definitions used by this build are defined. If not specified, the EWM process area identified by the processAreaName attribute is used. Nevertheless, if the process area is a team area, the EWM process area must be explicitly identified to define where the Enterprise Extensions system definitions are.	No
reportAppend	This option controls whether the build definition report is appended to or overwrites the specified report file. Valid values are `true` and `false`. If the value is `true`, the build definition report will be appended to the specified report file. If `false`, the build definition report will overwrite (replace) the specified report file. The default is `false`.	No
reportCondensed	Thihs option controls the format of build properties written to the build definition report. Valid values are `true` and `false`. If the value is `true`, each build property will be reported on a single line, displaying only the name and value of the property. If `false`, each build property will be reported on multiple lines, displaying each attribute of the build property on a line. The default value is `false`.	No
reportFile	The name of the report file. If a reportFile is specified, the build definition report will be written to the file. If omitted, the build definition report will be written to the build log.	No
reportFolder	The name of the report file folder. This is the location for the report file. A fully qualified path is required.	No
reportNoUuid	This option controls whether or not UUID values are printed. Valid values are `true` and `false`. If the value is `true`, UUID values are printed x-ed out. If `false`, UUID values are printed as strings. The defualt value is `false`.	No
reportSorted	This option controls whether or not build properties are reported in sorted order in the build definition report. Valid values are `true` and `false`. If the value is `true`, build properties are reported in sorted name order. If `false`, build properties are reported in random order. The default is `false`.	No

Build Definition Elements

One or more buildDefinition elements can be specified within the exportBuildDefinition element. Build definition elements are used to identify a series of build definitions to export. Both the builId attribute and buildDefinition elements can be specified. At lease one buildDefinition element or the buildId attribute is required.

The following table describes the valid buildDefinition element attributes.

Attribute	Description	Required
buildId	The ID for the build that is to be created.	Yes
buildWorkspace	The name of the workspace to use as a reference for streams, components, projects and files used by the build and included in the build definition. This does not have to be the workspace that is used by the build, but it can be. It must be a workspace that is attached to the same streams, components, projects, and files used by the build. This workspace is used as the prototype for any workspace defined to the build that is created by the creatBuildDefinition task.	No
exportReportAppend	This option controls the contents of the reportAppend attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportAppend="true" attribute added to the task. Specify `false` to have the reportAppend="false" attribute added to the task. If this attribute is omitted, the reportAppend attribute will be omitted from the task in the export.	No
exportReportCondensed	This option controls the contents of the reportCondensed attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportCondensed="true" attribute added to the task. Specify `false` to have the reportCondensed="false" attribute added to the task. if this attribute is omitted, the reportCondensed attribute will be omitted from the task in the export.	No
exportReportFile	This option controls the contents of the reportFile adttribute on the exported createBuildDefinition or updateBuildDefinition task. Specify a file_name to have the reportFile="file_name"attribute added to the task. If this attribute is omitted, the reportFolder attribute will be omitted from the task in the export.	No
exportReportFolder	This option controls the contents of the reportFolder attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify a folder_path to have the reportFolder="folder_path" attribute added to the task. If this attribute is omitted, the reportFolder attribute will be omitted from the task in the export.	No
exportReportNoUuid	This option controls the contents of the reportNoUuid attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportNoUuid="true" attribute added to the task. Specify `false` to have the reportNoUuid="false" attribute added to the task. If this attribute is omitted, the reportNoUuid attribute will be omitted from the task in the export.	No
exportReportOnly	This option controls the contents of the reportONly attribute on the exported createBuildDefinition task. Specify `true` to have the reportOnly="true" attribute added to the task. Specify `false` to have the reportOnly="false" attribute added to the task. If this attribute is omitted, the reportOnly attribute will be omitted from the task in the export. This option is recognized only if exportCreate is set to `true`.	No
exportReportSorted	This option controls the contents of the reportSorted attribute on the exported createBuildDefinition or updateBuildDefinition task. Specify `true` to have the reportSorted="true" attribute added to the task. Specify `false` to have the reportSorted="false" attribute added to the task. If this attribute is omitted, the reportSorted attribute will be omitted from the task in the export.	No
processAreaNameDefinitions	The name of the EWM process area where Enterprise Extensions resource definitions used by this build are defined. If not specified, the EWM process area identified by the processAreaName attribute is used. Nevertheless, if the process area is a team area, the EWM process area must be explicitly identified to define where the Enterprise Extensions system definitions are.	No
reportAppend	This option controls whether the build definition report is appended to or overwrites the specified report file. Valid values are `true` and `false`. If the value is `true`, the build definition report will be appended to the specified report file. If `false`, the build definition report will overwrite (replace) the specified report file. The default is `false`.	No
reportCondensed	Thihs option controls the format of build properties written to the build definition report. Valid values are `true` and `false`. If the value is `true`, each build property will be reported on a single line, displaying only the name and value of the property. If `false`, each build property will be reported on multiple lines, displaying each attribute of the build property on a line. The default value is `false`.	No
reportFile	The name of the report file. If a reportFile is specified, the build definition report will be written to the file. If omitted, the build definition report will be written to the build log.	No
reportFolder	The name of the report file folder. This is the location for the report file. A fully qualified path is required.	No
reportNoUuid	This option controls whether or not UUID values are printed. Valid values are `true` and `false`. If the value is `true`, UUID values are printed x-ed out. If `false`, UUID values are printed as strings. The defualt value is `false`.	No
reportSorted	This option controls whether or not build properties are reported in sorted order in the build definition report. Valid values are `true` and `false`. If the value is `true`, build properties are reported in sorted name order. If `false`, build properties are reported in random order. The default is `false`.	No

Note:

If any one of the exportReportAppend, exportReportCondensed, exportReportFile, exportReportFolder, exportReportNoUuid, exporeReportSorted, or exportReportOnly attributes are specified on the exportBuildDefinition element, the value for the attribute will be used for all exported builds.
If any one of the exportReportAppend, exportReportCondensed, exportReportFile, exportReportFolder, exportReportNoUuid, exportReport Sorted, or exportReportOnly attributes are specified on the exportBuildDefinition element, the value for the attribute can be overridden by a similar attribute on a buildDefinition element.
If any one of the exportReportAppend, exportReportCondensed, exportReportFile, exportReportFolder, exportReportNoUuid, exportReportSorted, or exportReportOnly attributes are specified on the exportuildDefinition element and overridden by a similar attribute on a buildDefinition element, the value for the attribute will revert back to the value specified on the exportBuildDefinition element for subsequent buildDefinition elements unless overridden on the subsequent buildDefinition elements.
If the processAreaNameDefinitions attribute is specified on the exportBuildDefinittion element, the value for the attribute will be used for all exported builds.
If the processAreaNameDefinitions attribute is specified on the exportBuildDefinition element, the value for the attribute can be overridden by a similar attribute on a buildDefinition element.
If the processAreaNameDefinitions attribute is specified on the exportBuildDefinition element and overridden by a similar attribute on a buildDefinition element, the value for the attribute will revert back to the value specified on the exportBuildDefinition element for subsequent builDefinition elements unless overridden on the subsequent buildDefinition elements.
The value for the buildWorkspace attribute specified on the exportBuildDefinition element will be used for all exported builds.
The value for the buildWorkspace attribute specified on the exportBuildDefinition element can be overridden by a smiliar attribute on a buildDefinition element.
The value for the buildWorkspace attribute specified on the exportBuildDefinition element and overridden by a similar attribute on abuildDefinition element will revert back to the value specified on the exportBuildDefinition element for subsequent buildDefinition elements unless overridden on the subsequent buildDefinition elements.
When creating or maintaining a series of similar builds, define a single prototype workspace for the builds and specify that workspace for the buildWorkspace attribute. If the createWorkspace attribute is set to true, any unique workspaces required by a build, and not found ind the repository will be automatically created by the createBuildDefinition task using the prototype workspace as a model when the build definition is created. This feature can be used to avoid the overhead of manually creating individual workspaces for a series of builds.

Examples

Export build definitions:


<target name="test" description="Export Build Definition">
  
  <xt:exportbuilddefinition
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    buildId="Test.djr.Dpnd.013"
    buildWorkspace="Test.djr.Stream.000.Workspace"
    processAreaName="${paDJR}"
    processAreaNameDefinitions="Liams PA"
    exportFile="BuildDefinition.000.xml"
    exportFolder="C:\Users\djreilly\Downloads"
    exportFormat="true"
    exportLog="true"
    exportReportCondensed="true"
    exportReportFile="Test.djr.Dpnd.013.txt"
    exportReportFolder="C:\Users\djreilly\Downloads"
    exportReportSorted="true">
  </xt:exportbuilddefinition>
  
  <xt:exportbuilddefinition
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    buildId="Test.djr.Dpnd.013"
    buildWorkspace="Test.djr.Stream.000.Workspace"
    processAreaName="${paDJR}"
    processAreaNameDefinitions="Liams PA"
    exportFile="BuildDefinition.001.xml"
    exportFolder="C:\Users\djreilly\Downloads"
    exportFormat="true"
    exportLog="true"
    exportReportCondensed="true"
    exportReportFile="Test.djr.Dpnd.013.txt"
    exportReportFolder="C:\Users\djreilly\Downloads"
    exportReportSorted="true">
    
    <xt:buildDefinition buildId="Test.djr.Dpnd.000" processAreaNameDefinitions="${paDJR}" exportReportFile="Test.djr.Dpnd.000.txt"/>
    <xt:buildDefinition buildId="Test.djr.Dpnd.001" processAreaNameDefinitions="${paDJR}" exportReportFile="Test.djr.Dpnd.001.txt"/>
    <xt:buildDefinition buildId="Test.djr.Dpnd.010" processAreaNameDefinitions="${paDJR}" exportReportFile="Test.djr.Dpnd.010.txt"/>
    <xt:buildDefinition buildId="Test.djr.Dpnd.011" processAreaNameDefinitions="${paDJR}" exportReportFile="Test.djr.Dpnd.011.txt"/>
    <xt:buildDefinition buildId="Test.djr.Dpnd.012" exportReportFile="Test.djr.Dpnd.012.txt"/>
    
  </xt:exportbuilddefinition>
 
</target>