Configuration as Code HTTP API

18 minute readReference

You can use HTTP API endpoints to manage Configuration as Code (CasC) bundles and create a new item in the operations center based on a CasC items.yaml file.

If you use an HTTP API endpoint to upload a bundle, the parent and availabilityPattern properties in the controller bundle.yaml file are not supported. The parent and availabilityPattern properties are only supported for configuring bundle availability and for bundle inheritance for controller bundles that are added to the operations center using the CasC bundle location.

This page includes API endpoints for interacting with CasC. Some of these endpoints are specific to the operations center, while other are available for both operations centers and controllers.

Authentication and authorization

To access the CasC API, you need an API authentication token and administrator access rights. Refer to API authentication for more information.

Operations center-specific endpoints

The table below contains endpoints only available in operations centers running the CloudBees CasC Server plugin. Replace OC_URL with your operations center’s URL.
Table 1. Endpoints and methods for the operations center
Endpoint Description Parameters Prerequisites

GET ${OC_URL}/casc-bundle/list

Lists all available controller CasC bundles on the operations center.

None.

GET ${OC_URL}/casc-bundle/raw-bundle-validation-log

Returns the full validation log for all raw bundles. If the optional bundle parameter is specified, the output is filtered to only return the validation log for that bundle. If the optional controller parameter is true, the output is enriched with controller effective validation log.

  • Name: bundle (optional)

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

  • Name: controller (optional)

  • Parameter type: Query string parameter

  • Data type: boolean

  • Description: When the parameter value is true, each raw bundle validation log has a new controllers item that lists all effective validation logs of the corresponding bundle.

GET ${OC_URL}/casc-bundle/effective-bundle-validation-log

Returns the full validation log for all effective bundles. If the optional controller parameter is specified, the output is filtered to only return the validation log for that controller.

  • Name: controller (optional)

  • Parameter type: Query string parameter, accepts a regular expression

  • Data type: string

  • Description: The name of the controller. For example, controller-.*01.

GET ${OC_URL}/config-bundle-download-link

Downloads the client controller linkfile.

  • Name: id

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The full path of the controller item in the operations center. For example, folder1/controller1.

POST ${OC_URL}/casc-bundle/check-out

Checks out the bundles from all CasC bundle locations to the operations center and returns the JSON array of bundle sources, where each one contains an array of bundles.

Name: timeout (optional)

  • Description: Checks out timeout in seconds. The default value is 600 seconds and can be set in the global configuration.

POST ${OC_URL}/casc-bundle/get-effective-bundle

Downloads the effective bundle and applies CasC bundle inheritance, so it can be validated on the controller using the casc-bundle-mgnt/casc-bundle-validate endpoint.

The expected input is a .zip file that contains all child and parent bundles that have changes. The output is the effective bundle in .zip format. The following is an example of the file structure of the .zip file:

branch-1
- folder1
   - bundle-1
   - bundle-2
- folder2
   - bundle-3
- bundle-4
branch-2
- bundle-5
▼

Inconsistencies found within a bundle (such as referencing a missing file), returns an error and the effective bundle is not generated.

  • Name: bundle

  • Parameter type: Multipart/form-data

  • Data type: binary

  • Description: Attach the .zip file that contains the bundle.
If the branch name follows the Gitflow pattern (for example, feature/branch_name) when the endpoint receives a zip file containing the folder structure; escape the / character in the branch name and convert it to ___, so the branch feature/branch_name becomes the folder feature___branch_name.

POST ${OC_URL}/casc-bundle/regenerate-token

Regenerates the controller bundle token and returns the new bundle information when successful.

  • Name: controllerPath

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The full path of the controller item in the operations center. For example, folder1/controller1.
The bundleId parameter has been deprecated in version 2.289.1.2. The controllerPath parameter should be used for all new applications.

POST ${OC_URL}/casc-bundle/set-availability-pattern

