Creating hosts with a REST API

Use this endpoint to create one or more hosts.The [confluence_note] macro is a standalone macro and it cannot be used inline.
This topic contains the following information:

Related topics

Deleting-hosts-with-a-REST-API

Listing-host-details-with-a-REST-API

Modifying-tag-details-associated-with-hosts-with-a-REST-API

Modifying-user-groups-associated-with-hosts-with-a-REST-API

Enabling-or-disabling-Agents-with-a-REST-API

Endpoint overview

Use the POST method to create one or more hosts. Creation of hosts can simplify and automate the data collector creation process.

Typically, a host is created to capture details of the target host from which you want to collect data. In addition to this, you can specify other details such as the Collection Station (or Collection Agent) to be used for data collection, tag details, user group permissions, and collection profile details.

Request URL

POST <protocol>://<host>:<port>/olaengine/itdaws/hostservices/hosts?version=<apiVersion>

In the preceding URL, the following definitions apply:

  • <protocol> refers to the protocol that you want to use for communication with the Console Server.
  • <host> refers to the host name of the Console Server.
  • <port> refers to the port number of the Console Server. The default port is 9797.

  • (Optional) <apiVersion> refers to the API version. In this case, the value must be 2.5.

    Tip

    Generally the API version is the same as the product version on which the API can be run.

Request body

While running this request, at a minimum you need to specify the host name and instance name. Specifying other parameters such as tag details, user group permissions, and collection profile details is optional. For more information about the parameters, see Parameter definitions.

To understand the structure of the request body, see the examples.

Examples

The following examples illustrate the inputs for creating hosts by using the POST method.

Example 1: Create a single host by specifying Agent details, tag details, and user group details

The following example illustrates the inputs and response for creating a single host, "HostA" on the "localhost" machine with these details:

  • Collection Agent, "Agent1.bmc.com" with the status enabled.
  • Tag details:
    • Tag name, "os" with corresponding tag values, "Windows" and "Linux".
    • Tag name, "tier" with corresponding tag values, "WebServer" and "AppServer".
  • Group access permissions for existing user groups, "AppAdminGroup" and "TroubleshooterGroup".

Request URL

POST http://localhost:9797/olaengine/itdaws/hostservices/hosts?version=2.5
Request body
{
   "hosts": [{
       "host": {
           "name": "HostA",
           "instanceName": "HostA",
           "agents": [{
               "agentName": "Agent1.bmc.com",
               "enabled": "true"
            }],
           "tagsList": {
               "os": [
                   "Windows",
                   "Linux"
                ],
               "tier": [
                   "WebServer",
                   "AppServer"
                ]
            },
           "userGroupList": [{
               "userGroupName": "AppAdminGroup"
            }, {
               "userGroupName": "TroubleshooterGroup"
            }]
        }
    }]
}
Response
{
   "statusCode":   "200",
   "statusMessage":   "OK",
   "hosts": [{
       "host": {
           "id":   "9ad49715-8f39-4579-b327-7edfac545ed1",
           "name":   "HostA",
           "instanceName":   "HostA",
           "agents": [{
               "agentId":   "Agent1.bmc.com",
               "agentName":   "Agent1.bmc.com",
               "enabled":  true
            }],
           "tagsList": {
               "os": [
                   "Windows",
                   "Linux"
                ],
               "tier": [
                   "WebServer",
                   "AppServer"
                ]
            },
           "userGroupList": [{
               "userGroupId":   "1b9ef5be-850c-49fe-b931-da19336d763e",
               "userGroupName":   "AppAdminGroup",
               "deletable":  null,
               "organizationID":  null,
               "users":  null
            }, {
               "userGroupId":   "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
               "userGroupName":   "TroubleshooterGroup",
               "deletable":  null,
               "organizationID":  null,
               "users":  null
            }]
        }
    }],
   "totalRecords":  1,
   "pageSize":  0
}

Example 2: Create multiple hosts by specifying Agent details and tag details

The following example illustrates the inputs and response for creating hosts, "HostB" and "HostC" on the "localhost" machine.

The following table provides the inputs used while creating the hosts.The [confluence_table-plus] macro is a standalone macro and it cannot be used inline.

Request URL

POST http://localhost:9797/olaengine/itdaws/hostservices/hosts
Request body
{
   "hosts": [{
           "host": {

               "name": "HostB",
               "instanceName": "HostB",
               "agents": [{

                   "agentName": "Agent1.bmc.com",
                   "enabled": "true"
                }],
               "tagsList": {
                   "os": [
                       "Windows",
                       "Linux"
                    ]
                }
            }
        }, {
           "host": {
               "name": "HostC",
               "instanceName": "HostC",
               "enabled": "true",
               "agents": [{
                   "agentName": "Agent2.bmc.com",
                   "enabled": "true"
                }],
               "tagsList": {
                   "tier": [
                       "WebServer",
                       "AppServer"
                    ]
                }
            }
        }
    ]
}
Response
{
"statusCode": "200",
"statusMessage": "OK",
"hosts": [{
"host": {
"id": "ae9890d7-40c1-4ca5-82bd-e58b81ada358",
"name": "HostB",
"instanceName": "HostB",
"agents": [{
"agentId": "Agent1.bmc.com",
"agentName": "Agent1.bmc.com",
"enabled": true
}],
"tagsList": {
"os": ["Windows", "Linux"]
}
}
}, {
"host": {
"id": "d67953aa-5c93-443a-a826-c24af725050c",
"name": "HostC",
"instanceName": "HostC",
"agents": [{
"agentId": "Agent2.bmc.com",
"agentName": "Agent2.bmc.com",
"enabled": true
}],
"tagsList": {
"tier": ["WebServer", "AppServer"]
}
}
}],
"totalRecords": 2,
"pageSize": 0
}

