×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
BMC TrueSight IT Data Analytics 11.0 Developing

Creating hosts with a REST API

Use this endpoint to create one or more hosts.

Notes

  • Before running this endpoint, you need to generate an authorization token by running the login endpoint. This token is used to authenticate a user into the product. You need to pass this token in the header each time you want to run the endpoint.
  • To log out from a given session, you need to run the logout endpoint.

For more information, see Developing.

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.

Host nameInputs
Host B
  • Collection Agent, "Agent1.bmc.com"
  • Tag name, "os" with corresponding tag values, "Windows" and "Linux".
Host C
  • Collection Agent, "Agent2.bmc.com"
  • Tag name, "tier" with corresponding tag values, "WebServer" and "AppServer".

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.

Parameter nameDescription
Basic details

name

Required

Name of the target host from which you want to collect data.

You can use the same value for the instance name and name parameters.

instanceName

Required

Custom name by which you might want to identify the target host. 

You can use the same value for the instance name and name parameters.

Collection Agent (or Collection Station) details: "agents": [{

agentName

Optional

Name of the Collection Agent (or Collection Station) that you want to associate with the host.

This Agent will be used for collecting the data from the target host.

enabled 

Optional, applicable only when you specify the agentName parameter.

Indicates whether the Collection Agent (or Collection Station) specified must be enabled or not.

Can be one of the following:

  • true: Set this value to enable the Collection Agent (or Collection Station) to collect data.
  • false: Set this value to stop the Collection Agent (or Collection Station) from collecting data.

Collection profile details: "collectionProfiles": [{

name

Optional

Name of the collection profile that you want to associate with the host.

Note: You can associate multiple collection profiles with a single host. To associate multiple collection profiles, you need to specify a comma-separated list of values. For more information, see Example 3: Create a host with advanced inputs.

Tag details: "tagsList": {

Tag names with corresponding values

Optional

Names of existing tags with corresponding values that you want to associate with the host.

A tag can have multiple values. These values need to be specified in the following format:

"tagsList": {

    "<tagName1>": ["<tagvalue1>", "<tagvalue2>"],

    "<tagName2>": ["<tagvalue1>", "<tagvalue2>"]

},

For more information, see Example 1: Create a single host with basic inputs.

User group details: "userGroupList": [{

userGroupName

Optional

Names of existing user groups that you want to associate with the host.

To associate multiple user groups, you need to specify a comma-separated list of values. For more information, see Example 3: Create a host with advanced inputs.

Note: The value is case sensitive.

By specifying user groups you can provide access to the data collected from this host to a particular set of users. To enable the user group permissions specified, you need to ensure that data access control is enabled at Administration > System Settings.

While creating data collectors, you can inherit the group access permissions enabled with this parameter by selecting the Inherit Host Level Access Groups From Target Host check box.

Response elements

The following sections help you understand the response elements:

Element definitions

The endpoint response contains the following main elements:

Response elementDescription

statusCode

String

A string describing the status code returned.

For more information, see HTTP status codes.

statusMessage 

String

Message explaining the reason for the response.

hosts

Array

Can be one of the following:
  • Successful response: Details of one or more hosts created.
    The parameters in the array have one-to-one mapping with the inputs specified in the request body.
  • Unsuccessful response: Details of the error – severity, error code, and error message.
  • Multiple status response: Based on the success or failure of multiple independent operations, the array can contain successful responses (hosts created) and unsuccessful responses (error details).

totalRecords

Long

The total number of hosts created by running the API.

pageSize

Long

Can be one of the following:

  • The default page size used for displaying configured hosts at Administration > Hosts.
  • The page size configured while running the API request.

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.

Status codeDescription
200Request completed successfully.
207Some hosts could not be created.
400

Invalid inputs:

  • Mandatory parameters are not specified.
  • Collection profile name does not exist.
  • One or more user group names do not exist.
  • Agent name does not exist or Agent status does not match.
  • Host-Agent combination already exists.
401Authorization error (invalid authorization token or authorization token not present).
500

Error occurred while processing the request. Occurrence of this error is rare.

For more information, see the error message. Alternatively, see the itda.log located at %BMC_ITDA_HOME%\logs.


Was this page helpful? Yes No Submitting... Thank you
Last modified by Melody Locke on Oct 20, 2017
developing endpoint

Comments

Log in or register to comment.

Developing
Deleting hosts with a REST API
© Copyright 2014-2017 BMC Software, Inc
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.