DEV Community: Mecomis

Working with Helix ALM REST API Part 6: Automated Testing

Mecomis — Mon, 17 Mar 2025 09:47:28 +0000

Today we'll conclude our series of posts focusing on various features from Perforce's Helix ALM REST API. Today's feature is about working with a CI/CD (continuous integration/continuous delivery) pipeline for automated testing and integrating it with the API. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The Helix ALM REST API has several endpoints that developers can use for interfacing with their organization's Helix ALM instance. The wide variety of endpoints provide many possibilities for developers to create tools or scripts to aid in their organization's workflow, with few limitations.

The REST API is available at:

https://{organization}:{port}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{organization}:{port}

where {organization} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the server that is running the Helix ALM instance.

Automated Testing

Helix ALM provides integration with CI/CD pipelines, allowing organizations to have full traceability between their builds and tests, and associating the results back to test cases. The system offers two primary methods for submitting build and test results: the Helix ALM Test Management plugin for Jenkins and a REST API for other testing tools and environments. For this article, we will focus on the latter.

At the core of Helix ALM's automated testing framework are automation suites, which serve as containers for grouping related automated tests. These suites are logical organizations of a set of tests based on a common factor. The system supports both automatic and manual association of test results with test cases. Achieving this association using the REST API is a multi-step process.

First, we need to create an automation suite, specifying the script ID prefix and any test cases we want to associate. It's also possible to associate the test cases later in a separate request to the

/{projectID}/automationSuites/{automationSuiteID}/testCases

endpoint. A successful creation will return an HTTP 201 response along with the created automation suite in the response body.

With our automation suite created, we can now run our automated tests for a build and submit the results to the REST API. We need to send the results to the

/{projectID}/automationSuites/{automationSuiteID}/submitBuild

endpoint, where the {automationSuiteID} is the ID we received in the response when we created the automation suite. The structure of the data that the endpoint is expecting is an Automation Build object with the following name-value pairs:
Number (string)

Description
Branch
Start date
Duration
External URL
Results, array of

Where a Result object has its own name-value pairs:

Name
Unique name
Status
Device
Manufacturer
Model
OS
OS version
Browser
Browser version
Start date
Duration (milliseconds)
External URL

There is one more name-value pair named "properties" which accepts a JSON object of any name-value pair. This is for unique properties from the build process that do not match the REST API's structure, and can be included as part of the Automation Build or Result objects. The first name-value pair "name" is where we will associate the test from the build with our Helix ALM test case by appending the automation suite's script ID prefix to the test case's number. The unique name is the name of the test from the build process.

The "status" value is a specific JSON object that the REST API expects. It's comprised of ID and label values. The ID and label follow the following convention:
1 => Passed
2 => Failed
3 => Skipped
4 => Blocked
5 => Unknown

Example

Let's see how we can implement the above description of automation suites into a simple example.

An automation suite item first needs a name, like "Alpha Tests" or "Final Tests"; then it needs a description; a true or false value if it is active; a list of test cases that are associated with the suite; a list of owners; and finally the script ID prefix, which can be like "Alpha-" or "Final-".

Regardless of the programming language of choice, we want something, when serialized, to represent the following JSON object:

{
  "automationSuitesData": [
  {
    "name": "Example Test Suite",
    "description": "Automation suite for grouping our automated tests.",
    "active": true,
    "scriptIDPrefix": "EX-",
    "owners": [
      {
        "lastName": "John",
        "firstName": "Doe",
        "id": 135,
        "username": "jdoe"
      },
      …
    ],
    "testCases": {
      "testCasesData": [
        {
          "id": 1,
          "number": 1
        },
        …
      ]
      }
    }
  ]
}

With this we attach it to the body of our POST request and send it to the /{projectID}/automationSuites endpoint. Upon success, we will receive a response along with some JSON data in the body. What we need to record are the ID, associated test cases, and script ID prefix values.