Example 3: Create a host by specifying Agent details, tag details, user group details, and collection profile details

The following example illustrates the inputs and response for creating a host, "HostD" on the "localhost" machine with these details:

  • Collection Station, "clmhost.bmc.com"
  • Tag details:
    • Tag name, "os" with corresponding tag values, "Windows" and "Linux"
    • Tag name, "tier" with corresponding tag values, "WebServer" and "AppServer"
  • Group access permissions for existing user groups, "AppAdminGroup" and "TroubleshooterGroup".
  • Existing collection profiles, "ITDA Collection Metrics" and "ITDA Tomcat Metrics".

Request URL

POST http://localhost:9797/olaengine/itdaws/hostservices/hosts?version=2.5
Request body
{
   "hosts": [{
       "host": {
           "name": "HostD",
           "instanceName": "HostD",
           "agents": [{
               "agentName": "collection-station_clmhost.bmc.com",
               "enabled": "true"
            }],

           "collectionProfiles": [{
               "name": "ITDA Collection Metrics",
               "name": "ITDA Tomcat Metrics"
            }],

           "tagsList": {
               "os": [
                   "Windows",
                   "Linux"
                ],
               "tier": [
                   "WebServer",
                   "AppServer"
                ]
            },
           "userGroupList": [{
               "userGroupName": "AppAdminGroup"
            }, {
               "userGroupName": "TroubleshooterGroup"
            }]
        }
    }]
}
Response
{
   "statusCode":   "200",
   "statusMessage":   "OK",
   "hosts": [{
       "host": {
           "id":   "34c909a9-78ea-4082-a1b6-a19f334eb84e",
           "name":   "HostD",
           "instanceName":   "HostD",
           "agents": [{
               "agentId":   "collection-station_clm-pun-013622",
               "agentName":   "collection-station_clm-pun-013622",
               "enabled":  true
            }],
           "tagsList": {
               "os": [
                   "Windows",
                   "Linux"
                ],
               "tier": [
                   "WebServer",
                   "AppServer"
                ]
            },
           "userGroupList": [{
               "userGroupId":   "1b9ef5be-850c-49fe-b931-da19336d763e",
               "userGroupName":   "AppAdminGroup",
               "deletable":  null,
               "organizationID":  null,
               "users":  null
            }, {
               "userGroupId":   "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
               "userGroupName":   "TroubleshooterGroup",
               "deletable":  null,
               "organizationID":  null,
               "users":  null
            }]
        }
    }],
   "totalRecords":  1,
   "pageSize":  0
}

Parameter definitions

The following parameters can be used in the request body.The [confluence_table-plus] macro is a standalone macro and it cannot be used inline.

Response elements

The following sections help you understand the response elements:

Element definitions

The endpoint response contains the following main elements:The [confluence_table-plus] macro is a standalone macro and it cannot be used inline.

Successful response sample

See examples.

Unsuccessful response sample

{
"statusCode": "400",
"statusMessage": "Bad Request",
"hosts": [{
"messages": [{
"severity": "Error",
"code": "entity.does.not.exist",
"text": "Invalid Collection Profile Name. Collection Profile Name with value ITDA Tomcat Metrics does not exist."
}]
}],
"totalRecords": 1,
"pageSize": 0
}

Multiple status response sample

{
   "statusCode": "207",
   "statusMessage": "Multi Status",
   "hosts": [{
       "host": {
           "id": "a917cc5c-274d-4dae-92c3-215852da163b",
           "name": "HostA",
           "instanceName": "HostD",
           "agents": [{
               "agentId": "Agent1.bmc.com",
               "agentName": "Agent1.bmc.com",
               "enabled": true
            }],
           "tagsList": {
               "os": [
                   "Windows",
                   "Linux"
                ]
            },
           "userGroupList": [{
               "userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
               "userGroupName": "TroubleshooterGroup",
               "deletable": null,
               "organizationID": null,
               "users": null
            }]
        }
    }, {
       "messages": [{
           "severity": "Error",
           "code": "host.and.agent.duplicate.errror",
           "text": "Combination of Host Name and Agent Name should be unique. Host HostC with Agent Agent2.bmc.com already exists."
        }]
    }],
   "totalRecords": 2,
   "pageSize": 0
}

HTTP status codes

The following table describes the status codes that are likely to appear while working with this endpoint.

The [confluence_table-plus] macro is a standalone macro and it cannot be used inline.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*