Build Service

The build service allows you 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.

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

CLI Syntax

The following shows the CLI syntax for the build command:

ctm build <definitionsFile> [deployDescriptorFile] [StandardsFile]

The following table describes the build command parameters.

Parameter

Description

<definitionsFile>

Defines the .json file or archive that contains code for jobs, folders, or calendars.

Valid formats:

  • .json

  • .zip or .tar.gz

Calendar definitions must be in .json format only.

[deployDescriptorFile]

(Optional) Defines the file that includes the original definitionsFile rules.

The rules enable you to transform Control-M JSON code properties. 

For detailed information, see Deploy Descriptor.

[StandardsFile]

(Optional) Defines the .json file that contains the Control-M environment site standards.

For detailed information, see Site Standards.

REST API Syntax

The following example shows the REST API syntax for the build command in 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 Python:

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 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.

The following shows an example of a typical response to the build command:

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
    }]
}