ALM Octane REST API Java SDK

Maven

<dependency>
    <groupId>com.microfocus.adm.almoctane.sdk</groupId>
    <artifactId>sdk-src</artifactId>
    <version>24.3</version>
</dependency>

Gradle

compile group: 'com.microfocus.adm.almoctane.sdk', name: 'sdk-src', version: '24.3'

Introduction

A Java SDK that can be used to connect to ALM Octane's REST API. See the Javadoc for more information of how to use the SDK. See also the REST API documentation for more details about Octane's API.

This has multiple sub-projects:

1. sdk-src which is the main source of the Java SDK
2. sdk-integration-tests which can be run to test the SDK against your Octane server
3. sdk-usage-examples which contain some simple examples as to how to use the SDK
4. sdk-generate-entity-models-maven-plugin which contains a maven plugin that generates POJO's for your servers Octane entities see "Entity Generation"
5. sdk-extension which provides some tools to access more of the sdk-src's underlying implementation

The easiest way to compile the project is to use maven and run the command:

mvn clean install

from the root directory.

Creating JavaDoc

In order to create javadoc run the following maven command from the sdk-src directory:

mvn javadoc:javadoc

This will create a javadoc site in the sdk-src/target/site/apidocs directory

Entity Generation

You can generate entities based on your server's metadata using the sdk-generate-entity-models-maven-plugin plugin. This plugin connects to your ALM Octane server using the given authentication credentials, shared space and work space and generates strongly typed entities that can be used instead of the generic out of the box entity that comes with the SDK.

To enable this, add the following to your project's POM file (assuming 16.1.100 being the SDK version):

 <build>
        <plugins>
            <plugin>
                <groupId>com.microfocus.adm.almoctane.sdk</groupId>
                <artifactId>sdk-generate-entity-models-maven-plugin</artifactId>
                <version>24.3</version>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <clientId>client_id</clientId>
                    <clientSecret>client_secret</clientSecret>
                    <server>http[s]://server[:port]</server>
                    <sharedSpace>SSID</sharedSpace>
                    <workSpace>WSID</workSpace>
                    <techPreview>boolean (default false)</techPreview>
                    <!--
                        By default the plugin will generate the sources to the generated-source directory under
                        the target.  If you wish to place this in a different place then use this parameter
                    -->
                    <!-- <generatedSourcesDirectory></generatedSourcesDirectory> -->
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>build-helper-maven-plugin</artifactId>
                <version>1.9.1</version>
                <executions>
                    <execution>
                        <id>addGeneratedEntitiesSources</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>add-source</goal>
                        </goals>
                        <configuration>
                            <sources>
                                <!--
                                  This assumes that you leave the configuration of the plugin above
                                  to use the maven generated-sources directory as the place where the generated
                                  sources will be
                                -->
                                <source>${project.build.directory}/generated-sources</source>
                            </sources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <!--
                The sources need to be compiled using Java 8 at least.  Use this if this needs to 
                be explicit
            -->
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

Alternatively you can use the maven command line command to generate. See the maven documentation for more details as to how to do this.

Generated Directories

The generator will create three directories under the com.hpe.adm.nga.sdk package:

• entities
• enums
• model

With the generated code. Do not edit the generated code since it will be overwritten each time you run a maven build.

Using the generated code

See the following example for how to use the generated code:

        final Octane octane = new Octane.Builder(...).build();
        final WorkItemRootEntityModel workItemRootEntityModel = octane.entityList(WorkItemRootEntityList.class).at(1001).get().execute();

        final EpicEntityModel rootEpic = octane.entityList(EpicEntityList.class).create().entities(Collections.singleton(
                new EpicEntityModel("rootepic", workItemRootEntityModel, Phases.EpicPhase.NEW)
        )).execute().iterator().next();
        final FeatureEntityModel featureEntityModel = octane.entityList(FeatureEntityList.class).create().entities(Collections.singleton(
                new FeatureEntityModel("feature1", Phases.FeaturePhase.NEW).setParent(rootEpic)
        )).execute().iterator().next();
        final DefectEntityList defectEntityList = octane.entityList(DefectEntityList.class);
        final DefectEntityModel defect = defectEntityList.create().entities(Collections.singleton(
                new DefectEntityModel("defect", featureEntityModel, Phases.DefectPhase.DEFERRED)
        )).execute().iterator().next();
        defect.setSeverity(Lists.Severity.HIGH).setDescription("this has been updated");
        defectEntityList.update().entities(Collections.singleton(defect)).execute();

Please note that due to the way that the Octane REST API works only a limited number of fields will be automatically retrieved from the server. Due to this the addFields method should be used to explicitly state which fields should be retrieved. You can see more information here

Logging

The SDK uses SLF4J internally for all logging. This means that the users of the library can control the logging framework used for the implementation. The easiest way is to add a maven dependency to such an implementation (slf4j-simple, log4j, logback etc.)

Example

    <dependencies>
        <dependency>
            <groupId>com.microfocus.adm.almoctane.sdk</groupId>
            <artifactId>sdk-src</artifactId>
            <version>24.3</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
            <version>1.7.25</version>
        </dependency>
    </dependencies>

This will make the sdk use log4j as an slf4j implementation, configuring a log4j.xml in your project will also take effect on the sdk.

Space and Workspace admin

By various combinations of not setting the space id, or setting the space id and not the workspace id, the admin of those spaces can be accessed. See the TestSharedSpaceAdmin and TestWorkSpaceAdmin tests for examples of how these can be used.

Currently the admin sections are not available using generated entities - but the CRUD functions are available

What's New

