Control-M Automation API Administration

Control-M Automation API consists of the following components:

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 is 8443, that is a reversed proxy to localhost (127.0.0.1), port 48080.

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

Changing the Automation API Server Port

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

The default port for the Automation API server is 48080.

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 48081

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

      > automation_api_config --change_to_free_port 48081

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

    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, use a value of 0 (the default).

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

Limiting API Connections to a Specific GUI Server

This procedure describes how to limit Automation API connections to a specific Control-M/EM GUI Server. By default, the Automation API connects with any available GUI server. You can set a specific GUI server as the only GUI server to which the Automation API can connect.

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 set a specific GUI server for association with the Automation API:

      > automation_api_config --gui_server <server_name>

    • To remove the limitation and revert to the default behavior, that is, Automation API connects to any available GUI server:

      > automation_api_config --gui_server

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

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 1800 seconds (30 minutes).

    The maximum value that you can set is limited by the EM system parameter MaxUserTimeoutSec, which has a default of 10800 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 --token_timeout <session_token_timeout>

    > automation_api_config --set_log_level <logLevelOptions>

    where <logLevelOptions> is structured as: server:logLevel

    For server, specify one of the following values: aapi, capi, all

    For logLevel, specify one of the following values: error, warn, info, debug, trace, default

    To change the log level of the Automation API server to debug: automation_api_config --set_log_level aapi:debug

    To change the log level of the Configuration API server to trace: automation_api_config --set_log_level capi:trace

    To restore the log level of all servers: automation_api_config --set_log_level all:default

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 2000 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 2000 run IDs).

  6. Click Save.