Specifies the availability pattern, to define the path to controllers that can use the bundle.

  • Name: bundleId

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

  • Name: regex

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The full path to one or more controllers that can use the bundle. This must be a regular expression and defines the bundles you can assign to a controller. For example, folder1/.* to use the bundle with any controller in the "folder1" folder.

POST ${OC_URL}/casc-bundle/set-global-availability-pattern-behavior

Specifies the default global availability pattern behavior for the controller CasC bundle.

  • Name: visibility

  • Parameter type: Query string parameter

  • Data type: string

  • Description: When the parameter value is true, all CasC bundles that do not have a regex availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.

POST ${OC_URL}/casc-bundle/clear-availability-pattern

Uses the availability pattern defined in the bundle.yaml file and clears the availability pattern for the controller CasC bundle if previously defined.

  • Name: bundleId

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

POST ${OC_URL}/casc-bundle/set-controller-to-bundle

Assigns a new controller path and returns the new bundle information when successful.

For this command to be successful, you must first define the availability pattern for the bundle by sending the /casc-bundle/set-availability-pattern or /casc-bundle/set-global-availability-pattern-behavior request.

  • Name: bundleId

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

  • Name: controllerPath

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The full path of the controller item in the operations center. For example, folder1/controller1.

POST ${OC_URL}/casc-bundle/set-default-bundle

Specifies a default bundle that is pre-selected in the operations center controller configuration screen when setting up a new controller.

The default bundle is pre-selected for controllers that match the availability pattern of the default bundle. To set the availability pattern of the default bundle, you can use the /casc-bundle/set-availability-pattern or /casc-bundle/set-global-availability-pattern-behavior request.

Specifying a default bundle does not assign the bundle to a controller. When setting up a new controller in the operations center, you must select Save or Apply from the controller configuration screen to assign the pre-selected bundle to the controller.

  • Name: bundleId

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

POST ${OC_URL}/casc-bundle/validate-uploaded-bundle

Validates a bundle stored in the operations center.

  • Name: bundleId

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

POST ${OC_URL}/casc-bundle/pre-validate-bundle

Validates raw bundles before adding them to the operations center. The bundle must be a .zip file.

The expected input is a .zip file that contains all child and parent bundles that have changes. The output is the effective bundle in .zip format. The following is an example of the file structure of the .zip file:

branch-1
- folder1
   - bundle-1
   - bundle-2
- folder2
   - bundle-3
- bundle-4
branch-2
- bundle-5
▼

Inconsistencies found within a bundle, such as referencing a missing file, return an error, and the effective bundle is not generated.

  • Name: bundle

  • Parameter type: Multipart/form-data

  • Data type: binary

  • Description: Attach the .zip file that contains the bundle.
If the branch name follows the Gitflow pattern (for example, feature/branch_name) when the endpoint receives a zip file containing the folder structure; escape the / character in the branch name and convert it to ___, so the branch feature/branch_name becomes the folder feature___branch_name.

Endpoints for operations centers and controllers

The table below contains endpoints available for operations centers and controllers. Replace CBCI_INSTANCE_URL with your instance’s URL.
Table 2. Common CasC endpoints and methods for operations centers and controllers
Endpoint Description Parameters Prerequisites

GET ${CBCI_INSTANCE_URL}/casc-bundle-mgnt/casc-bundle-update-log

Returns the same information that is available from the Update log tab on the CloudBees Configuration as Code export and update screen.

None.

GET ${CBCI_INSTANCE_URL}/casc-bundle-mgnt/check-bundle-update

Checks for bundle updates and returns information about the validation of the current bundle and the new available bundle version. If a bundle update is available, you can issue the /casc-bundle-mgnt/reload-bundle command to immediately apply the updated bundle without restarting the instance.

None.

GET ${CBCI_INSTANCE_URL}/core-casc-export

Generates the entire CasC bundle as plain text and all the YAML files are concatenated.

None.

GET ${CBCI_INSTANCE_URL}/core-casc-export/zipExport

