Skip to content

Set Object's Manual State

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

Request

HTTP Request

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

Permissions

objectPermissions & (modify-objects | manage-objects)

Path parameters

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

Body parameters

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.

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
}

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 null. See the Manual State model for more information.

Example

Set manual state

Request

Here is how you can set a new state:

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

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"
}

See Also