Control-M/EM Configuration

The following API commands enable you to configure Control-M/EM to manage, monitor and troubleshoot Control-M/EM servers, their databases, components, and services.

config em:agentsLog::get

The config em:agentsLog::get command enables you to get the contents of the Control-M/EM Configuration Agents log. This log lists the events and monitoring actions that the Configuration Agents perform on all Control-M/EM components, such as starting up and shutting down components and checking database connections.

  • CLI

  • REST

ctm config em:agentsLog::get

The following example shows the REST API syntax for the config em:agentsLog::get command in cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
curl -H "$AuthHeader" "$endpoint/config/em/agentsLog"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Response

The following example response shows two log messages. Each message is identified by its host, entry time, and full message text.

Copy 
{
    "host": "host-1-wat2",
    "entryTime": "2025-04-02T08:47:50Z",
    "message": "Component {Gateway/host-1-wat2/abc3/} activate retries exhausted."
},
{
    "host": "host-2-wat2",
    "entryTime": "2025-04-02T08:48:10Z",
    "message": "State of component {CMS/host-2-wat2/abc3/} changed from 'Down' to 'Warning' "
}

config em:component::get

The config em:component::get command enables you to get the definitions of a Control-M/EM component.

  • CLI

  • REST

ctm config em:component::get <host> <type> <name>

The following example shows the REST API syntax for the config em:component::get command in cURL:

Copy 
host=host3
type=Web_Server
name=logical_name
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/em/component/$host/$type/$name"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config em:component::get command parameters.

Parameter

Description

host

Defines the hostname of the server where the Control-M/EM component is running.

type

Determines one of the following Control-M/EM component types:

  • Forecast_Server

  • GCS: Global Events Server

  • GUI_Server

  • Self_Service_Server

  • BIM: SLA Management

  • ARCHIVE: Workload Archiving Server

  • Web Server

  • CMS: Configuration Management Server

  • Gateway

name

Defines the logical name of the EM component.

Response

The following example shows a response to the config em:component::get command for a Forecast Server. You can use such a response as the starting point for a configuration file that you can submit when you add a component or update a component. For descriptions of the parameters in the response, see the config em:component::add command or the config em:component::update command.

Copy 
{
   "name":"server2",
   "type":"Forecast_Server",
   "host":"host-1-wat2",
   "desiredState":"Down",
   "checkInterval":20,
   "additionalParameters":"flag"
}

 

config em:component::add

The config em:component::add command enables you to add a component for management by Control-M/EM.

Various types of components are available, including components that handle global events, forecast scheduling, and monitor batch and Self Service operations. BMC recommends to load-balance these components across distributed environments to ensure optimal performance.

  • CLI

  • REST

ctm config em:component::add [host] [type] [name] [desiredState] [checkInterval] [additionalParameters] [guiServerName] [-f <configuration file>]

The following example shows the REST API syntax for the config em:component::add command in cURL:

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

curl -X POST -H "$AuthHeader" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" "$endpoint/config/em/component"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config em:component::add command parameters.

Parameter

Description

name

Defines the logical name of the EM component.

The following components must always receive the same name:

  • WS for a Web_Server

  • GCS

type

Determines one of the following Control-M/EM component types:

  • Forecast_Server

  • GCS: Global Events Server

  • GUI_Server

  • Self_Service_Server

  • BIM: SLA Management

  • ARCHIVE: Workload Archiving Server

  • Web_Server

  • Gateway

host

Defines the hostname of the server where the Control-M/EM component is running.

desiredState

Determines one of the following states for the Control-M/EM component:

  • Up

  • Down

  • Ignored

checkInterval

Defines an interval, in seconds, for checking the component status.

Valid Values: 1-100

additionalParameters

Defines additional startup options for the component.

This parameter is not relevant for an ARCHIVE component.

guiServerName

Defines the name of the GUI Server connected to this Control-M/EM component.

This parameter is relevant only for the following component types:

  • BIM

  • Self_Service_Server

  • ARCHIVE

configuration file

(Optional) Defines a pathname to a JSON file that contains component definitions, as shown in the following example:

Copy 
{
   "name":"gui",
   "type":"Forecast_Server",
   "host":"host-1-wat2",
   "desiredState":"Down",
   "checkInterval":20,
   "additionalParameters":"flag"
}

The use of a configuration file replaces all other parameters in the command. You can use the response from config em:component::get as the starting point for your configuration file.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em:component::update

The config em:component::update command enables you to update the definitions of a component managed by Control-M/EM.

  • CLI

  • REST

ctm config em:component::update [host] [type] [name] [desiredState] [checkInterval] [additionalParameters] [guiServerName] [-f <configuration file>]

The following example shows the REST API syntax for the config em:component::update command in cURL:

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

curl -X PUT -H "$AuthHeader" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" "$endpoint/config/em/component"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config em:component::update command parameters.

Parameter

Description

name

Defines the logical name of the EM component.

Several components must always receive the same name, as follows:

  • WS for a Web_Server

  • CMS

  • GCS

type

