Host Group Configuration

The following API commands enable you to configure host groups:

config server:hostgroups::get

The config server:hostgroups::get command enables you to get a list of host groups defined in the Control-M/Server. Each entry is a host group name. The list includes only those host groups that you are authorized to manage.

CLI Syntax

Copy 
ctm config server:hostgroups::get <server>

Where server is the name of the Control-M/Server.

REST API Syntax

cURL:

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

curl -H "$AuthHeader" "$endpoint/config/server/$server/hostgroups"

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

config server:hostgroup::update

The config server:hostgroup::update command enables you to update the list of Agents that are in a host group. This overwrites the current list of Agents. If the specified host group does not exist, a new host group is created.

This API command is especially useful if you want to add or remove multiple Agents in a host group all at once, or create a new host group with multiple associated Agents.

For more information about host group definitions, including participation rules, see Host Group Data File.

CLI Syntax

Copy 
ctm config server:hostgroup::update <server> <hostgroup> -f <configuration file>

The following table describes the config server:hostgroup::update command parameters.

Parameter

Description

server

Name of Control-M/Server.

hostgroup

Name of host group.

configuration file

JSON file that contains definitions and participation rules of Control-M/Agents within the host group, as described in Host Group Data File.

The configuration file must contain definitions of at least one agent.

Participation rules limit the inclusion of the Agent host in the host group to scheduled dates and times or in response to events.

The hostgroupAgentParticipation object, which was used in the past to define participation rules, has been deprecated and has been replaced by the participationRules object. To support backward compatibility, this API command still recognizes the hostgroupAgentParticipation object.

As your starting point, you can use config server:hostgroup:agents::get to obtain a list of all defined Agents in a host group. Ensure that you edit the output from that command to match the required format described in Host Group Data File.

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

REST API Syntax

cURL, with one Agent defined in the host group:

Copy 
server=myServer
hostgroup=myHostGroup
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST --data "hostGroupDefinitions.json" "$endpoint/config/server/$server/hostgroup/$hostgroup"

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

config server:hostgroup::delete

The config server:hostgroup::delete command enables you to delete a specified host group from the Control-M/Server, provided that you are authorized to manage this host group.

CLI Syntax

Copy 
ctm config server:hostgroup::delete <server> <hostgroup>

The following table describes the config server:hostgroup::delete command parameters.

Parameter

Description

server

Name of Control-M/Server.

hostgroup

Name of host group.

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

REST API Syntax

cURL:

Copy 
server=myServer
hostgroup=myHostGroup
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup"

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

config server:hostgroups:agents::get

The config server:hostgroups:agents::get command enables you to get the list of host groups defined in the Control-M/Server, along with the list of Agents in each host group. The list includes only those host groups that you are authorized to manage.

For each Agent, details of the defined participation rules are provided. Participation rules limit the inclusion of the Agent host in the host group to scheduled dates and times or in response to events, as described in Host Group Data File.

The hostgroupAgentParticipation object, which was used in the past to define participation rules, has been deprecated and has been replaced by the participationRules object.

CLI Syntax

Copy 
ctm config server:hostgroups:agents::get <server>

where server is the name of a Control-M/Server.

REST API Syntax

cURL:

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

curl -H "$AuthHeader" "$endpoint/config/server/$server/hostgroups/agents"

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

config server:hostgroup:agents::get

The config server:hostgroup:agents::get command enables you to get the list of Agents in a host group, provided that you are authorized to manage this host group. Each entry is the logical name of an Agent.

For each Agent, details of the defined participation rules are provided. Participation rules limit the inclusion of the Agent host in the host group to scheduled dates and times or in response to events, as described in Host Group Data File.

The hostgroupAgentParticipation object, which was used in the past to define participation rules, has been deprecated and has been replaced by the participationRules object.

You must have Control-M/EMversion 9.0.21 or higher to run this command.

CLI Syntax

Copy 
ctm config server:hostgroup:agents::get <server> <hostgroup>

The following table describes the config server:hostgroup:agents::get command parameters.

Parameter

