Common pitfall while updating release tokens

book

Article ID: 207503

calendar_today

Updated On:

Products

Continuous Delivery Director

Issue/Introduction

This document illustrate the most common mistakes observed while updating release-tokens.

Cause

In most obvious use case where the CDD Rest API are used to automatically update the release token values via continuous build systems, we observed some common mistakes which may lead to broken integration. In this article we would like to introduce those common mistakes and the API to be used to avoid such scenario.

 

Scenario: Update the release token

Common workflow:

  • Get the Id and name of release token  [API used: GET /releases/{releaseId}/tokens]

Usage example

Request & Response Types

    • curl -X GET --header "Accept: application/json" "http://CDD-HOSTNAME:CDD-PORT/cdd/design/0000/v1/releases/4/tokens?filter=release"
    • Response

      {
      "data":
       [ 
        { 
         "release": 
          { 
           "id": 4, 
           "className": "IdentifiableDto" 
          },
          "isProduction": false, 
          "isSystem": false, 
          "scope": "PHASE_SCOPE", 
          "value": "from API", 
          "name": "release", 
          "id": 10, 
          "className": "ReleaseTokenDto" 
        } 
       ] 
      }​
    • curl -X GET --header "Accept: application/json" "http://CDD-HOSTNAME:CDD-PORT/cdd/design/0000/v1/releases/4/tokens"
    • Response 
    • {
        "data": [
          {
            "release": {
              "id": 4,
              "className": "IdentifiableDto"
            },
            "isProduction": false,
            "isSystem": true,
            "scope": "PHASE_SCOPE",
            "name": "Test Application.last_successful_change",
            "id": 9,
            "className": "ReleaseTokenDto"
          },
          {
            "release": {
              "id": 4,
              "className": "IdentifiableDto"
            },
            "isProduction": false,
            "isSystem": false,
            "scope": "PHASE_SCOPE",
            "value": "from API",
            "name": "release",
            "id": 10,
            "className": "ReleaseTokenDto"
          }
        ]
      }​
  • Update the release token in specific release via token-id and name acquired from step 1 [API used: PUT /releases/{releaseId}/tokens/{tokenId}]
    • Most common assumptions
      • When using the API with filter as illustrated in example 1 i.e. filter=release, and using the first id returned the assumption is that API will only return a single node, which is not the case. If you are getting only one result it's because you have only one token matching filter i.e. release. If you have more than one token matching filter=release API will return more than one node
    Example: API returning more than one node matching filter=release
    {
      "data": [
        {
          "release": {
            "id": 4,
            "className": "IdentifiableDto"
          },
          "isProduction": false,
          "isSystem": false,
          "scope": "PHASE_SCOPE",
          "value": "from API",
          "name": "release",
          "id": 10,
          "className": "ReleaseTokenDto"
        },
        {
          "release": {
            "id": 4,
            "className": "IdentifiableDto"
          },
          "isProduction": false,
          "isSystem": false,
          "scope": "PHASE_SCOPE",
          "value": "",
          "name": "release_number",
          "id": 11,
          "className": "ReleaseTokenDto"
        }
      ]
    }
      • The other scenario as illustrated in example 2, using the API without filter which will return a long list of token and writing your own JSON filter to loop though data list to find matching token name and id, ignore the important field i.e. "isSystem". As shown in example 2

Issues

1: Picking up wrong token-id from the filtered list and trying to update a read-only tokens, i.e. system token/built-in tokens, results in failure to update token

2: Trying to spent lot of time in parsing non-filtered JSON to get the token-name and token-id. It's also possible just breaking at first occurrence of specific name i.e. 'release' and not checking of "isSystem". In either case it's not efficient

Environment

Release : 7.0, 8.0.0 or higher

Component : CONTINUOUS DELIVERY DIRECTOR

Resolution

The above mentioned scenario illustrate the inefficient way of updating token which are prone to error if not handled properly. The elegant way to update a release token is to use below API which update the token in a release by exact token-name.

API: PATCH /releases/{releaseName}/{releaseVersionName}/tokens/{tokenName}

Example Usage:

curl -X PATCH --header "Content-Type: application/json" --header "Accept: application/json" -d "{\"value\": \"REST API1\"}" 
"http://CDD-HOSTNAME:8080/cdd/design/0000/v1/releases/6.7%20RA/1/tokens/release_number"