Generates the zip file that contains all the exported CasC YAML files. If a bundle update is available, you can issue the /core-casc-effective-bundle-export command to immediately apply the updated bundle without restarting the instance.

None.

GET ${CBCI_INSTANCE_URL}/core-casc-schema-download/download/bundle-descriptor.json

Returns schema files used during CasC bundle validation from the bundle descriptor.

None.

  • CloudBees CI 2.426.3.1 or later

  • No specific plugin needed

GET ${CBCI_INSTANCE_URL}/core-casc-schema-download/download/plugin-catalog.json

Returns schema files used during CasC bundle validation from the plugin-catalog.yaml file.

None.

  • CloudBees CI 2.426.3.1 or later

  • No specific plugin needed

GET ${CBCI_INSTANCE_URL}/core-casc-schema-download/download/plugins.json

Returns schema files used during CasC bundle validation from the plugins.yaml file.

None.

  • CloudBees CI 2.426.3.1 or later

  • No specific plugin needed

GET ${CBCI_INSTANCE_URL}/core-casc-schema-download/download/items.json

Returns schema files used during CasC bundle validation from the items.yaml file.

None.

  • CloudBees CI 2.426.3.1 or later

  • No specific plugin needed

GET ${CBCI_INSTANCE_URL}/core-casc-schema-download/download/rbac.json

Returns schema files used during CasC bundle validation from the rbac.yaml file.

None.

  • CloudBees CI 2.426.3.1 or later

  • No specific plugin needed

GET ${CBCI_INSTANCE_URL}/core-casc-schema-download/download/variables.json

Returns schema files used during CasC bundle validation from the variables.yaml file.

None.

  • CloudBees CI 2.426.3.1 or later

  • No specific plugin needed

POST ${CBCI_INSTANCE_URL}/casc-bundle-mgnt/reload-bundle

Applies the bundle update without restarting the instance when possible.

None.

POST ${CBCI_INSTANCE_URL}/casc-items/create-items

Creates a new item in the CloudBees CI instance based on an items.yaml file stored in the local filesystem.

  • Name: path (optional)

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The full path of the folder where the item is created. If the optional parameter is not specified when calling the API endpoint, the value defaults to the root of the instance. If the optional parameter is specified, then the folder path must exist prior to issuing the command. For example, /folder1.

  • Name: yaml

  • Parameter type: Query string parameter

  • Data type: string

  • Description: The full path on the local filesystem to the items.yaml file. For example, /casc/items.yaml.

POST ${CBCI_INSTANCE_URL}/core-casc-effective-bundle-export

Exports the current CasC bundle as a zip file.

None.

POST ${CBCI_INSTANCE_URL}/core-casc-effective-bundle-export/downloadFile/

Downloads the contents of the YAML file.

None.

POST ${CBCI_INSTANCE_URL}/export/download

Exports the item to the CasC YAML file. The path should include the Uniform Resource Identifier (URI) to the job. You can also end the request with the file name of the section: bundle.yaml, jenkins.yaml, plugins.yaml, plugin-catalog.yaml, rbac.yaml, items.yaml to download the section content.

None.

POST ${CBCI_INSTANCE_URL}/casc-bundle-mgnt/casc-bundle-validate

Validates a bundle against an instance. The bundle must be a .zip file. In this API, the .zip file format only contains the bundle files directly with no parent (branch) folder included. The bundle can only contain a single bundle.

  • Name: bundle

  • Parameter type: Multipart/form-data

  • Data type: binary

  • Description: Attach the .zip file that contains the bundle.

Request examples

In the request examples, admin is the name of the user attempting to send the request and https://my-operations-center.com/cjoc/ is the URL for the operations center.
Table 3. Request examples
Endpoint Request example

GET /casc-bundle/list

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"
▼

GET /casc-bundle-mgnt/casc-bundle-update-log

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle-mgnt/casc-bundle-update-log"
▼

GET /casc-bundle-mgnt/check-bundle-update

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle-mgnt/check-bundle-update"
▼

