Creating hosts 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.
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
- Example 2: Create multiple hosts by specifying Agent details and tag details
- Example 3: Create a host by specifying Agent details, tag details, user group details, and collection profile details
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
"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"
}]
}
}]
}
"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.
Request URL
"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"
]
}
}
}
]
}
"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
"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"
}]
}
}]
}
"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.
Response elements
The following sections help you understand the response elements:
- Element definitions
- Successful response sample
- Unsuccessful response sample
- Multiple status response sample
Element definitions
The endpoint response contains the following main elements:
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.