How to programmatically connect a Client controller to an Operation Center for CloudBees Core on Traditional Platform


  • I want to programmatically instantiate and connect a Client controller to an Operations Center for CloudBees Core on Traditional Platform. This is typically needed when creating Client controllers using Automatization tools such as Chef, Puppet, Ansible, AWS Cloud Formation or Azure ARM Templates.



The resolution of this article is illustrated by the following example:

  • Server
    • URL:
  • Client controller to create
    • Name: my-client-controller
      • This name is visible in the user interface of CloudBees CI on Traditional Platform
    • Id: 5
      • Arbitrary integer
      • This internal identifier is not visible
      • The identifier + '-' + - also known as idName - must be unique.
    • Grant Id: fjs2ktwfgd
      • Arbitrary secret shared between Operations Center and the Client controller to establish the connection. This secret is no longer used once the connection is established.
      • Using a random value is recommended
    • websocket: true
      • Websocket is the recommend protocol for Client controller (also for and Inbound Agents)
      • If websocket : false the Operation Center needs to have enabled TCP port for inbound agents

1. From the Operation Center Controller, declare the Client controller Item

Create via Groovy

// Imports
import com.cloudbees.opscenter.server.model.ClientMaster
import com.cloudbees.opscenter.server.model.ConnectedMaster
import com.cloudbees.opscenter.server.model.OperationsCenter
import com.cloudbees.opscenter.server.config.ConnectedMasterWebSocketProperty

// Input parameters
def clientcontrollerName = "my-client-controller"
def clientcontrollerId = 5
def clientcontrollerGrantId = "fjs2ktwfgd"
def websocket = true
def javaProperties = "-DMASTER_OPERATIONSCENTER_ENDPOINT=${Jenkins.instance.getRootUrlFromRequest()} -DMASTER_ENDPOINT= "

// Create Client controller Declaration
Clientcontroller cm = OperationsCenter.instance.createClientcontroller(clientcontrollerName)

// Another way to create a Clientcontroller is as follow
//Clientcontroller cm = Jenkins.instance.createProject(Clientcontroller.class, clientcontrollerName)

//Set Client controller properties
cm.setIdName(ConnectedMaster.createIdName(clientcontrollerId, clientcontrollerName))
// Set the licensing strategy to its default by passing 'null' ConnectedMasterLicenseServerProperty(null))
if (websocket) {  ConnectedMasterWebSocketProperty(true))

if (OperationsCenter.instance.getConnectedMasterByName(cm.idName)!=null){
    println "Created Clientcontroller '${}' known as '${cm.idName}'"
    javaProperties +=  " -DMASTER_INDEX=${} -DMASTER_NAME=${} -DMASTER_GRANT_ID=${cm.grantId} "
    if (websocket) {
        javaProperties +=  "-DMASTER_WEBSOCKET=true"
    println "[INFO ] Java Properties to add to client controller \"${javaProperties}\""
} else {
    println "[ERROR ]" + clientcontrollerName + "has not been created in CJOC"

2. From the Client controller Controller, add Operation Center connection details in the startup parameters

Copy the Java Properties to add to client controller from the previos step into its Java system properties to Push the connection from the controller to the Operation Center.

Created Clientcontroller 'my-client-controller' known as '5-my-client-controller'
[INFO ] Java Properties to add to client controller "-DMASTER_OPERATIONSCENTER_ENDPOINT= -DMASTER_ENDPOINT= -DMASTER_INDEX=5 -DMASTER_NAME=my-client-controller -DMASTER_GRANT_ID=fjs2ktwfgd -DMASTER_WEBSOCKET=true"
  • Note: Replace -DMASTER_ENDPOINT= by the URL of the Client controller to connect

We can use the optional startup parameter -DMASTER_OPERATIONSCENTER_CERTS to define the SSL Certificate used by the HTTP endpoint of Operation Center if the endpoint uses HTTPS and if the SSL certificate is not trusted by the JVM SSL trust store.


The following groovy provides information about the client controllers (id, idName, grantId) defined in the Operations Center. It must therefore be run on the CJOC:

import com.cloudbees.opscenter.server.model.OperationsCenter

OperationsCenter.instance.getConnectedMasters().each {
    println "${}"
    println " id: ${}"
    println " idName: ${it.idName}"
    println " grantId: ${it.grantId}"

See also Operations Center-Client controller connectivity issues

Tested product/plugin versions

The latest update of this article has been tested with

Have more questions?


  • 0
    Yeun nah Tan

    Is there a place that I can get the documentation of CJOC APIs?

  • 0
    Denys Digtiar

    Hi Yeun,

    Correct me if I am wrong but based on the context it looks like you are looking for Java API documentation. I am afraid we do not publish it at the moment. 

    You can find REST APIs documented here in Knowledgebase and in the Documentation.

  • 0
    Neil Houston

    Hi Denys,

    I cannot find the rest api documentation specific to CJOC anywhere...

    Do you have a link?

    If it's not currently possible; can you backlog the ability to create clientmasters via the rest api?

  • 0
    Denys Digtiar

    No, the documentation is not extensive. A few examples are:


    Scripting Templates

    The Client Master is special type of project, therefore it should be possible to follow the below KB to create it:

    How to create a job using the REST API and cURL?

    However as this article highlights, create a project is not enough, you need to establish the connection between two. 

    What was the original reason you asked for the API documentation?

    It will probably be easier to move this discussion to the support ticket.

Please sign in to leave a comment.