## Introduction
A Java SDK that should be used by the CI plugin to connect and communicate with ALM Octane. See the Javadoc for more information about the CI Plugin SDK API.
This Java SDK project has two sub-projects:
-
integrations-dto, which contains the definition and building factory of all DTO objects used for communication with ALM Octane.
-
integrations-sdk, which is the main source of the CI Plugin SDK.
## Compiling the Project
The easiest way to compile the project is to use Maven and run the following command from the root directory:
mvn clean install
## Creating JavaDoc
To create Javadoc, run the following Maven command from the project root directory:
mvn javadoc:aggregate
This creates a javadoc site in the
/target/site/apidocs/index.html
## Include in Your Project
Add the following dependency to the pom.xml to use this SDK in your project:
<dependency>
<artifactId>integrations-sdk</artifactId>
<groupId>com.hpe.adm.octane.plugins</groupId>
<version>1.0</version>
</dependency>
## Usage Examples
The following CI plugins already use CI Plugin SDK for ALM Octane to connect and communicate with ALM Octane:
Octane Bamboo Plugin
Octane TeamCity Plugin
## Initializing
To start using the CI Plugin SDK, first initialize an OctaneSDK instance. This class provides the main entry point of interaction between the SDK and its services, and interaction between the concrete CI plugin and its services.
OctaneSDK.init(new MyPluginServices(), true);
The init()
method expects an object that implements the CIPluginServices
interface. This object is actually a composite API of all the endpoints to be implemented by a hosting CI Plugin for ALM Octane use cases.
## Communicating with ALM Octane using Data Transfer Objects (DTO)
Data transfer object (DTO) is a design pattern used to transfer data between software application subsystems. We use DTO objects to communicate data to ALM Octane.
Any DTO in the system should be created using DTOFactory
:
T dto = DTOFactory.getInstance().newDTO(Class<T> targetType);
## Updating ALM Octane with CI Events
Upon a CI event, the CI plugin must update ALM Octane using the EventsService
object. The steps are:
- Get the CI event.
- Create the
CIEvent
DTO using the info from the CI event and the CI environment. - Provide this DTO to the
publishEvent
method ofEventsService
.
CIEvent ciEvent = DTOFactory.getInstance().newDTO(CIEvent.class)
.setEventType(eventType)
.setCauses(causes)
.setProject(project)
.setProjectDisplayName(displayName)
.setBuildCiId(buildCiId)
.setEstimatedDuration(estimatedDuration)
.setStartTime(startTime)
.setPhaseType(phaseType);
OctaneSDK.getInstance().getEventsService().publishEvent(ciEvent);
## Submitting Source Control Management (SCM) Data
SCM data are provided by the Source Control Management tool about changes in source code reflected in a specific CI build. SCM data should be submitted to ALM Octane as part of the CIEvent
DTO.
ciEvent.setScmData(scmData);
## ALM Octane Pipeline Structure
ALM Octane pipelines represent the flow of the CI server jobs and steps. Pipeline provides a clear, multi-level, analytic view of specific CI process, CI runs and their status so you can track product quality and progress.
ALM Octane pipeline supports a hierarchical structure of pipeline nodes. Any PipelineNode
can contain a list of internal phases and list of post-build phases. Each PipelinePhase
in turn contains a list of child pipeline nodes.
Pipeline nodes in internal phases represent CI nodes that complete their execution before post-build phases start to execute. Each internal phase should contain nodes that are running in parallel.
This structure is used for correct pipeline representation in ALM Octane. This way in ALM Octane, it is possible to see the flow of steps in the CI server, including which steps run in sequence and which steps run as parts of other steps.
## Providing CI Build Information
The ALM Octane server may ask for a specific build information of some pipeline. To provide the information, implement two CIPluginServices
methods:
SnapshotNode getSnapshotByNumber(String ciJobId, String buildCiId, boolean subTree)
This provides a snapshot of the specified CI build of the specified CI job.
```java SnapshotNode getSnapshotLatest(String ciJobId, boolean subTree) ``` >_This provides a snapshot of the latest CI build of the specified CI job._
The main DTOs for CI build snapshots are ```SnapshotNode``` and ```SnapshotPhase```. These provide the same hierarchical structure described in the [Pipeline Structure](#alm-octane-pipeline-structure) section and allow the ALM Octane user to see the build number, the last run date, the run status, and the duration of the run.
## Providing Test Results
Test results for a specific build are provided by CIPluginServices.getTestsResult
method.
TestsResult getTestsResult(String jobId, String buildNumber)
This provides test result report for the specific build. The
TestResult
DTO should contain a list of all test runs (TestRun
) that were executed in the job specified by thejobId
.
Each ```TestRun``` object represents a single test that ran in a specific CI build. It contains all the information of this specific test, the run result status (```TestRunResult``` enum) and error information if the test failed. Also a url to the test report page can be provided with the ```setExternalReportUrl()``` method.