{
"automationSuitesData": [
  {
    "id": 135,
    "name": "Example Test Suite",
    "description": "Automation suite for grouping our automated tests.",
    "active": true,
    "scriptIDPrefix": "EX-",
    "testCases": {
      "testCasesData": [
        {
          …
        }
      ]
     …
    }
  ]
}

Either the build process triggers the creation of an automation suite when it is completed or the automation suite is created before the build process begins, and this will depend on the individual organization. Nonetheless, the outcome is the same because we begin the process of associating the results.

The build process and the results of it will depend on what technology the organization is using. For this portion of the example, we will use a dummy test output for our automation suite process.

Test Report
Start Date: 2025–01–01T14:30:00Z

Operating System: Windows 10 Pro (Version 21H2)

Test Suite: TC-1
Test Case: testValidLogin
Duration: 1.5 seconds
Result: Passed

Test Suite: TC-2
Test Case: testSearchWithInvalidKeyword
Duration: 1.8 seconds
Result: Failed
Error Message: Expected product count: 0 but found: 3
Stack Trace:
at com.example.tests.ProductSearchTests.testSearchWithInvalidKeyword(ProductSearchTests.java:42)

This dummy test report includes test cases 1 & 2, labelled as "test suite" in the dummy report. Our recently created automation suite should already have these test cases associated with it, if not, then we need to add them by making a POST to the

/{projectID}/automationSuites/{automationSuiteID}/testCases

endpoint.

We now start the process of converting the test report into an automation build that can be accepted by the REST API. There will be a number of assumptions going forward and we will note them when clarity may be needed. First, we are assuming that the test report has already been parsed into a data structure that we can use. For this example, we will use C# and will map the dummy test report results to a list of Result records using a function that takes a "test suite" from the report and creates the appropriate Result. Recall that an Automation Build is an item with an array of Result items.

public List<Result> MapTestSuite(TestSuite testSuite) =>
  testSuite.TestCases.Select(testReportCase =>
  {
    return new Result
    {
      Name = ScriptIdPrefix + testReportCase.Number,
      UniqueName = testReportCase.Name,
      Duration = testReportCase.Duration,
      OS = testSuite.OS,
      OsVersion = testSuite.OsVersion,
      StartDate = testSuite.StartDate,
      Status = ConvertTestResult(testReportCase.Result),
      Properties = new List<ResultProperty>
      {
        new() {
          Name = "ErrorMessage",
          Value = testReportCase.Error.ErrorMessage
        },
        new() {
          Name = "StackTrace",
          Value = testReportCase.Error.StackTrace
        }
      }
    };
}).ToList();

For simplicity, we are assuming that the duration has been converted to milliseconds.

The "scriptIDPrefix" comes from when we created the automation suite, and it is needed to associate the test case with the result. Our test report calls the test case "test suite" in this example. We assume that the "TC-" prefix is removed when we are accessing the "Number" property, as shown on line 5.

If you are unfamiliar with C#, line 2 uses the "Select" extension method to project each element of a sequence into a new form by incorporating the element's index.

For line 12, we are assuming that the function "ConvertTestResult" converts the result of the test case to the "status" JSON object that the REST API is expecting. It follows the same pattern as mentioned above, where the ID: 1 => Passed, 2 => Failed, etc.

For the Properties object, the items are stored in a simple list, and we are ignoring any checks if the test case from the report contains an error message or not. There can be additional properties from the test report that require their own entry; for example, "failure type" or "failure value".

With the results created for the automation build, we can continue and add the remaining data: number, description, branch, start date, and the external URL where the test was run. All these values will depend on your individual organization. The only value required by the REST API is number, which it expects as a string and not a numeric value.

Serializing the data we should get something like:

{
  "description": "Example build",
  "branch": "Example Branch",
  "startDate": "2025–01–01T07:58:33.074Z",
  "duration": 533432,
  "number": "2",
  "externalURL": "https://cicd.example.com:8080/job/ExampleJob/2",
  "properties": [
    {
      "name": "Additional Property",
      "value": "Example value"
    }
  ],
  "results": [
    {
      "name": "EX-1",
      "uniqueName": "testValidLogin",
      "status": {
        "id": 1
      },
      "device": null,
      "manufacturer": null,
      "model": null,
      "os": "Windows 10",
      "osVersion": "21H2",
      "browser": null,
      "browserVersion": null,
      "startDate": "2025–01–01T07:58:33.074Z",
      "duration": 1500,
      "externalURL": null,
      "properties": []
    },
    {
      "name": "EX-2",
      "uniqueName": "testSearchWithInvalidKeyword",
      "status": {
        "id": 2
    },
    "os": "Windows 10",
    "osVersion": "21H2",
    "startDate": "2025–01–01T07:58:33.074Z",
    "duration": 1800,
    "properties": [
      {
        "name": "Error Message",
        "value": "Expected product count: 0 but found: 3"
      },
      {
        "name": "Stack Trace",
        "value": "at com.example.tests.ProductSearchTests.testSearchWithInvalidKeyword(ProductSearchTests.java:42)"
      },
     ]
    }
  ]
}

Now we attach it to the body of the POST request and send it to the

/{projectID}/automationSuites/{automationSuiteID}/submitBuild

endpoint. Upon success, we will receive a 201 response along with a
builds data object containing the ID of the build we just submitted.
Conclusion
And that's all there is to it. The difficulty comes with mapping the test report produced by your CI/CD process. With proper planning and understanding of both your testing framework and the Helix ALM REST API structure, this integration can provide invaluable traceability between your development process and your test management system.

This concludes our series about discussing various aspects about the Helix ALM REST API, we hope it has helped explain how things work and clarified any uncertainty. If you need help creating a solution for this process or need support with Helix ALM, contact us at Mecomis and we'll gladly help.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

Working with Helix ALM REST API Part 5: Test Steps Structure

Mecomis — Fri, 14 Mar 2025 11:14:42 +0000

Today we’ll be continuing our series of posts focusing on various features from Perforce’s Helix ALM REST API. Today’s feature is about the structure of test steps for test cases. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The Helix ALM REST API has several endpoints that developers can use for interfacing with their organization’s Helix ALM instance. The wide variety of endpoints provide many possibilities for developers to create tools or scripts to aid in their organization’s workflow, with few limitations.

The REST API is available at:

https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the machine that is running the Helix ALM instance.

Tests Steps Structures

The Helix ALM REST API has two different types of test step objects: basic and detailed. Both are quite similar with a few key differences that we will go into depth on in the test case step structure section. Finally, we will look at manual test runs and the structure of the JSON object that the REST API provides.

Test Case Step Structure

Common Object Structures

The general structure of the test case step shares a common base that resembles the following:

steps (TestCaseStepContainer object):  
{  
  self: string 
  stepsData (TestCaseStepData object):  
  {  
    modifiedToCorrectSyntax: boolean 
    type: enum [ basic, detailed ] 
    basic: array of TestCaseBasicStepData objects 
    detailed: array of TestCaseDetailedStepData objects 
  }  
}

Here is where the structure diverges, depending on the type of test case step data object that it is. Before we investigate the basic and detailed test case step data objects, let’s examine a few additional objects that are common to both basic and detailed test case steps.

FileReference Object Structure

fileReference:
{
  id: int64
  referenceType: enum [attachment, sourceFile ]
}

ExpectedResult Object Structure

expectedResult: 
{ 
  text: string 
  fileReferences: array of FileReference objects 
}

SharedStep Object Structure

shared:  
{ 
  testCaseID: int64 
  link: string 
}

Basic

First up is the TestCaseBasicStepData object, which represents test cases that have their view mode property set to basic to text.

The TestCaseBasicStepData object resembles:

{
  type: enum [comment, step, expected, result, fileReferences, shared ]
  comment: string
  expectedResult: ExpectedResult object
  fileReferences: array of FileReference objects
  shared: SharedStep object
  step: TestCaseBasicStep object
}

Expanding on the TestCaseBasicStep object, we see that it resembles:

step:
{
  number: int64
  text: string
  stepRows: array of TestCaseBasicStepRow objects
}

Drilling down further for the stepRows name and examining the TestCaseBasicStepRow object, we see that it is comprised of:

{
  type: enum [ expectedResult ]
  expectedResult: ExpectedResult object
}

Detailed

Next is the TestCaseDetailedStepData object, which represents test cases with detailed grid view set on the view mode property.

The TestCaseDetailedStepData object resembles:

{
  type: enum [ comment, step, shared ]
  comment: string
  shared: SharedStep object
  step: TestCaseDetailedStep object
}

Like the basic test case step, the detailed object contains a further object for the test case step. It resembles:

step:
{
  number: int64
  text: string
  stepRows: array of TestCaseDetailedStepRow objects
}

The TestCaseDetailedStepRow is similar to the TestCaseBasicStepRow. It resembles:

{
  type: enum [ expectedResult, stepNote ]
  expectedResult: ExpectedResult object
  stepNote: string
}

Manual Test Run Step Structure

Testers can enter results (Pass, Failed, or Undetermined) on each manual test run step in Detailed Grid View, but not in Text View or Grid View.

The manual test run step object mostly resembles the same structure as the test case step one but with a few key differences.

First, all objects follow the same naming pattern but are renamed to TestRun–. Test runs derived from basic test cases have some additional data that will be explored below. In addition, since there is a lot of overlap with test cases, we will exclude values that were shown in the previous section.

TestRunStepsData object:

{
  basic: array of TestRunBasicStepData [
  {
    type: enum [ comment, step, expectedResult, fileReferences, problemStatement ]
    expectedResult: TestRunBasicExpectedResult object
    {
      completed: boolean
      …
    }
    problemStatement: string
    …
  } ]
  detailed: array of TestRunDetailedStepData [
  {
    step: TestRunStep object
    {
      stepRows: array of TestRunStepRow objects [
      {
        type: [ expectedResult, stepNote, testCaseStepNote, problemStatement ]
        problemStatement: string
        testCaseStepNote: string
        …
      } ]
      stepResult: TestRunStepResult object
      {
        dateTime: DateTime
        result: enum [ passed, failed, undetermined ]
        user: User object
      }
      actualResult: ExpectedResult object
      …
    }
  } ]
}

As we can see, there are quite a few differences, but, at the same time, quite a few similarities too. Keep the following in mind when working with manual test runs:

Step results are only returned if they have a value. To add a step result, you must add it to the step and update the manual test run. You cannot delete a step result.
Step notes must be added before expected results.
Step text is read-only and cannot be edited. However, some data can be manipulated depending on the test run type. Consult the table below.

Test Run type	Available editing actions
Text View (basic)	None; read-only.
Grid View (basic)	Change the “completed” property.
	Add, edit, & delete “problemStatement”
Detailed Grid View (detailed)	Add, edit, delete “problemStatement”
	Add, edit, & delete “actualResults”
	Add, edit, & delete “stepNote”[1]
	Add or modify the TestRunStepResult’s “result”

[1] Not to be confused with the “testCaseStepNote”, which is read-only.

Conclusion

In conclusion, the Helix ALM REST API provides a robust and flexible way to interact with test steps in both test cases and manual test runs. By understanding the different object structures for basic and detailed test steps, as well as the nuances between test case steps and manual test run steps, developers can effectively read, write, and manipulate test step data programmatically.

By leveraging the Helix ALM REST API and these test step structures, organizations can build custom tools and integrations to streamline their test management processes. Whether it’s automatically generating test cases, aggregating test results, or synchronizing data with other systems, the possibilities are vast. As always, refer to the official Helix ALM REST API documentation for the most up-to-date and detailed information.

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain the error and response codes that you will run into when using the API. In part 6 we will conclude this series by looking at automated testing.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

Working with Helix ALM REST API Part 4: Error and Response Codes

Mecomis — Fri, 31 Jan 2025 14:24:00 +0000

Helix ALM LogoToday we'll be continuing our series of posts focusing on various features from Perforce's Helix ALM REST API. Today's feature is about the API's error and response codes. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The REST API is available at:

https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the machine that is running the Helix ALM instance.

Error and Response Codes

The Helix ALM REST API has three kinds of response codes, two of which are error codes. Responses may include a JSON object in the body providing additional information. The first kind of response codes has to do with the 200 range of HTTP responses, the second covers client error codes of the 400 range, and the last are server error codes of the 500 range.

Success Codes

200 - Success

The 200 status code indicates that the request was successful. The response returned is unique to the specific request and may contain data or other relevant information. Typically, for a GET or PUT endpoint response, the data is a JSON object with a single item or a list of items. In the case of the search POST endpoint, it is a list of items that match the search query.

For example, the GET endpoint for querying a list of projects returns a JSON object that looks like:

{
  "projects": [
    {
      "id": 1,
      "name": "{project name}",
      "uuid": "{UUID}"
     },
     {
       "id": 2,
       "name": "{project name}",
       "uuid": "{UUID}"
     },
     etc…
  ],
  "projectsLoading": 0
}

PUT requests generally return the status code 200 when updating a list of objects; otherwise, the PUT request returns status code 204 when updating a specific item. The JSON object returned upon updating a list of items is the same list of the items but a reduced object with only a few name/value pairs in each item. An example of this looks like:

{
  "{item types}": [
    {
      "id": XX,
      "number": YYY,
      "tag": "ZZ-ZZZ",
      "self": "https://{organization}:{port}/helix-alm/api/v0/{project id}/{item type}/{id}",
      "ttstudioURL": "ttstudio://{organization}:{port}//{project id}/dfct?recordID={id}",
      "httpURL": "http://{organization}/ttweb/index.html#Default/{project id}/{item type}/{id}/"
    },
    etc…
  ]
}

201 - Success (Created Item)

When a request to create a new item is successful, the API returns a 201 status code. Similar to the 200 code, the response is specific to the request and may include additional details about the newly created item.

An example of this looks like:

{
  "{item types}": [
    {
      "id": XX,
      "number": YYY,
      "tag": "ZZ-ZZZ",
      "self": "https://{organization}:{port}/helix-alm/api/v0/{project id}/{item type}/{id}",
      "ttstudioURL": "ttstudio://{organization}:{port}//{project id}/dfct?recordID={id}",
      "httpURL": "http://{organization}/ttweb/index.html#Default/{project id}/{item type}/{id}/"
    },
    etc…
  ]
}

204 - Success (Updated Item)

If an item is successfully updated through an API request, a 204 status code is returned. In this case, no additional information is provided in the response.

206 - Partial Success

A 206 status code signifies that the request was partially successful, this error may occur when a PUT or POST request with multiple items has a problem with one item, but changes to or creation of other items are successful. The response contains details about which parts of the request succeeded and which failed.

The response data is an errorResponseArray object, comprised of two parts: the error array and the items array of the updated or created items.

An example where the Steps field is missing a formattedString property looks like:

{
  "errors":[
    {
      "message": "The Steps field must have a formattedString property.",
      "statusCode": 400,
      "code": "Bad Request",
      "errorElementPath": "/{item type}/{index in items array}/fields/{index in fields array}"
    }
  ],
  "{item types}": [
    …
  ]
}

Note: the items array is excluded for brevity and resembles the response body from code 201.

Client Error Codes

When a request is unsuccessful, the server will return one of these error codes. The object in the body depends on the nature of the error. Typically, the object consists of an HTTP status code, a description of the code, along with the error message itself. Some error codes may include the path to the element that caused the error.

400 - Bad Request

When a request is missing required parameters or contains invalid information, the API returns a 400 status code. This indicates that the client needs to modify the request before sending it again.
An example of the error response object returned looks like:

{
  "message": "Validation errors. Invalid parameter (issues): Value failed JSON Schema validation. Expected type string but found type integer",
  "statusCode": 400,
  "code": "Bad Request",
  "errorElementPath": "/issues/0/fields/1/label"
}

The "errorElementPath" value indicates the location of where the offending data was incorrect in the request object.
In our example the error path is "/issues/0/fields/1/label". "issues" is the item type; 0 is the index of the issue in the zero-based array object; "fields" is the object where the error occurred, in the second field object (denoted by 1), at the label value.

401 - Unauthorized

A 401 status code means that access is denied due to incorrect or unrecognized credentials, such as an invalid username/password combination or an expired access token.

{
  "message": "Access denied",
  "statusCode": 401,
  "code": "Unauthorized"
}

403 - Forbidden

If a user doesn't have the necessary permissions to perform the requested action, a 403 status code is returned. This could be due to various reasons, such as not having a valid license, not being part of the requested project, or lacking the required security commands.

{
  "message": "You cannot log in to this project.",
  "statusCode": 403,
  "code": "Forbidden"
}

404 - Not Found

When the requested record or resource cannot be found, the API returns a 404 status code.

{
  "message": "No project found with name \"Unknown Project\"",
  "statusCode": 404,
  "code": "Not Found"
}

409 - Conflict

A 409 status code indicates that a conflict occurred while processing the request. This could happen if the record is locked by another user or if the project is locked by an administrator.

{
  "message": "Record is locked for editing by another user.",
  "statusCode": 409,
  "code": "Conflict"
}

429 - Too Many Requests

If a user sends too many requests within a specified rate limiting timeframe, the API may return a 429 status code to prevent abuse or overload.

{
  "message": "The rate limit has been exceeded. Retry in X seconds.",
  "statusCode": 429,
  "code": "Rate limit exceeded"
}

Server Error Codes

These error codes generally indicate an issue on the server side of the Helix ALM REST API.

500 - Internal Server Error

The 500 status code is a generic error indicating that something went wrong on the server side. The error message included in the response may provide more details about the specific issue.

{
  "message": "The server experienced an error handling the request.",
  "statusCode": 500,
  "code": "Internal Server Error",
  "errorElementPath": "/{item type}/{index}"
}

503 - Service Unavailable

When the API server is unavailable or busy, a 503 status code is returned. This could be caused by throttling or a server lock due to high traffic or maintenance.

{
  "message": "The service is currently overloaded.",
  "statusCode": 503,
  "code": "Service Unavailable"
}

Conclusion

Understanding the various response and error codes in the Helix ALM REST API is essential for effective integration and troubleshooting. The API follows standard HTTP status code conventions, with success codes (200–206) indicating successful operations, client error codes (400–429) helping developers identify and fix issues in their requests, and server error codes (500–503) signaling server-side problems. Each response type is accompanied by detailed JSON objects that provide specific information about the operation's outcome or the nature of any errors encountered. By familiarizing themselves with these codes and their associated response formats, developers can build more robust applications that properly handle both successful operations and potential error scenarios when interacting with the Helix ALM platform.

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain the error and response codes that you will run into when using the API. In part 5 we will look at constructing test steps for test cases.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

Working with Helix ALM REST API Part 3: Conventions & Exceptions

Mecomis — Mon, 27 Jan 2025 09:21:38 +0000

Today we'll be continuing our series of posts focusing on various features from Perforce's Helix ALM REST API. Today's feature is about the API's conventions and exceptions. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The REST API is available at:

https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the machine that is running the Helix ALM instance.

API Conventions and Exceptions

Case Sensitivity

The API is case sensitive except for field names in the following areas, which are not case sensitive:

Search parameters
PUT and POST fields array
'fields' parameter that indicates the fields to return (URL parameter and POST search)

What this means in terms of constructing the request is that the URL's search and field query parameter can look like:

/{endpoint}?search=PRODUCT = 'Wysi CRM'
/{endpoint}?fields=sUmMaRy,DESCRIPTION,product

Note: the specified criteria of the search parameter is still subject to case sensitivity.

The fields array in a PUT or POST body is the same as the above example in terms of case insensitivity and applies to the label value in the field object.

"fields": [
  {
    "label": "SUMMARY",
    "string": "New issue from REST API"
  },
  {
    "label": "prOduCt",
    "menuItem": {
      "label": "Activity Professional Suite (APS)"
    }
  }
]

Note: the label of the menu item object is case sensitive.

Date Formatting

Date and date/time values are always specified in ISO 8601 extended format for UTC (GMT) time. For example:

2025–01–01
2025–01–01T00:00:00Z

The Helix ALM REST API returns dates and date/time information in the above format when requested. Serializing dates and date/time depends on the programming language used. In C#, serializing DateTime objects to ISO 8601 is done by default. An example of one such language that does not support the format by default is Python. To achieve this in Python, it requires the use of the datetime's "isoformat()" method.

import json
from datetime import datetime

current_time = datetime.now()
iso8601_string = current_time.isoformat()
json_string = json.dumps({'timestamp': iso8601_string})

Be sure to check the documentation of your chosen programming language to ensure that Datetime objects match Helix's format.

Numbers

Numeric values must be represented in a consistent format regardless of the locale or region where the Helix ALM REST API is being used. Different locales may have different conventions for representing numbers, such as using commas or periods as decimal separators. However, the API expects decimal numbers to always use a period (.) as the decimal separator, regardless of the locale.
Valid:

{
  "decimal": 3.1,
  "id": 1,
  "label": "Decimal Field",
  "type": "decimal"
}

Invalid:

{
  "decimal": 3,1,
  "id": 1,
  "label": "Decimal Field",
  "type": "decimal"
}

Special Characters and Spaces in Field Names

Field names and values that contain spaces or special characters may cause searches to fail and return 400. In order for searches to work properly with these fields, the names and values must include quotes around them.
In terms of the search query parameters in a URL, this looks like:

/{endpoint}?search='Versions Impacted' = '1.0'

Note: for readability, the spaces and special characters are not URL-escaped.

In a POST search, the query would look like:

{
  "search": "'Versions Impacted' = '1.0'",
  "fields": [
    "summary",
    "description",
    "status"
  ],
  "page": 1,
  "per_page": 20,
  "formattedText": true
}

Field names that contain commas are not supported in URL search query parameters. Instead, use the POST search endpoint because JSON supports commas.

Conclusion

Understanding these API conventions and exceptions is crucial for successful integration with the Helix ALM REST API. By following the guidelines for case sensitivity, date formatting, number representation, and handling of special characters, you can avoid common pitfalls and ensure their API requests are properly formatted. Remember to pay special attention to field naming conventions, use appropriate date formats based on your programming language, maintain consistent number formatting regardless of locale, and properly quote fields containing spaces or special characters. When working with complex field names, particularly those containing commas, utilize the POST search endpoint instead of URL parameters. These standards help maintain consistency and reliability across all API interactions.

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain some of the idiosyncrasies of the API. In part 4 we will look at the API's errors and response codes.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

Working with Helix ALM REST API Part 2: Filtering

Mecomis — Wed, 22 Jan 2025 10:44:04 +0000

Today we'll be continuing our series of posts focusing on various features from Perforce's Helix ALM REST API. Today's feature is about using filters to limit the number of items returned by a request. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The REST API is available at:
https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:
https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:
../Perforce/Helix ALM/helix-alm-rest-api/config/config.json
on the machine that is running the Helix ALM instance.

REST API Features

Filtering

When throughput or bandwidth is an issue, or a subset of items is needed, the Helix ALM REST API allows calls to pass a set of query parameters to return a limited amount of items.

Fields

The fields parameter returns only the specified fields back with the items. The parameter is an array of strings and comma separated. The fields parameter is included after the URL of the endpoint.
An example looks like:
…/issues?fields=Status,Summary,Description
Here we are returning only the fields "Status", "Summary", and "Description" with each Issue item. If a field has a space then it must be wrapped in single quotes, e.g. 'Has Attachments'.
Lists of fields can be gotten from the Fields endpoints,
/{projectID}/configs/fields/{fieldItemType}/customFields
and
/{projectID}/configs/fields/{fieldItemType}/systemFields
where {fieldItemType} is one of the following:

document fields
issue fields
requirement fields
test case fields
test run fields
test variant fields

Search

The search parameter queries the API for items that match the specified criteria. The parameter is a string of fields with search operators and the search value. The search parameter is included after the URL of the endpoint.
Let's look at an example.
…/testCases?search=Summary CONTAINS 'text in summary'
This example searches for test case items where the summary field contains the specified text. To chain multiple search terms together a logical operator of "and", "or", or "not" needs to be used.
For example:
…?search=Summary CONTAINS 'text in summary' AND Status = 'Open'

This example will look for items that contain the specified text in the summary field and also have the "Open" status. More detail about the search operators below. The logical operator is case-insensitive.
It's important to note that a search query must be properly encoded for the URL, with the following characters escaped with their percent sign values:

/ ? : @ - . _ ~ ! $ & ' ( ) * + , ; =

Taking our previous example, the query now becomes:

…?search=Summary%20CONTAINS%20%27text%20in%20summary%27%20and%20Status%20%3D%20%27Open%27

Be careful escaping the initial '=' after search as this is needed to indicate the start of the search query, and any subsequent '&' symbols for combining URL parameters, such as 'search=…&fields=…'

Paging

Paging can be used to reduce the amount of items returned per request. By default, the API returns 300 items per page unless the "per_page" parameter is set. The page parameter is used for navigating between the pages and fetching the next batch of items.
In the response object, there is an additional section with paging information.
The paging object looks like:

"paging": {
  "page": {page number},
  "pageLimit": {item limit per page},
  "totalCount": {total items},
  "totalPages": {total pages},
  "links": [
    {
      "ref": "self",
      "href": "{url}",
      "method": "GET"
    },
    {
      "ref": "first",
      "href": "{url}",
      "method": "GET"
    },
    {
      "ref": "last",
      "href": "{url}",
      "method": "GET"
    },
    {
      "ref": "next",
      "href": "{url}",
      "method": "GET"
    }
  ]
}

Page number is the current page number of the response. Page limit is the number of items per page. Total count is how many items there are in total. Total pages is how many pages there are in total.
The page and per_page parameters are included in the query. An example of the query in the URL looks like:
…?page=1&per_page=10

Operator syntax

There are three logical operators and ten comparison operators for constructing a query.
The logical operators are: "and", "not", and "or".
The comparison operators are:

EQUALS or =
This operator looks for an exact match of the value from the specified field

NOT EQUALS or !=
A combination of the logical "not" and the equals comparison operator.

GREATER or >
Applies to numeric and date-date/time fields

GREATER_EQUAL or >=
Applies to the same fields as GREATER

LESS or <
Applies to the same fields as GREATER

LESS_EQUAL or <=
Applies to the same fields as GREATER

IN or :
Applies to lists, folder, and number fields.
Syntax is: Field IN ('value-1', 'value-2'), equivalent to Field = 'value-1', or Field = value-2.

IN_RECURSE or :?
Performs a recursive comparison in folders.

CONTAINS or ~
Applies to text only fields for a case-insensitive comparison of the supplied string value with the specified field.

CONTAINS_CASE or ^
Applies to text only fields for a case-sensitive comparison of the supplied string value with the specified field.

In addition to these operators, Boolean values are "true" and "false".

For menu fields that have not been assigned a value, the value "NOT_SET" can be used, e.g. Product = NOT_SET.

Conclusion

The Helix ALM REST API provides developers with powerful and flexible ways to interact with their Helix ALM instance through various filtering mechanisms. By utilizing fields, search parameters, and paging options, developers can efficiently retrieve and manage data while optimizing performance. The API's comprehensive set of operators - including logical, comparison, and specialized operators for different data types - enables precise querying capabilities. This flexibility, combined with proper URL encoding and pagination handling, makes the API a robust tool for integrating Helix ALM into an organization's development workflow.

Whether developers need to retrieve specific fields, search for particular items, or manage large datasets through paging, the API provides the necessary functionality to create effective tools and automation scripts.

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain filtering with the API. In part 3 we will look at the API's conventions and exceptions.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

Working with Helix ALM REST API Part 1: Authentication

Mecomis — Mon, 20 Jan 2025 11:20:20 +0000

Today we’ll be starting a series of posts focusing on various features from Perforce’s Helix ALM REST API. Today’s feature is about authenticating a client. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The REST API is available at:

https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the machine that is running the Helix ALM instance.

REST API Features

Authentication

There are several ways to authenticate with the REST API. However, to first make any requests the user must belong to a security group that has Allow Login via SOAP enabled in order to use the API. The RBAC (role-based access control) for the security group and user will depend on the your organization, but for this series we will be assuming that there are no restrictions on what the security group can access. It is also recommended to create an API key for the user, but it is not strictly necessary for authentication. If the API key is created, note it down somewhere because the key’s secret is only shown once. For both the security group and API key, an administrator must create these in the Helix ALM client application.

Basic Authentication

Basic authentication is done with the user’s username and password and attached in the request header. The value of the username and password must be Base64 encoded and conform to:

Authorization: Basic username:password

API Key Authentication

Key authentication is similar to basic authentication but instead of including username and password in the header, the API key is sent instead. The value for the authorization header must conform to:

Authorization: ApiKey apiKey:apiSecret

Access Token

Regardless of which authentication method is chosen, all endpoints will require an access token — the only endpoints which do not require an access token are the projects and the token endpoints.

To receive the access token, make a GET request to the endpoint:

https://{API URL}/helix-alm/api/v0/{projectID}/token

The project ID can be gotten from the /projects endpoint. Alternatively, the project name may be used instead but if there are spaces in the project’s name then these must be URL escaped.

The response from the REST API is an access token object, shown below:

{
  "tokenType": "Bearer",
  "expiresOn": "2000–00–00T00:00:00Z",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5… "
}

The access token then needs to be included in the Authorization header with “Bearer” preceding the value.

GET /helix-alm/api/v0/{ProjectID}/{Endpoint} HTTP/1.1
> Host: {Your host}
> accept: application/json
> Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5...

In C#, setting the access token to the header might look like:

private void SetRequestAccessToken(ref HttpRequestMessage request, AccessToken accessToken)
{
  string authorization = $"Bearer {accessToken.AccessToken}");
  request.Headers.Add("Authorization", authorization);  
}