• CE 24.3

  • Generate entities plugin now supports fields that point to generic lists (e.g. EntityIconEntityModel.conditionFieldValue)

• CE 24.1.5

  • Fixed vulnerabilities from jetty

• CE 24.1.4

  • Added support for SessionId authentication

• CE 24.1.3

  • Fixed vulnerabilities from org.json and google-http-client

• CE 24.1.2

  • Fixed extracting facts from business rules
  • Improved parsing of date fields
  • Replaced hardcoded unsupported characters check with java.lang.Character API (Vanilla SDK)

• CE 24.1.1

  • ArrayFieldModel can now be used for fields containing generic JSONArray

• CE 24.1

  • Object field model is now sent as JSON instead of String

• CE 23.4

  • Added support for operating with business rules (see README)

• 23.3.1

  • Fixed bug related to JSON Array response parsing
  • Fixed DateFieldModel bug related to the clear method
  • Updated licenses

• 23.3.0

  • Query is now sent as an encoded string so that special characters are now supported for api data filtering
  • Fixed bug related to code generation based on ALM Octane entities containing special characters
  • Updated org.json to version 20230227

• 16.1.100.3

  • Added new clearField method on generated models which sets the field value to null instead of removing it

• 16.1.100.2

  • Added Query.NULL and Query.NULL_REFERENCE values for filtering not populated fields

• 16.1.100.1

  • Added a new OctaneHttpClient using Jetty, for HTTP/2 support

• 16.1.100

  • Fixed vulnerability by removing transitive dependency for apache-commons-text

• 16.0.400.1

  • Fixed bug related to session cookie collision on parallel requests

• 16.0.400

  • Fixed list entity bug related to pagination
  • Updated google client version to 1.42.0
  • Support multiple attachments in single requests

• 16.0.300

  • Fixed ClassCastException on EmptyFieldModel Issue 133
  • Replaced / with _ in list name generation Issue 124
  • Added OctanePartialException message Issue 132

• 15.1.60

  • Added support for Basic Authentication. If the Octane space parameter SUPPORTS_BASIC_AUTHENTICATION is set to true,
    when creating the Octane object, the class SimpleBasicAuthentication can be used in order to connect to Octane via basic authentication.

• 15.1.40

  • EntityModel now has a toString() for easier logging. Enhancement 102
  • Added possibility to add a header to a single request and extend the current url. Enhancement 104
  • Added a way of setting:
    • the connection and read timeouts Enhancement 101,
    • the HttpTransport Enhancement 103
    • a boolean for accepting self-signed ssl certificates 64

• 15.1.20

  • Enable entity generation using the tech preview api mode. Adds more entities and fields
  • Manipulate test scripts using the SDK. See TestExample in the sdk-usage-examples module for more information
  • Able to get the context for space and workspace admins
  • FIX for Bug 97. Logging uses the slf4j paradigm for formatting strings
  • Internal fix to enable OctaneClassFactory too be set by the Builder

• 15.0.40.1

  • FIX for Bug 79. User defined lists are now created with a _ in front of the package name when using the generator to ensure Java convention is followed

• 15.0.40

  • Get the server version using the SiteAdmin API. This matches the serverurl/admin/server/version REST call
  • The way that the API mode can be set has changed. It is now easier to set the technical preview by using the APIMode interface and default classes. Other modes can be set as well. See Javadoc for more details

• 15.0.20

  • Lists are now created in their own classes. The package name is based on the list's logical name. This was necessary due to non-unique list names. In order to try to preserve backward compatibility the actual class name should be the same but are now in separate packages. That means that in the best case only imports need to be changed.
    • In addition to this list names need to conform to Java standards. If a list name starts with an illegal character such as a number then the name will start with a '$'.
  • Due to a bug on Octane - the run_history entity's ID is marked as an integer as opposed to a string. This causes an issue in the entity generation. Therefore the run_history entity will not be generated until this bug is fixed in Octane

• 12.60.41

  • Float fields now supported via FloatFieldModel if they are enabled on the Octane server.
  • Change to maven group id: com.microfocus.adm.almoctane.sdk

• 12.60.21

  • Fixed bug where etag header was not being set properly
  • Fixed null pointer if the sdk encountered un-parsable entity JSON
  • Octane.OctaneBuilder now has constructor that allows passing a specific instance of OctaneHttpClient for the Octane object

• 12.55.32

  • Octane server errors will not be properly parsed into an ErrorModel object
  • ErrorModels from OctaneExceptions will now also contain the HTTP status code
  • Added ObjectFieldModel for fields that contain JSON content but do not represent a relation to another entity model
  • Added helper methods for comparing entity models

• 12.55.8

  • Fixed various bugs related to entity generation
  • Fixed bug related to http session handling
  • HTTP proxy settings are now logged

• 12.55.5

  • Added Entity Generation
  • Added Etag support. If the server resource has an etag then it is cached by the SDK for as long as the process is alive. The cache is destroyed once the process ends
  • All entity ids are now Strings. IDs are strings according to the metadata but there was some code that assumed IDs were integers
  • Entity collection now returns an OctaneCollection which is an extension of Collection. This includes important metadata about the returned collection:
    • The total count of entities (not including the current limit)
    • Whether the number of requested entities exceeds the total count of entities.
  • Added support for IN and BTW for queries
  • SDK extension moved, now part of the sdk repository,
  • SDK now uses SLF4J internally for all logging

  See the ALM Octane documentation for more information

Disclaimer

Certain versions of software accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. This software was acquired by Micro Focus on September 1, 2017, and is now offered by OpenText. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.