GET /casc-bundle/raw-bundle-validation-log

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/raw-bundle-validation-log?bundle=casc-bundle-java&controller=true"
▼

GET /casc-bundle/effective-bundle-validation-log

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/effective-bundle-validation-log?controller=controller-.*01"
▼

GET /config-bundle-download-link

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/config-bundle-download-link/?id=folder1/controller1"
▼

GET /core-casc-export

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-ci-instance.com/core-casc-export"
▼

GET /core-casc-export/zipExport

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-ci-instance.com/core-casc-export/zipExport"
▼

POST /casc-bundle/check-out

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/check-out"
▼

POST /casc-bundle/get-effective-bundle

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" --data-binary @/path/to/bundle.zip -H "Content-Type: application/zip;charset=utf-8" -XPOST "https://my-operation-center.com/casc-bundle/get-effective-bundle?bundle=casc-bundle-java" --output response.zip
▼

POST /casc-bundle/regenerate-token

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/regenerate-token?controllerPath=folder1/controller1"
▼

POST /casc-bundle/set-availability-pattern

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-availability-pattern?bundleId=casc-bundle-java&regex=folder1.*"
▼

POST /casc-bundle/set-global-availability-pattern-behavior

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-global-availability-pattern-behavior?visibility=true"
▼

POST /casc-bundle/clear-availability-pattern

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com//casc-bundle/clear-availability-pattern?bundleId=casc-bundle-java"
▼

POST /casc-bundle/set-controller-to-bundle

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-controller-to-bundle?bundleId=casc-bundle-java&controllerPath=folder1/controller1"
▼

POST /casc-bundle/set-default-bundle

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-default-bundle?bundleId=casc-bundle-java"
▼

POST /casc-bundle/validate-uploaded-bundle

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/validate-uploaded-bundle?bundleId=casc-bundle-java
▼

POST /casc-bundle-mgnt/reload-bundle

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle-mgnt/reload-bundle"
▼

POST /casc-items/create-items

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-items/create-items?path=/folder1" --data-binary @/casc/items.yaml -H "Content-Type:text/yaml"
▼

POST /core-casc-effective-bundle-export

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-ci-instance.com/core-casc-effective-bundle-export/" --output download.zip
▼

POST /core-casc-effective-bundle-export/downloadFile/

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-ci-instance.com/core-casc-effective-bundle-export/downloadFile/bundle.yaml"
▼

POST /export/download

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-ci-instance.com/job/self-service/export/download"
▼

POST /casc-bundle-mgnt/casc-bundle-validate

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle-mgnt/casc-bundle-validate" --header "Content-type: application/zip" --data-binary "@/path/to/your/bundle.zip"
▼

POST CBCI_INSTANCE_URL/casc-bundle/pre-validate-bundle

 
curl -s -H 'Accept: application/json' -H 'Content-Type: application/zip;charset=utf-8' --user [USER] --data-binary @[PATH_TO_ZIP] -XPOST $CBCI_INSTANCE_URL/casc-bundle/pre-validate-bundle
▼

Response examples