Server Certificate Validation Callback

When any request is made to the Helix ALM REST API it will return a response with an SSL certificate. By default, it is a self-signed certificate that is created by the API the first time the server is launched. If a non-default certificate is used, then the configuration file must be modified to reflect this choice. This setting is found in the config file.

How the program interfacing with the API handles the certificate callback is highly dependent on the programming language chosen. For our examples, we will ignore validation for now.

In C# that might look like:

HttpClientHandler handler = new HttpClientHandler();
handler.ClientCertificateOptions = ClientCertificateOption.Manual;
System.Net.ServicePointManager.ServerCertificateValidationCallback =
  ((sender, certificate, chain, sslPolicyErrors) => true);
httpClient = new HttpClient(handler);

In Python, ignoring the certificate can be done with:

ssl_context = ssl.create_default_context()
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE

and then passing the "ssl_context" to the context parameter in the urllib.request.urlopen() method.

In Go, initializing a transport and then passing it to the client can look like:

transport := &http.Transport {
  TLSClientConfig: &tls.Config {
    InsecureSkipVerify: true,
  },
}
client := &http.Client {
   Transport: transport,
   …
}

Using the REST API

Now, let’s look at an example of how to use the REST API. This example will demonstrate authenticating with the “Traditional Template” project provided by Perforce. For other organizations, these item types may be named differently, but here the default terms of “issue”, “requirement”, “test case”, and “test run” will be used. The example code will be in C#, but it should be relatively straightforward to translate it into another programming language.

Initialization

First, we initialize the HTTP client with the base address and set the media type header.

// Using the handler we created earlier for the server certificate callback
HttpClient client = new HttpClient(handler);
client.BaseAddress = new Uri("https://{API URL}/helix-alm/api/v0/");
// Make sure the headers are clear
client.DefaultRequestHeaders.Accept.Clear();
// Add "application/json" media type to the header
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

Access Token

Next, we will get an access token using the API key that was created for the REST API user.

// Be sure to URL escape the space
string url = "Traditional Template/token";
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, url);
string authorization = $"ApiKey {ApiKey}";
request.Headers.Add("Authorization", authorization);
AccessToken responseBody = await SendRequest<AccessToken>(request);

Alternatively, the third line may be substituted with the basic authentication approach if desired.

SendRequest<T>() is our method that uses our HttpClient object to send the request to the specified endpoint using the HttpClient.SendAsync() method. T is a generic object type that the method expects returned from the response. Here, we have specified that the object to return is of type AccessToken. So what happens in our method is that it sends the request to the API, waits for a response, deserializes the JSON data into our AccessToken class, and returns the data to the caller.

The AccessToken class is relatively simple, as we saw earlier from the JSON data in the API’s response, containing only a token type, expiration date, and the token itself. This is easy for a JSON deserializer to handle. For more complex data that need serialization, we can pass JSON serializer options, from the System.Text.Json namespace, to our SendRequest<T>() method, depending on which object we are deserializing. For your programming language of choice, you will have to consult the documentation for how to handle de/serializing data in JSON.

Nonetheless, we now have our access token, which we will attach in the header for all subsequent HTTP requests. To attach the access token to the header, we can use a method such as:

private void SetRequestAccessToken(HttpRequestMessage request, AccessToken accessToken)
{ 
  string authorization = string.Format("Bearer {0}", accessToken.AccessToken);
  request.Headers.Add("Authorization", authorization);    
}

Conclusion

In this example we looked at how to authenticate a client. We first initialized our HTTP client, attached our API key in the authorization header, sent our GET request to the /token endpoint, and received an access token for our future requests.

There are more features and endpoints not covered here because their use will largely depend on the requirements of the individual organization in regards to its workflow and project management. However, this example should be enough to help anyone new to the Helix ALM REST API to get started.

Thank you for reading our article about the Helix ALM REST API, we hope you have become a little bit more knowledgeable about authenticating a client for the API. In part 2 we will look at retrieving items using the REST API and how to limit the number of items returned.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

API Security: Vulnerability and Prevention

Mecomis — Wed, 15 Jan 2025 13:56:50 +0000

Cyber security is a frequent topic in the news and among developers. Today we will look at some security topics for APIs (application programming interfaces), how vulnerabilities can exist and some preventative measures. There are many different definitions of API, but as a simple definition for API, as the name suggests, is a programming interface that allows applications to communicate with each other. So how does this lead to security issues? Let's have a look.

Authentication

Authentication is the process of verifying the identity of the client making the API request. It answers the question: "Are you who you say you are?" The client proves their identity, commonly by providing an authenticator (username & password, security token, etc).

Vulnerabilities

A common vulnerability is not having any measures in place to limit the number of log in attempts nor using a second authenticator. This vulnerability allows an attacker to brute force his way in by guessing or using stolen usernames and passwords. Other vulnerabilities are the lack of multi-factor authentication, sending passwords in URLs, weak password storage practices, and improper token validation.

Prevention

First and foremost, it's important to have a complete understanding of all the possible authentication flows in one's system. Have multi-factor authentication where possible, especially for sensitive operations. Implementing anti-brute force mechanisms, rate limits, and lockout protections, using standard conventions for password storing, and token generation can go a long way for preventing potential incidents.

Authorization

Authorization answers the question: "Are you allowed to do what you're trying to do?" The API checks the client's permissions to decide if the requested operation should be permitted or denied.

Vulnerabilities

There are roughly three main types of authorization vulnerabilities that one should be aware of: broken object level authorization (BOLA) where users access unauthorized objects, broken function level authorization (BFLA) where users access unauthorized functions, and broken object property level authorization (BOPLA) where users modify unauthorized object properties.

Prevention

Authorization vulnerabilities can be solved by applying the principle of least privilege; although, this does not solve all authorization vulnerabilities, it is an important first step in controlling them. One BOLA preventative measure is performing a check on all actions that a client submits. BFLA prevention should deny all access by default, only opened where necessary. For BOPLA specifically, implement property-level checks and careful object serialization.

Resource Consumption

APIs consume resources such as network bandwidth, memory, or storage, and when exploited such things can result in financial loss.

Vulnerabilities

APIs are vulnerable to large resource consumption if there are no restrictions in place to limit client calls. Unrestricted requests will quickly consume an API's network bandwidth, CPU, memory, and storage. Secondary effects could see the business incur costs associated with downstream, third-party API requests or storage providers.

Prevention

Implement rate limiting, request throttling, configure spending limits for third-party services, and limit payload data size.

API Configurations

It can be a tricky task to configure an API on first setup, maybe time is short or you just aren't familiar with the technology. In either case, misconfiguration can make an API vulnerable.

Vulnerabilities

Common misconfiguration include: unchanged default settings, like default admin credentials or left open ports; unnecessary enabled features, like less secure endpoints used for testing; improper CORS headers, allowing cross-origin reads of sensitive API data; lack of encryption, such as no TLS support; and overly detailed error messages that expose system internals.

Prevention

Implement security throughout the API lifecycle with regular configuration reviews, automated assessments, proper encryption, restricted HTTP verbs, well-defined CORS policies, and careful error handling to prevent information leakage.

Thank you for reading our article about API security, we hope you have become a little bit more knowledgeable in the fields of cyber security and APIs. If you would like to read our full article about API security, have further questions, or a general inquiry, please contact us.