Control-M Automation API Administration

Control-M Automation API provides an automated interface to Control-M for the management of job workflows as code. For more information, see the Control-M Automation API documentation.

Control-M Automation API consists of the following components:

• Developer Kit: Contains REST API, CLI, and sample code

• Control-M Automation API server

• Configuration API server

The Control-M Automation API server is a Control-M/EM component that exposes Control-M REST API over HTTPS and is managed by the Control-M Web Server. When the Web Server starts up and shuts down, the emrestsrv process starts and stops with it. The default listening port, 8443, is a reversed proxy to localhost (127.0.0.1), port 32080.

Startup: > start_web_server

Shutdown: > stop_web_server

Additional procedures related to the Provision service in the Control-M Automation API are discussed in Control-M Automation API Provisioning.

You can apply authorizations to API services, as discussed in Control-M Automation API Authorizations.

You can manage Control-M Automation API as follows:

• Changing the Automation API Server Port

• Limiting Incoming Traffic through an API Gateway

• Configuring Automation API Session Timeout

• Allowing Session Tokens to Display in Responses to API Commands

• Setting the Log Level in Automation API

• Controlling the Database Connection for Stored Procedure Data

• Configuring Control-M Web Server to HTTPS

• Enabling a Caching Period of Control-M/Server Details

• Setting Annotations as Optional in API Commands

• Configuring Maximum Number of Run IDs Saved in the Control-M/EM Database

Changing the Automation API Server Port

The default ports for the Automation API server are 32080 and 32081.

This procedure describes how to change the Automation API server port and the Configuration API server port.

Begin

1. Run one of the following commands:

   • UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config

   • Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat

2. Do one of the following:

   • To change the default port number, run the following command:

     > automation_api_config --change_port 32081

   • To change to port number 32081 or any available port above 32081, run the following command:

     > automation_api_config --change_to_free_port 32081

   The Configuration API server is assigned the next port or the next free port after the specified port. In the example above, the Configuration API server might be assigned port number 32082.

   Applying the change in configuration restarts the API process (the emrestsrv process).

Limiting Incoming Traffic through an API Gateway

This procedure describes how to limit incoming traffic into the Automation API server or Configuration API server through an API gateway, allowing communication only from a specific port.

Begin

1. Run one of the following commands:

   • UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config

   • Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat

2. Run the following command:

   > automation_api_config --allowed_incoming_port <allowedPort>

   where <allowedPort> is the number of the port from which incoming traffic is allowed to pass through the API gateway to the Automation API Server or Configuration API server.

   Supported values range from 1025 to 65535. To allow traffic from all ports, type 0 (the default).

   Applying the change in configuration redeploys the API gateway in the Tomcat web application.

Configuring Automation API Session Timeout

This procedure describes how to configure the length of time that an Automation API session is allowed to remain idle before the session token times out.

Begin

1. Run one of the following commands:

   • UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config

   • Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat

2. Run the following command:

   > automation_api_config --token_timeout <session_token_timeout>

   where <session_token_timeout> is the time in seconds until the session token expires when the session has been idle. The default is 1,800 seconds (30 minutes).

   The maximum value that you can set is limited by the EM system parameter MaxUserTimeoutSec, which has a default of 10,800 seconds (3 hours).

   Due to internal processing controlled by the Sample Rate System environment variable (EM_REFRESH_INTERVAL), timing out of the session token might be delayed by up to 10 minutes (the default value of this environment variable).

Applying the change in configuration restarts the API process (the emrestsrv process).

Allowing Session Tokens to Display in Responses to API Commands

This procedure describes how to enable the display of session tokens in URIs within responses to API commands.

Begin

1. Run one of the following commands:

   • UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config

   • Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat

2. Run the following command:

   > automation_api_config --allow_token_in_uri true

   Applying the change in configuration restarts the API process (the emrestsrv process).

   To revert to the default display of API responses, which does not contain session tokens in URIs, run the command with a value of false:

   > automation_api_config --allow_token_in_uri false

Setting the Log Level in Automation API

This procedure describes how to set the log level of the Automation API server and Configuration API server.

Begin

1. Run one of the following commands:

   • UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config

   • Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat

2. Run the following command:

   > automation_api_config --set_log_level <logLevelOptions>

   where <logLevelOptions> is structured as server:logLevel or server:module=logLevel

   • server: one of the following server types:

     • aapi

     • capi

     • all

   • logLevel: one of the following log levels:

     • error

     • warn

     • info

     • debug

     • trace

     • default

   • module: one of the following modules:

     • root

     • server

     • server.lang,

     • saas

   • To change the log level of the Automation API server to debug, run the following command:

     automation_api_config --set_log_level aapi:debug

   • To change the log level of the Configuration API server to trace, run the following command:

     automation_api_config --set_log_level capi:trace

   • To restore the log level of all servers, run the following command:

     automation_api_config --set_log_level all:default

   • To change the log level of the server.lang module of the Automation API server to trace, run the following command:

     automation_api_config --set_log_level aapi:server.lang=trace

