AHPTool Documentation

Originally Wiki'd By: Brad Galla

This page lists the documentation for AHPTool. You can find this documentation located in your server's dev-kit available on the tools page.

AHPTool is a command-line interface for AnthillPro that provides communication between agent-side commands, scripting and the AnthillPro central server. AHPTool is focused on setting and retrieving information from the AnthillPro server in the context of a running workflow: It can be used to look up or set properties at the system, step, request, job, Build Life and agent levels. AHPTool can upload and retrieve Test, Coverage, Analytics, or Issue data in the form of an XML document to AnthillPro --making it an excellent integration point for writing your own Plugin or script.

  • Common usage
    • AHPTool is used by automation engineers and AnthillPro Plugin developers looking to streamline communication between Plugins or scripts run on the agent and the AnthillPro server --including the lookup of properties. For example, AHPTool enables you to write an integration with your custom testing tool. Following the AHPTool schemas, you can transform the tool's output into AnthillPro XML, and then feeds that file into AHPTool for upload.

AHPTool is packaged with every AnthillPro agent. To access it, go to the agent's /bin directory and run either the ahptool.sh or ahptool.cmd file. This will show you all the available commands and arguments. Alternately, you can download the agent-only installer from Supportal.

AHPTool Commands and Arguments

The section below shows the formation of the ahptool command line.

ahptool [global-args...] [args...] command [-] [filename]

  • command
    • One of the named commands below in the Commands section
  • -
    • Read XML input from the ahptool stdin. See command for requirements.
  • filename
    • Read XML input from a file with the given filename. See command for requirements.

Global Args

COMMAND DESCRIPTION REQ'D
-authtoken Can be set as AH_AUTH_TOKEN in the environment. A authentication token generated by the Anthill server. authtoken or a username/password is required.
-password A password to authenticate with the Anthill server. authtoken or a username/password is required.
-username A username to authenticate with the Anthill server. authtoken or a username/password is required.
-weburl Can be set as AH_WEB_URL in the environment. The base URL of the Anthill server. Eg. https://localhost:8443 X

Commands

COMMAND DESCRIPTION ARGUMENT ARGUMENT DESCRIPTION REQ'D
addIssues Add issues attached to source changes. Requires XML input. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The build life id to add issues to. X
addSourceAnalytics Add a source analytics report to a build life. Requires XML input. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to add the report to. X
-report The name of the report. X
addSourceChanges Add source changes for a build life. Requires XML input. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to add the source changes to. X
addTestCoverage Add a test coverage report to a build life. Requires XML input. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to add the report to. X
-report The name of the report. X
addTests Add a test report to a build life. Requires XML input. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to add the report to. X
-report The name of the report. X
getAgentProperties Get properties of a agent configuration.. To get all properties in XML form, do not give a value for 'property'. To get just the text value of a property, give a property name for 'property'. -agent The id of the agent to get the properties from. X
-property The name of the property to get the value of.
getBuildLifeProperties Get properties of a build life.. To get all properties in XML form, do not give a value for 'property'. To get just the text value of a property, give a property name for 'property'. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to get the properties from. X
-property The name of the property to get the value of.
getDependencyPlan Get all dependencies for a build life. This includes transitive dependencies. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life. X
getIssues Get issues related to a build life through source changes. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life. X
getJobProperties Get properties of a job execution.. To get all properties in XML form, do not give a value for 'property'. To get just the text value of a property, give a property name for 'property'. -job Can be set via the environment variable AH_JOB_ID. The id of the job execution to get the properties from. X
-property The name of the property to get the value of.
getRequestProperties Get properties of a request.. To get all properties in XML form, do not give a value for 'property'. To get just the text value of a property, give a property name for 'property'. -request The id of the request to get the properties from. X
-property The name of the property to get the value of.
getSourceAnalytics Get a source analytics report of a build life. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to get the report from. X
-report The name of the report. X
getSourceChanges Get source changes of a build life. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to add the source changes to. X
getStepProperties Get properties of a step execution.. To get all properties in XML form, do not give a value for 'property'. To get just the text value of a property, give a property name for 'property'. -job Can be set via the environment variable AH_JOB_ID. The id of the step's job execution to get the properties from. X
-step The index of the step within the job execution or 'current' for the latest step.
-property The name of the property to get the value of.
getSystemProperties Get properties of a global system scope. To get all properties in XML form, do not give a value for 'property'. To get just the text value of a property, give a property name for 'property'. -property The name of the property to get the value of.
getTestCoverage Get a test coverage report of a build life. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to get the report from. X
-report The name of the report. X
getTests Get a test report of a build life. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to get the report from. X
-report The name of the report. X
getWorkDir Get the current working direcotry of a job execution. -job Can be set via the environment variable AH_JOB_ID. The id of the job to get the working directory from. X
setAgentProperties Set properties on a agent configuration. Requires XML input. -agent The id of the agent to set the properties on. X
setBuildLifeProperties Set properties on a build life. Requires XML input. -buildlife Can be set via the environment variable AH_BUILD_LIFE_ID. The id of the build life to set the properties on. X
setJobProperties Set properties on a job execution. Requires XML input. -job Can be set via the environment variable AH_JOB_ID. The id of the job execution to set the properties on. X
setRequestProperties Set properties on a request. Requires XML input. -request The id of the request to set the properties on. X
setStepProperties Set properties on a step execution. Requires XML input. -job Can be set via the environment variable AH_JOB_ID. The id of the step's job execution to set the properties on. X
-step The index of the step within the job execution or 'current' for the latest step.
setSystemProperties Set properties on a global system scope. Requires XML input.
setWorkDir Set the current working directory of a job execution. This blocks until the lock is acquired. Requires XML input. -job Can be set via the environment variable AH_JOB_ID. The id of the job to set the working directory for. X

