Set Link’s Manual State

Sets a link’s manual state. Returns a JSON representation of the updated link.

Request

HTTP Request

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

Permissions

linkPermissions & (modify-links | manage-links)

Path parameters

Parameter Type Description

id

String
required

The ID of a link 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.

clearedByState

Array

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

reason

Boolean

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 link will switch to the specified state with the since parameter. At the timestamp, specified in the until field, the link 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 link whose state was manually set. See the Link model for a list of fields that this request returns.

If the state was set, the link’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 link’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=<...>
link_id=<...>
url=https://$saymon_hostname/node/api/links/$link_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 linkId = <...>
let path = "/node/api/links/" + linkId + "/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 linkId = <...>
let path = "/node/api/links/" + linkId + "/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 = <...>
link_id = <...>
url = "https://" + saymon_hostname + "/node/api/links/" + \
    link_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=<...>
link_id=<...>
url=https://$saymon_hostname/node/api/links/$link_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 linkId = <...>
let path = "/node/api/links/" + linkId + "/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 linkId = <...>
let path = "/node/api/links/" + linkId + "/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 = <...>
link_id = <...>
url = "https://" + saymon_hostname + "/node/api/links/" + \
    link_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