Response examples are formatted for better readability.
GET /casc-bundle/list
GET /casc-bundle-mgnt/casc-bundle-update-log
GET /casc-bundle-mgnt/check-bundle-update?quiet=false
GET /casc-bundle-mgnt/check-bundle-update?quiet=true
GET /casc-bundle/raw-bundle-validation-log
GET /casc-bundle/effective-bundle-validation-log
GET /config-bundle-download-link
GET /core-casc-export
POST /casc-bundle/check-out
POST /casc-bundle/get-effective-bundle
POST /casc-bundle/regenerate-token
POST /casc-bundle/set-availability-pattern
POST /casc-bundle/set-global-availability-pattern-behavior
POST /casc-bundle/clear-availability-pattern
POST /casc-bundle/set-controller-to-bundle
POST /casc-bundle/set-default-bundle
POST /casc-bundle/validate-uploaded-bundle?bundleId=core-casc-export-jenkins&quiet=false
POST /casc-bundle/validate-uploaded-bundle?bundleId=core-casc-export-jenkins&quiet=true
POST /casc-bundle-mgnt/reload-bundle
POST /casc-items/create-items
POST /core-casc-effective-bundle-export
POST /core-casc-effective-bundle-export/downloadFile/
POST /export/download
POST /casc-bundle-mgnt/casc-bundle-validate?quiet=false
POST /casc-bundle-mgnt/casc-bundle-validate?quiet=true
POST /CBCI_INSTANCE_URL/casc-bundle/pre-validate-bundle?quiet=false
POST /CBCI_INSTANCE_URL/casc-bundle/pre-validate-bundle?quiet=true
{
    "bundles":[
        {
            "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex": "folder1/.*",
            "name": "casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [
                "folder1/controller1"
            ],
            "availableFor": [
                "folder1/controller1",
                "folder1/controller2"
            ]
        }
    ]
}
▼
{
    "update-log-status": "ENABLED",
    "retention-policy": 10,
    "versions": [
        {
            "version": "6",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00006"
        },
        {
            "version": "5",
            "date": "09 May 2022",
            "errors": 1,
            "warnings": 0,
            "folder": "20220509_00005"
        },
        {
            "version": "4",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00004"
        },
        {
            "version": "3",
            "date": "09 May 2022",
            "errors": 1,
            "warnings": 0,
            "folder": "20220509_00003"
        },
        {
            "version": "2",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00002"
        },
        {
            "version": "1",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00001"
        }
    ]
}
▼
{
  "update-available": false,
  "versions": {
    "current-bundle": {
      "version": "1",
      "validations": [
        "WARNING - [CATALOGVAL] - More than one plugin catalog file used in zip-core-casc-1652255664849. Using only first read file.",
        "INFO - [APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml.",
        "INFO - [CATALOGVAL] - [MultipleCatalogFilesValidator] No catalog validation needed.",
        "INFO - [CATALOGVAL] - [PluginCatalogInOCValidator] No plugin catalog specified.",
        "INFO - [CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated.",
        "INFO - [DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files.",
        "INFO - [ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle.",
        "INFO - [JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle.",
        "INFO - [PLUGINVAL] - [PluginsToInstallValidator] All plugins are present in the envelope or in the plugin catalog.",
        "INFO - [SCHEMA] - All YAML files validated correctly against their corresponding schemas",
        "INFO - [STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type.",
        "INFO - [VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml."
      ]
    }
  },
  "items": {
    "deletions": []
  }
}
▼
{
  "update-available": false,
  "versions": {
    "current-bundle": {
      "version": "1",
      "validations": [
        "WARNING - [CATALOGVAL] - More than one plugin catalog file used in zip-core-casc-1652255664849. Using only first read file."
      ]
    }
  },
  "items": {
    "deletions": []
  }
}
▼
{
    "validation-log": [
        {
            "bundle-id": "casc-bundle-java",
            "records": [
                {
                    "version": "3",
                    "errors": 0,
                    "warnings": 0,
                    "folder": "20220607_00003",
                    "date": "07 June 2022"
                },
                {
                    "version": "2",
                    "errors": 0,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder."
                    ],
                    "folder": "20220607_00002",
                    "date": "07 June 2022"
                },
                {
                    "version": "1",
                    "errors": 1,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder.",
                        "ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer."
                    ],
                    "folder": "20220607_00001",
                    "date": "07 June 2022"
                }
            ],
            "controllers": [
                {
                    "controller": "controller-AB01",
                    "records": [
                        {
                            "bundle": "casc-bundle-java",
                            "assigned": true,
                            "version": "0d4b2b2d6f8ba0872a33120a0548a483",
                            "errors": 0,
                            "warnings": 1,
                            "messages": [
                                "WARNING - [PLUGINVAL] - Plugin casc-bundle-java is not in the CloudBees Assurance Program (CAP) or in applicable plugin catalog(s)"
                            ],
                            "folder": "20220725_00002",
                            "date": "25 July 2022"
                        }
                    ]
                }
            ]
        }
    ]
}
▼
{
    "validation-log": [
        {
            "controller": "controller-AB01",
            "records": [
                {
                    "bundle": "casc-bundle-java",
                    "assigned": true,
                    "version": "3",
                    "errors": 0,
                    "warnings": 0,
                    "folder": "20220607_00003",
                    "date": "07 June 2022"
                },
                {
                    "bundle": "casc-bundle-java-02",
                    "assigned": false,
                    "version": "2",
                    "errors": 0,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder."
                    ],
                    "folder": "20220607_00002",
                    "date": "07 June 2022"
                },
                {
                    "bundle": "casc-bundle-java-01",
                    "assigned": false,
                    "version": "1",
                    "errors": 1,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder.",
                        "ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer."
                    ],
                    "folder": "20220607_00001",
                    "date": "07 June 2022"
                }
            ]
        }
    ]
}
▼
{
    "url": "https://my-operation-center.com/zip-bundle/0e9f58f059c8d91170d4c4b68c6766fb/folder1/{CTRL}1",
    "token": "bc1d6f32-0d6d-4580-b25c-423282ea3925"
}
▼
# bundle.yaml
apiVersion: "1"
id: "jenkins"
description: "Autogenerated bundle descriptor"
version: "1"
jcasc:
  - "jenkins.yaml"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
