New Documentation

   

Control-M Automation API Documentation has moved to a new location, with a new design to enhance ease of use.

Environment service

The Environment service enables you to manage environments, including defining and selecting the Control-M environment to use. An environment is a combination of an endPoint and API token

An endPoint has the following format:

https://<controlmEndPointHost>/automation-api

The Helix Control-M endpoint host has the following format:  <tenant-name>-aapi.prod.controlm.com.

Environments are saved in the env.json file, which is located under the .ctm folder, on the home user that has read/write permissions only for the logged in user. Sensitive information, such as passwords and tokens, is encrypted in the env.json file.

For example, the following command adds an environment named myEnvironment. In this command, you must include a valid token, as described in Authentication service.

ctm environment add myEnvironment "https://tenant-123-aapi.prod.controlm.com/automation-api" "<token>"

environment show

Returns a list of all defined environments.

CLI Syntax

CLI
ctm environment show

environment add

Adds a new environment for a Control-M instance.

CLI Syntax

CLI
ctm environment add <env> <endPoint> <token>

Where:

Parameter

Description

<env>

Environment name

<endPoint>

Control-M REST API endPoint

<token>

An API authentication token that allows the logged-in user to submit API requests

For more about tokens, see Authentication service.

Note

While the environment is added, it is checked for its policy regarding certificates. If the environment is currently set to accept self-signed certificates, a warning is displayed. If you want to apply a stricter policy of accepting only certificates signed by a trusted Certificate Authority (and not accepting self-signed certificates), you can use the ctm environment configure command to set the rootCertificateRequired parameter to true.

environment set 

Sets the default environment for interactive work. All commands are sent to this environment unless a different environment is defined using the -e option.

Note

When no environments are defined and you add the very first environment (using the environment add command), that first environment is automatically set as the default. Later, after additional environments have been defined, use this command to set a new default.

CLI Syntax

CLI
ctm environment set <env>

Where:

Parameter

Description

<env>

Environment name

environment delete

Deletes an environment.

CLI Syntax

CLI
ctm environment delete <env>

Where:

Parameter

Description

<env>

Environment name

environment update

Updates an environment property. The property <name> can be an endPoint and token, or additionalLoginHeader.

CLI Syntax

CLI
 >ctm environment update <env> <name> <value>

Where:

Parameter

Description

<env>

Environment name

<name>

The name of the property, one of the following:

  • endPoint
  • keyToken
  • additionalLoginHeader

<value>

Property value for the specified property name:

PropertyDescription
endpointA URL that points to the endpoint and begins with https.
keyToken

Name of an authentication token that allows the logged-in user to submit API requests

For more about tokens, see Authentication service.

additionalLoginHeader

An additional header to include in login requests sent by the CLI, with the following format:

“Header_Name:Header_value”

environment copy 

Duplicates an environment. 

CLI Syntax

CLI
ctm environment <env> <newEnv>

Where:

Parameter

Description

<env>

Environment name

<newEnv>

Name of the new environment

environment load 

Enables you to load one or more predefined environments using the env.json file.

CLI Syntax

CLI
ctm environment load <enviromentsFile>

Where:

Parameter

Description

<enviromentsFile>

The env.json file, which is located under the .ctm folder on the home user that has read/write permissions only for the logged in user.

Note: Do not encrypt sensitive information, such as passwords and tokens, in the env.json file. This sensitive information is encrypted automatically when the file is loaded.

environment configure

This command allows you to set parameters for all environments.

CLI Syntax

CLI
ctm environment configure <setting name> [setting value]

Where:

Parameter

Description

<setting name>

Parameter name

[setting value]

Parameter value

Possible parameters:

ParameterValueDefaultDescription
rootCertificateRequiredfalse | truefalse

Disable API calls that use a self-signed HTTPS certificate, and allow only certificates that are signed by a trusted Certificate Authority.

By default, self-signed certificates are allowed.

EXT_APPLICATION_ARTIFACTS_JSON_URLpath to local repository of imagesN/ASet a path to a local repository of provisioning images, overriding the location used by default for provisioning actions performed by the  Provision service.
EXT_AUTO_DEPLOYpath to local repository of installation artifactsN/ASet a path to a local repository of installation artifacts for provisioning actions performed by the Provision service.
listenerLogSizeMbmaximum log size in megabytes10 MB

The maximum size of Alerts listener logs stored in <HOME>/.ctm/logs.

listenerMaxFileCountnumber of log files to save10 logsThe number of most recent Alerts listener log files to save in <HOME>/.ctm/logs.
listenerLogLevel

In descending severity and ascending detail:

  • error
  • warn
  • info
  • debug
  • trace
infoThe level of severity and detail of messages in the Alerts listener logs stored in <HOME>/.ctm/logs.
Was this page helpful? Yes No Submitting... Thank you

Comments