Description

server

Defines the name of a Control-M/Server.

hostgroup

Defines the name of a host group.

REST API Syntax

cURL:

Copy 
server=controlm
hostgroup=HostGroup1
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/server/$server/hostgroup/$hostgroup/agents"

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

config server:hostgroup:agent::add

The config server:hostgroup:agent::add command enables you to add an Agent to a host group and creates the host group if it does not exist.

The response lists the Agent hosts in the host group after the action is completed, along with details of participation rules defined for each Agent host, as described in Host Group Data File.

CLI Syntax

Copy 
ctm config server:hostgroup:agent::add <server> <hostgroup> <host> [-f <configuration file>]

The following table describes the config server:hostgroup:agent::add command parameters.

Parameter

Description

server

Name of Control-M/Server.

hostgroup

Name of host group.

host

Name of host or alias of the Agent. This is the logical name of the Agent.

configuration file

(Optional) JSON file that contains additional parameters and definitions of participation rules, as described in Host Group Data File.

Participation rules limit the inclusion of the Agent host in the host group to scheduled dates and times or in response to events.

The hostgroupAgentParticipation object, which was used in the past to define participation rules, has been deprecated and has been replaced by the participationRules object. To support backward compatibility, this API command still recognizes the hostgroupAgentParticipation object.

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

REST API Syntax

cURL:

Copy 
server=controlm
hostgroup=mygroup
host=myhost
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST --data "hostGroupDefinitions.json" "$endpoint/config/server/$server/hostgroup/$hostgroup/agent"

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

config server:hostgroup:agent::delete

The config server:hostgroup:agent::delete command enables you to remove an Agent from a host group, provided that you are authorized to manage this host group. If the group is empty after this deletion, it is also deleted.

The response lists the Agent hosts in the host group after the action is completed, along with details of participation rules defined for each Agent host, as described in Host Group Data File.

CLI Syntax

Copy 
ctm config server:hostgroup:agent::delete <server> <hostgroup> <host>

The following table describes the config server:hostgroup:agent::delete command parameters.

Parameter

Description

server

Name of Control-M/Server.

hostgroup

Name of host group.

host

Name of host or alias of the Agent. This is the logical name of the Agent.

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

REST API Syntax

cURL:

Copy 
server=controlm
hostgroup=mygroup
host=myhost
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup/agent/$host"

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

Host Group Data File

The Host Group Data File code sample shows the definitions of an Agent host in a configuration file that you can submit as a payload JSON file using the config server:hostgroup:agent::add API command.

Copy 
{
   "host": "agent2",
   "tag": "abcd",
   "participationRules": [
   {
      "ruleType": "EVENT",
      "event":
      {
         "name": "ABCD",
         "runDate": "1208"
      }
   },
   {
      "ruleType": "DATE_TIME",
      "dateTime":
      {
         "date": 
         {
            "betweenDate":
            {
               "fromDate": "20221104",
               "toDate": "20221108"
            }
         }, 
         "time": 
         {
            "betweenTime": 
            {
               "fromTime": "1400",
               "toTime": "1500"
            }
         }   
      }
   } ]
}

The following code sample shows the definitions of multiple Agent hosts in a configuration file that you can submit using the config server:hostgroup::update API command.

Copy 
{
   "tag": "abcd",
   "agentslist": [
   {
      "host": "Agent1",
      "participationRules": [
      {
         "ruleType": "EVENT",
         "event": 
         {
            "name": "aaa1",
            "runDate": "1208"
         }
      } ]
   },
   {
      "host": "Agent2",
      "participationRules": [
      {
         "ruleType": "DATE_TIME",
         "dateTime":
         {
            "date":
            {
               "betweenDate": 
               {
                  "fromDate": "20221104",
                  "toDate": "20221108"
               }
            }, 
            "time":
            {
               "betweenTime":
               {
                  "fromTime": "1400",
                  "toTime": "1500"
               }
            }   
         }
      } ]
   } ]
}

General Host Properties

The following table describes the General Host properties that are available for Control-M/Agents defined in the configuration file.

