Build Service

The build service enables you validate the definitions of jobs, folders, or calendars that you plan to deploy. In addition, the build service enables you to manage workspaces.

Definition Validation

You can use the build command to compile definitions of jobs, folders, or calendars and check their validity for your Control-M environment. Control-M validation includes basic Control-M rules, such as field length, valid characters, and mandatory fields. The build service also checks that the JSON is valid.

If Control-M Workload Change Manager is part of your solution, the system evaluates definitions according to the relevant site standards.

build

The build command validates definitions of jobs, folders, or calendars that you submit in a JSON-format definitions file or a package of multiple definitions files in ZIP or TAR.GZ format.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -F "definitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/build"

token = r_login.json()['token']
 
# -----------------
# Built
uploaded_files = [
('definitionsFile', ('Jobs.json', open('examples/AutomationAPISampleFlow.json', 'rb'), 'application/json'))
]
 
r = requests.post(endPoint + '/build', files=uploaded_files, headers={'x-api-key': + token}, verify=False)
print(r.content)
print(r.status_code)
exit(r.status_code == requests.codes.ok)

The following table describes the build command parameters.

Response

The response contains the following information:

• The total amount of elements created, such as folders, sub-folders, jobs, and site standards.

• An indication if the system applied a Deploy Descriptor.

• The following validation messages for site standards:

  • An error message if validations are strictly enforced.

  • A warning message if validations are not strictly enforced.

    If validations are not strictly enforced, site standard warning messages appear in the build command response by default. If you do not want these warning messages in the response, open the automation-api.properties file and add the buildWarningsEnabled property with the value set to false.

{
    "deploymentFile": "Folder.json",
    "deploymentState": ""DEPLOY FOLDERS 1/1",
    "deploymentStatus": "ENDED_OK",
    "successfulFoldersCount": 0,
    "successfulSmartFoldersCount": 1,
    "successfulSubFoldersCount": 0,
    "successfulJobsCount": 1,
    "successfulConnectionProfilesCount": 0,
    "successfulDriversCount": 0,
    "successfulStandardsCount": 2,
    "isDeployDescriptorValid": false,
    "warnings": [{
        "message": "Department has to be from values [HR, DEV, FINANCE] ",
        "id": "Validation10006",
        "item": "Job: Folder_1/os_Job_2 -> Parent Folder",
        "file": "Folder.json",
        "line": 3,
        "col": 25
    }]
}

Workspace Management

The following build commands enable you to manage workspaces.

• build workspaces::get

• build workspace::get

• build workspace::update

• build workspace::delete

• build workspace::return

build workspaces::get

The build workspaces::get command enables you to retrieve details of workspaces. Workspace details can include a Workspace ID for each workspace, which you can utilize in other API commands. You can filter the data with a search query.

endpoint=https://<controlm>:8443/automation-api
token=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/build/workspaces?state=UserWork&workspaceName=S*"

The following table describes the build workspaces::get command parameters.

-s runs a search in query string format. Multiple criteria are separated by &, such as workspaceName=Workspace3test&folderName=Folder_1. The following table lists the fields available for a search query.

Response

The following example shows the details of two workspaces:

{
  "retCode": 0,
  "workspaces": [
    {
      "id": 6,
      "name": "MyWorkspaceA"
    },
    {
      "id": 1,
      "name": "MyWorkspaceB"
    }
  ]
}

build workspace::get

The build workspace::get command enables you to retrieve details of a workspace with a Workspace ID.

workspaceId=19
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/build/workspace/$workspaceId"

The following table describes the build workspace::get command parameters.

Response

The following example shows the details returned for a workspace with workspace ID 19:

{
  "id": 19,
  "type": "Request",
  "state": "UserWork",
  "name": "Workspace 15:19:42",
  "description": "",
  "owner": "emuser1",
  "approver": "u2",
  "createdTime": "2026-04-29T12:19:44.762",
  "updatedTime": "2026-04-29T12:21:38.294",
  "changeId": "",
  "changedManagedLastUpdate": "2026-04-29T12:21:18.983",
  "emailRecipient": ""
}

build workspace::update

The build workspace::update command enables you to update a workspace.

workspaceId=19
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT -F "definitionsFile=@examples/Workspace19.json" "$endpoint/build/workspace/$workspaceId"

The following table describes the build workspace::update command parameters.

Response

The following example shows the details returned to update a workspace:

{
  "name": "string",
  "description": "string",
  "changeId": "string",
  "emailRecipient": "string"
}

build workspace::delete

The build workspace::delete command enables you to delete a workspace.

workspaceId=19
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/build/workspace/$workspaceId"

The following table describes the build workspace::delete command parameters.

build workspace::return

The build workspace::return command enables you, the approver, to reject a workspace and return it to the user who submitted it for review.

Workspace status changes from Approver Work to Returned to User.

To use this API command, you must have Control-M Workload Change Manager installed.

workspaceId=19
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -d "@examples/returnNotes.json" \
"$endpoint/build/workspace/$workspaceId/return"

The following table describes the build workspace::return command parameters.

{"returnReason": "Please fix the workspace."}

If annotation is enabled for the Scheduling definitions category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.