Config - Contacts
Object type: contact
Request URL: /rest/config/contact
Methods:
GET— List users.POST— Create users.PUT— Update users.DELETE— Unimplemented.
Listing Contacts Copied
Example GET and response Copied
Optional parameters:
s.COLUMN— searches by the column for the specified value. Invalid columns are silently ignored.
There are additional options for filtering by related objects:
s.roles.name— searches for users that have this role. If this parameter is repeated, it will list all users that have any of these roles. To find users that have all of the roles, you must include thec.roles.name=allparameter.s.roles.id— same ass.roles.name, but searches roles by id;c.roles.id=alllists users with all the requested roles.
$ opsview_rest --token-file /path/to/opsview_restapi_token --pretty GET 'config/contact?s.name=admin'
{
list => [
{
description => "System Administrator",
enable_tips => 0,
fullname => "Administrator",
homepage_id => 2,
id => 1,
language => "",
mylinks => [ ],
name => "admin",
notificationprofiles => [ ],
realm => "local",
ref => "/rest/config/contact/1",
roles => [
{ name => "Administrator", ref => "/rest/config/role/10" },
],
sharednotificationprofiles => [ ],
uncommitted => 0,
variables => [
{ name => "RSS_COLLAPSED", value => 1 },
{ name => "RSS_MAXIMUM_AGE", value => 1440 },
{ name => "RSS_MAXIMUM_ITEMS", value => 30 },
],
},
],
summary => { allrows => 4, page => 1, rows => 1, totalpages => 1, totalrows => 1 },
}
Contacts can have multiple roles. The roles field is an array of role objects, each with name and ref fields.
When listing contacts, you can filter by role using s.roles.name, s.roles.id, c.roles.name, or c.roles.id. The legacy s.role.* and c.role.* search parameters are also accepted and are mapped to the corresponding roles parameters.
Creating Contacts Copied
At least one role must be specified when creating a contact. If roles (or the legacy role field) is omitted or empty, the request returns HTTP 400 with the message Must specify at least one role.
Example POST Copied
$ opsview_rest --token-file /path/to/opsview_restapi_token --content-file=newcontact.json POST 'config/contact'
Contents of file newcontact.json:
{
"language": "",
"homepage_id": null,
"name": "newuser",
"variables": [],
"description": "",
"sharednotificationprofiles": [],
"notificationprofiles": [],
"mylinks": [],
"fullname": "New User",
"realm": "local",
"roles": [
{
"ref": "/rest/config/role/10",
"name": "Administrator"
}
],
"enable_tips": "1",
"uncommitted": "0"
}
The legacy role field (a single role object) is still accepted for backward compatibility and is converted to a one-element roles array.
Updating Contacts Copied
Example PUT Copied
$ opsview_rest --token-file /path/to/opsview_restapi_token PUT 'config/contact '{"name":"newuser", "fullname":"John Smith"}'
When updating an existing contact, you do not need to include roles unless you want to change them. However, if you include roles or role explicitly, at least one role must be specified. Sending an empty roles array or an empty role value returns HTTP 400 with the message Must specify at least one role.
When creating a contact via PUT (for example, upserting by name), at least one role must be specified in the same way as for POST.
Note
For more information on how to generate and use the token file, see opsview_rest documentation.