Set Object’s Manual State

Sets an object’s manual state. Returns the updated object.

The object will remain in specified State until it is manually unset with 'clear' flag.

You can also disable data collection for the specified object until the manual state is reset. To do this, set the unmanaged parameter to true in the request body. Check the example below.

Request

HTTP Request

PUT /node/api/objects/:id/manual-state

Permissions

objectPermissions & (modify-objects | manage-objects)

Path parameters

Parameter Type Description

Parameter	Type	Description
id	String `required`	The ID or discovery ID of the object whose manual state must be set.

String
required

The ID or discovery ID of the object whose manual state must be set.

Body parameters

Parameter Type Description

Parameter	Type	Description
stateId	String `required`	The ID of a state to be set.
clear	Boolean	Whether to clear a previously set state. If set to `true`, the `stateId` parameter isn’t required.
since	String	A timestamp since when the state should be set.
until	Integer	A timestamp when the state should be unset.
reason	String	The reason why the state was set.
clearedByState	Array	A list of states that trigger a cleaning of the current state.
unmanaged	Boolean	Whether the object receives data from agent during the currently set manual state.

stateId

String
required

The ID of a state to be set.

clear

Boolean

Whether to clear a previously set state. If set to true, the stateId parameter isn’t required.

since

String

A timestamp since when the state should be set.

until

Integer

A timestamp when the state should be unset.

reason

String

The reason why the state was set.

clearedByState

Array

A list of states that trigger a cleaning of the current state.

unmanaged

Boolean

Whether the object receives data from agent during the currently set manual state.

Request body

{
    "stateId": 3,
    "clear": false,
    "reason": "Testing"
}

You can set the time at which the object will switch to the specified state with the since parameter. At the timestamp, specified in the until field, the object will automatically reset back to the state it was in before you set it manually.

You can set either of these parameters or both at the same time.

{
    "stateId": 4,
    "reason": "Setting the timed state",
    "since": 1666281549581,
    "until": 1666282447355
}

You can also mark object as unmanaged. This means that this object will not receive stat data from agent and will ignore attempts to put data via the REST API, using Set Entity Stat, Set Link’s Stat, or Set Object’s Stat methods. To do this, set the unmanaged parameter to true:

{
    "stateId": 4,
    "reason": "Stopping data collection for this object",
    "unmanaged": true
}

You can use any state for unmanaged entities.

Response

Returns the object whose state was manually set. See the Object model for a list of fields that this request returns.

If the state was set, the object’s manual_state variable would contain the state’s ID, the reason and the ID of the user who set the state. If the state was cleared, the object’s manual_state variable would be set to null (even if manual state wasn’t set before). See the Manual State model for more information.

Example

Set manual state

Request

Here is how you can set a new state:

Bash
JavaScript
NodeJS
Python

login=<...>
password=<...>
saymon_hostname=<...>
object_id=<...>
url=https://$saymon_hostname/node/api/objects/$object_id/manual-state

curl -X PUT $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "stateId": 3,
    "clear": false,
    "reason": "Testing"
}
EOF

let login = <...>
let password = <...>
let saymonHostname = <...>
let objectId = <...>
let path = "/node/api/objects/" + objectId + "/manual-state";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Authorization", auth);
headers.append("Content-Type", "application/json");

let data = JSON.stringify({
    "stateId": 3,
    "clear": false,
    "reason": "Testing"
});

let requestOptions = {
    method: "PUT",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));

const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let objectId = <...>
let path = "/node/api/objects/" + objectId + "/manual-state";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "PUT",
    "hostname": saymonHostname,
    "headers": {
        "Authorization": auth,
        "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
    "stateId": 3,
    "clear": false,
    "reason": "Testing"
});

req.write(data);
req.end();

import requests

login = <...>
password = <...>
saymon_hostname = <...>
object_id = <...>
url = "https://" + saymon_hostname + "/node/api/objects/" + \
    object_id + "/manual-state";

body = {
    "stateId": 3,
    "clear": false,
    "reason": "Testing"
}

response = requests.request("PUT", url, json=body, auth=(login, password))
print(response.text)

Response

{
    "id": "5e21b85b308c3c66d64e07d2",
    "name": "CPU",
    "discovery_id": "example-CPU",
    "object_groups": [],
    "geoposition": [],
    "child_ref_ids": [],
    "child_link_ids": [],
    "child_ids": [],
    "parent_id": "5e21b85b308c3c66d64e07bc",
    "weight": 1,
    "tags": [],
    "last_state_update": 1585047151777,
    "updated": 1585047151770,
    "created": 1579268187099,
    "state_id": 7,
    "class_id": 4,
    "_stateConditionRefs": [],
    "operations": [],
    "properties": [],
    "client_data": "{...}",
    "manual_state": {
        "stateId": 3,
        "reason": "Testing",
        "by": "62c2f3ce80c8654892764d56"
    },
    "owner_id": "5e21b752308c3c66d64e072c"
}