rbac:
  - "rbac.yaml"
items:
  - "items.yaml"

# jenkins.yaml
...
▼
{
    "remotes": [
        {
            "name": "my-local-bundle-sources",
            "bundles": [
                {
                    "bundleName": "bundle-1",
                    "localText": "2022-09-20T15: 16: 27.318"
                },
                {   "bundleName": "bundle-2",
                    "localText": "2022-09-20T15: 16: 27.318"
                }
            ]
        }
    ]
}
▼
Instead of a response, the zip bundle is downloaded to the download.zip file.
▼
{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}
▼
{
    "controllers": [
        "folder1/controller1",
        "folder1/controller2"
    ]
}
▼
{
    "visibility": true
}
▼
{
    "controllers": [
        "folder1/controller1",
        "folder1/controller2"
    ]
}
▼
{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}
▼
{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}
▼
{
  "valid": true,
  "structureValidations": [
    {
            "level": "WARNING",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - The following files have been detected in the bundle folder but they are not yaml files: sample.txt."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_STRUCTURE",
      "message": "[STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_CONTENT",
      "message": "[CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated."
    },
    {
      "level": "INFO",
      "validationCode": "SCHEMA",
      "message": "[SCHEMA] - All YAML files validated correctly against their corresponding schemas"
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_STRUCTURE",
      "message": "[STRUCTURE] - [ParentValidator] Inheritance validation passed."
    },
    {
      "level": "INFO",
      "validationCode": "DESCRIPTOR",
      "message": "[DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_VERSION",
      "message": "[VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_API",
      "message": "[APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_JCASC_STRATEGY",
      "message": "[JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_ITEM_STRATEGY",
      "message": "[ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle."
    },
    {
      "level": "INFO",
      "validationCode": "PLUGIN_CATALOG",
      "message": "[CATALOGVAL] - [MultipleCatalogFilesValidator] Just one file defining the plugin catalog."
    }
  ],
  "controllerValidations": []
}
▼
{
  "valid": true,
  "structureValidations": [
    {
            "level": "WARNING",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - The following files have been detected in the bundle folder but they are not yaml files: sample.txt."
        }
  ],
  "controllerValidations": []
}
▼
{
    "reloaded": true
}
▼
{
    "basePath": "/folder1"
}
▼
Instead of a response, the zip bundle is downloaded to the download.zip file.
▼
apiVersion: "1"
id: "oc"
description: "Operations Center Bundle"
version: "1.3"
items:
  - "items/items.yaml"