AHPTool Schemas

The schemas for variable XML are in this section.

Issues Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:complexType name="Issues">
<xsd:sequence>

<xsd:element name="issue" type="Issue" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="date" type="xsd:string" use="required"/>

</xsd:complexType>
<xsd:complexType name="Issue">

<xsd:sequence>
<xsd:element name="name" type="xsd:string" minOccurs="1"/>
<xsd:element name="type" type="xsd:string" minOccurs="0"/>
<xsd:element name="status" type="xsd:string" minOccurs="0"/>
<xsd:element name="description" type="xsd:string" minOccurs="0"/>

</xsd:sequence>
<xsd:attribute name="issue-tracker" type="xsd:string" use="required"/>
<xsd:attribute name="id" type="xsd:string" use="required"/>
<xsd:attribute name="change-id" type="xsd:long" use="optional"/>

</xsd:complexType>
<xsd:element name="issues" type="Issues"/>
</xsd:schema>

Properties Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

<xsd:complexType name="Properties"> 
<xsd:sequence> 
<xsd:element name="property" type="Property" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:complexType name="Property"> 
<xsd:simpleContent> 

<xsd:extension base="xsd:string"> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 
<xsd:attribute name="secure" type="xsd:boolean"/> 

</xsd:extension> 
</xsd:simpleContent> 
</xsd:complexType> 

<xsd:element name="properties" type="Properties"/> 

</xsd:schema>

SCM Change Log Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

<xsd:complexType name="ChangeLog"> 
<xsd:sequence> 
<xsd:element name="log-info" type="ChangeLogInfo" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="change-set" type="ChangeSet" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:complexType name="ChangeLogInfo"> 
<xsd:sequence> 
<xsd:element name="build-life" type="xsd:long" minOccurs="1" maxOccurs="1"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:complexType name="ChangeSet"> 
<xsd:sequence> 
<xsd:element name="repository-id" type="xsd:string" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="repository-type" type="xsd:string" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="anthill-id" type="xsd:long" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="id" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="user" type="xsd:string" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="module" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="branch" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="date" type="date_time" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="file-set" type="FileSet" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="properties" type="Properties" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="comment" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:complexType name="FileSet"> 
<xsd:sequence> 
<xsd:element name="file" type="Change" minOccurs="1" maxOccurs="unbounded"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:complexType name="Change"> 
<xsd:simpleContent> 

<xsd:extension base="xsd:string"> 
<xsd:attribute name="change-type" type="change_type"/> 
<xsd:attribute name="revision-number" type="xsd:string"/> 

</xsd:extension> 
</xsd:simpleContent> 
</xsd:complexType> 

<xsd:complexType name="Properties"> 
<xsd:sequence> 
<xsd:element name="property" type="Property" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:complexType name="Property"> 

<xsd:sequence> 
<xsd:element name="name" type="xsd:string" minOccurs="1" maxOccurs="1"/> 
<xsd:element name="value" type="xsd:string" minOccurs="1" maxOccurs="1"/> 

</xsd:sequence> 
</xsd:complexType> 

<xsd:simpleType name="change_type"> 

<xsd:restriction base="xsd:string"> 
<xsd:enumeration value="A"/> 
<xsd:enumeration value="M"/> 
<xsd:enumeration value="D"/> 

</xsd:restriction> 
</xsd:simpleType> 

<!--"yyyy-MM-dd HH:mm:ss Z" --> 
<xsd:simpleType name="date_time"> 
<xsd:restriction base="xsd:string"> 
<xsd:pattern value="\d{4}-([0][1-9]|[1][0-2])-([0][1-9]|[2][0-9]|[3][0-1]) ([0-1][0-9]|[2][0-3]):[0-5][0-9]:[0-5][0-9].[0-9]+ .+"/> 
</xsd:restriction> 
</xsd:simpleType> 