Determines one of the following Control-M/EM component types:

  • Forecast_Server

  • GCS: Global Events Server

  • GUI_Server

  • Self_Service_Server

  • BIM: SLA Management

  • ARCHIVE: Workload Archiving Server

  • Web Server

  • CMS: Configuration Management Server

  • Gateway

host

Defines the hostname of the server where the Control-M/EM component is running.

desiredState

Determines one of the following states for the Control-M/EM component:

  • Up

  • Down

  • Ignored

  • Recycle

checkInterval

Defines an interval, in seconds, for checking the component status.

Valid Values: 1-100

additionalParameters

Defines additional startup options for the component.

This parameter is not relevant for an ARCHIVE component.

guiServerName

Defines the name of the GUI Server connected to this Control-M/EM component.

This parameter is relevant only for the following component types:

  • BIM

  • Self_Service_Server

  • ARCHIVE

configuration file

(Optional) Defines a pathname to a JSON file that contains component definitions, as shown in the following example:

Copy 
{
   "name":"gui",
   "type":"Forecast_Server",
   "host":"host-1-wat2",
   "desiredState":"Down",
   "checkInterval":20,
   "additionalParameters":"flag"
}

The use of a configuration file replaces all other parameters in the command. You can use the response from config em:component::get as the starting point for your configuration file.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em:component::delete

The config em:component::delete command enables you to delete a component managed by Control-M/EM.

  • CLI

  • REST

ctm config em:component::delete <host> <type> <name>

The following example shows the REST API syntax for the config em:component::delete command in cURL:

Copy 
host=host3
type=Web_Server
name=logical_name
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -X DELETE -H "$AuthHeader" \
"$endpoint/config/em/component/$host/$type/$name"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config em:component::delete command parameters.

Parameter

Description

host

Defines the hostname of the server where the Control-M/EM component is running.

type

Determines one of the following Control-M/EM component types:

  • Forecast_Server

  • GCS: Global Events Server

  • GUI_Server

  • Self_Service_Server

  • BIM: SLA Management

  • ARCHIVE: Workload Archiving Server

  • Gateway

name

Defines the logical name of the EM component.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em:component::desiredState

The config em:component::desiredState command enables you to change the desired state of a component managed by Control-M/EM.

  • CLI

  • REST

ctm config em:component::desiredState <host> <type> <name> <desiredState> [extension] [-f <configuration file>]

The following example shows the REST API syntax for the config em:component::desiredState command in cURL:

Copy 
host=host3
type=Web_Server
name=logical_name
desiredState=Recycle
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" \
"$endpoint/config/em/component/$host/$type/$name/desiredState/$desiredState"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config em:component::desiredState command parameters.

Parameter

Description

type

Determines one of the following Control-M/EM component types:

  • Forecast_Server

  • GCS: Global Events Server

  • GUI_Server

  • Self_Service_Server

  • BIM: SLA Management

  • ARCHIVE: Workload Archiving Server

  • Web Server

  • CMS: Configuration Management Server

  • Gateway

  • service

name

Defines the logical name of the EM component.

Several components must always receive the same name, as follows:

  • WS for a Web_Server

  • CMS

  • GCS

host

Defines the hostname of the server where the Control-M/EM component is running.

desiredState

Determines one of the following states for the Control-M/EM component:

  • Up

  • Down

  • Ignored

  • Recycle

extension

Defines the extension of a service-type component, as displayed in the Service Name column in the list of services.

configuration file

(Optional) Defines a pathname to a JSON file that contains component definitions, as shown in the following example:

Copy 
{
   "type":"Forecast_Server",
   "name":"host-1-wat2",
   "host":"host-1-wat2",
   "desiredState":"Recycle"
}

The use of a configuration file replaces all other parameters in the command.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em:db::space

The config em:db::space command retrieves current Control-M/EM database usage statistics.

  • CLI

  • REST

ctm config em:db::space

The following example shows the REST API syntax for the config em:db::space command in cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
curl -X POST -H "$AuthHeader" "$endpoint/config/em/db/space"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Response

The following example shows a response to the ctm config em:db::space command:

Copy 
[
   {
      "name": "emdb",
      "type": "data + log",
      "size": "68946 MB",
      "free": "68923 MB",
      "used": "23 MB",
      "usedPercentage": "0.03%",
      "location": "Control-M Installation Device"
   }
]

config em:db::details

The config em:db::details command gets current Control-M/EM database details.

  • CLI

  • REST

ctm config em:db::details

The following example shows the REST API syntax for the config em:db::details command in cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
curl -H "$AuthHeader" "$endpoint/config/em/db/details"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Response

The following example shows a response to the ctm config em:db::details command:

Copy 
{
   "name": "emdb@dba-5-wat1:5432",
   "type": "PostgreSQL",
   "version": "15.3",
   "host": "dba-5-wat1",
   "port": "5432",
   "schemaName": "emdb",
   "pgattributes": {
      "replicationStatus": "OFF",
      "diskSpace": 68924,
      "archivingStatus": 0,
      "archivingDiskSpace": 0,
      "postgresDef": {
         "secondaryDBHost": "",
         "archivingPath": "",
         "primaryDBLogPath": "/home/dbauser/ctm_em/pgsql/data/pg_log",
         "secondaryDBLogPath": ""
      }
   }
}