Test Management for Jira plugin API

If you are using the ALM Octane – Test Management for Jira plugin version 1.0.8.2 or later, you can use the following API resources in your Jira on-premises environment.

Login

To use the ALM Octane Test Management Jira Plugin REST API you need to be authenticated. For that you can use basic auth or session cookie.

Basic auth:

For every request add the header:

Authorization: Basic <username: password >

Note: <username: password> has to be base64-encoded

Cookie auth:

You can get the cookie by using the following URL, providing a JSON with the username and password:

POST <JIRA_BASE_URL>/rest/auth/1/session 
{ 
	"username" : "<username>",
	"password" : "<password>"
}

Use the provided cookies on subsequent requests.

Back to top

Proxy Settings

Add proxy settings:

PUT <JIRA_BASE_URL>/rest/octane-admin/1.0/proxy

{

"host": "<PROXY_HOST>",

"port": "<PROXY_PORT>",

"username": "…",

"password": "…",

"nonProxyHost": "…"

}

The nonProxyHost represents the list of hosts for no proxy use, separated by the '|' character. The wildcard '*' can be used.

Status 200 (OK) is returned if the proxy settings were added successfully.

Get proxy settings:

GET <JIRA_BASE_URL>/rest/octane-admin/1.0/proxy

Returns a JSON with the proxy configuration settings, with the following format:

{

"host": "…",

"port": "…",

"username": "…",

"password": "…",

"nonProxyHost": "…"

}

Back to top

Space Configuration

Test Space Connection:

POST <JIRA_BASE_URL>/rest/octane-admin/1.0/spaces/test-connection

As data, you need to provide a JSON with the space configuration that you want to test the connection for.

You can either test the connection for an already defined space connection, in which case you need to provide the space configuration ID in the JSON, or test the connection to a new location.

For example, testing the connection to an already defined space configuration:

{

"id": "<spaceConfigurationId>",

"location": "http://localhost:9090/dev/ui/?p=1001/1002",

"clientId": "<username>",

"clientSecret": "<password>"

}

You can send the request without the ID if you want to test the connection before creating the space configuration:

{

"location": "http://localhost:9090/dev/ui/?p=1001/1002",

"clientId": "<username>",

"clientSecret": "<password>"

}

The request will check if the location specified is accessible with the credentials <username> and <password> and also validate the uniqueness of the space configuration name and location.

Status 409 (Conflict) is returned in case the connection could not be established or the validations failed, along with an error message.

Status 200 (OK) is returned in case of a successful connection.

Add new space configuration:

POST <JIRA_BASE_URL>/rest/octane-admin/1.0/spaces

As data, you need to provide a JSON with the name of the configuration, base URL of the ALM Octane server, and the client ID and client secret used to login. For example:

{

"name": "local",

"location": "http://localhost:8080/dev/ui/?p=1001/1002",

"clientId": "<username>",

"clientSecret": "<password>"

}

The location represents the URL of your ALM Octane application.

For example: http://myServer.myCompany.com:8081/ui/?p=1001

Note:  

  • The server base URL and the shared space ID are mandatory for the location. Everything that comes after the shared space ID will be ignored.
  • You cannot have two space configurations with the same name or location.

To validate the connection, use the REST call for testing the connection (see above).

Get space configuration:

GET <JIRA_BASE_URL>/rest/octane-admin/1.0/spaces

Returns the configuration of all defined spaces in a JSON format.

Update space configuration:

PUT <JIRA_BASE_URL>/rest/octane-admin/1.0/spaces/{space_configuration_id}

Provide the updated space configuration JSON, as in the example below:

{

"name": "local",

"location": "http://localhost:9090/dev/ui/?p=1001/1002",

"clientId": "<username>",

"clientSecret": "<password>"

}

Returns the updated space configuration in JSON format.

Delete space configuration:

DELETE <JIRA_BASE_URL>/rest/octane-admin/1.0/spaces/{space_configuration_id}

Returns status 200 (OK) if successful, 404 (Not Found) if the space configuration ID doesn’t exist.

Back to top

Workspace Configuration

Get all workspace configurations

GET <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces

Returns a JSON array with all defined workspace configurations.

Get workspace configuration

GET <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces/{workspaceConfigurationId}

Returns a JSON with the workspace configuration for the specified {workspaceConfigurationId}.

Add workspace configuration

POST <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces

JSON body example:

{

"spaceConfigId": "<space_configuration_id>",

"workspaceId": "1002",

"workspaceName": "default_workspace",

"octaneUdf": "jira_udf",

"jiraIssueTypes": ["Bug", "Epic","Story"],

"jiraProjects": [“<JIRA_PROJECT_KEY>"]

}

The data provided will be validated. The workspace needs to be active, part of the given space and not already used. Each Jira project can be selected for one ALM Octane workspace only.

Status 200 (OK) will be returned in case the request is successful, along with the configuration JSON containing all the fields.

Response body example:

{

"id": "<workspace_configuration_id>",

"spaceConfigId": "<space_configuration_id>",

"spaceConfigName": "local",

"workspaceId": "1002",

"workspaceName": "default_workspace",

"octaneUdf": "jira_udf",

"octaneEntityTypes": [ "User Story", "Defect", "Feature"],

"jiraIssueTypes": ["Epic","Bug","Story"],

"jiraProjects": [“<JIRA_PROJECT_KEY>"]

}

The octaneEntityTypes list will be autocompleted with the supported entity types from ALM Octane that have the specified UDF in the given workspace. If no entities are found, an error message will be returned and the request will have status 409 (CONFLICT).

Update workspace configuration

PUT <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces/{workspaceConfigurationId}

Provide updated JSON, as in the example below:

{

"workspaceId":"1002",

"workspaceName":"default_workspace",

"spaceConfigId":"78b8c1b9-353b-4f6d-bbae-937280386f10",

"spaceConfigName":"local_rest",

"octaneUdf":"jira_udf",

"jiraIssueTypes":["Bug","Epic","Task"],

"jiraProjects":["“<JIRA_PROJECT_KEY>"]

}

Status 200 (OK) will be returned in case the request is successful, along with the updated configuration JSON containing all the fields. Note that an update request will refresh the octaneEntityTypes list.

Delete workspace configuration:

DELETE <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces/{workspaceConfigurationId}

Returns status 200 (OK) if successful.

Back to top

Other Helpful Resources

Get supported ALM Octane types

The following request will provide a list with the ALM Octane entity type names that are supported and contain the udf provided in the query parameter for the given space and workspace:

GET <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces/supported-octane-types?space-config-id={spaceConfigurationId}&workspace-id={workspaceId}&udf-name={udf_name}

Example of response: ["Defect", "Feature", "User Story"]

Get possible user-defined fields for Jira

The following request will return the name of the ALM Octane user-defined fields that contain the word “jira” for the space and workspace provided in the query parameters.

GET <JIRA_BASE_URL>/rest/octane-admin/1.0/workspaces/possible-jira-fields?space-config-id={spaceConfigurationId}&workspace-id={workspaceId}

Example of response: ["jira_udf"]

Back to top

See also: