Differences between codebeamer API JSONs

There are specific differences resulting from changes in the codebeamer API JSON, these differences are presented in the below diff report files. The files contain information about what has been added, removed, or replaced (including the operation executed - add, remove, replace, API paths, request parameters and default parameter values, example responses, etc.) in the Swagger API documentation between different codebeamer versions:

• *.add.json - files contain information about what has been added to the version indicated, compared to the previous version.
• *.remove.json - files contain information about what has been removed from the version indicated, compared to the previous version.
• *.replace.json - files contain information about what has been replaced in the version indicated, compared to the previous version.

Swagger API changes - 22.10-LTS (GINA)

Test Run Changes

Endpoint changes

• /v3/trackers/{testRunTrackerId}/automatedtestruns - The Optional Test Case Run conclusion property has been added to the model.

Swagger API changes - 22.04 (FELICITY)

Wiki-Text Changes

References to attachments in Wiki-Text are added based on attachments IDs instead of attachment names. Even so the ID-based syntax is not new it has not been commonly used before.

The old name based syntax is still supported and will not be converted, therefore integrations interpreting the attachment references in Wiki-Text will have to support both types of references.

Example:

Old Syntax

[!1639645149914.png!]

New Syntax (potentially will be adjusted in final release)

[CB:/displayDocument/1639645149914.png?artifact_id=309875&version=1|CB:/displayDocument/1639645149914.png?artifact_id=309875&version=1]

Test Run Changes

New endpoint

• /v3/trackers/{testRunTrackerId}/automatedtestruns - This endpoint has been created to carry out automated or high number of test runs. The performance of tracker items has been increased to 12000+ uploadable test case results.

Swagger API changes - 21.09 (EMMA)

API Throttling

Breaking changes

Due to internal changes from 21.09 (Emma) the hashes of the tracker item attachment is calculated with SHA-512 algorithm therefore the Attachment model has changed.

Unknown properties are rejected in JSON payload

From 21.09 (Emma) codebeamer will reject the unknown properties in any Swagger communication model.

For Example this will be rejected:

{

"id": 1091,

"name": "Optimize routing algorithm1",

"foo": "bar",

"descriptionFormat": "Wiki",

...

}

with the following HTTP 400 - Bad request error message:

{

"message": "JSON parse error: Unrecognized field \"foo\"

...

}

New functionality

New endpoints added to

• Create a baseline
• Get a project role of a project member
• Get permissions of all fields of a tracker
• Get field accessibility (read, write, visible) for a tracker item
• Maintenance mode management

Models are extended:

• Email property is included in UserReference model
• Suspected flags are included in TrackerItemReference models
• ArtifactReference is introduced for Document type tracker
• HideIf and MandatoryIf formulas are added to field definition
• Project id and user status filtering criteria is added to user search endpoint

Item tags included in JSON

From 21.09-SP3, if present, tags of an item are included in the response when calling issues/defects via the API.

Input parameter changes in project content

POST /v3/projects/{projectId}/content endpoint parameters changed:

• skipBranches parameter removed
• skipDocuments perameter removed
• skipWikiPages parameter default value changed to true

Swagger API changes - 21.04 (DOROTHY)

Test management

• POST /api/v3/trackers/{testRunTrackerId}/testruns - This endpoint only supports a single type input which means that only test cases or a single test run can be provided. Therefore two new error messages will appear:
  • HTTP 400 - Only one test set is accepted. For multiple test sets please use trackers/{testRunTrackerId}/testruns/generatefromtestset endpoint.
  • HTTP 400 - Test Cases and Test Sets cannot be mixed. Please use separate request for them.
  • As it is mentioned there is a new POST /api/v3/trackers/{testRunTrackerId}/testruns/generatefromtestset endpoint for test run generation from multiple test sets.
  • If a Formal test run is being created, the not "Accepted" test cases are rejected while using any tracker item creational endpoint.

Swagger API changes - 20.11-SP4 (CARMEN)

Tracker item

Endpoint changes

• DELETE /api/v3/items/{itemId} - no longer deletes the item from the database, but moves it to the trash instead

Swagger API changes - 20.11-LTS (CARMEN)

This page summarizes the API changes needs to be considered during the codebeamer upgrade to 20.11 (Carmen).

User data

Permissions

User data access has been revised and from 20.11 (Carmen) they can only be accessed with the proper permissions.

These permissions can configured on user group level:

{codebeamer url}/sysadmin/userGroups.spr?groupId={groupId}

For Example in case the API user doesn't have Account - View Email Address permissions the email property won't be populated in the User and UserReference models.

Extended UserReference model

Following the feedback of our customers we have extended the UserReference to contain the e-mail address of the referenced account. This only happens if the Account - View Email Address permission is granted for the API user (see the details in the previous section).

    {
      "id": 123,
      "name": "user_name",
      "type": "UserReference",
      "email": "user@example.com"
    },

Accounts - Admin permission checks

As a result of the proper user data permission checks we have removed the restrictions on every user related endpoint.

Since 20.11 (Carmen) the following endpoints won't need Accounts - Admin user group permission to be called:

• /v3/users
• /v3/users/{userId}

Getting project members

We have introduced two new endpoints to retrieve members of a given project.

These endpoints need specific permission settings:

• /v3/projects/{projectId}/members
  • Returns the user references and group references assigned to the project.
  • Needs Members - View project role permission.
• /v3/users/groups/{groupId}/members
  • Returns the user references assigned to a specific user group.
  • Needs Accounts - Admin user group permission.

Tracker item

Update of Parent field

The users were able to update the Parent field of the item using the POST /v3/items/{itemId}/fields and this could've caused inconsistent tracker outline in case when the parent item was from an incompatible tracker.

From 20.11 (Carmen) the Parent cannot be set to tracker item from another tracker.

New endpoints

• GET /v3/items/{itemId}/fields - Getting all tracker item fields in customField format grouped by read/write permissions
• GET /v3/items/{itemId}/lock - Getting locking information regarding to a tracker item
• PUT /v3/items/{itemId}/lock - Setting lock on a tracker item
• DELETE /v3/items/{itemId}/lock - Removing lock from a tracker item
• GET /v3/trackers/{trackerId}/children - Getting all root level items for a tracker in an array like format
• PUT /v3/trackers/{trackerId}/children - Modifying the order of all root level items for a tracker in an array like format
• POST /v3/trackers/{trackerId}/children - Moving an item in a tracker into root level

Tracker

New endpoints

• GET /v3/trackers/{trackerId}/baselines - Getting all baselines defined for a tracker

Endpoint changes

• GET /v3/trackers/{trackerId}/outline- Bug fixes and performance optimizations were made in the following form:
  • A new, optional resultDepthFilter parameter were introduced which enables query optimization via defining the depth of the returned outline.
  • To be able to decide if an item has more children in the outline, we have introduced a new hasChildren boolean property in the OutlineItem model.
  • Using these two new attributes you are able to implement a level-by-level discovery on the tracker outline. You can initially return the first level of items and then only expand on specific children using the already existing parentItemId parameter.

• When a field has default value and user has not permission to write this field, during a Swagger Work Item modification request codebeamer will set the field value to default when field value was null in Swagger request.