Property

Description

tag

Defines an optional tag associated with the host group and each of the Control-M/Agents in it, used in Role-Based Administration (RBA).

You can define a tag only during the creation of a host group. You cannot change the tag after the host group is created.

Tags can contain alphanumeric characters, as well as the underscore character, and can be up to 85 characters long.

host

Defines the host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent.

participationRules

Lists the defined rules that limit the inclusion of the Agent host in the host group to scheduled dates and times or in response to events.

ruleType

Determines the type of participation rule:

  • DATE_TIME: The Agent host is included in the host group only during scheduled dates and times. See DateTime Rule Properties. 

  • EVENT: The Agent host is included in the host group only in response to a specific event. See Event Rule Properties.

DateTime Rule Properties

The following table describes the DateTime Rule properties that define DateTime rules under a dateTime object.

Property

Description

date

Defines dates for inclusion of the Agent host in the host group.

Under date, use one of the following types of date definitions:

  • allDays

  • everyWeekDays

  • betweenDate

  • betweenDateTime

  • betweenWeekDayTime

  • onDates

allDays

Schedules the inclusion of the Agent host in the host group on all days.

Values: true|false

If you set allDays to false, you must include a second date definition.

everyWeekDays

Schedules week days for the inclusion of the Agent host in the host group.

Values: At least one of the following:

  • "SUN"

  • "MON"

  • "TUE"

  • "WED"

  • "THU"

  • "FRI"

  • "SAT"

Copy 
"everyWeekDays": ["MON", "WED", "FRI"]

betweenDate

Schedules the inclusion of the Agent host in the host group to a range of calendar dates, between a fromDate and a toDate.

Format: YYYYMMDD

Copy 
"betweenDate": 
{
   "fromDate": "20221104",
   "toDate": "20221108"
}

betweenDateTime

Schedules the inclusion of the Agent host in the host group to a time range between specified calendar dates and times. 

Format:

  • Dates: YYYYMMDD

  • Times: hhmm, where mm is rounded to a quarter of the hour (00, 15, 30, or 45).

Copy 
"betweenDateTime": 
{
   "fromDate": "20221104",
   "fromTime": "1230",
   "toDate": "20221104",
   "toTime": "1430"
}

betweenWeekDayTime

Schedules the inclusion of the Agent host in the host group to a time range between specified week days and times. 

Format:

  • Week Days: "SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT".

  • Times: hhmm, where mm is rounded to a quarter of the hour (00, 15, 30, or 45).

Copy 
"betweenWeekDayTime":
{
   "fromWeekDay": "MON",
   "fromTime": "1230",
   "toWeekDay": "TUE",
   "toTime": "1430"
}

onDates

Defines specific calendar dates for the inclusion of the Agent host in the host group.

Format:

  • At least one YYYYMMDD date.

  • 1–100 dates.

Copy 
"onDates": ["20221116", "20221123"]

time

Defines a time range on the scheduled dates for inclusion of the Agent host in the host group.

You can combine time definitions with the following date definitions:

  • allDays

  • everyWeekDays

  • betweenDate

  • onDates

Under time, use one of the following types of time definitions:

  • allHours

  • betweenTime

allHours

Schedules the inclusion of the Agent host in the host group at all hours of the day (for the specified dates).

Values: true|false

If you set allHours to false, you must also include the betweenTime property.

betweenTime

Schedules the inclusion of the Agent host in the host group to a time range, between a fromTime and a toTime.

Format: hhmm, where mm is rounded to a quarter of the hour (00, 15, 30, or 45).

Copy 
"betweenTime":
{
   "fromTime": "1415",
   "toTime": "1545"
}

Event Rule Properties

The following table describes the Event Rule properties that define event-type rules under an event object.

Property

Description

name

Determines the name of the event.

runDate

Determines the date to schedule the event.

  • MMDD: A specific date in MMDD format.

    0511

  • AnyDate: Any scheduled date.

  • RunDate: Control-M scheduled date.

  • NoDate: Not date-specific.