Controlling the Database Connection for Stored Procedure Data

This procedure describes how to enable retrieval (GET) of data for evaluation of Stored Procedures in a new format that contains full parameter details. This format enables you to use the connection profile to deploy Stored Procedures without accessing the database during deployment. However, to support the previous JSON format, API commands continue, by default, to GET Stored Procedure definitions in the old JSON format.

This option is available as of Control-M Automation API 9.0.21.030.

Begin

1. Run one of the following commands:

   • UNIX: $HOME/ctm_em/etc/emweb/automation-api/bin/automation_api_config

   • Windows: %EM_HOME%\emweb\automation-api\bin\automation_api_config.bat

2. Run the following command:

   > automation_api_config -speval false

   To revert to the default of retrieving Stored Procedure data in the old format:

   > automation_api_config -speval true

Configuring Control-M Web Server to HTTPS

This procedure describes how to configure Control-M Web Server to HTTPS using your own signed certificate. By default, a self-signed auto-generated certificate is used for HTTPS on port 8443. If you have previously configured Control-M Web Server to HTTPS, your configuration and port remain the same.

Begin

1. Navigate to <EM_HOME>\etc\emweb\tomcat\conf\server.xml

2. Replace keystoreFile="conf\emweb_unsigned.keystore" with a reference to your own certificate keystore, as described in Configuring Control-M/EM Web Server to work with HTTPS.

   You can harden the CLI by configuring the environment to disable communication using self-signed certificates, as described in Environment Service.

Enabling a Caching Period of Control-M/Server Details

This procedure describes how to configure a caching period of Control-M/Server details.

Use this procedure to improve performance of the config server:hostgroup:agents::get command, which retrieves a list of Agents in a host group, when many Agents are installed and configured.

Begin

1. Navigate to the <EM_HOME>\etc\emweb\configuration-api\bin\emconfigrstsrv file, and open it for editing.

2. Before the emrestcmd java command, define a new system environment variable named SECONDS_CONFIG_CTM_LIST_DESTINATION_CACHE, and set it to the relevant number of seconds.

   For example:

   export SECONDS_CONFIG_CTM_LIST_DESTINATION_CACHE=180

Setting Annotations as Optional in API Commands

This procedure describes how to set annotations as optional in API commands, even though annotations have been enabled in Control-M.

Control over the requirement for annotations in API commands is useful, for example, in the following scenario:

In earlier versions of Control-M Automation API (before support for annotations was introduced in version 9.0.19.000), you created many scripts. However, the API commands in these scripts do not specify any annotations. You now want to upgrade to a more recent version of the Control-M Automation API, but need more time to update your scripts and complete the migration.

Begin

1. From the Components Tree pane in the CCM, select the Control-M/EM component and from the Home tab, in the Definitions group, click System Parameters.

   The Control-M/EM System Parameters dialog box appears.

2. In the left pane, click Advanced.

   A list of defined system parameters is displayed on the right.

3. If the list of system parameters is long, filter the list by typing aapi in the Type field in the filter row at the top.

4. Double-click the SkipAnnotationValidation parameter.

   The Control-M/EM - Update System Parameter dialog box appears.

5. In the Value field, set the value to true (activate skipping).

6. Click Save.

   Annotation is set as optional. Now, whenever an API command is run without an annotation specified, a default annotation is used, with the subject "Automation API" and the description "Annotation was not provided by the user."

   When you no longer want to skip annotation validation, you can change the value to false in this system parameter.

Configuring Maximum Number of Run IDs Saved in the Control-M/EM Database

This procedure describes how to configure the maximum number of run IDs from Control-M Automation API commands that are stored in the Control-M/EM database. By default, a maximum of 2,000 most recent run IDs are saved in the Control-M/EM database, and you can raise this maximum, as necessary.

Begin

1. From the Components Tree pane in the CCM, select the Control-M/EM component and from the Home tab, in the Definitions group, click System Parameters.

   The Control-M/EM System Parameters dialog box appears.

2. In the left pane, click Advanced.

   A list of defined system parameters is displayed on the right.

3. If the list of system parameters is long, filter the list by typing aapi in the Type field in the filter row at the top.

4. Double-click the MaxRecentRunIds parameter.

   The Control-M/EM - Update System Parameter dialog box appears.

5. In the Value field, enter a new value, typically a value higher than the default maximum of 2,000 run IDs.

6. Click Save.