Set Entity’s Manual State

Sets a manual state of a link or an object. Returns a JSON representation of the updated entity.

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

Request

HTTP Request

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

Permissions

entityPermissions

Path parameters

Parameter Type Description

id

String
required

The ID of an entity whose state should be set.

Body parameters

Parameter Type Description

stateId

String
required

The ID of a state to be set.

clear

String

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

until

Integer

A timestamp when the state should be unset.

clearedByStateId

Array

A list of states that triggers cleaning of the current state.

reason

String

The reason why the state was set.

since

Integer

A timestamp when the state was set.

Request body

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

You can set the time at which the entity will switch to the specified state with the since parameter. At the timestamp, specified in the until field, the entity 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 entity whose state was manually set. See the Link and Object models for a list of fields that this request returns.

If the state was set, the entity’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 entity’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=<...>
entity_id=<...>
url=https://$saymon_hostname/node/api/entities/$entity_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 entityId = <...>
let path = "/node/api/entities/" + entityId + "/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 entityId = <...>
let path = "/node/api/entities/" + entityId + "/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 = <...>
entity_id = <...>
url = "https://" + saymon_hostname + "/node/api/entities/" + \
    entity_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": "5e79fddb6ec5ea28e5105f65",
    "source": "5e79baae6ec5ea28e5105caa",
    "target": "5e79bbe86ec5ea28e5105d04",
    "owner_id": "5e21b752308c3c66d64e072c",
    "weight": 42,
    "tags": [],
    "last_state_update": 1585124964884,
    "updated": 1585124964878,
    "created": 1585053147047,
    "state_id": 9,
    "class_id": 35,
    "_stateConditionRefs": [],
    "operations": [],
    "properties": [
        {
            "name": "Bus_(computing).pdf",
            "value": "upload_a81d451eeebde3da52f7f83a6b83f78f",
            "type_id": 7,
            "id": "5e7a04dc6ec5ea28e5105f7e"
        }
    ],
    "manual_state": {
        "stateId": 3,
        "reason": "Testing",
        "by": "62c2f3ce80c8654892764d56"
    }
}

Clear manual state

Here is how you can clear a state:

Request

  • Bash

  • JavaScript

  • NodeJS

  • Python

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

curl -X PUT $url -u $login:$password \
    -H "Content-Type: application/json" \
    --data '{"clear": true}'
let login = <...>
let password = <...>
let saymonHostname = <...>
let entityId = <...>
let path = "/node/api/entities/" + entityId + "/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 entityId = <...>
let path = "/node/api/entities/" + entityId + "/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

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

body = {
    "clear": True
}

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

Response

{
    "id": "5e79fddb6ec5ea28e5105f65",
    "source": "5e79baae6ec5ea28e5105caa",
    "target": "5e79bbe86ec5ea28e5105d04",
    "owner_id": "5e21b752308c3c66d64e072c",
    "weight": 42,
    "tags": [],
    "last_state_update": 1585124964884,
    "updated": 1585124964878,
    "created": 1585053147047,
    "state_id": 9,
    "class_id": 35,
    "_stateConditionRefs": [],
    "operations": [],
    "properties": [
        {
            "name": "Bus_(computing).pdf",
            "value": "upload_a81d451eeebde3da52f7f83a6b83f78f",
            "type_id": 7,
            "id": "5e7a04dc6ec5ea28e5105f7e"
        }
    ],
    "manual_state": null
}

See Also