catalog:
  - "catalog/plugin-catalog.yaml"
▼
kind: folder
name: self-service
description: Folder to host freestyle jobs and folders
displayName: Self Service
groups:
- roles:
  - name: selfservice
    grantedAt: current
  name: SelfService
properties:
- envVars: {
    }
- kubernetesFolderProperty: {
    }
- itemRestrictions:
    allowedTypes:
    - hudson.model.FreeStyleProject
    - com.cloudbees.hudson.plugins.folder.Folder
    filter: true
▼
{
  "valid": true,
  "validation-messages": [
    "ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer.",
    "WARNING - [JCASC] - It is impossible to validate the Jenkins configuration. Please review your Jenkins and plugin configurations. Reason: jenkins: error configuring 'jenkins' with class io.jenkins.plugins.casc.core.JenkinsConfigurator configurator.",
    "INFO - [STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type.",
    "INFO - [DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files.",
    "INFO - [VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml.",
    "INFO - [APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml.",
    "INFO - [JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle.",
    "INFO - [ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle.",
    "INFO - [CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated.",
    "INFO - [SCHEMA] - All YAML files validated correctly against their corresponding schemas",
    "INFO - [CATALOGVAL] - [PluginCatalogInOCValidator] No plugin catalog specified.",
    "INFO - [PLUGINVAL] - [PluginsToInstallValidator] All plugins are present in the envelope or in the plugin catalog.",
    "INFO - [CATALOGVAL] - [MultipleCatalogFilesValidator] No catalog validation needed.",
    "INFO - [JCASC] - [JCasCValidator] All configurations validated successfully.",
    "INFO - [PLUGINVAL] - [PluginsToInstallValidator] All plugins are present in the envelope or in the plugin catalog."
  ]
}
▼
{
  "valid": true,
  "validation-messages": [
    "ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer.",
    "WARNING - [JCASC] - It is impossible to validate the Jenkins configuration. Please review your Jenkins and plugin configurations. Reason: jenkins: error configuring 'jenkins' with class io.jenkins.plugins.casc.core.JenkinsConfigurator configurator."
  ]
}
▼
{
  "validations": [
    {
      "bundle": "cm-casc-bundle/core-casc-export-jenkins",
      "result": {
        "valid": true,
        "structureValidations": [
          {
            "level": "ERROR",
            "validationCode": "BUNDLE_CONTENT",
            "message": "[CONTVAL] - Missing Jenkins Configuration as Code file specified in the bundle.yaml file."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_CONTENT",
            "message": "[CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated."
          },
          {
            "level": "INFO",
            "validationCode": "SCHEMA",
            "message": "[SCHEMA] - All YAML files validated correctly against their corresponding schemas"
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - [ParentValidator] Inheritance validation passed."
          },
          {
            "level": "INFO",
            "validationCode": "DESCRIPTOR",
            "message": "[DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_VERSION",
            "message": "[VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_API",
            "message": "[APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_JCASC_STRATEGY",
            "message": "[JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_ITEM_STRATEGY",
            "message": "[ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle."
          },
          {
            "level": "INFO",
            "validationCode": "PLUGIN_CATALOG",
            "message": "[CATALOGVAL] - [MultipleCatalogFilesValidator] Just one file defining the plugin catalog."
          }
        ],
        "controllerValidations": []
      }
    }
  ]
}
▼
{
  "validations": [
    {
      "bundle": "cm-casc-bundle/core-casc-export-jenkins",
      "result": {
        "valid": true,
        "structureValidations": [
          {
            "level": "ERROR",
            "validationCode": "BUNDLE_CONTENT",
            "message": "[CONTVAL] - Missing Jenkins Configuration as Code file specified in the bundle.yaml file."
          }
        ],
        "controllerValidations": []
      }
    }
  ]
}
▼

Response model

Table 4. Response model
Element Type Description

