The task retrieves configuration information for the specified Build Orchestrator build. The type of information retrieved is controlled by the inclusion of the following as sub-elements within the element:

At least one sub-element listed above must be specified to retrieve configuration information for the Build Orchestrator build. No error is generated if sub-elements are omitted.

Attributes

The task supports Team Build Attributes, Build Extensions Debugging Attributes, Build Extensions General Attributes, as well as, its own task specific attributes. Click on a link for more information on the common attributes.

The following table describes the task specific attributes for the task:

Action Element

The Action Element is specified to retrieve action definition details defined in the Build Orchestrator build. The following table describes the valid Action Element attributes:

When an Action Element is specified and the Build Orchestrator build has actions defined, action definition details are returned to the Ant environment in the property arrays described in the following table:

Example

The following example is extracted from the BuildOrchestratorSetup macro. The code segment listed here calls the buildOrchestrator task to retrieve action information, creates a set of build properties, loops through the actions via the index property returned by the buildOrchestrator task (actionCount), and for each action it creates a set of properties for the action entry, with the prefix and index portion stripped from the property names, and finally it calls another macro (BuildOrchestrator.Action) to process the action:

<xt:buildOrchestrator
    buildResultUUID="@{buildResultUUID}"
    passwordFile="@{passwordFile}"
    repositoryAddress="@{repositoryAddress}"
    userId="@{userId}"
    verbose="@{verbose}"
    >
    <xt:actions fetch="true" prefix="@{prefixAction}" property="actionCount"/>
</xt:buildOrchestrator>
<echo level="debug">actionCount:          ${actionCount}</echo>

<propertyset id="BuildOrchestratorProperties.Build">
    <propertyref prefix="team.enterprise."/>
</propertyset>
<echo level="debug">Properties.Build:     ${toString:BuildOrchestratorProperties.Build}</echo>

<ac:for param="i" list="${actionCount}">
    <sequential>
        <propertyset id="BuildOrchestratorProperties.Entry">
            <propertyref prefix="@{prefixAction}@{i}."/>
            <mapper type="glob" from="@{prefixAction}@{i}.*" to="*"/>
        </propertyset>
        <echo level="debug">Properties.Entry:     ${toString:BuildOrchestratorProperties.Entry}</echo>
        
        <antcall target="BuildOrchestrator.Action">
            <param name="action.activityLabel"      value="@{activityLabel}"/>
            <param name="action.buildResultUUID"    value="@{buildResultUUID}"/>
            <param name="action.parent"             value="@{parent}"/>
            <propertyset id="BuildOrchestratorProperties.Action">
                <propertyset refid="BuildOrchestratorProperties.Build"/>
                <propertyset refid="BuildOrchestratorProperties.Entry"/>
            </propertyset>
        </antcall>
    </sequential>
</ac:for>
    

Dependent Element

The Dependent Element is specified to retrieve information on dependent builds defined in the Build Orchestrator build. Dependent builds are builds that depend on the successful completion of another orchestrated build. The following table describes the valid Dependent Element attributes:

When a Dependent Element is specified and the Build Orchestrator build has dependent builds defined, build definition details are returned to the Ant environment in the property arrays described in the following table:

Example

The following example is extracted from the BuildOrchestratorCheck macro. The code segment listed here calls the buildOrchestrator task to retrieve dependent information, creates a set of build properties, loops through the dependent builds via the index property returned by the buildOrchestrator task (dependentCount), and for each dependent build it checks for the required "done files", and if all are present, sets the dependentReady property to true:

<xt:buildOrchestrator
    orchestratorBuildId="@{orchestratorBuildId}"
    passwordFile="@{passwordFile}"
    repositoryAddress="@{repositoryAddress}"
    userId="@{userId}"
    verbose="@{verbose}"
    >
    <xt:dependent prefix="@{prefixDependent}" property="dependentCount"/>
    <xt:housekeeping prefix="@{prefixHousekeeping}" property="housekeepingCount"/>
</xt:buildOrchestrator>
<echo level="debug">dependentCount:       ${dependentCount}</echo>
<echo level="debug">housekeepingCount:    ${housekeepingCount}</echo>

<propertyset id="BuildOrchestratorProperties.Build">
    <propertyref prefix="team.enterprise."/>
</propertyset>
<echo level="debug">Properties.Build:     ${toString:BuildOrchestratorProperties.Build}</echo>

<local name="dependentStage"/>
<local name="housekeepingStage"/>

...

