Build Service

The build service allows you to compile definitions of jobs, folders, or calendars and verify that they are valid for your Control-M environment. Control-M validation includes basic Control-M rules such as length of fields, allowed characters, and mandatory fields. Build will also check that the JSON is valid.

If Control-M Change Manager is part of your solution, definitions will be evaluated against the relevant site standards.

The build command can receive a definitions file in .json format or packages of multiple definition files in .zip or .tar.gz format. For more information, see Code Reference.

CLI Syntax

Copy 
ctm build <definitionsFile> [deployDescriptorFile] [StandardsFile]

Where:

Parameter

Description

<definitionsFile>

The file or archive that contains code for jobs, folders, or calendars.

Valid formats are:

  • .json

  • .zip or .tar.gz.

Calendar definitions are supported in .json format only.

[deployDescriptorFile]

(Optional) The file that includes the rules to apply on the original definitionsFile.

The rules enable transforming Control-M JSON code properties. 

For detailed information, see Deploy Descriptor.

[StandardsFile]

(Optional) The .json file that contains the site standards that apply to the Control-M environment.

For detailed information, see Site Standards.

REST API Syntax

Example using cURL:

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

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

To select the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

The following example shows how to use the build command in a Python function :

Copy 
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)

For more information, see Control-M Automation REST API Reference.

Response

The following example demonstrates a typical response to the build command. The response summarizes the amount of various elements created (such as folders, subfolders, jobs, and site standards) and indicates whether a Deploy Descriptor is applied.

The response also provides validation messages for site standards. An error message appears if validations are strictly enforced, or a warning message if validations are not strictly enforced.

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

Copy 
{
    "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
    }]
}