Clear manual state

Here is how you can clear the state:

Request

Bash
JavaScript
NodeJS
Python

login=<...>
password=<...>
saymon_hostname=<...>
object_id=<...>
url=https://$saymon_hostname/node/api/objects/$object_id/manual-state

curl -X PUT $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "clear": true
}
EOF

let login = <...>
let password = <...>
let saymonHostname = <...>
let objectId = <...>
let path = "/node/api/objects/" + objectId + "/manual-state";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Authorization", auth);
headers.append("Content-Type", "application/json");

let data = JSON.stringify({
    "clear": true
});

let requestOptions = {
    method: "PUT",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));

const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let objectId = <...>
let path = "/node/api/objects/" + objectId + "/manual-state";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "PUT",
    "hostname": saymonHostname,
    "headers": {
        "Authorization": auth,
        "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
    "clear": true
});

req.write(data);
req.end();

import requests
import json

login = <...>
password = <...>
saymon_hostname = <...>
object_id = <...>
url = "https://" + saymon_hostname + "/node/api/objects/" + \
    object_id + "/manual-state";

body = {
    "clear": True
}

response = requests.request("PUT", url, json=body, auth=(login, password))
print(response.text)

Response

{
    "id": "5e21b85b308c3c66d64e07d2",
    "name": "CPU",
    "discovery_id": "example-CPU",
    "object_groups": [],
    "geoposition": [],
    "child_ref_ids": [],
    "child_link_ids": [],
    "child_ids": [],
    "parent_id": "5e21b85b308c3c66d64e07bc",
    "weight": 1,
    "tags": [],
    "last_state_update": 1585047151777,
    "updated": 1585047151770,
    "created": 1579268187099,
    "state_id": 7,
    "class_id": 4,
    "_stateConditionRefs": [],
    "operations": [],
    "properties": [],
    "client_data": "{...}",
    "manual_state": null,
    "owner_id": "5e21b752308c3c66d64e072c"
}

Set unmanaged state

Here is how you can clear the state:

Request

Bash
JavaScript
NodeJS
Python

login=<...>
password=<...>
saymon_hostname=<...>
object_id=<...>
url=https://$saymon_hostname/node/api/objects/$object_id/manual-state

curl -X PUT $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "stateId": 4,
    "reason": "Stopping data collection for this object",
    "unmanaged": true
}
EOF

let login = <...>
let password = <...>
let saymonHostname = <...>
let objectId = <...>
let path = "/node/api/objects/" + objectId + "/manual-state";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Authorization", auth);
headers.append("Content-Type", "application/json");

let data = JSON.stringify({
    "stateId": 4,
    "reason": "Stopping data collection for this object",
    "unmanaged": true
});

let requestOptions = {
    method: "PUT",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));

const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let objectId = <...>
let path = "/node/api/objects/" + objectId + "/manual-state";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "PUT",
    "hostname": saymonHostname,
    "headers": {
        "Authorization": auth,
        "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
    "stateId": 4,
    "reason": "Stopping data collection for this object",
    "unmanaged": true
});

req.write(data);
req.end();

import requests
import json

login = <...>
password = <...>
saymon_hostname = <...>
object_id = <...>
url = "https://" + saymon_hostname + "/node/api/objects/" + \
    object_id + "/manual-state";

body = {
    "stateId": 4,
    "reason": "Stopping data collection for this object",
    "unmanaged": true
}

response = requests.request("PUT", url, json=body, auth=(login, password))
print(response.text)

Response

{
    "id": "5e21b85b308c3c66d64e07d2",
    "name": "CPU",
    "discovery_id": "example-CPU",
    "object_groups": [],
    "geoposition": [],
    "child_ref_ids": [],
    "child_link_ids": [],
    "child_ids": [],
    "parent_id": "5e21b85b308c3c66d64e07bc",
    "weight": 1,
    "tags": [],
    "last_state_update": 1585047151777,
    "updated": 1585047151770,
    "created": 1579268187099,
    "state_id": 7,
    "class_id": 4,
    "_stateConditionRefs": [],
    "operations": [],
    "properties": [],
    "client_data": "{...}",
    "manual_state": {
        "stateId": 4,
        "reason": "Stopping data collection for this object",
        "unmanaged": true
    },
    "owner_id": "5e21b752308c3c66d64e072c"
}

Set Object’s Manual State

Request

HTTP Request

Permissions

Path parameters

Body parameters

Request body

Response

Example

Set manual state

Request

Response

Clear manual state

Request

Response

Set unmanaged state

Request

Response

See Also