assigned

boolean

If assigned is true, the current validation log is the result of an effective bundle that is currently assigned to a controller. If not, assigned is false. This optional attribute is available with the CloudBees CasC Server plugin, version 1.76 and later.

availableFor

array of objects

Controllers that can be assigned to the bundle based on the availability pattern.

availabilityPatternFromYaml

string

Returns true if the availability pattern is defined in the bundle.yaml file. Returns false if the availability pattern is defined in the UI or using the /casc-bundle/set-availability-pattern request.

bundles

array of objects

All bundles available on the operations center.

controllers

array of objects

The full paths of all controllers that can use the bundle.

linkFileContent

string

Contains two entries in string format wrapped in quotes and separated by newline characters: url and token. The url is the bundle URL where the operations center exposes its content. The token is the access token for the bundle.

name

string

The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

regex

string

The full path to one or more controllers in the operations center that can use the bundle. This must be a regular expression. It defines the bundles you can assign to a controller. For example, folder1/.*.

token

string

The access token for the bundle.

url

string

The bundle URL where the operations center exposes its content.

usedBy

string

The names of controllers assigned to the bundle.

visibility

string

The default global availability pattern behavior for the bundle.

Status and error codes

Table 5. Status and error codes
Code Description

200

Success

403

Not authorized. Administrator permission required.

404

The provided controller path, endpoint, or method cannot be found.

500

Server error.

Examples for configuring a controller using CasC

Once the CasC bundle has been configured in the operations center, you can define an availability pattern to make the bundle available to controllers, assign the bundle to a controller, and specify a default bundle.

  1. Send the GET /casc-bundle/list request to list all available CasC bundles on the operations center. For example:

    curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"
    ▼

    In this example, there is one bundle named casc-bundle-java:

    {
    "bundles":[
        {
            "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex": "",
            "name": "casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [],
            "availableFor": []
        }
    ]
}
    ▼

  2. Define the availability pattern for the bundle. You have two options:

    • Option 1: Send the POST /casc-bundle/set-availability-pattern request to define the path to the controllers that can use the bundle. For example:

      curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-availability-pattern?bundleId=casc-bundle-java&regex=folder1.*"
      ▼

      If successful, a list of all controllers that can use the bundle is returned:

      {
    "controllers": [
        "folder1/controller1",
        "folder1/controller2"
    ]
}
      ▼

    • Option 2: Send the POST /casc-bundle/set-global-availability-pattern-behavior request to define the default global availability pattern behavior for bundles that do not have an availability pattern defined. This option provides more flexibility, but is less secure. For example:

      curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-global-availability-pattern-behavior?visibility=true"
      ▼

      If successful, the default global availability pattern behavior is returned:

      {
    "visibility": true
}
      ▼

  3. Send the POST /casc-bundle/set-controller-to-bundle request to assign a bundle to a controller. For example:

    curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-controller-to-bundle?bundleId=casc-bundle-java&controllerPath=folder1/controller1"
    ▼

    If successful, the bundle information is returned:

    {
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}
    ▼

  4. Send the GET /casc-bundle/list request again. For example:

    curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"
    ▼

    The casc-bundle-java bundle is now assigned to folder/controller1 and also available for assignment to folder1/controller2, based on the availability pattern you defined.

    {
    "bundles":[
        {
            "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex": "folder1/.*",
            "name": "casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [
                "folder1/controller1"
            ],
            "availableFor": [
                "folder1/controller1",
                "folder1/controller2"
            ]
        }
    ]
}
    ▼

  5. Optionally, specify a default bundle to pre-select a bundle in the controller configuration screen when setting up a new controller. For example, to specify casc-bundle-java as the default bundle, send the POST /casc-bundle/set-default-bundle request:

    curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-default-bundle?bundleId=casc-bundle-java"
    ▼

    If successful, the default bundle information is returned:

    {
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}
    ▼
API authentication
Role-Based Access Control