<xsd:element name="change-log" type="ChangeLog"/> 

</xsd:schema>

Source-analytics Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

<xsd:complexType name="SourceAnalytics"> 
<xsd:sequence> 
<xsd:element name="finding" type="Finding" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 

<xsd:attribute name="type" type="xsd:string" use="required"/> 
<xsd:attribute name="buildLifeId" type="xsd:long" use="required"/> 
<xsd:attribute name="urlLink" type="xsd:string" use="optional"/> 
<xsd:attribute name="findingUrlLink" type="xsd:string" use="optional"/> 

</xsd:complexType> 

<xsd:complexType name="Finding"> 

<xsd:sequence> 
<xsd:element name="id" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="file" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="line" type="xsd:long" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="name" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="severity" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="description" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
<xsd:element name="status" type="xsd:string" minOccurs="0" maxOccurs="1"/> 
</xsd:sequence> 
</xsd:complexType> 

<xsd:element name="analytics" type="SourceAnalytics"/> 

</xsd:schema>

Test-coverage Report Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

<xsd:complexType name="CoverageReport"> 
<xsd:sequence> 
<xsd:element name="coverage-groups" type="CoverageGroup" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 
<xsd:attribute name="type" type="xsd:string" use="required"/> 
<xsd:attribute name="job-id" type="xsd:long" use="required"/> 
<xsd:attribute name="line-percentage" type="xsd:double" use="optional"/> 
<xsd:attribute name="method-percentage" type="xsd:double" use="optional"/> 
<xsd:attribute name="branch-percentage" type="xsd:double" use="optional"/> 

</xsd:complexType> 

<xsd:complexType name="CoverageGroup"> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 
<xsd:attribute name="line-percentage" type="xsd:double" use="optional"/> 
<xsd:attribute name="method-percentage" type="xsd:double" use="optional"/> 
<xsd:attribute name="branch-percentage" type="xsd:double" use="optional"/> 
<xsd:attribute name="complexity" type="xsd:double" use="optional"/> 

</xsd:complexType> 

<xsd:element name="coverage-report" type="CoverageReport"/> 

</xsd:schema>

Test Report Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

<xsd:complexType name="TestReport"> 
<xsd:sequence> 
<xsd:element name="test-suite" type="TestSuite" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 
<xsd:attribute name="type" type="xsd:string" use="required"/> 
<xsd:attribute name="job-id" type="xsd:long" use="required"/> 
<xsd:attribute name="successes" type="xsd:long" use="optional"/> 
<xsd:attribute name="failures" type="xsd:long" use="optional"/> 

</xsd:complexType> 

<xsd:complexType name="TestSuite"> 
<xsd:sequence> 

<xsd:element name="test" type="Test" minOccurs="0" maxOccurs="unbounded"/> 
</xsd:sequence> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 
<xsd:attribute name="successes" type="xsd:long" use="required"/> 
<xsd:attribute name="failures" type="xsd:long" use="required"/> 

</xsd:complexType> 

<xsd:complexType name="Test"> 
<xsd:sequence> 

<xsd:element name="message" type="xsd:string" minOccurs="0"/> 
</xsd:sequence> 
<xsd:attribute name="name" type="xsd:string" use="required"/> 
<xsd:attribute name="class-name" type="xsd:string" use="optional"/> 
<xsd:attribute name="result" type="TestResult" use="required"/> 
<xsd:attribute name="time" type="xsd:unsignedInt" use="optional"/> 

</xsd:complexType> 

<xsd:simpleType name="TestResult"> 

<xsd:restriction base="xsd:string"> 
<xsd:enumeration value="success"/> 
<xsd:enumeration value="failure"/> 
<xsd:enumeration value="error"/> 

</xsd:restriction> 
</xsd:simpleType> 

<xsd:element name="test-report" type="TestReport"/> 

</xsd:schema>

Working Directory Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

<xsd:complexType name="WorkDir"> 
<xsd:simpleContent> 
<xsd:extension base="xsd:string"> 
<xsd:attribute name="scope" type="Scope" use="required"/> 
</xsd:extension> 
</xsd:simpleContent> 
</xsd:complexType> 

<xsd:simpleType name="Scope"> 

<xsd:restriction base="xsd:string"> 
<xsd:enumeration value="job"/> 
<xsd:enumeration value="workflow"/> 

</xsd:restriction> 
</xsd:simpleType> 

<xsd:element name="work-dir" type="WorkDir"/> 

</xsd:schema>

Appendix A: Property XML Example

This is an example XML that can be used with certain steps involving properties (such as setting build life properties):

<Properties>
    <property name="test" type="text">test2</property>
</Properties>