<!-- Dependent builds -->
<ac:for param="i" list="${dependentCount}">
    <sequential>
        <echo level="debug">buildId:              ${@{prefixDependent}@{i}.buildId}</echo>
        <echo level="debug">dependsOn:            ${@{prefixDependent}@{i}.dependsOn}</echo>
        <echo level="debug">dependsOn.done:       ${@{prefixDependent}@{i}.dependsOn.done}</echo>
        
        <local name="dependentToken"/>
        <script language="javascript">
            <![CDATA[
                var stringValue = project.getProperty("@{prefixDependent}@{i}.dependsOn");
                project.setProperty("dependentToken",stringValue.split(",").length);
            ]]>
        </script>
        <echo level="debug">dependentToken:       ${dependentToken}</echo>
        
        <local name="dependentReady"/>
        <ac:if>
            <length string="${@{prefixDependent}@{i}.dependsOn}" when="greater" length="0"/>
            <ac:then>
                <condition property="dependentReady">
                    <resourcecount when="equal" count="${dependentToken}">
                        <fileset dir="@{doneDirectory}" includes="${@{prefixDependent}@{i}.dependsOn.done}"/>
                    </resourcecount>
                </condition>
            </ac:then>
            <ac:else>
                <property name="dependentReady" value="true"/>
            </ac:else>
        </ac:if>
        <echo level="debug">dependentReady:       ${dependentReady}</echo>
        
        ...
        
</ac:for>
    

DependsOn Element

The DependsOn Element is specified to retrieve information on "depends on" builds. DependsOn builds are builds that some Dependent or Housekeeping build depends on. The following table describes the valid DependsOn Element attributes:

When a DependsOn Element is specified and the Build Orchestrator build finds that other builds have a dependency on the specified build, dependency details are returned to the Ant environment in the property arrays described in the following table:

Example

The following example is extracted from the BuildOrchestratorClear macro. The code segment listed here calls the buildOrchestrator task to retrieve "depends on" information for the specified build and if any is found it deletes the "done file" and "submitted file" associated with the dependent or housekeeping build:

<xt:buildOrchestrator
    orchestratorBuildId="@{orchestratorBuildId}"
    passwordFile="@{passwordFile}"
    repositoryAddress="@{repositoryAddress}"
    userId="@{userId}"
    verbose="@{verbose}"
    >
    <xt:dependsOn buildId="@{buildDefinitionId}" prefix="@{prefixDependsOn}" property="dependsOnFound"/>
</xt:buildOrchestrator>
<echo level="debug">dependsOnFound:       ${dependsOnFound}</echo>

<ac:if>
    <istrue value="${dependsOnFound}"/>
    <ac:then>
        <ac:for list="${@{prefixDependsOn}dependent}" delimiter="," param="buildId">
            <sequential>
                <DeleteFileDone buildId="@{buildId}" doneDir="@{doneDirectory}" label="@{activityLabel}.ClearDoneFile"/>
                <DeleteFileSubmitted buildId="@{buildId}" doneDir="@{doneDirectory}" label="@{activityLabel}.ClearDoneFile"/>
            </sequential>
        </ac:for>
        <ac:for list="${@{prefixDependsOn}housekeeping}" delimiter="," param="buildId">
            <sequential>
                <DeleteFileDone buildId="@{buildId}" doneDir="@{doneDirectory}" label="@{activityLabel}.ClearDoneFile"/>
                <DeleteFileSubmitted buildId="@{buildId}" doneDir="@{doneDirectory}" label="@{activityLabel}.ClearDoneFile"/>
            </sequential>
        </ac:for>
    </ac:then>
</ac:if>
    

Housekeeping Element

The Housekeeping Element is specified to retrieve information on housekeeping builds. Housekeeping builds are builds that perform some sort of housekeeping process and execute after all Primary, Secondary, and Dependent builds have successfully completed. The following table describes the valid Housekeeping Element attributes:

When a Housekeeping Element is specified and the Build Orchestrator build has housekeeping builds defined, build definition details are returned to the Ant environment in the property arrays described in the following table:

Example

The following example is extracted from the BuildOrchestratorCheck macro. The code segment listed here calls the buildOrchestrator task to retrieve housekeeping information, creates a set of build properties, loops through the housekeeping builds via the index property returned by the buildOrchestrator task (housekeepingCount), and for each housekeeping build it checks for the required "done files", and if all are present, sets the housekeepingReady property to true:

<xt:buildOrchestrator
    orchestratorBuildId="@{orchestratorBuildId}"
    passwordFile="@{passwordFile}"
    repositoryAddress="@{repositoryAddress}"
    userId="@{userId}"
    verbose="@{verbose}"
    >
    <xt:dependent prefix="@{prefixDependent}" property="dependentCount"/>
    <xt:housekeeping prefix="@{prefixHousekeeping}" property="housekeepingCount"/>
</xt:buildOrchestrator>
<echo level="debug">dependentCount:       ${dependentCount}</echo>
<echo level="debug">housekeepingCount:    ${housekeepingCount}</echo>

<propertyset id="BuildOrchestratorProperties.Build">
    <propertyref prefix="team.enterprise."/>
</propertyset>
<echo level="debug">Properties.Build:     ${toString:BuildOrchestratorProperties.Build}</echo>

<local name="dependentStage"/>
<local name="housekeepingStage"/>

...

<!-- Housekeeping builds -->
<ac:if>
    <not><istrue value="${dependentStage}"/></not>
    <ac:then>
        <ac:for param="i" list="${housekeepingCount}">
            <sequential>
                <echo level="debug">buildId:              ${@{prefixHousekeeping}@{i}.buildId}</echo>
                <echo level="debug">dependsOn:            ${@{prefixHousekeeping}@{i}.dependsOn}</echo>
                <echo level="debug">dependsOn.done:       ${@{prefixHousekeeping}@{i}.dependsOn.done}</echo>
                
                <local name="housekeepingToken"/>
                <script language="javascript">
                    <![CDATA[
                        var stringValue = project.getProperty("@{prefixHousekeeping}@{i}.dependsOn");
                        project.setProperty("housekeepingToken",stringValue.split(",").length);
                    ]]>
                </script>
                <echo level="debug">housekeepingToken:    ${housekeepingToken}</echo>
                
                <local name="housekeepingReady"/>
                <ac:if>
                    <length string="${@{prefixHousekeeping}@{i}.dependsOn}" when="greater" length="0"/>
                    <ac:then>
                        <condition property="housekeepingReady">
                            <resourcecount when="equal" count="${housekeepingToken}">
                                <fileset dir="@{doneDirectory}" includes="${@{prefixHousekeeping}@{i}.dependsOn.done}"/>
                            </resourcecount>
                        </condition>
                    </ac:then>
                    <ac:else>
                        <property name="housekeepingReady" value="true"/>
                    </ac:else>
                </ac:if>
                <echo level="debug">housekeepingReady:    ${housekeepingReady}</echo>
                
                ...
                
            </sequential>
        </ac:for>
    </ac:then>
</ac:if>
    

Primary Element

The Primary Element is specified to retrieve information on primary builds defined in the Build Orchestrator build. Primary builds run in dedicated build engines and are the first builds processed in an orchestrated build. The following table describes the valid Primary Element attributes:

When a Primary Element is specified and the Build Orchestrator build has primary builds defined, build definition details are returned to the Ant environment in the property arrays described in the following table:

Example

The following example is extracted from the BuildOrchestratorStart macro. The code segment listed here calls the buildOrchestrator task to retrieve primary information, creates a set of build properties, loops through the primary builds via the index property returned by the buildOrchestrator task (primaryCount), and for each primary build it calls the BuildOrchestrator.Primary macro to submit the build:

<xt:buildOrchestrator
    buildResultUUID="@{buildResultUUID}"
    passwordFile="@{passwordFile}"
    repositoryAddress="@{repositoryAddress}"
    userId="@{userId}"
    verbose="@{verbose}"
    >
    <xt:primary prefix="@{primaryPrefix}" property="primaryCount"/>
    <xt:secondary prefix="@{prefixSecondary}" property="secondaryCount"/>
</xt:buildOrchestrator>
<echo level="debug">primaryCount:         ${primaryCount}</echo>
<echo level="debug">secondaryCount:       ${secondaryCount}</echo>

<propertyset id="BuildOrchestratorProperties.Build">
    <propertyref prefix="team.enterprise."/>
</propertyset>
<echo level="debug">Properties.Build:     ${toString:BuildOrchestratorProperties.Build}</echo>

<ac:for param="i" list="${primaryCount}">
    <sequential>
        <propertyset id="BuildOrchestratorProperties.Entry">
            <propertyref prefix="@{primaryPrefix}@{i}."/>
            <mapper type="glob" from="@{primaryPrefix}@{i}.*" to="*"/>
        </propertyset>
        <echo level="debug">Properties.Entry:     ${toString:BuildOrchestratorProperties.Entry}</echo>
        
        <antcall target="BuildOrchestrator.Primary">
            <param name="primary.activityLabel"      value="@{activityLabel}"/>
            <param name="primary.buildResultUUID"    value="@{buildResultUUID}"/>
            <param name="primary.parent"             value="@{parent}"/>
            <propertyset id="BuildOrchestratorProperties.Primary">
                <propertyset refid="BuildOrchestratorProperties.Build"/>
                <propertyset refid="BuildOrchestratorProperties.Entry"/>
            </propertyset>
        </antcall>
    </sequential>
