Host Group Configuration

The following API commands enable you to configure host groups:

config server:hostgroups::get
config server:hostgroup::update
config server:hostgroup::delete
config server:hostgroups:agents::get
config server:hostgroup:agents::get
config server:hostgroup:agent::add
config server:hostgroup:agent::delete

config server:hostgroups::getLink copied to clipboard

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 the server parameter defines the Control-M/Server name.

REST API Syntax

cURL:

Copy

server=IN01
curl -H "x-api-key: $token" "$endpoint/config/server/$server/hostgroups"

config server:hostgroup::updateLink copied to clipboard

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

Defines the Control-M/Server name.

hostgroup

Defines the host group name.

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 the Configuration domain, 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=IN01
hostgroup=myHostGroup
curl -H "x-api-token: $token" -H "Content-Type: application/json" -X POST --data "hostGroupDefinitions.json" "$endpoint/config/server/$server/hostgroup/$hostgroup"

config server:hostgroup::deleteLink copied to clipboard

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	Defines the Control-M/Server name.
hostgroup	Defines the host group name.

REST API Syntax

cURL:

Copy

server=IN01
hostgroup=myHostGroup
curl -H "x-api-token: $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup"

config server:hostgroups:agents::getLink copied to clipboard

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=IN01
curl -H "x-api-key: $token" "$endpoint/config/server/$server/hostgroups/agents"

config server:hostgroup:agents::getLink copied to clipboard

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.

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:hostgroup:agents::get <server> <hostgroup>

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

Parameter	Description
server	Defines the Control-M/Server name.
hostgroup	Defines the host group name.

REST API Syntax

cURL:

Copy

server=IN01
hostgroup=HostGroup1
curl -H "x-api-key: $token" "$endpoint/config/server/$server/hostgroup/$hostgroup/agents"

config server:hostgroup:agent::addLink copied to clipboard

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	Defines the Control-M/Server name.
hostgroup	Defines the host group name.
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.

REST API Syntax

cURL:

Copy

server=IN01
hostgroup=mygroup
host=myhost
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST --data "hostGroupDefinitions.json" "$endpoint/config/server/$server/hostgroup/$hostgroup/agent"

config server:hostgroup:agent::deleteLink copied to clipboard

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	Defines the Control-M/Server name.
hostgroup	Defines the host group name.
host	Defines the Agent hostname or alias. This is the logical name of the Agent.

REST API Syntax

cURL:

Copy

server=IN01
hostgroup=mygroup
host=myhost
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup/agent/$host"

Host Group Data FileLink copied to clipboard

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

{
   "applicationType": "OS",
   "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 PropertiesLink copied to clipboard

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

Property	Description
applicationType	Enables you to filter hosts based on the plug-ins that are installed and job types that can run. Values: OS: No filtering, for regular script or command jobs AFL: Control-M for Airflow (Control-M Web only) AI: Control-M Application Integrator (including Control-M Integrations) AP: Control-M Application Pack AWS: Control-M for AWS BACKUP: Control-M for Backup CLOUD: Control-M for Cloud COGNOS: Control-M for IBM Cognos DATABASE: Control-M for Databases DATASTAGE: Control-M for IBM InfoSphere DataStage ETL_INFA: Control-M for Informatica FILE_TRANS: Control-M for Advanced File Transfer HADOOP: Control-M for Hadoop JAVA: Control-M for Java MSG: Control-M for Messaging OEBS: Control-M for Oracle E-Business Suite PS8: Control-M for PeopleSoft SAP: Control-M for SAP WS: Control-M for Web Services Default: OS
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 PropertiesLink copied to clipboard

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" CopyCopied to clipboard `"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 CopyCopied to clipboard `"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). CopyCopied to clipboard `"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). CopyCopied to clipboard `"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. CopyCopied to clipboard `"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). CopyCopied to clipboard `"betweenTime": { "fromTime": "1415", "toTime": "1545" }`

Event Rule PropertiesLink copied to clipboard

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

Property	Description
name	Determines the event name.
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.

Property

Description

name

Determines the event name.

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.