</ac:for>
    

Secondary Element

The Secondary Element is specified to retrieve secondary builds defined in the Build Orchestrator build. Secondary builds run in the same dedicated build engines that run the primary builds, but are queued to the dedicated engines after all primary builds have been submitted. The following table describes the valid Secondary Element attributes:

When a Secondary Element is specified and the Build Orchestrator build has secondary builds defined, build definition details are returned to the Ant environment in the property arrays described in the following table:

Example

The following example is extracted from the BuildOrchestratorStart macro. The code segment listed here calls the buildOrchestrator task to retrieve secondary information, creates a set of build properties, processes the primary builds, and then loops through the secondary builds via the index property returned by the buildOrchestrator task (secondaryCount), and for each secondary build it calls the BuildOrchestrator.Secondary macro to submit the build:

<xt:buildOrchestrator
    buildResultUUID="@{buildResultUUID}"
    passwordFile="@{passwordFile}"
    repositoryAddress="@{repositoryAddress}"
    userId="@{userId}"
    verbose="@{verbose}"
    >
    <xt:primary prefix="@{primaryPrefix}" property="primaryCount"/>
    <xt:secondary prefix="@{prefixSecondary}" property="secondaryCount"/>
</xt:buildOrchestrator>
<echo level="debug">primaryCount:         ${primaryCount}</echo>
<echo level="debug">secondaryCount:       ${secondaryCount}</echo>

<propertyset id="BuildOrchestratorProperties.Build">
    <propertyref prefix="team.enterprise."/>
</propertyset>
<echo level="debug">Properties.Build:     ${toString:BuildOrchestratorProperties.Build}</echo>

<ac:for param="i" list="${primaryCount}">
    <sequential>
        <propertyset id="BuildOrchestratorProperties.Entry">
            <propertyref prefix="@{primaryPrefix}@{i}."/>
            <mapper type="glob" from="@{primaryPrefix}@{i}.*" to="*"/>
        </propertyset>
        <echo level="debug">Properties.Entry:     ${toString:BuildOrchestratorProperties.Entry}</echo>
        
        <antcall target="BuildOrchestrator.Primary">
            <param name="primary.activityLabel"      value="@{activityLabel}"/>
            <param name="primary.buildResultUUID"    value="@{buildResultUUID}"/>
            <param name="primary.parent"             value="@{parent}"/>
            <propertyset id="BuildOrchestratorProperties.Primary">
                <propertyset refid="BuildOrchestratorProperties.Build"/>
                <propertyset refid="BuildOrchestratorProperties.Entry"/>
            </propertyset>
        </antcall>
    </sequential>
</ac:for>

<ac:for param="i" list="${secondaryCount}">
    <sequential>
        <propertyset id="BuildOrchestratorProperties.Entry">
            <propertyref prefix="@{prefixSecondary}@{i}."/>
            <mapper type="glob" from="@{prefixSecondary}@{i}.*" to="*"/>
        </propertyset>
        <echo level="debug">Properties.Entry:     ${toString:BuildOrchestratorProperties.Entry}</echo>
        
        <antcall target="BuildOrchestrator.Secondary">
            <param name="secondary.activityLabel"      value="@{activityLabel}"/>
            <param name="secondary.buildResultUUID"    value="@{buildResultUUID}"/>
            <param name="secondary.parent"             value="@{parent}"/>
            <propertyset id="BuildOrchestratorProperties.Secondary">
                <propertyset refid="BuildOrchestratorProperties.Build"/>
                <propertyset refid="BuildOrchestratorProperties.Entry"/>
            </propertyset>
        </antcall>
    </sequential>
</ac:for>
    

Notes

• When specifying the buildResultUuid attribute be sure to specify the build result UUID of a Build Orchestrator build result. The UUID of build results from orchestrated builds - Dependent, DependsOn, Housekeeping, Primary, and Secondary builds - will not have a UUID that qualifies. Only the result from a Build Orchestrator build, a build with a Build Orchestrator configuration element, qualifies. Orchestrated builds must be passed the UUID of the Build Orchestrator build result to use this attribute.