Introduction
The SLV NorthBound API allows developers to access data, features and services from a SLV Central Management Server. This includes the configuration and the geolocalization of smart city devices, the analysis of failures and energy consumptions and the real time control and command of devices.
The SLV API provides answers in two formats, JSON and XML.
This set of methods is updated periodically with new ones. We may occasionally deprecate features. If you have a problem, please reach out to us at support@streetlight-vision.com
We provide code examples in Python and Shell. They can be viewed in the dark area to the right.
Version history
7.19 - 2021.12.16
- Added three new fields unitKey, unitLabel and unitShorthand in the response of getDeviceMeteringValueDescriptors API
7.18 - 2021.07.19
- Added new property value support for retrieve version number api
7.17 - 2021.06.30
- Renamed chapter 13 "Reports" to "Scheduled reports"
- Added a new chapter On-demand reports
- Added a new chapter Helper methods
7.16 - 2021.03.05
- Added a new chapter Authorization
- Added a new chapter TLS support
- Removed the "admin" fields of the user-related example responses
- Added new methods to manage roles for user profiles
- Included the 'id' field into the example responses of endpoints returning Profiles
7.14 - 2020.09.25
- Added methods for controlling multiple devices at once in the Real-time control chapter
7.12
- Added chapters Reports, Alarms and Alarm instances
7.10
- Updated the Authentication chapter with notes regarding CAAS single-sign on
7.8
- Updated the Authentication chapter with CSRF token information
- Added apis SwitchOnExt and SwitchOffExt to control the relays of Cabinet controller device category
6.1.1
- Moved to this new documentation format
Authentication
In SLV 6 and SLV 7 until 7.7
Authentication to the API is performed via HTTP Basic Auth.
Your SLV CMS credentials serve as API credentials as well. They are represented in the code examples by USERNAME and PASSWORD.
API requests without authentication will fail with some random-looking HTML content.
To authenticate against an SLV CMS using HTTP Basic Auth, use the following code:
import urllib.request
# This code assumes that all requests will be made with urllib.request
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm="Authentication required",
uri=HOST,
user=USERNAME,
passwd=PASSWORD)
opener = urllib.request.build_opener(auth_handler)
urllib.request.install_opener(opener)
# With shell, you can just pass your username and password with each request
curl "api_endpoint_here"
-u USERNAME:PASSWORD
Depending on your programmaing language, you may have to specify a URI or hostname. In the Python example, it is represented by the HOST parameter. HOST is the IP address or domain name of the SLV CMS. Make sure to add the port (separated by a colon) when it is different from 80 and 443, e.g. mydomain.com:8080
SLV 7.8 and above
Starting with SLV 7.8, additional CSRF protection has been added, which requires all third-party applications that interface with SLV through the API to be modified to use a more secure authentication scheme. Third-party applications must obtain a CSRF token before making any other API call. To do so, clients must call the API method userprofile/getCurrentUser with the following request headers:
X-CSRF-Token = "Fetch"
X-Requested-With = "XMLHttpRequest"
SLV will then provide a CSRF token in the response header X-CSRF-Token. To make a subsequent API call, clients must include the token as part of the request headers, using the key X-CSRF-Token.
It is also highly recommended to create and reuse a single session for all SLV API requests to avoid having to follow this authentication process before each request. By creating and reusing a single session, the token request needs to be made only once and HTTP Basic Auth credentials can be omitted from subsequent API calls.
Example with the API getGeozoneRoot
import requests
# SLV CMS parameters
SLV_URL = <your SLV CMS URL>
SLV_USERNAME = <your SLV CMS username>
SLV_PASSWORD =<your SLV CMS password>
# Create a session
my_session = requests.Session()
# Get the CSRF token
token_request_headers = {
'X-CSRF-Token': 'Fetch',
'X-Requested-With': 'XMLHttpRequest'
}
token_response = my_session.post(SLV_URL + "/api/userprofile/getCurrentUser", auth=(SLV_USERNAME, SLV_PASSWORD), headers=token_request_headers)
# Save the token
token_header = {'X-CSRF-Token': token_response.headers['X-CSRF-Token']}
# Make the getGeozoneRoot call
# Note the reuse of the session, the use of the CSRF token and the absence of other credentials
payload = {
'computeHierarchyInfos': 'true',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/asset/getGeozoneRoot", params=payload, headers=token_header)
# Do something with the result
CSRF Token Expiration and Error Handling
A token expires along with its associated SLV CMS session. By default, a session expires after a period of inactivity of thirty minutes.
Requests that do not include a CSRF token or that include an incorrect or invalid token are rejected by CMS with the HTTP code 403 and with the response header X-CSRF-Token set to required.
Single-sign on with CAAS
If your SLV CMS instance is using single-sign on with CAAS (available from SLV 7.10), you must take the following into consideration: - your CAAS user account must have the role Stateless authentication enabled, - each call to the SLV API must include your basic auth crendentials in addition to the CSRF token.
Authorization
Each API method requires authorization in order to be executed by the caller. This document provides at the bottom of each method description the SLV application that the caller should have access to in order to successfully call the method. Any of the application listed is sufficient for the caller to be authorized. If the caller does not have access to any of these applications, then the call will be rejected with an HTTP 403 error.
The authorization table sometimes refers to the Desktop application: access to this application is automatically granted to any user profile created via the SLV user interface, although this permission is not explicitely visible in the Users application.
TLS support
Starting from version 7.16, SLV only supports TLS v1.2 connections. You should ensure that your software is able to connect to SLV using the latest TLS protocols and ciphers.
Error codes
| Error code | Description |
|---|---|
| 400 | INVALID REQUEST |
| 601 | CONNECT EXCEPTION |
| 602 | IO EXCEPTION |
| 603 | ID NAME ALREADY USED |
| 604 | UNAUTHORIZED NULL PARAMETER |
| 605 | MISSING PARAMETER |
| 606 | UNKNOWN HOST EXCEPTION |
| 610 | GEOZONE NOT FOUND |
| 611 | DEVICE NOT FOUND |
| 612 | COMMAND NOT FOUND |
| 613 | ITEM NOT FOUND |
| 614 | RESOURCE NOT FOUND |
| 620 | OPERATION NOT SUPPORTED |
| 630 | OPERATION NOT AUTHORIZED |
| 999 | UNKNOWN ERROR |
| 1001 | TIMEZONE NOT FOUND |
1. User profiles
The user profile
A user profile is a set of properties shared by several users: it is more commonly called a user group.
It is referenced by its name. Below are its main attributes:
| Attributes | Description |
|---|---|
| name | Profile name |
| blockedActions | List of actions that cannot be performed |
| locale | Language following the format lg_CN. lg is the ISO-639 language code, CN is the ISO-3166 country code. |
| geoZoneRootId | ID of the top-level (root) geozone |
| skin | Name of the skin |
1.01 Create a user profile
Create a new user profile called My profile and having access to the geozone ID 1
import requests
payload = {
'profilName': 'My profile',
'geoZoneId': '1',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/createProfil", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"id" : "1",
"name" : "My profile",
"properties" :
[
{
"key" : "css",
"value" : "/resources/css/default.css"
},
{
"key" : "skin",
"value" : "streetlight"
},
{
"key" : "img.bottombanner",
"value" : "/resources/img/bottomBar.gif"
},
{
"key" : "providerRootId",
"value" : ""
},
{
"key" : "locale",
"value" : "en_US"
},
{
"key" : "img.topbanner",
"value" : "/resources/img/topbanner_left.gif"
},
{
"key" : "customerRootId",
"value" : ""
},
{
"key" : "desktop",
"value" : "desktopApplicationDefault.xml"
},
{
"key" : "geoZoneRootId",
"value" : "1"
},
{
"key" : "maintenanceAccessFromDeviceCard",
"value" : "false"
},
{
"key" : "hilitable",
"value" : "/resources/js/hilitableTable.js"
},
{
"key" : "blockedActions",
"value" : ""
},
{
"key" : "hide.topbanner",
"value" : "true"
},
{
"key" : "hide.bottombanner",
"value" : "true"
},
{
"key" : "userType",
"value" : "unknown"
},
{
"key" : "img.topcenterbanner",
"value" : "/resources/img/topbanner_center.gif"
},
{
"key" : "img.toprightbanner",
"value" : "/resources/img/topbanner_right.gif"
}
]
}
To create a user profile, you should call the method createProfil available at /api/userprofile.
| Arguments | |
|---|---|
| profilName (required) | Name of the new profile |
| geoZoneId (required) | ID of the top-level (root) geozone |
| Available with the following applications |
|---|
| Users |
1.02 Update a user profile
Update the user profile called My profile with typical profile attributes
import requests
payload = {
'profilName': 'My profile',
'property.locale': 'en_US',
'property.skin': 'streetlight',
'property.geoZoneRootId': 1,
'property.blockedActions': 'SLVAssetManagementAPI!deleteGeoZone,SLVAssetManagementAPI!deleteDevice',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/updateProfilProperties", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
"OK"
After creating a user profile, you will probably want to update its attributes. Call the method updateProfilProperties at /api/userprofile.
| Arguments | |
|---|---|
| profilName (required) | Name of the profile to update |
| property.key | Attribute to update, specified by key |
| Available with the following applications |
|---|
| Users |
1.03 Delete a user profile
Delete the user profile called My profile
import requests
payload = {
'profilName': 'My profile',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/deleteProfil", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" : null
}
To delete a user profile, call the method deleteProfil at /api/userprofile.
| Arguments | |
|---|---|
| profilName (required) | Name of the profile to delete |
| Available with the following applications |
|---|
| Users |
1.04 Retrieve the profile of the current user
Get the current user profile
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/getCurrentProfil", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"id" : 1,
"name" : "My profile",
"properties" :
[
{
"key" : "css",
"value" : "/resources/css/default.css"
},
{
"key" : "skin",
"value" : "streetlight"
},
{
"key" : "img.bottombanner",
"value" : "/resources/img/bottomBar.gif"
},
{
"key" : "providerRootId",
"value" : ""
},
{
"key" : "locale",
"value" : "en_US"
},
{
"key" : "img.topbanner",
"value" : "/resources/img/topbanner_left.gif"
},
{
"key" : "customerRootId",
"value" : ""
},
{
"key" : "desktop",
"value" : "desktopSilverlight.xml"
},
{
"key" : "geoZoneRootId",
"value" : "1"
},
{
"key" : "maintenanceAccessFromDeviceCard",
"value" : "false"
},
{
"key" : "hilitable",
"value" : "/resources/js/hilitableTable.js"
},
{
"key" : "blockedActions",
"value" : ""
},
{
"key" : "hide.topbanner",
"value" : "true"
},
{
"key" : "hide.bottombanner",
"value" : "true"
},
{
"key" : "userType",
"value" : "unknown"
},
{
"key" : "img.topcenterbanner",
"value" : "/resources/img/topbanner_center.gif"
},
{
"key" : "img.toprightbanner",
"value" : "/resources/img/topbanner_right.gif"
}
]
}
To know the attributes of the current user profile, call getCurrentProfil at /api/userprofile. This method has no required parameter.
The method getProfilProperties at /api/asset can also be used and provides the same information with a slightly different output; it provides only the profile properties, not the profile name.
| Available with the following applications |
|---|
| Always available |
1.05 Retrieve all profiles
Get all user profiles available at the geozone ID 1 and all of its sub-geozones
import requests
payload = {
'geoZoneId': 1,
'recurse': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/getGeoZoneProfils", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
[
{
"id" : 1,
"name" : "My profile",
"properties" :
[
{
"key" : "css",
"value" : "/resources/css/default.css"
},
{
"key" : "skin",
"value" : "streetlight"
},
{
"key" : "img.bottombanner",
"value" : "/resources/img/bottomBar.gif"
},
{
"key" : "providerRootId",
"value" : ""
},
{
"key" : "locale",
"value" : "en_US"
},
{
"key" : "img.topbanner",
"value" : "/resources/img/topbanner_left.gif"
},
{
"key" : "customerRootId",
"value" : ""
},
{
"key" : "desktop",
"value" : "desktopSilverlight.xml"
},
{
"key" : "geoZoneRootId",
"value" : "1337"
},
{
"key" : "maintenanceAccessFromDeviceCard",
"value" : "false"
},
{
"key" : "hilitable",
"value" : "/resources/js/hilitableTable.js"
},
{
"key" : "blockedActions",
"value" : ""
},
{
"key" : "hide.topbanner",
"value" : "true"
},
{
"key" : "hide.bottombanner",
"value" : "true"
},
{
"key" : "userType",
"value" : "unknown"
},
{
"key" : "img.topcenterbanner",
"value" : "/resources/img/topbanner_center.gif"
},
{
"key" : "img.toprightbanner",
"value" : "/resources/img/topbanner_right.gif"
}
]
},
{
...
}
]
You can obtain the list of all user profiles with a specific top-level geozone using the method getGeoZoneProfils at /api/userprofile.
| Arguments | |
|---|---|
| geoZoneId (required) | Desired top-level geozone |
| recurse | If set to true, this method will also return the user profiles that have a top-level geozone being a child of the geozone specified by geoZoneId. Set to false if not specified. |
| Available with the following applications |
|---|
| Log Viewer |
| Users |
1.06 Retrieve all user profile attributes
Example request
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/getProfilPropertyDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
[
{
"dataFormat" : null,
"enumValues" :
[
{
"label" : "Unknown",
"properties" : null,
"value" : "unknown"
},
{
"label" : "Human",
"properties" : null,
"value" : "human"
},
{
"label" : "Controller",
"properties" : null,
"value" : "controller"
}
],
"format" : null,
"label" : "??profil.property.name.userType??",
"labelKey" : "profil.property.name.userType",
"name" : "userType",
"type" : "enum.single"
},
{
...
}
]
To obtain the list of all user profile attributes available, use the method getProfilPropertyDescriptors at /api/userprofile. It has no required parameter.
If an attribute has a specific set of accepted values, its type will be enum.single and enumValues will list all accepted values.
| Available with the following applications |
|---|
| Users |
1.07 Retrieve roles associated with the current profile
Example request
import requests
payload = {
'ser': 'json',
'includeDetails': 'false'
}
r = requests.get(SLV_URL + "/api/userprofile/getCurrentProfileRoles", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"grantedRoles": [
{
"name": "EnergyAnalysisApp",
"blockable": false
},
{
"name": "DashboardApp",
"blockable": false
},
...
],
"blockedRoles": [
{
"name": "ControlCenterApp",
"blockable": false
},
...
]
}
You can obtain the list of all roles associated with the current user profile using the method getCurrentProfileRoles at /api/userprofile.
| Arguments | |
|---|---|
| includeDetails | If set to true, the method returns the list of privileges associated with each role included in the response. Set by default to false if not specified |
| Available with the following applications |
|---|
| Desktop |
| Users |
1.08 Retrieve roles associated with a profile
Retrieving the roles and privileges associated with the profile ID 1
import requests
payload = {
'ser': 'json',
'profileId': 1,
'includeDetails': 'true'
}
r = requests.get(SLV_URL + "/api/userprofile/getProfileRoles", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"grantedRoles": [
{
"name": "EnergyAnalysisApp",
"blockable": false,
"privileges": [
{
"name": "ShowEnergyAnalysisApplicationAction"
}
]
},
{
"name": "DashboardApp",
"blockable": false,
"privileges": [
{
"name": "ShowDashboardApplicationAction"
}
]
},
...
],
"blockedRoles": [
{
"name": "ControlCenterApp",
"blockable": false,
"privileges": [
{
"name": "ShowControlCenterApplicationAction"
}
]
},
...
]
}
You can obtain the list of all roles associated with a profile using the method getProfileRoles at /api/userprofile.
| Arguments | |
|---|---|
| profileId (required) | Desired user profile |
| includeDetails | If set to true, the method returns the list of privileges associated with each role included in the response. Set by default to false if not specified |
| Available with the following applications |
|---|
| Users |
1.09 Set granted and blocked roles associated with a profile
Granting the roles
EnergyAnalysisAppandAddNodeChangeand blocking the rolesControllersAppandModifyDeviceInventoryfor the user profile ID 1
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('ser', 'json'),
('profileId', 1),
('grantedRoles', 'EnergyAnalysisApp'),
('grantedRoles', 'AddNodeChange'),
('blockedRoles', 'ControllersApp'),
('blockedRoles', 'ModifyDeviceInventory')
])
r = requests.post(SLV_URL + "/api/userprofile/setRoles", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
"OK"
You can set the granted and blocked roles for a given profile using the method setRoles at /api/userprofile.
| Arguments | |
|---|---|
| profileId (required) | Desired user profile |
| grantedRoles | Role to be granted to the user profile |
| blockedRoles | Role to be blocked for the user profile |
| Available with the following applications |
|---|
| Users |
1.10 Retrieve all available roles
Example request
import requests
payload = {
'ser': 'json',
'includeDetails': 'true'
}
r = requests.get(SLV_URL + "/api/userprofile/getAllAvailableRoles", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
[
{
"name" : "ExecuteCommand",
"blockable" : true,
"privileges" : [
{
"name" : "execute_device_command"
}
]
},
{
"name" : "ImportCsvOrSdpFile",
"blockable" : true,
"privileges" : [
{
"name" : "import_geozones_fromcsvfile"
},
{
"name" : "import_brands_fromcsvfile"
},
{
"name" : "import_devicesfromcsvfile"
},
{
"name" : "import_devicesfromsdpfile"
}
]
},
{
"name" : "EnergyAnalysisApp",
"blockable" : false,
"privileges" : [
{
"name" : "ShowEnergyAnalysisApplicationAction"
}
]
},
...
]
You can obtain the list of all roles available using the method getAllAvailableRoles at /api/userprofile.
| Arguments | |
|---|---|
| includeDetails | If set to true, the method returns the list of privileges associated with each role included in the response. Set by default to false if not specified |
| Available with the following applications |
|---|
| Users |
2. Users
The user
A user is defined by its login name and the user profile it belongs to. Additionnal info can be defined for a user, most importantly her email address since it is used not only for sending alarms and reports but also for the password recovery process!
Users are referenced by their login name. Below are the main attributes of a user:
| Attributes | |
|---|---|
| login | Login name |
| password | Password |
| profilName | User profile |
| geoZoneRootId | ID of the top-level (root) geozone |
| contact | Contact object (see below) |
| properties | Array of key/value pairs storing UI configuration properties |
The contact
A contact is a simple list of properties referenced by a numeric ID:
| Attributes | |
|---|---|
| id | ID |
| address | Address |
| Email address | |
| name | Name |
| pager | Pager number |
| phone | Phone number |
2.01 Create a user
Create a user belonging to the profile My profile with the login johndoe and some other example attributes
import requests
payload = {
'login': 'johndoe',
'password': 'Johndoe-2016',
'firstName': 'John',
'lastName': 'Doe',
'profilName': 'My profile',
'email': 'johndoe@streetlight-vision.com',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/userprofile/createUser", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"contact" :
{
"address" : null,
"id" : 11,
"mail" : "johndoe@streetlight-vision.com",
"name" : null,
"pager" : null,
"phone" : null
},
"firstName" : "John",
"lastName" : "Doe",
"login" : "johndoe",
"password" : "",
"profilName" : "My profile",
"properties" :
[
]
}
To create a user profile, you should call the method createUser available at /api/userprofile.
| Arguments | |
|---|---|
| login (required) | Login name |
| password (required) | Password |
| profilName (required) | User profile |
| firstName | First name |
| lastName | Last name |
| address | Address |
| phone | Phone number |
| pager | Pager number |
| Email address |
2.02 Update a user
Update the email address of johndoe
import requests
payload = {
'login': 'johndoe',
'email': 'johndoe-new@streetlight-vision.com',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/userprofile/updateUser", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
"OK"
To update any of the attribute set when creating a user with createUser (except the user password), you may use the method updateUser available at /api/userprofile.
It takes the same parameters:
| Arguments | |
|---|---|
| login (required) | Login name |
| profilName | User profile |
| firstName | First name |
| lastName | Last name |
| address | Address |
| phone | Phone number |
| pager | Pager number |
| Email address |
2.03 Update user UI properties
Update two dummy properties property1 and property2 for the user johndoe
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('userLogin', 'johndoe'),
('propertyName', 'property1'),
('propertyValue', 'value1'),
('propertyName', 'property2'),
('propertyValue', 'value2'),
('ser', 'json')
])
r = requests.post(SLV_CMS + "/api/userprofile/updateUserProperty", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
"OK"
Since user UI properties are actually an array of key/value pairs, a specific method is provided to update them: updateUserProperty available at /api/userprofile. It takes an arbitrary number of key/value pairs.
| Arguments | |
|---|---|
| userLogin (required) | Login name |
| propertyName | Property key |
| propertyValue | Property value |
2.04 Retrieve the current user
Example request
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/getCurrentUser", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"contact" :
{
"address" : null,
"id" : 11,
"mail" : "johndoe-new@streetlight-vision.com",
"name" : null,
"pager" : null,
"phone" : null
},
"firstName" : "John",
"lastName" : "Doe",
"login" : "johndoe",
"password" : "",
"profilName" : "My profile",
"properties" :
[
{
"key" : "property2",
"value" : "value2"
},
{
"key" : "property1",
"value" : "value1"
}
]
}
To retrieve the attributes of the current user, call getCurrentUser at /api/userprofile. This method has no required parameter.
2.05 Retrieve all users
Get all users that we have access to
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/getAllUsers", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"contact" :
{
"address" : null,
"id" : 11,
"mail" : "johndoe-new@streetlight-vision.com",
"name" : null,
"pager" : null,
"phone" : null
},
"firstName" : "John",
"lastName" : "Doe",
"login" : "johndoe",
"password" : "",
"profilName" : "My profile",
"properties" :
[
{
"key" : "property2",
"value" : "value2"
},
{
"key" : "property1",
"value" : "value1"
}
]
},
...
]
To obtain the list of all users, call getAllUsers at /api/userprofile. This method has no required parameter.
2.06 Retrieve users under a specific geozone
Get all users under the geozone ID 1 and all of its sub-geozones
import requests
payload = {
'geoZoneId': 1,
'recurse': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/userprofile/getGeoZoneUsers", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
[
{
"contact" :
{
"address" : null,
"id" : 11,
"mail" : "johndoe-new@streetlight-vision.com",
"name" : null,
"pager" : null,
"phone" : null
},
"firstName" : "John",
"lastName" : "Doe",
"login" : "johndoe",
"password" : "",
"profilName" : "My profile",
"properties" :
[
{
"key" : "property2",
"value" : "value2"
},
{
"key" : "property1",
"value" : "value1"
}
]
},
...
]
To obtain the list of all users whose user profile is under a specific geozone , call getGeoZoneUsers at /api/userprofile.
| Arguments | |
|---|---|
| geoZoneId (required) | Desired top-level geozone |
| recurse | If set to true, this method will also return the users whose user profile have a top-level geozone being a child of the geozone specified by geoZoneId. Set to false if not specified. |
2.07 Delete a user
Delete the user test42
import requests
payload = {
'login': 'test42',
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/userprofile/deleteUser", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" : null
}
To delete a user, call the method deleteUser available at /api/userprofile. Note that if you try to delete a user that is not visible to you, you will get an error.
| Arguments | |
|---|---|
| login (required) | Login name |
2.08 Update the current user password
Set the password to newPass-1
import requests
payload = {
'previousPassword': 'PASSWORD',
'newPassword': 'newPass-1',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/userprofile/changePassword", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
"OK"
There is a specific method to update the current user password as the old password is required before a new password can be set. The method changePassword at /api/userprofile must be called to change a password. It only applies to the user who is currently logged in.
| Arguments | |
|---|---|
| previousPassword (required) | Previous password |
| newPassword (required) | New password |
2.09 Recover a forgotten password
Ask the server to initiate the password recovery process for johndoe
import requests
payload = {
'login': 'johndoe',
'ser': 'json'
}
r = requests.post(SLV_URL + "/public/api/publicconfig/sendResetPasswordRequestByMail", data=payload)
Example response
"OK"
To trigger the password recovery mechanism, call the method sendResetPasswordRequestByMail available at /public/api/publicconfig. This method does not require any authentication!
| Arguments | |
|---|---|
| login (required) | Login name |
2.10 Verify a password
Check that the password PASSWORD is correct for the current user
import requests
payload = {
'password': 'PASSWORD',
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/userprofile/checkPassword", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" : true
}
Even though you are already logged in, you may call the method checkPassword available at /api/userprofile to check that a password matches the password stored in the database for the current user.
| Arguments | |
|---|---|
| password (required) | Password for the current user |
3. Providers
The provider
A provider represents an electricity provider (a utility). It has a display name and holds a pollution rate, which enables the server to generate pollution saving numbers.
Provides are referenced by an internal ID generated by the server.
| Attributes | |
|---|---|
| id | Internal ID (int) |
| name | Name |
| pollution | Number of kg of emitted CO2 per generated KWh |
| type | provider by default |
3.01 Create a provider
Create a provider called My new provider
import requests
payload = {
'name': 'My new provider',
'pollutionRate': 0.42,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/assetmanagement/createProvider", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"id" : 3826,
"name" : "My new provider",
"pollution" : 0.42,
"type" : "provider"
}
To create a new provider, call the method createProvider available at /api/assetmanagement.
| Arguments | |
|---|---|
| name (required) | Provider name |
| pollutionRate (required) | Number of kg of emitted CO2 per generated KWh (float) |
| Available with the following applications |
|---|
| Equipment Inventory |
3.02 Retrieve all providers
Get all providers
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getAllProviders", params=payload, auth=('USERNAME', 'PASSWORD'))
Example response
[
{
"id" : 4,
"name" : "EDF",
"pollution" : 0.11,
"type" : "provider"
},
{
"id" : 5,
"name" : "RWE",
"pollution" : 0.783,
"type" : "provider"
},
...
]
To retrieve the list of all providers, call the method getAllProviders available at /api/asset. This method has no required parameter.
| Available with the following applications |
|---|
| Advanced Search |
| Desktop |
| Equipment Inventory |
3.03 Update a provider
Change the pollution rate of the provider ID 3826
import requests
payload = {
'providerId': 3826,
'newName': 'My new provider',
'pollutionRate': 0.11,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/assetmanagement/updateProvider", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"id" : 3826,
"name" : "My new provider",
"pollution" : 0.11,
"type" : "provider"
}
To change the name or the pollution rate of provider, you may call updateProvider available at /api/assetmanagement.
| Arguments | |
|---|---|
| providerId (required) | Provider ID |
| newName (required) | Provider name |
| pollutionRate (required) | Number of kg of emitted CO2 per generated KWh (float) |
| Available with the following applications |
|---|
| Equipment Inventory |
3.04 Delete a provider
Delete the provider ID 3826
import requests
payload = {
'id': 3826,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/assetmanagement/deleteProvider", data=payload, auth=('USERNAME', 'PASSWORD'))
Example response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" : null
}
To delete a provider, call the method deleteProvider available at /api/assetmanagement.
| Arguments | |
|---|---|
| id (required) | Provider ID |
| Available with the following applications |
|---|
| Equipment Inventory |
4. Lamp types
The lamp type (brand)
A brand is an object representing a lamp type in the SLV CMS. It is referenced by its internal server ID. Below are its main attributes:
| Attributes | |
|---|---|
| id | Internal server ID (int) |
| name | Brand textual ID |
| description | Brand display name |
A lamp type also has numerous optional attributes. The list of those attributes should be obtained directly from the server.
4.01 Create a lamp type
Creating a new lamp type identified as
slv-lampand calledSLV Lampwith a couple of sample properties
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('name', 'slv-lamp'),
('description', 'SLV Lamp'),
('propertyName', 'LampPower'),
('propertyValue', '85'),
('propertyName', 'Vno'),
('propertyValue', '230'),
('ser', 'json')
])
r = requests.post(SLV_CMS + "/api/assetmanagement/createBrand", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"label" : "SLV Lamp",
"properties" :
{
"Vno" : "230",
"name" : "slv-lamp",
"description" : "SLV Lamp",
"LampPower" : "85",
"id" : "1163",
"lifeTime" : "null"
},
"value" : 1163
}
To create a new lamp type, the method createBrand available at /api/assetmanagement should be used. A lamp type can have any number of arbitrary properties, so this method can take any number of propertyName/propertyValue pairs in addition to its required parameters.
| Arguments | |
|---|---|
| name (required) | Brand textual ID |
| description (required) | Brand display name |
| propertyName | Property name |
| propertyValue | Property value |
The server reponse contains the server-generated internal ID (properties.id) that should be used for further operations on lamp types.
| Available with the following applications |
|---|
| Equipment Inventory |
4.02 Update a lamp type
Updating the properties LampPower and Vno of the lamp type ID 1163
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('id', '1163'),
('propertyName', 'LampPower'),
('propertyValue', '48'),
('propertyName', 'Vno'),
('propertyValue', '110'),
('ser', 'json')
])
r = requests.post(SLV_CMS + "/api/assetmanagement/updateBrand", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"label" : "SLV Lamp",
"properties" :
{
"Vno" : "110",
"name" : "slv-lamp",
"description" : "SLV Lamp",
"LampPower" : "48",
"id" : "1163",
"lifeTime" : "null"
},
"value" : 1163
}
To update the attributes of a lamp type, use the method updateBrand available at /api/assetmanagement. This method can take any number of propertyName/propertyValue pairs in addition to the required id.
| Arguments | |
|---|---|
| id (required) | Internal server ID (int) |
| newName | New brand textual ID |
| newDescription | New drand display name |
| propertyName | Property name |
| propertyValue | Property value |
| Available with the following applications |
|---|
| Equipment Inventory |
4.03 Delete a lamp type
Deleting the lamp type ID 1163
import requests
payload = {
'brandId': '1163',
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/assetmanagement/deleteBrand", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" : null
}
To delete a lamp type from the server, use the method deleteBrand available at /api/assetmanagement.
| Arguments | |
|---|---|
| brandId (required) | Internal server ID (int) |
| Available with the following applications |
|---|
| Equipment Inventory |
4.04 Retrieve all lamp types
Retrieving all lamp types
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getAllBrands", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"label" : "HPS 70W Ferro",
"properties" :
{
"ILevel2min" : "0",
"Vmax" : "250",
"ILevel1min" : "100",
"description" : "HPS 70W Ferro",
"Ino" : "100",
"CLOValue" : "100",
"WarmUpTime" : "10",
"CLOBHLimit" : "0",
"Pmax" : "70",
"PFmin" : "0.6",
"Vmin" : "200",
"ILevel1max" : "1300",
"ILevel2max" : "2000",
"Vno" : "180",
"name" : "/SLV/HPS/70/MAG",
"BHmax" : "20000",
"id" : "1",
"lifeTime" : "20000",
"ControlVoltMax" : "0",
"minOutputValue" : "0",
"Interface" : "EM"
},
"value" : 1
},
...
]
To retrieve all lamp types, use the method getAllBrands available at /api/asset. This method has no required parameter.
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Data History |
| Desktop |
| Device History |
| Equipment Inventory |
| Failure Tracking |
| Installation |
4.05 Retrieve all lamp type attributes
Retrieving all lamp type attributes
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/assetmanagement/getBrandPropertyDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "standard",
"criticity" : 0,
"dataFormat" :
{
"defaultValue" : "Manufacturer/LampTechno/Power/BallastType"
},
"failure" : false,
"help" : null,
"label" : "Identifier",
"labelKey" : "brand.property.strId.label",
"name" : "LampType",
"type" : "string",
"unit" : null
},
...
]
To retrieve the list of all lamp type attributes available on the server, use the method getBrandPropertyDescriptors available at /api/assetmanagement. This method has no required parameter.
If an attribute has a specific set of accepted values, its type will be select and dataFormat will list all accepted values.
| Available with the following applications |
|---|
| Equipment Inventory |
4.06 Import lamp types with a CSV
The CSV file should be formatted as follows:
attribute1_name;attribute2_name;...;attributeN_name
lamptype1_attribute1_value;lamptype1_attribute2_value;...;lamptype1_attributeN_value
...
lamptypeM_attribute1_value;lamptypeM_attribute2_value;...;lamptypeM_attributeN_value
Importing lamp types from the file lamptypes.csv
import requests
with open('lamptypes.csv', 'r') as myfile:
data=myfile.read()
payload = {
'csvFile': data,
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/assetmanagement/importBrandsFromCsvFileAsync", data=payload, auth=('USERNAME', 'PASSWORD'))
print (r.text)
Sample response
{
"batchId" : "1483606585540",
"batchProgressMessage" : null,
"batchProgressValue" : 0,
"batchRunning" : true,
"cancelRequested" : false,
"cancelled" : false,
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"lineResults" :
[
{
"errorMessages" : null,
"errorMessagesCount" : 0,
"inError" : false,
"index" : 0,
"infoMessagesCount" : 0,
"messages" : null,
"messagesCount" : 0,
"ok" : false,
"properties" : null,
"state" : 0,
"stateStr" : "-",
"warning" : false,
"warningMessages" : null,
"warningMessagesCount" : 0
}
],
"lineResultsErrorCount" : 0,
"lineResultsOkCount" : 0,
"lineResultsUndefinedCount" : 1,
"lineResultsWarningCount" : 0,
"linesResultsCount" : 1,
"properties" : null,
"running" : true,
"totalLinesResultsCount" : 1
}
}
You may create new lamp types from a CSV file that contains their definition. To do so, use the method importBrandsFromCsvFileAsync available at /api/assetmanagement. It returns a batch object.
| Arguments | |
|---|---|
| csvFile (required) | Content of the CSV file |
| Available with the following applications |
|---|
| Equipment Inventory |
5. Geozones
The geozone
A geozone is the equivalent of a folder in a file system. It can contain other geozones (sub-geozones) and devices. It also represents an rectangular area of the world map. It is identified by a server-generated ID. Below are its main attributes:
| Attributes | |
|---|---|
| id | Geozone ID (int) |
| name | Geozone name |
| type | It will always be geozone |
| parentId | ID of the parent geozone |
| idsPath | List of geozone IDs that lead from the top-level geozone to this geozone |
| namesPath | List of geozone names that lead from the top-level geozone to this geozone |
| latMax | Maximum latitude (float) |
| latMin | Minimum latitude (float) |
| lngMax | Maximum longitude (float) |
| lngMin | Minimum longitude (float) |
| devicesCount | Number of devices |
| childrenCount | Number of sub-geozones |
5.01 Create a geozone
Creating a geozone called
My new geozoneunder the geozone ID 1
import requests
payload = {
'name': 'My new geozone',
'parentId': 1,
'latMin': 48.79035455868981,
'latMax': 48.92655972351346,
'lngMin': 2.1097183227539067,
'lngMax': 2.5491714477539067,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/assetmanagement/createGeozone", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"activityCardsCount" : 0,
"childrenCount" : 0,
"devicesCount" : 0,
"hierarchyActivityCardsCount" : -1,
"hierarchyDevicesCount" : -1,
"id" : 3831,
"idsPath" : "1/3831",
"latMax" : 48.92655972351346,
"latMin" : 48.79035455868981,
"lngMax" : 2.5491714477539067,
"lngMin" : 2.1097183227539067,
"name" : "My new geozone",
"namesPath" : "GeoZones/My new geozone",
"parentId" : 1,
"properties" : null,
"type" : "geozone"
}
To create a geozone, call the method createGeozone available at /api/assetmanagement.
| Arguments | |
|---|---|
| name (required) | Geozone name |
| parentId (required) | ID of the parent geozone |
| latMax (required) | Maximum latitude (float) |
| latMin (required) | Minimum latitude (float) |
| lngMax (required) | Maximum longitude (float) |
| lngMin (required) | Minimum longitude (float) |
| Available with the following applications |
|---|
| Equipment Inventory |
5.02 Update a geozone
Updating the geozone ID 3831 with some additional properties
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('geozoneId', '3831'),
('newName', 'Paris'),
('lngMax', '2.5491714477539067'),
('lngMin', '2'),
('latMax','48.92655972351346'),
('latMin','48.79035455868981'),
('propertyName', 'virtual.energy.consumption.jan'),
('propertyValue', '18000'),
('propertyName', 'virtual.energy.consumption.feb'),
('propertyValue', '17500'),
('ser', 'json')
])
r = requests.post(SLV_CMS + "/api/assetmanagement/updateGeozone", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"activityCardsCount" : 0,
"childrenCount" : 0,
"devicesCount" : 0,
"hierarchyActivityCardsCount" : -1,
"hierarchyDevicesCount" : -1,
"id" : 3831,
"idsPath" : "1/3824/3831",
"latMax" : 48.92655972351346,
"latMin" : 48.79035455868981,
"lngMax" : 2.5491714477539067,
"lngMin" : 2.0,
"name" : "Paris",
"namesPath" : "GeoZones/Paris",
"parentId" : 1,
"properties" : null,
"type" : "geozone"
}
To modify an existing geozone, call the method updateGeozone available at /api/assetmanagement. In addition to its main attribute, a geozone can have any number of optional arbitrary properties, so this method may take any number of propertyName/propertyValue pairs in addition to its required parameters.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| newName (required) | Geozone name |
| latMax (required) | Maximum latitude (float) |
| latMin (required) | Minimum latitude (float) |
| lngMax (required) | Maximum longitude (float) |
| lngMin (required) | Minimum longitude (float) |
| parentId | ID of the new parent geozone |
| propertyName | Property name |
| propertyValue | Property value |
| Available with the following applications |
|---|
| Equipment Inventory |
5.03 Delete a geozone
Deleting the geozone ID 3831 and everything belonging to it
import requests
payload = {
'geozoneId': '3831',
'pullUpContent': 'false',
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/assetmanagement/deleteGeozone", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
"OK"
To delete a geozone, use the method deleteGeozone available at /api/assetmanagement.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| pullUpContent | If set to true, moves the content of the geozone under the parent geozone. If set to false, deletes everything under the geozone. True by default |
| Available with the following applications |
|---|
| Equipment Inventory |
5.04 Retrieve all geozones
Retrieving all geozones
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getAllGeozones", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"activityCardsCount" : 0,
"childrenCount" : 10,
"devicesCount" : 7,
"hierarchyActivityCardsCount" : -1,
"hierarchyDevicesCount" : -1,
"id" : 1,
"idsPath" : "1",
"latMax" : 80.0,
"latMin" : -80.0,
"lngMax" : 179.9999,
"lngMin" : -179.9999,
"name" : "GeoZones",
"namesPath" : "GeoZones",
"parentId" : null,
"properties" : null,
"type" : "geozone"
},
...
]
To retrieve all geozones visible by the current user, use the method getAllGeozones available at /api/asset. It has no required parameter.
The method getGeozones available at /api/asset is equivalent to this method.
| Available with the following applications |
|---|
| Equipment Inventory |
5.05 Retrieve a geozone
Retrieving the geozone ID 1
import requests
payload = {
'id': 1,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getGeozone", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"activityCardsCount" : 0,
"childrenCount" : 4,
"devicesCount" : 1,
"hierarchyActivityCardsCount" : -1,
"hierarchyDevicesCount" : -1,
"id" : 1,
"idsPath" : "1",
"latMax" : 80.0,
"latMin" : -80.0,
"lngMax" : 179.9999,
"lngMin" : -179.9999,
"name" : "GeoZones",
"namesPath" : "GeoZones",
"parentId" : null,
"properties" : null,
"type" : "geozone"
}
To retrieve the basic properties of a geozone, you may use the method getGeozone available at /api/asset.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| Available with the following applications |
|---|
| Equipment Inventory |
5.06 Retrieve optional properties
Retrieving the optional properties of the geozone ID 1
import requests
payload = {
'geozoneId': 1,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/assetmanagement/getGeozoneValueDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "standard",
"criticity" : 0,
"dataFormat" :
{
"min" : "0"
},
"failure" : false,
"help" : null,
"label" : "January kWh",
"labelKey" : "db.meaning.virtual.energy.consumption.jan.label",
"name" : "virtual.energy.consumption.jan",
"type" : "int",
"unit" : null
}
...
]
To retrieve the optional properties of a geozone, you may use the method getGeozoneValueDescriptors available at /api/logging.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| Available with the following applications |
|---|
| Desktop |
| Equipment Inventory |
5.07 Retrieve optional values
Retrieving two optional values for geozone ID 1
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('geozoneId', '1'),
('valueName', 'virtual.energy.consumption.jan'),
('valueName', 'virtual.energy.consumption.feb'),
('ser', 'json')
])
r = requests.post(SLV_CMS + "/api/logging/getGeozoneLastValues", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"eventTime" : "2016-12-05 00:00:00",
"groupId" : 1,
"info" : "",
"meaningLabel" : "January kWh",
"name" : "virtual.energy.consumption.jan",
"updateTime" : "2016-12-05 00:00:00",
"value" : 20000.0
},
{
"eventTime" : "2016-12-05 00:00:00",
"groupId" : 1,
"info" : "",
"meaningLabel" : "February kWh",
"name" : "virtual.energy.consumption.feb",
"updateTime" : "2016-12-05 00:00:00",
"value" : 19000.0
}
]
To retrive the values of those optional properties, use the method getGeozoneLastValues available at /api/logging. This method takes any number of valueName. The server response includes values in the same order as the request parameters.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| valueName (required) | Name of the optional attribute |
| Available with the following applications |
|---|
| Desktop |
| Equipment Inventory |
5.08 Retrieve the top-level geozone
Retrieving the root geozone with geozone tree data
import requests
payload = {
'computeHierarchyInfos': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getGeozoneRoot", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"activityCardsCount" : 0,
"childrenCount" : 4,
"devicesCount" : 1,
"hierarchyActivityCardsCount" : 0,
"hierarchyDevicesCount" : 43,
"id" : 1,
"idsPath" : "1",
"latMax" : 80.0,
"latMin" : -80.0,
"lngMax" : 179.9999,
"lngMin" : -179.9999,
"name" : "GeoZones",
"namesPath" : "GeoZones",
"parentId" : null,
"properties" : null,
"type" : "geozone"
}
To retrieve the top-level (or root) geozone for the current user, use the method getGeozoneRoot available at /api/asset. This method has no required parameter.
| Arguments | |
|---|---|
| computeHierarchyInfos | Set to true to obtain data about the whole geozone tree (e.g. hierarchyDevicesCount for the total number of devices). If set to false, the server will return -1 for that data. Defaults to false |
| Available with the following applications |
|---|
| Desktop |
5.09 Retrieve a geozone tree
Retrieving the geozone tree starting from geozone ID 1
import requests
payload = {
'geozoneId': 1,
'includeParentId': 'true',
'includeIdsPath': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getGeoZoneHierarchyLight", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"label" : "GeoZones",
"properties" :
{
"idsPath" : "1",
"parentId" : "null"
},
"value" : 1
},
{
"label" : "Chalais",
"properties" :
{
"idsPath" : "1/28/24",
"parentId" : "28"
},
"value" : 24
},
...
]
To retrieve the list of all sub-geozones having a specific ancestor, use the method getGeozoneHierarchyLight available at /api/asset.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| includeParentId | Set to true to obtain the parent geozone ID in a separate variable in the response. Defaults to false |
| includeIdsPath | Set to true to obtain the ID of all ancestors of each geozone listed, starting from the root geozone. Defaults to false |
| Available with the following applications |
|---|
| Equipment Inventory |
5.10 Retrieve direct sub-geozones
Retrieving the direct sub-geozone of geozone ID 1
import requests
payload = {
'geozoneId': 1,
'computeHierarchyInfos': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getGeoZoneChildrenGeoZones", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"activityCardsCount" : 0,
"childrenCount" : 1,
"devicesCount" : 0,
"hierarchyActivityCardsCount" : 0,
"hierarchyDevicesCount" : 4,
"id" : 28,
"idsPath" : "1/28",
"latMax" : 48.93039429902821,
"latMin" : 48.794425751649555,
"lngMax" : 2.524795532226563,
"lngMin" : 2.150230407714844,
"name" : "Paris",
"namesPath" : "GeoZones/Paris",
"parentId" : 1,
"properties" : null,
"type" : "geozone"
},
...
]
You may retrieve only the direct sub-geozones of a specific geozone by calling the method getGeozoneChildrenGeozones available at /api/asset.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID |
| computeHierarchyInfos | Set to true to obtain data about the sub-geozone tree starting from that geozone (e.g. hierarchyDevicesCount for the total number of devices). If set to false, the server will return -1 for that data. Defaults to false |
| Available with the following applications |
|---|
| Equipment Inventory |
5.11 Search for a geozone by name
Searching for a geozone which name contains par
import requests
payload = {
'name': 'par',
'partialMatch': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/searchGeozones", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"activityCardsCount" : 0,
"childrenCount" : 1,
"devicesCount" : 0,
"hierarchyActivityCardsCount" : -1,
"hierarchyDevicesCount" : -1,
"id" : 28,
"idsPath" : "1/28",
"latMax" : 48.93039429902821,
"latMin" : 48.794425751649555,
"lngMax" : 2.524795532226563,
"lngMin" : 2.150230407714844,
"name" : "Paris",
"namesPath" : "GeoZones/Paris",
"parentId" : 1,
"properties" : null,
"type" : "geozone"
}
]
You can search for a geozone by name by using the method searchGeozones available at /api/asset.
| Arguments | |
|---|---|
| name (required) | Name to search for |
| partialMatch | Set to true to obtain results that partially match. Defaults to false |
| Available with the following applications |
|---|
| Equipment Inventory |
6. Batches
The batch
A batch is the result of an asynchronous operation (e.g. commissioning devices) that may take longer than a few seconds to complete. This enables any client to avoid blocking while waiting for the operation to complete. Below are its attributes:
| Attributes | |
|---|---|
| batchId | Batch ID (int) |
| batchProgressMessage | Message describing the status of the batch |
| batchProgressValue | Percentage of completion of the batch. May be equal to -1 if the info is not available yet |
| batchRunning | Indicates whether the batch has completed or not (boolean) |
| cancelRequested | Indicates whether a cancel order has been issued for the batch (boolean) |
| cancelled | Indicates whether the batch has been cancelled (boolean) |
| errorCode | Error code |
| errorCodeLabel | Description of the error |
| message | Message describing the status of the batch |
| status | Status of the batch (OK or ERROR) |
| statusError | Indicates whether any error occured processing this batch (boolean) |
| statusOk | Indicates whether any error occured processing this batch (boolean) |
| value | Data structure provided by the underlying process |
6.01 Retrieve the status of a batch
Retrieving the status of batch ID 1481016600181
import requests
payload = {
'batchId': 1481016600181,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/batch/getBatchResult", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"batchId" : "1481016600181",
"batchProgressMessage" : "Commissioning process finished.",
"batchProgressValue" : 100,
"batchRunning" : false,
"cancelRequested" : false,
"cancelled" : false,
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"errorMessagesCount" : 0,
"infoMessagesCount" : 4,
"login" : "admin",
"status" : 0,
"stepResults" :
[
{
"errorMessages" :
[
],
"errorMessagesCount" : 0,
"infoMessages" :
[
{
"status" : 0,
"statusText" : "OK",
"text" : "Inventory has been checked in the database and is consistent"
}
],
"infoMessagesCount" : 1,
"label" : "Check database configuration",
"messages" :
[
{
"status" : 0,
"statusText" : "OK",
"text" : "Inventory has been checked in the database and is consistent"
}
],
"status" : 0,
"stepLabel" : "Check database configuration",
"stepName" : "check",
"warningMessages" :
[
],
"warningMessagesCount" : 0
},
{
"errorMessages" :
[
],
"errorMessagesCount" : 0,
"infoMessages" :
[
{
"status" : 0,
"statusText" : "OK",
"text" : "Devices configs are pushed using mode 'LIST'."
},
{
"status" : 0,
"statusText" : "OK",
"text" : "2 devices in list. 2 were pushed. 0 were ignored and 0 were not pushed because not found on controller."
},
{
"status" : 0,
"statusText" : "OK",
"text" : "All messages and configuration data have been sent and accepted by the controller"
}
],
"infoMessagesCount" : 3,
"label" : "Commissioning",
"messages" :
[
{
"status" : 0,
"statusText" : "OK",
"text" : "Devices configs are pushed using mode 'LIST'."
},
{
"status" : 0,
"statusText" : "OK",
"text" : "2 devices in list. 2 were pushed. 0 were ignored and 0 were not pushed because not found on controller."
},
{
"status" : 0,
"statusText" : "OK",
"text" : "All messages and configuration data have been sent and accepted by the controller"
}
],
"status" : 0,
"stepLabel" : "Commissioning",
"stepName" : "commissioning",
"warningMessages" :
[
],
"warningMessagesCount" : 0
}
],
"warningMessagesCount" : 0
}
}
To retrieve the status of a batch, use the method getBatchResult available at /api/batch.
| Arguments | |
|---|---|
| batchId (required) | Batch ID (int) |
| Available with the following applications |
|---|
| Alarm Manager |
| Control Center |
| Desktop |
| Equipment Inventory |
| Scheduling Manager |
7. Devices
The device
A device is identified by a server-generated ID. Despite its name, it may represent any object apart from a geozone. A device is always attached to a controller and has its own identifier on that controller.
| Attributes | |
|---|---|
| id | Device ID (int) |
| name | Device name |
| categoryStrId | Device category |
| geozoneId | ID of the parent geozone |
| controllerStrId | Controller to which the device is attached |
| idOnController | Device identifier on the controller |
| lat | Latitude |
| lng | Longitude |
7.01 Retrieve all device categories
Retrieving all device categories
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getCategories", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"displayName" : "Vehicle Charging Station",
"hidden" : false,
"strId" : "vehicleChargingStation"
},
{
"displayName" : "Environmental Sensor",
"hidden" : false,
"strId" : "envSensor"
},
...
]
To retrive all device categories, use the method getCategories available at /api/asset. It has no required parameter.
| Available with the following applications |
|---|
| Batch Control |
| Desktop |
7.02 Create a device
Creating a new controller device
import requests
payload = {
'userName': 'My controller',
'categoryStrId': 'controllerdevice',
'controllerStrId': 'mycontroller',
'idOnController': 'controllerdevice',
'geoZoneId':3837,
'lat':48.84031689136024,
'lng':2.3790979385375977,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/assetmanagement/createCategoryDevice", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"address" : null,
"categoryStrId" : "controllerdevice",
"controllerStrId" : "mycontroller",
"functionId" : null,
"geoZoneId" : 3837,
"geoZoneNamesPath" : "GeoZones/My new geozone",
"id" : 16872,
"idOnController" : "controllerdevice",
"lat" : 48.84031689136024,
"lng" : 2.3790979385375977,
"modelName" : null,
"name" : "My controller",
"nodeTypeStrId" : null,
"properties" :
[
{
"key" : "controller.firmwareVersion",
"value" : null
},
{
"key" : "firmwareVersion",
"value" : null
},
{
"key" : "controller.model",
"value" : null
},
{
"key" : "controller.host",
"value" : null
},
{
"key" : "controller.installDate",
"value" : "2016/12/06 11:47:36"
},
{
"key" : "controller.updateTime",
"value" : ""
},
{
"key" : "power",
"value" : null
},
{
"key" : "powerCorrection",
"value" : null
},
{
"key" : "tooltip",
"value" : ""
}
],
"technologyStrId" : null,
"type" : "device"
}
To create a device, use the method createCategoryDevice available at /api/assetmanagement. Since a device is always attached to a controller, you must specify a controller when creating a device.
| Arguments | |
|---|---|
| userName (required) | Device name |
| categoryStrId (required) | Device category |
| geozoneId (required) | ID of the parent geozone |
| controllerStrId (required) | Controller to which the device is attached. Use only lowercase letters and digits |
| idOnController (required) | Device identifier on the controller. Use only lowercase letters and digits |
| lat (required) | Latitude (float) |
| lng (required) | Longitude (float) |
| Available with the following applications |
|---|
| Equipment Inventory |
| Installation |
7.03 Retrieve a device
Retrieving the device ID 16872
import requests
payload = {
'deviceId': '16872',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getDevice", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"address" : null,
"categoryStrId" : "controllerdevice",
"controllerStrId" : "mycontroller",
"functionId" : null,
"geoZoneId" : 3837,
"geoZoneNamesPath" : "GeoZones/My new geozone",
"id" : 16872,
"idOnController" : "controllerdevice",
"lat" : 48.84031689136024,
"lng" : 2.3790979385375977,
"modelName" : null,
"name" : "My controller",
"nodeTypeStrId" : null,
"properties" :
[
{
"key" : "controller.firmwareVersion",
"value" : "xmltech.v1"
},
{
"key" : "firmwareVersion",
"value" : "xmltech.v1"
},
{
"key" : "controller.model",
"value" : null
},
{
"key" : "controller.host",
"value" : "localhost:8005"
},
{
"key" : "controller.installDate",
"value" : "2016/12/06 11:47:36"
},
{
"key" : "controller.updateTime",
"value" : ""
},
{
"key" : "power",
"value" : null
},
{
"key" : "powerCorrection",
"value" : null
},
{
"key" : "userproperty.ControllerCacheMode",
"value" : "default"
},
{
"key" : "userproperty.controller.auth.password",
"value" : "password"
},
{
"key" : "userproperty.reportFrequency",
"value" : 60
},
{
"key" : "userproperty.reportTime",
"value" : "06:00"
},
{
"key" : "userproperty.serverMsgUrl.webapp",
"value" : "http://localhost:8080/reports"
},
{
"key" : "userproperty.TimeZoneId",
"value" : "Europe/Paris"
},
{
"key" : "userproperty.timeout",
"value" : 30000
},
{
"key" : "userproperty.controller.auth.username",
"value" : "user"
},
{
"key" : "tooltip",
"value" : ""
}
],
"technologyStrId" : null,
"type" : "device"
}
To retrieve a device, use the method getDevice available at /api/asset.
| Arguments | |
|---|---|
| deviceId (required) | Device ID (int) |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Dashboard |
| Desktop |
| Equipment Inventory |
| Failure Tracking |
7.04 Retrieve devices by geozone
Retrieving all streetlight and switch devices belonging to geozone ID 1 and its sub-geozones
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('geozoneId', 1),
('recurse','true'),
('categoryStrId', 'streetlight'),
('categoryStrId', 'switch'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/asset/getGeozoneDevices", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"address" : null,
"categoryStrId" : "streetlight",
"controllerStrId" : "meifoo",
"functionId" : "Lamp1",
"geoZoneId" : 1,
"geoZoneNamesPath" : "GeoZones",
"id" : 5238,
"idOnController" : "227.lamp1",
"lat" : 22.3476744529559,
"lng" : 114.109046459198,
"modelName" : "SysNode double DALI ballasts",
"name" : "227.lamp1",
"nodeTypeStrId" : "sysnode_dali_2b",
"properties" :
[
{
"key" : "dimmable",
"value" : true
},
{
"key" : "controller.firmwareVersion",
"value" : "talq"
},
{
"key" : "power",
"value" : 100.0
},
{
"key" : "powerCorrection",
"value" : 20.0
},
{
"key" : "lampTypeName",
"value" : "/SLV/HPS/70/MAG"
},
{
"key" : "lampLifeTime",
"value" : 20000
},
{
"key" : "userproperty.ballast.dimmingtype",
"value" : "DALI LOG"
},
{
"key" : "userproperty.DimmingGroupName",
"value" : ""
},
{
"key" : "userproperty.location.locationtype",
"value" : "LOCATION_TYPE_PREMISE"
},
{
"key" : "userproperty.network.highvoltagethreshold",
"value" : 245
},
{
"key" : "userproperty.network.lowvoltagethreshold",
"value" : 215
},
{
"key" : "userproperty.network.supplyvoltage",
"value" : "120 Volts"
},
{
"key" : "userproperty.OffLuxLevel",
"value" : 30.0
},
{
"key" : "userproperty.OnLuxLevel",
"value" : 10.0
},
{
"key" : "userproperty.PowerFactorThreshold",
"value" : 0.6
},
{
"key" : "tooltip",
"value" : "SysNode double DALI ballasts[First ballast] - HPS 70W Ferro"
}
],
"technologyStrId" : "lonworks",
"type" : "device"
},
...
]
To retrieve all devices belonging to a specific geozone, use the method getGeozoneDevices available at /api/asset. You may restrict your search to certain device categories by specifying them using categoryStrId.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID (int) |
| recurse | Set to true to obtain devices belonging to the whole geozone tree under the specified geozone. Defaults to false |
| categoryStrId | Category ID (string) |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Dashboard |
| Desktop |
| Equipment Inventory |
| Failure Tracking |
7.05 Retrieve devices by controller
Retrieving all devices belonging to controller mycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getControllerDevices", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"address" : "1-3 Rue de Chalais",
"categoryStrId" : "streetlight",
"controllerStrId" : "mycontroller",
"functionId" : "dimmer0",
"geoZoneId" : 24,
"geoZoneNamesPath" : "GeoZones/Paris/Chalais",
"id" : 45,
"idOnController" : "lamp002",
"lat" : 48.77389325261077,
"lng" : 2.331140041351319,
"modelName" : "XML Light Point v1",
"name" : "Lamp 002",
"nodeTypeStrId" : "xmllightpoint.v1",
"properties" :
[
{
"key" : "dimmable",
"value" : true
},
{
"key" : "controller.firmwareVersion",
"value" : null
},
...
],
"technologyStrId" : "xmltech",
"type" : "device"
},
...
]
To retrieve all devices belonging to a specific controller, use the method getControllerDevices available at /api/asset.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller ID (string) |
| Available with the following applications |
|---|
| Desktop |
| Real-time Control |
7.06 Retrieve devices within boundaries
Retrieving all devices with a latitude between 48.840 and 48.841 and a longitude between 2.378 and 2.381
import requests
payload = {
'latMin':48.840,
'latMax':48.841,
'lngMin':2.378,
'lngMax':2.381,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getDevicesInBounds", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"address" : "5 Boulevard de Bercy",
"categoryStrId" : "controllerdevice",
"controllerStrId" : "newcontroller",
"functionId" : null,
"geoZoneId" : 3837,
"geoZoneNamesPath" : "GeoZones/My new geozone",
"id" : 16871,
"idOnController" : "controllerdevice",
"lat" : 48.84031689136024,
"lng" : 2.3790979385375977,
"modelName" : null,
"name" : "New Controller",
"nodeTypeStrId" : null,
"properties" : null,
"technologyStrId" : null,
"type" : "device"
},
...
]
To retrieve all devices within a certain geographical area, you may use the method getDevicesInBounds available at /api/asset.
| Arguments | |
|---|---|
| latMin (required) | Minimum latitude (float) |
| latMax (required) | Maximum latitude (float) |
| lngMin (required) | Minimum longitude (float) |
| lngMax (required) | Maximum longitude (float) |
| light | If set to true, always returns properties=null. Defaults to true |
| Available with the following applications |
|---|
| Equipment Inventory |
7.07 Retrieve devices closest to a location
Retrieving the device closest to latitude 48.7735 and longitude 2.331145
import requests
payload = {
'latMin': '48.773',
'latMax': '48.774',
'lngMin': '2.33114',
'lngMax': '2.33115',
'maxDevices': '1',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getDevicesNearCenter", params=payload, auth=('USERNAME', 'PASSWORD'))
print (r.text)
Sample response
[
{
"address" : "1-3 Rue de Chalais",
"categoryStrId" : "streetlight",
"controllerStrId" : "mycontroller",
"functionId" : "dimmer0",
"geoZoneId" : 24,
"geoZoneNamesPath" : "GeoZones/Paris/Chalais",
"id" : 45,
"idOnController" : "lamp002",
"lat" : 48.77389325261077,
"lng" : 2.331140041351319,
"modelName" : "XML Light Point v1",
"name" : "Lamp 002",
"nodeTypeStrId" : "xmllightpoint.v1",
"properties" :
[
{
"key" : "dimmable",
"value" : true
}
],
"technologyStrId" : "xmltech",
"type" : "device"
}
]
You may also retrieve all devices within a certain geographical area and closest to the center of that area by using the method getDevicesNearCenter available at /api/asset.
| Arguments | |
|---|---|
| latMin (required) | Minimum latitude (float) |
| latMax (required) | Maximum latitude (float) |
| lngMin (required) | Minimum longitude (float) |
| lngMax (required) | Maximum longitude (float) |
| lightDevices | If set to true, always returns properties=null. Defaults to true |
| maxDevices | Maximum number of results to return. Unlimited by default |
| Available with the following applications |
|---|
| Equipment Inventory |
7.08 Retrieve a device timezone
Retrieve the timezone of device ID 16871
import requests
payload = {
'deviceId':16871,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getDeviceTimeZone", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"displayName" : "Central European Time [+01:00]",
"dstSaving" : 3600000,
"id" : "Europe/Paris",
"rawOffset" : 3600000
}
To retrieve the timezone of a device, call the method getDeviceTimeZone available at /api/asset. The id provided in the result follows the nomenclature used in tzdata.
| Arguments | |
|---|---|
| deviceId (required) | Device ID (int) |
| Available with the following applications |
|---|
| Failure Analysis |
7.09 Retrieve all timezones
Retrieving all timezones available
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/controller/getAvailableTimezones", params=payload, auth=('admin', 'password'))
Sample response
[
{
"displayName" : "Niue Time [-11:00]",
"dstSaving" : 0,
"id" : "Pacific/Niue",
"rawOffset" : -39600000
},
{
"displayName" : "Samoa Standard Time [-11:00]",
"dstSaving" : 0,
"id" : "Pacific/Midway",
"rawOffset" : -39600000
},
...
]
You may retrieve the list of all timezones available on the server by calling the method getAvailableTimezones available at /api/controller. This method has no required parameter.
| Available with the following applications |
|---|
| Desktop |
| Equipment Inventory |
| Report Manager |
7.10 Retrieve all controllers
Retrieving all controllers
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getAllControllers", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"controllerDevice" :
{
"address" : "32 Avenue du Général Leclerc",
"categoryStrId" : "controllerdevice",
"controllerStrId" : "mycontroller",
"functionId" : null,
"geoZoneId" : 24,
"geoZoneNamesPath" : "GeoZones/Chalais",
"id" : 43,
"idOnController" : "controllerdevice",
"lat" : 48.77430688385805,
"lng" : 2.3315960168838505,
"modelName" : null,
"name" : "My Controller",
"nodeTypeStrId" : null,
"properties" :
[
{
"key" : "controller.firmwareVersion",
"value" : null
},
{
"key" : "firmwareVersion",
"value" : null
},
{
"key" : "controller.model",
"value" : null
},
{
"key" : "controller.host",
"value" : "localhost:8005"
},
{
"key" : "controller.installDate",
"value" : "2016/01/04 16:32:28"
},
{
"key" : "controller.updateTime",
"value" : ""
},
{
"key" : "power",
"value" : null
},
{
"key" : "powerCorrection",
"value" : null
},
{
"key" : "tooltip",
"value" : ""
}
],
"technologyStrId" : null,
"type" : "device"
},
"firmwareVersion" : null,
"geoZoneNamesPath" : "GeoZones/Chalais",
"host" : "10.0.0.1:8123",
"id" : null,
"installDate" : "2016-01-04 16:32:28",
"model" : null,
"name" : "My Controller",
"strId" : "mycontroller",
"type" : "controller",
"updateDate" : null
},
...
]
You may retrieve the list of all devices of type "Controller" created on the server by calling the method getAllControllers available at /api/asset. This method has no required parameter.
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
7.11 Retrieve a controller
Retrieving the controller mycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getController", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"controllerDevice" :
{
"address" : "32 Avenue du Général Leclerc",
"categoryStrId" : "controllerdevice",
"controllerStrId" : "mycontroller",
"functionId" : null,
"geoZoneId" : 24,
"geoZoneNamesPath" : "GeoZones/Paris/Chalais",
"id" : 43,
"idOnController" : "controllerdevice",
"lat" : 48.77430688385805,
"lng" : 2.3315960168838505,
"modelName" : null,
"name" : "My Controller",
"nodeTypeStrId" : null,
"properties" :
[
{
"key" : "controller.firmwareVersion",
"value" : null
},
{
"key" : "firmwareVersion",
"value" : null
},
{
"key" : "controller.model",
"value" : null
},
{
"key" : "controller.host",
"value" : "localhost:8005"
},
{
"key" : "controller.installDate",
"value" : "2016/01/04 16:32:28"
},
{
"key" : "controller.updateTime",
"value" : ""
},
{
"key" : "power",
"value" : null
},
{
"key" : "powerCorrection",
"value" : null
},
{
"key" : "tooltip",
"value" : ""
}
],
"technologyStrId" : null,
"type" : "device"
},
"firmwareVersion" : null,
"geoZoneNamesPath" : "GeoZones/Paris/Chalais",
"host" : "localhost:8005",
"id" : null,
"installDate" : "2016-01-04 16:32:28",
"model" : null,
"name" : "My Controller",
"strId" : "mycontroller",
"type" : "controller",
"updateDate" : null
}
You may retrieve a Controller device by its ID by using the method getController available at /api/asset.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller ID (string) |
| Available with the following applications |
|---|
| Control Center |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
7.12 Retrieve controllers using a dimming group
Retriving all controllers that are using the dimming group DimmingLED in geozone ID 1
import requests
payload = {
'name': 'DimmingLED',
'geozoneId': '1',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getControllerStrIdsFromDimmingGroup", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample result
[
"SLV_Demo",
"mycontroller"
]
You may identify controllers that are using a specific dimming group by using the method getControllerStrIdsFromDimmingGroup available at /api/asset
| Arguments | |
|---|---|
| name (required) | Dimming group name |
| geozoneId | Geozone ID (int). Defaults to the user's root geozone |
| Available with the following applications |
|---|
| Scheduling Manager |
7.13 Retrieve device clusters
Retrieving three clusters for streetlight devices with a latitude between 48 and 49 and a longitude between 2 and 3, belonging to geozone ID 1
import requests
payload = {
'latMin': '48',
'latMax': '49',
'lngMin': '2',
'lngMax': '3',
'geozoneId': '1',
'categoryStrId': 'streetlight',
'clustersCount': 3,
'recurse': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/getDevicesClusters", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"count" : 6,
"latCentroid" : 48.87324464444057,
"latMax" : 48.8733940038274,
"latMin" : 48.8729958829734,
"lngCentroid" : 2.3232760045190664,
"lngMax" : 2.32348952227755,
"lngMin" : 2.32307431094284,
"mass" : 6.0,
"variance" : 3.5834473048150056E-7
},
{
"count" : 3,
"latCentroid" : 48.773893252457334,
"latMax" : 48.7740452713285,
"latMin" : 48.773741233432744,
"lngCentroid" : 2.331140041351319,
"lngMax" : 2.3312956094741826,
"lngMin" : 2.330984473228455,
"mass" : 3.0,
"variance" : 9.4623402446814E-8
},
{
"count" : 9,
"latCentroid" : 48.873119329399664,
"latMax" : 48.8734423459107,
"latMin" : 48.8727135300601,
"lngCentroid" : 2.3218937703299423,
"lngMax" : 2.32268138241508,
"lngMin" : 2.3209068826408,
"mass" : 9.0,
"variance" : 0.0000032950002138123737
}
]
You may retrieve device clusters by calling the method getDevicesClusters available at /api/asset. You may restrict the results to certain device categories by specifying them using categoryStrId.
| Arguments | |
|---|---|
| latMin (required) | Minimum latitude (float) |
| latMax (required) | Maximum latitude (float) |
| lngMin (required) | Minimum longitude (float) |
| lngMax (required) | Maximum longitude (float) |
| geozoneId | Geozone ID (int). Defaults to the root geozone |
| categoryStrId | Device categories |
| clusterCount | Maximum number of clusters to return. Defaults to 10 |
| recurse | Set to true to include devices belonging to sub-geozones. Defaults to false |
| Available with the following applications |
|---|
| Equipment Inventory |
| Failure Analysis |
7.14 Update a device
Updating the location of the device
mycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId','mycontroller'),
('idOnController','controllerdevice'),
('valueName', 'lat'),
('value','48.84031689136024'),
('valueName', 'lng'),
('value','2.3790979385375977'),
('doLog', 'true'),
('ser', 'json')
])
r = requests.post(SLV_CMS + "/api/loggingmanagement/setDeviceValues", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
[
"OK:48.84031689136024",
"OK:2.3790979385375977"
]
}
To update a device, use the method setDeviceValues available at /api/loggingmanagement. You must specify the device to update by its controllerStrId and idOnController attributes. The method setDeviceValues can be used to set any number of arbitrary device attributes by taking any number of valueName/value pairs.
You may also use the method setDeviceValue (without the final "s"). However, it accepts only a single (valueName,value) pair.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| valueName (required) | Attribute name |
| value (required) | Attribute value |
| doLog | Set to true to log historical changes in the database. Defaults to false |
| eventTime | Date and time at which the device has been created, in the format YYYY-MM-DD HH:mm:ss (e.g. 2016-08-02 11:45:00). If not specified, it will be automatically generated by the server |
| createDevice | Set to true to create the specified device if it does not exist. Defaults to false |
| Available with the following applications |
|---|
| Equipment Inventory |
| Installation |
| Inventory Verification |
7.15 Delete a device
Deleting the device lamp3 on controller mycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'lamp3',
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/assetmanagement/deleteDevice", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
python "OK"
To delete a single device, use the method deleteDevice available at /api/assetmanagement
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Equipment Inventory |
7.16 Delete devices
Deleting devices lamp1 and lamp2 on controller mycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController','lamp1'),
('controllerStrId', 'mycontroller'),
('idOnController','lamp2'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/assetmanagement/deleteDevices", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
[
"OK",
"OK"
]
}
To delete devices in bulk, use the method deleteDevices available at /api/assetmanagement and specify any number of controllerStrId/idOnController pairs.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Equipment Inventory |
7.17 Replace lamps
Replacing the lamps of both devices lamp1 and lamp2 on controller mycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController','lamp1'),
('controllerStrId', 'mycontroller'),
('idOnController','lamp2'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/monitoringmanagement/replaceLamps", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
[
"OK",
"OK"
]
}
You may replace the lamp on a streetlight device by calling the method replaceLamps available at '/api/monitoringmanagement'. It is possible to specify any number of devices on which to perform this operation by using multiple controllerStrId/idOnController pairs.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Equipment Inventory |
7.18 Replace networked lighting controllers
Replacing the networked lighting controllers of both devices lamp1 (new unique address: A1) and lamp2 (new unique address: A2) on controller mycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController','lamp1'),
('newNetworkId','A1'),
('controllerStrId', 'mycontroller'),
('idOnController','lamp2'),
('newNetworkId', 'A2'),
('ser','json')
])
r = requests.post(SLV_URL + "/api/monitoringmanagement/replaceOLCs", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
[
"OK",
"OK"
]
}
You may replace the networked lighting controller on a streetlight device by calling the method replaceOLCs available at '/api/monitoringmanagement'. It is possible to specify any number of devices on which to perform this operation by using multiple controllerStrId/idOnController/newNetworkId tuples.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| newNetworkId (required) | Unique address of the new networked lighting controller |
| Available with the following applications |
|---|
| Equipment Inventory |
7.19 Commission controllers
Commissioning the controller configuration and devices on controller mycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'flags': 5,
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/controllermanagement/commissionControllerAsync", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"batchId" : "1481018818069",
"batchProgressMessage" : null,
"batchProgressValue" : -1,
"batchRunning" : true,
"cancelRequested" : false,
"cancelled" : false,
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"errorMessagesCount" : 0,
"infoMessagesCount" : 0,
"login" : "admin",
"status" : 0,
"stepResults" :
[
],
"warningMessagesCount" : 0
}
}
To commission a controller, i.e. the controller itself and all devices attached to it, use the method commissionControllerAsync available at /api/controllermanagement.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to commission |
| flags (required) | Indicates which items should be commissioned (int) |
The flags parameter should be specified depending on whether you would like to commission the controller configuration, the dimming schedules applicable to the controller devices or/and the controller devices.
| Flag | Value |
|---|---|
| Controller configuration | 1 |
| Calendar and schedules | 2 |
| Controller devices | 4 |
If you want to commission more than one item, simply add the corresponding values.
As commissioning a controller may take a long time, this method returns a batch object.
| Available with the following applications |
|---|
| Equipment Inventory |
7.20 Commission specific devices
Commissioning devices lamp1 and lamp2 on controller mycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController', 'lamp1'),
('idOnController', 'lamp2'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/controllermanagement/commissionControllerDevicesListAsync", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"batchId" : "1481011141616",
"batchProgressMessage" : null,
"batchProgressValue" : -1,
"batchRunning" : true,
"cancelRequested" : false,
"cancelled" : false,
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"errorMessagesCount" : 0,
"infoMessagesCount" : 0,
"login" : "admin",
"status" : 0,
"stepResults" :
[
],
"warningMessagesCount" : 0
}
}
To commission a list of devices that are not controllers, use the method commissionControllerDevicesListAsync available at /api/controllermanagement. It is possible to commission multiple devices at once as long as they all belong to the same controller. To do so, specify multiple idOnController.
As commissioning devices may take a long time, this method returns a batch object.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Equipment Inventory |
7.21 Import devices with a CSV
The CSV file should be formatted as follows:
attribute1_name;attribute2_name;...;attributeN_name
device1_attribute1_value;device1_attribute2_value;...;device1_attributeN_value
...
deviceM_attribute1_value;deviceM_attribute2_value;...;deviceM_attributeN_value
Importing devices via a CSV file (devices.csv)
import requests
with open('devices.csv', 'r') as myfile:
data=myfile.read()
payload = {
'csvFile': data,
'ser': 'json'
}
r = requests.post(SLV_URL + "/api/loggingmanagement/importDevicesFromCsvFileAsync", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"batchId" : "1483515808928",
"batchProgressMessage" : null,
"batchProgressValue" : 0,
"batchRunning" : true,
"cancelRequested" : false,
"cancelled" : false,
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"lineResults" :
[
null
],
"lineResultsErrorCount" : 0,
"lineResultsOkCount" : 0,
"lineResultsUndefinedCount" : 0,
"lineResultsWarningCount" : 0,
"linesResultsCount" : 0,
"properties" : null,
"running" : true,
"totalLinesResultsCount" : 1
}
}
You may create devices in bulk by importing a CSV file. The method to use is importDevicesFromCsvFileAsync, available at /api/loggingmanagement.
| Arguments | |
|---|---|
| csvFile (required) | Content of the CSV file |
| separatorChar | CSV separator. Defaults to semicolon |
| quoteChar | CSV quote character. Defaults to null |
| Available with the following applications |
|---|
| Equipment Inventory |
7.22 Import devices with a SDP
Importing devices via an SDP file (devices.sdp)
import requests
params = {'ser': 'json'}
payload = {'importSchedulers': 'false'}
files = {'sdpFile': ('devices.sdp', open('devices.sdp', 'rb'), 'application/octet-stream')}
r = requests.post(SLV_URL + "/api/loggingmanagement/importDevicesFromSdpFileAsync", params=params, data=payload, files=files, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"batchId" : "1483517633500",
"batchProgressMessage" : null,
"batchProgressValue" : -1,
"batchRunning" : true,
"cancelRequested" : false,
"cancelled" : false,
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"login" : "admin",
"project" : null,
"projectDisplayName" : null,
"properties" : null,
"running" : true,
"status" : 0,
"stepResults" :
[
]
}
}
You may also create devices in bulk by importing a SDP file for powerline projects. The method to use in this case is importDevicesFromSdpFileAsync, available at /api/loggingmanagement.
| Arguments | |
|---|---|
| sdpFile (required) | Content of the SDP file |
| importSchedulers | Set to true to also import schedulers contained in the SDP file. Defaults to true |
| Available with the following applications |
|---|
| Equipment Inventory |
7.23 Search for devices
Searching for devices whose name contain lamp in geozone ID 1, limiting results to 2
import requests
payload = {
'geozoneId': '1',
'recurse': 'true',
'returnedInfo': 'lightDevicesList',
'attributeName': 'name',
'attributeOperator': 'partial-match-i',
'attributeValue': 'lamp',
'maxResults': 2,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/asset/searchDevicesExt", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
[
{
"address" : "1-3 Rue de Chalais",
"categoryStrId" : "streetlight",
"controllerStrId" : "mycontroller",
"functionId" : "dimmer0",
"geoZoneId" : 24,
"geoZoneNamesPath" : "GeoZones/Chalais",
"id" : 44,
"idOnController" : "lamp001",
"lat" : 48.7740452713285,
"lng" : 2.3312956094741826,
"modelName" : "XML Light Point v1",
"name" : "Lamp 001",
"nodeTypeStrId" : "xmllightpoint.v1",
"properties" :
[
{
"key" : "dimmable",
"value" : true
}
],
"technologyStrId" : "xmltech",
"type" : "device"
},
{
"address" : "1-3 Rue de Chalais",
"categoryStrId" : "streetlight",
"controllerStrId" : "mycontroller",
"functionId" : "dimmer0",
"geoZoneId" : 24,
"geoZoneNamesPath" : "GeoZones/Chalais",
"id" : 45,
"idOnController" : "lamp002",
"lat" : 48.77389325261077,
"lng" : 2.331140041351319,
"modelName" : "XML Light Point v1",
"name" : "Lamp 002",
"nodeTypeStrId" : "xmllightpoint.v1",
"properties" :
[
{
"key" : "dimmable",
"value" : true
}
],
"technologyStrId" : "xmltech",
"type" : "device"
}
]
}
You may search for devices by using the method searchDevicesExt available at /api/asset. Each search criterion requires you to specify the attribute name being searched for, the search operator and the searched value. It is possible to add multiple search critiera by specifying multiple tuples (attributeName,attributeOperator,attributeValue); they will be linked with a logical AND by the server.
| Arguments | |
|---|---|
| geozoneId | ID of the geozone to search into. Defaults to the root geozone |
| recurse | Set to true to search in all sub-geozones recursively. Defaults to false |
| returnedInfo | Determines what kind of result is provided by the server, see below. Defaults to lightDevicesList |
| attributeName | Searched attribute name |
| attributeOperator | Search operator (see getDevicesLastValuesExtAsPaginatedArray for the list of accepted operators) |
| attributeValue | Searched value. If the search operator is binary, the two values should be separated by a pipe |
| maxResults | Maximum number of results to be returned by the server |
Below is a description of each possible value for returnedInfo:
| Value | Description |
|---|---|
| lightDevicesList | List of matching devices with only basic information about each device |
| devicesList | List of matching devices with extended information about each device |
| ids | List of the IDs of matching devices |
| devicesCount | Number of matching devices |
| Available with the following applications |
|---|
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Tracking |
| Inventory Verification |
| Real-time Control |
8. Device attributes
8.01 Retrieve device inventory attributes
Retrieving all inventory attributes for the device
mycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'controllerdevice',
'configFilePath': 'adminEquipmentsDeviceCardConfigs.xml',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/logging/getDeviceValueDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "internal",
"criticity" : 0,
"dataFormat" :
{
"readOnly" : "true",
"max.length" : "32",
"format" : "[a-zA-Z0-9\\[\\]_\\-@!:\\. ]+",
"mainGroup" : "controller.identity",
"mainGroup.labelKey" : "mainGroup.controller.identity.label",
"subGroup" : "controller.identity.group1",
"subGroup.labelKey" : "subGroup.controller.identity.group1.label",
"mainGroup.label" : "Identity",
"subGroup.label" : "Identity of the controller"
},
"failure" : false,
"help" : null,
"label" : "Controller ID",
"labelKey" : "db.meaning.controllerstrid.label",
"name" : "controllerStrId",
"type" : "string",
"unit" : null
},
...
]
To retrieve all inventory attributes available for a device, use the method getDeviceValueDescriptors available at /api/logging.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| configFilePath (required) | Always set to adminEquipmentsDeviceCardConfigs.xml |
| Available with the following applications |
|---|
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Equipment Inventory |
| Energy |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.02 Retrieve virtual device inventory attributes
Retrieving the inventory attributes for electrical meters. Note that in this example, for illustrative purposes we have added a second property (geozone) which actually has no influence on the server response.
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('propertyName', 'categoryStrId'),
('propertyValue', 'electricalCounter'),
('propertyName', 'geozone'),
('propertyValue', 'GeoZones/Paris'),
('configFilePath', 'adminEquipmentsDeviceCardConfigs.xml'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getVirtualDeviceValueDescriptors", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "internal",
"criticity" : 0,
"dataFormat" :
{
"max.length" : "32",
"editable" : "false",
"mandatory" : "true",
"format" : "[a-zA-Z0-9\\[\\]_\\-@!:\\. ]+",
"select.listingApiCall" : "SLVAssetAPI!getAllControllers",
"select.listingApiCall.labelPropertyName" : "name",
"select.listingApiCall.valuePropertyName" : "strId",
"mainGroup" : "energymeter.identity",
"mainGroup.labelKey" : "mainGroup.energymeter.identity.label",
"subGroup" : "energymeter.identity.group1",
"subGroup.labelKey" : "subGroup.energymeter.identity.group1.label",
"mainGroup.label" : "Identity",
"subGroup.label" : "Identity of the energy meter"
},
"failure" : false,
"help" : null,
"label" : "Controller ID",
"labelKey" : "db.meaning.controllerstrid.label",
"name" : "controllerStrId",
"type" : "select",
"unit" : null
},
...
]
You can also retrieve all inventory attributes available for a type of device without specifying an existing device. To do so, use the method getVirtualDeviceValueDescriptors available at /api/logging. This method takes an arbitrary number of (propertyName, propertyValue) pairs, but you will probably want to use a single pair to specify the device type, for instance propertyName = categoryStrId and propertyValue = streetlight.
| Arguments | |
|---|---|
| propertyName (required) | Device attribute name |
| propertyValue (required) | Device attribute value |
| configFilePath (required) | Always set to adminEquipmentsDeviceCardConfigs.xml |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Data History |
| Device History |
| Equipment Inventory |
| Installation |
8.03 Retrieve all device inventory attributes
Retrieving all device inventory attributes available
import requests
payload = {
'configFilePath': 'adminEquipmentsDeviceCardConfigs.xml',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/logging/getAllDevicesMeteringValueDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "internal",
"criticity" : 0,
"dataFormat" :
{
"max.length" : "32",
"editable" : "false",
"mandatory" : "true",
"format" : "[a-zA-Z0-9\\[\\]_\\-@!:\\. ]+",
"select.listingApiCall" : "SLVAssetAPI!getAllControllers",
"select.listingApiCall.labelPropertyName" : "name",
"select.listingApiCall.valuePropertyName" : "strId",
"mainGroup" : "networkcomponent.identity",
"mainGroup.labelKey" : "mainGroup.networkcomponent.identity.label",
"subGroup" : "networkcomponent.identity.group1",
"subGroup.labelKey" : "subGroup.networkcomponent.identity.group1.label",
"mainGroup.label" : "Identity",
"subGroup.label" : "Identity of the Network Component"
},
"failure" : false,
"help" : null,
"label" : "Controller ID",
"labelKey" : "db.meaning.controllerstrid.label",
"name" : "controllerStrId",
"type" : "select",
"unit" : null
},
...
]
To retrieve all device inventory attributes available, you may call the method getAllDevicesMeteringValueDescriptors available at /api/logging.
| Arguments | |
|---|---|
| configFilePath (required) | Always set to adminEquipmentsDeviceCardConfigs.xml |
| Available with the following applications |
|---|
| Real-time Control |
8.04 Retrieve device logging attributes
Retrieving all inventory attributes for the device
mycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'controllerdevice',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/logging/getDeviceValueDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "standard",
"criticity" : 0,
"dataFormat" : null,
"failure" : false,
"help" : null,
"label" : "Digital Input 1",
"labelKey" : "db.meaning.digitalinput1.label",
"name" : "DigitalInput1",
"type" : "boolean",
"unit" : null
},
...
]
To retrieve all logging attributes available for a device, use the method getDeviceValueDescriptors available at /api/logging without specifying any configFilePath.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Equipment Inventory |
| Energy |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.05 Retrieve device attributes by name
Retrieving the description of the attributes
latandlng
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('valueName', 'lat'),
('valueName', 'lng'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getDeviceValueDescriptorsByName", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
[
{
"category" : "internal",
"criticity" : 0,
"dataFormat" :
{
},
"failure" : false,
"help" : null,
"label" : "lat",
"labelKey" : null,
"name" : "lat",
"type" : "double",
"unit" : null
},
{
"category" : "internal",
"criticity" : 0,
"dataFormat" :
{
},
"failure" : false,
"help" : null,
"label" : "lng",
"labelKey" : null,
"name" : "lng",
"type" : "double",
"unit" : null
}
]
}
You may retrieve the description and details of device attributes if you always know their name by using the method getDeviceValueDescriptorsByName available at /api/logging. You may specify any number of attributes.
| Arguments | |
|---|---|
| valueName (required) | Attribute name |
| Available with the following applications |
|---|
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Equipment Inventory |
| Energy |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.06 Retrieve existing values for an attribute
Retrieving all existing values for the attribute luminaire.type
import requests
payload = {
'valueName': 'luminaire.type',
'quick': 'true',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/logging/getDistinctExistingValues", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"properties" :
{
"count" : "2"
},
"value" : "Type A"
},
{
"properties" :
{
"count" : "1"
},
"value" : "Type B"
}
]
You may retrieve the list of existing values for an inventory attribute by calling the method getDistinctExistingValues available at /api/logging.
| Arguments | |
|---|---|
| valueName (required) | Attribute name |
| quick | Defaults to false |
| geozoneId | Geozone ID (int). Defaults to the user's root geozone |
| recurse | Set to true to search through devices belonging to all sub-geozones. Defaults to true |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.07 Retrieve attributes by file
Retrieve all device attributes in gcCustomReportReportValuesSelected.xml
import requests
payload = {
'configFilePath': 'gcCustomReportReportValuesSelected.xml',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/logging/getAllDevicesValueDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "internal",
"criticity" : 0,
"dataFormat" :
{
"max.length" : "77",
"mainGroup" : "controller.inventory",
"mainGroup.labelKey" : "mainGroup.controller.inventory.label",
"subGroup" : "controller.inventory.location",
"subGroup.labelKey" : "subGroup.lightpoint.inventory.location.label",
"subGroup.collapsed" : "true",
"ExcludeFromCommissioning" : "true",
"mainGroup.label" : "Inventory",
"subGroup.label" : "Location"
},
"failure" : false,
"help" : null,
"label" : "Address 1",
"labelKey" : "db.meaning.address.label",
"name" : "address",
"type" : "string",
"unit" : null
},
...
]
You may retrieve all device attributes listed in a server-side configuration file by calling the method getAllDevicesValueDescriptors available at /api/logging.
| Arguments | |
|---|---|
| configFilePath (required) | File name |
The following file names are available:
| File name | Description |
|---|---|
| gcCustomReportReportValues.xml | |
| gcCustomReportReportValuesSelected.xml | |
| gcCustomReportReportValuesFavorites.xml | |
| gcDataHistoryReportValues.xml | |
| gcDataHistoryReportValuesSelected.xml | |
| gcDataHistoryReportValuesFavorites.xml | |
| gcEquipmentsReportValues.xml | |
| gcEquipmentsReportValuesSelected.xml | |
| gcEquipmentsReportValuesFavorites.xml |
| Available with the following applications |
|---|
| Equipment Inventory |
8.08 Retrieve devices attributes by file and category
Retrieving electrical counter attributes from the server configuration file batchApplicationDeviceCardConfigs.xml
import requests
payload = {
'categoryStrId': 'electricalCounter',
'configFilePath': 'batchApplicationDeviceCardConfigs.xml',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/logging/getCategoryDevicesValueDescriptors", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"category" : "standard",
"criticity" : 0,
"dataFormat" : null,
"failure" : false,
"help" : null,
"label" : "Lamp wattage (W)",
"labelKey" : "db.meaning.power.label",
"name" : "Power",
"type" : "float",
"unit" : "W"
},
{
"category" : "standard",
"criticity" : 0,
"dataFormat" : null,
"failure" : false,
"help" : null,
"label" : "Power - L1 (W)",
"labelKey" : "db.meaning.phase1power.label",
"name" : "PowerPhase1",
"type" : "float",
"unit" : "W"
},
...
]
You may retrieve device attributes listed in a server-side configuration for specific categories and that are applicable to existing devices only by calling the method getCategoryDevicesValueDescriptors available at /api/logging.
| Arguments | |
|---|---|
| categoryStrId (required) | Device category. Muutiple categories can be specified by separating them with a pipe character |
| configFilePath (required) | File name |
| Available with the following applications |
|---|
| Equipment Inventory |
8.09 Retrieve attributes values for a single device
Retrieving the latitude and longitude of device ID 16879
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('param0', '16879'),
('valueName', 'lat'),
('valueName', 'lng'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getDeviceLastValues", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"controllerStrId" : "mycontroller",
"deviceId" : 16879,
"errorMessage" : null,
"eventTime" : null,
"eventTimeAgeInSeconds" : null,
"idOnController" : "lamp1",
"info" : null,
"meaningLabel" : null,
"name" : "lat",
"status" : "OK",
"updateTime" : null,
"value" : 48.84032042200468
},
{
"controllerStrId" : "mycontroller",
"deviceId" : 16879,
"errorMessage" : null,
"eventTime" : null,
"eventTimeAgeInSeconds" : null,
"idOnController" : "lamp1",
"info" : null,
"meaningLabel" : null,
"name" : "lng",
"status" : "OK",
"updateTime" : null,
"value" : 2.3801171779632573
}
]
To retrieve the latest values for a single device attributes, use the method getDeviceLastValues available at /api/logging. You may retrieve the value of multiple attributes at once by specifying multiple valueName.
| Arguments | |
|---|---|
| param0 (required) | Device ID (int) |
| valueName (required) | Attribute name |
| returnTimeAges | Set to true to retrieve information about when those values have been recorded. Defaults to false |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.10 Retrieve attributes values for multiple devices
Retrieving the latitude and longitude of devices ID 16879 and 16880
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('param0', '16879'),
('param0', '16880'),
('param1', 'lat'),
('param1', 'lng'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getDevicesLastValues", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"controllerStrId" : "mycontroller",
"deviceId" : 16879,
"errorMessage" : null,
"eventTime" : null,
"eventTimeAgeInSeconds" : null,
"idOnController" : "lamp1",
"info" : null,
"meaningLabel" : null,
"name" : "lat",
"status" : "OK",
"updateTime" : null,
"value" : 48.84032042200468
},
{
"controllerStrId" : "mycontroller",
"deviceId" : 16879,
"errorMessage" : null,
"eventTime" : null,
"eventTimeAgeInSeconds" : null,
"idOnController" : "lamp1",
"info" : null,
"meaningLabel" : null,
"name" : "lng",
"status" : "OK",
"updateTime" : null,
"value" : 2.3801171779632573
},
{
"controllerStrId" : "mycontroller",
"deviceId" : 16880,
"errorMessage" : null,
"eventTime" : null,
"eventTimeAgeInSeconds" : null,
"idOnController" : "lamp2",
"info" : null,
"meaningLabel" : null,
"name" : "lat",
"status" : "OK",
"updateTime" : null,
"value" : 48.840272758283675
},
{
"controllerStrId" : "mycontroller",
"deviceId" : 16880,
"errorMessage" : null,
"eventTime" : null,
"eventTimeAgeInSeconds" : null,
"idOnController" : "lamp2",
"info" : null,
"meaningLabel" : null,
"name" : "lng",
"status" : "OK",
"updateTime" : null,
"value" : 2.380476593971253
}
]
To retrieve the latest values for multiple devices, use the method getDevicesLastValues available at /api/logging. You may specify multiple param0 and param1 to retrieve the value of several attributes on more than one device.
| Arguments | |
|---|---|
| param0 (required) | Device ID (int) |
| param1 (required) | Attribute name |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.11 Retrieve attributes values for multiple devices in an array
Retrieving the latitude and longitude of devices ID 10828 and 10829
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('deviceId', '10828'),
('deviceId', '10829'),
('valueName', 'lat'),
('valueName', 'lng'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getDevicesLastValuesAsArray", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"columnLabels" : null,
"columns" :
[
"lat",
"lng"
],
"columnsCount" : 2,
"properties" :
{
},
"rowsCount" : 2,
"values" :
[
[
35.15467904755724,
129.12042617797854
],
[
35.154731678957035,
129.12062466144565
]
]
}
To retrieve the latest values for multiple devices in a more condensed format, use the method getDevicesLastValuesAsArray available at /api/logging. You may specify multiple deviceId and valueName to retrieve the value of several attributes on more than one device.
| Arguments | |
|---|---|
| devceId (required) | Device ID (int) |
| valueName (required) | Attribute name |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.12 Retrieve attributes values for a whole geozone
Retrieving the name, latitude and longitude of all streetlights and controllers in geozone ID 3837. We also want to rename the columns in the result from lat and lng to Latitude and Longitude.
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('geozoneId', '3837'),
('categoryStrId', 'streetlight'),
('categoryStrId', 'controllerdevice'),
('valueName', 'name'),
('valueName', 'lat'),
('valueName', 'lng'),
('columnName', 'lat:Latitude'),
('columnName', 'lng:Longitude'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getGeoZoneDevicesLastValuesAsArray", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"columnLabels" : null,
"columns" :
[
"name",
"Latitude",
"Longitude"
],
"columnsCount" : 3,
"properties" :
{
},
"rowsCount" : 4,
"values" :
[
[
"New Controller",
48.84031689136024,
2.3790979385375977
],
[
"My controller",
48.84031689136024,
2.3790979385375977
],
[
"Lamp 1",
48.84032042200468,
2.3801171779632573
],
[
"Lamp 2",
48.840272758283675,
2.380476593971253
]
]
}
To retrieve the latest values for all devices belonging to a geozone, use the method getGeozoneDevicesLastValuesAsArray available at /api/logging. You may specify multiple categories and attributes by adding multiple categoryStrId and valueName to your request.
In the server response, columns will list the attribute names by default. If you would like to receive different names instead, you may specify multiple columnName, one per attribute to rename, in the format attribute name:desired column name.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID (int) |
| categoryStrId (required) | Category |
| valueName (required) | Attribute name |
| columnName | Mapping between the attribute name and the desired column name |
| recurse | Set to true to obtain devices belonging to the whole geozone tree under the specified geozone. Defaults to false |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.13 Retrieve paginated attributes values for a whole geozone
Retrieving the name, latitude and longitude of all devices in geozone ID 3837, with two devices per page and reading the second page.
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('geozoneId', '3837'),
('returnedValueName', 'name'),
('returnedValueName', 'lat'),
('returnedValueName', 'lng'),
('pageSize', '2'),
('pageIndex', '1'),
('recurse', 'false'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getDevicesLastValuesExtAsPaginatedArray", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"columnLabels" : null,
"columns" :
[
"name",
"lat",
"lng"
],
"columnsCount" : 3,
"pageIndex" : 1,
"pageSize" : 2,
"pagesCount" : 3,
"properties" :
{
},
"rowsCount" : 2,
"totalSize" : 5,
"values" :
[
[
"My controller",
48.84031689136024,
2.3790979385375977
],
[
"Lamp 1",
48.84032042200468,
2.3801171779632573
]
]
}
To retrieve the latest values for all devices belonging to a geozone, but with a paginated response from the server, use the method getDevicesLastValuesExtAsPaginatedArray available at /api/logging. You may specify multiple attributes by adding multiple returnedValueName to your request.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID (int) |
| returnedValueName (required) | Attribute name |
| pageSize (required) | Number of devices per page |
| pageIndex (required) | Page number, starting from zero |
| recurse (required) | Set to true to obtain devices belonging to the whole geozone tree under the specified geozone |
| addEventTimeColumns | Set to true to retrieve the date and time at which those values have been recorded. Defaults to false |
| filterAttributeName | Searched attribute name |
| filterAttributeOperator | Search operator |
| filterAttributeValue | Searched value. If the search operator is binary, the two values should be separated by a pipe |
| sortColumn | Sort attribute name |
| sortDesc | Set to true to sort in descending order, false in ascending order |
You may also restrict the results by adding search criteria. Each search criterion requires you to specify the attribute name being searched for, the search operator and the searched value. It is possible to add multiple search critiera by specifying multiple tuples (filterAttributeName, filterAttributeOperator, filterAttributeValue). Search operators available are listed below:
| Operator | Description |
|---|---|
| eq | EQUAL |
| ne | NOT EQUAL |
| eq-i | EQUAL IGNORE CASE |
| like | LIKE |
| like-i | LIKE IGNORE CASE |
| partial-match | PARTIAL MATCH |
| partial-match-i | PARTIAL MATCH IGNORE CASE |
| in | IN |
| gt | GREATER THAN |
| ge | GREATER OR EQUAL |
| lt | LOWER THAN |
| le | LOWER OR EQUAL |
| nin | NOT IN |
| begins | BEGINS |
| begins-i | BEGINS IGNORE CASE |
| ends | ENDS |
| ends-i | ENDS IGNORE CASE |
| between | BETWEEN |
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Dashboard |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
8.14 Retrieve attributes values for a whole geozone in a CSV file
Creating a CSV file called
All devices named -lamp- in geozone 3837with the name, latitude and longitude of all devices in geozone ID 3837 whose name containlamp
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('geozoneId', '3837'),
('returnedValueName', 'name'),
('returnedValueName', 'lat'),
('returnedValueName', 'lng'),
('recurse', 'false'),
('filterAttributeName', 'name'),
('filterAttributeOperator', 'partial-match-i'),
('filterAttributeValue', 'lamp'),
('csvPropertyName', 'fileBaseName'),
('csvPropertyValue', 'All devices named -lamp- in geozone 3837'),
('csvPropertyName', 'separatorChar'),
('csvPropertyValue', ';'),
('csvPropertyName', 'header'),
('csvPropertyValue', 'true'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/createDevicesLastValuesExtAsPaginatedArrayCsvFileUrl", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" : "/repository/protected-files/exports/admin/e036605902c02dd00b6e4574cc4b9f53/All%20devices%20named%20-lamp-%20in%20geozone%203837.csv"
}
To obtain the latest values for all devices belonging to a geozone inside a CSV file, call the method createDevicesLastValuesExtAsPaginatedArrayCsvFileUrl available at /api/logging.
| Arguments | |
|---|---|
| geozoneId (required) | Geozone ID (int) |
| returnedValueName (required) | Attribute name |
| recurse (required) | Set to true to obtain devices belonging to the whole geozone tree under the specified geozone |
| addEventTimeColumns | Set to true to retrieve the date and time at which those values have been recorded. Defaults to false |
| filterAttributeName | Searched attribute name |
| filterAttributeOperator | Search operator |
| filterAttributeValue | Searched value. If the search operator is binary, the two values should be separated by a pipe |
| csvPropertyName | CSV property name |
| csvPropertyValue | CSV property value |
CSV properties are described below. Note that it is possible to specify multiple properties by adding several couples csvPropertyName/csvPropertyValue to your request.
| CSV property name | Description |
|---|---|
| fileBaseName | CSV filename (excluding the .csv extension) |
| separatorChar | CSV separator |
| header | If set to true, includes a header line in the CSV file |
The server responds with a file path in value. You may then download the file from the concatenation of SLV_URL and value.
| Available with the following applications |
|---|
| Advanced Search |
| Data History |
| Equipment Inventory |
8.15 Retrieve device logging history
Retrieving the values of
LampLevelandLampCommandLevelon devices ID 5229 and 5230 between Nov 1st 2016 1:00pm and Nov 17th 2016 1:00pm
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('deviceId', '5229'),
('deviceId', '5230'),
('name', 'LampLevel'),
('name', 'LampCommandLevel'),
('from', '01/11/2016 13:00:00'),
('to', '17/11/2016 13:00:00'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/logging/getDevicesLogValues", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
[
{
"controllerStrId" : "flowermarket",
"deviceId" : 5230,
"errorMessage" : null,
"eventTime" : "2016-11-07 11:00:00",
"eventTimeAgeInSeconds" : null,
"idOnController" : "stl0002",
"info" : "",
"meaningLabel" : null,
"name" : "LampLevel",
"status" : "OK",
"updateTime" : "2016-11-07 18:08:07",
"value" : 100.0
},
{
"controllerStrId" : "flowermarket",
"deviceId" : 5229,
"errorMessage" : null,
"eventTime" : "2016-11-07 18:02:26",
"eventTimeAgeInSeconds" : null,
"idOnController" : "stl0001",
"info" : "",
"meaningLabel" : null,
"name" : "LampCommandLevel",
"status" : "OK",
"updateTime" : "2016-11-07 18:02:26",
"value" : 55.0
},
...
]
To retrieve the values of a device logging attribute over a period of time, use the method getDevicesLogValues available at /api/logging. You may specify multiple devices and/or multiple attributes.
| Arguments | |
|---|---|
| deviceId (required) | Device ID (int) |
| name (required) | Attribute name |
| from (required) | Start date and time in the format dd/MM/yyyy HH:mm:ss |
| to (required) | End date and time in the format dd/MM/yyyy HH:mm:ss |
| Available with the following applications |
|---|
| Dashboard |
| Data History |
| Device History |
| Energy |
| Failure Analysis |
9. Schedules
The schedule
A schedule is, in its simplest representation, a list of events (turn on, turn off, dim to a certain level) that devices must perform at specific times; those times may be absolute (e.g. 23:00) or relative to sunrise or sunset (e.g. five minutes before sunset). It is identified by a server-generated numeric ID and is attached to a geozone.
| Attributes | |
|---|---|
| id | Schedule ID (int) |
| name | Device name |
| type | Always set to schedule |
| category | Always set to STREETLIGHT_DIMMING |
| color | Color used to represent the schedule on the user interface. This attribute provides individual numerical values for red, green, blue and alpha channels in addition to the HTML color code |
| description | Textual description of the schedule |
| geozonePath | Geozone path attached to the schedule |
| readOnly | Indicates whether the current user is allowed to edit it (boolean) |
| template | Unused |
| timeline | Either T_12_12 for noon-to-noon or T_00_24 for midnight-to-midnight |
See the next chapter for more details about schedule events.
9.01 Create a schedule
Creating a new schedule called "Simple schedule" with a few attributes
import requests
payload = {
'name': 'Simple schedule',
'category': 'STREETLIGHT_DIMMING',
'color': '#FF424242',
'description': 'A sample schedule',
'timeline': 'T_12_12',
'template': '',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/createSchedule", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": 8
}
To create a new schedule, use the method createSchedule available at /api/dimmingscheduler. It returns the ID of the new schedule in value. A new schedule is always empty, so you need to add events to it: see the Schedule Events chapter for more details.
| Arguments | |
|---|---|
| name (required) | Schedule name |
| color | HTML code of the color used to represent the schedule on the user interface, including alpha channel |
| category | Only STREETLIGHT_DIMMING is supported |
| description | Textual description of the schedule |
| template | Unused, leave empty |
| timeline | Either T_12_12 for noon-to-noon or T_00_24 for midnight-to-midnight |
| Available with the following applications |
|---|
| Scheduling Manager |
9.02 Retrieve all schedules
Retrieving all schedules in the category 'STREETLIGHT_DIMMING'
import requests
payload = {
'category': 'STREETLIGHT_DIMMING',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/dimmingscheduler/getSchedules", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": [
{
"category": "STREETLIGHT_DIMMING",
"color": {
"alpha": 255,
"blue": 58,
"code": "#ffb3313a",
"green": 49,
"red": 179
},
"description": "",
"geoZonePath": "GeoZones",
"id": 1,
"name": "Simple scheduler",
"readOnly": false,
"template": "",
"timeline": "T_12_12",
"type": "schedule"
}
]
}
To retrieve all schedules, use the method getSchedules available at /api/dimmingscheduler
| Arguments | |
|---|---|
| category | Only STREETLIGHT_DIMMING is supported |
| Available with the following applications |
|---|
| Scheduling Manager |
9.03 Update a schedule
Updating schedule ID 8
import requests
payload = {
'scheduleId': 8,
'name': 'Simple SLV schedule',
'color': '#FFFF0000',
'description': 'A simple updated schedule',
'timeline': 'T_12_12',
'template': '',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/updateSchedule", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": null
}
To update an existing schedule, use the method updateSchedule available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| scheduleId (required) | Schedule ID (int) |
| name | Schedule name |
| color | HTML code of the color used to represent the schedule on the user interface, including alpha channel |
| description | Textual description of the schedule |
| template | Unused, leave empty |
| timeline | Either T_12_12 for noon-to-noon or T_00_24 for midnight-to-midnight |
| Available with the following applications |
|---|
| Scheduling Manager |
9.04 Delete a schedule
Deleting schedule ID 8
import requests
payload = {
'scheduleId': 8,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/deleteSchedule", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": null
}
To delete a schedule, use the method deleteSchedule available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| scheduleId (required) | Schedule ID (int) |
| Available with the following applications |
|---|
| Scheduling Manager |
10. Schedule events
The schedule event
A schedule event can be either punctual or occur over a time period. In the former case, it only has a start time. In the latter case, it has both a start and an end time. In addition, when an event occurs over a sun-based time period, it can include other sub-events; those sub-events cannot occur if they fall outside of the time period of the parent event.
Note that schedule events are never updated: they are deleted then recreated if necessary.
| Attributes | |
|---|---|
| id | Event ID (int) |
| name | Event name |
| type | Event type |
| start | Start time |
| end | End time |
| events | List of events happening between start and end |
| level | Dimming level (0 - 100) |
Absolute start and end times are represented as follows:
| Attributes | |
|---|---|
| hour | Hour (0-23) |
| minutes | Minutes (0-59) |
| seconds | Seconds (0-59) |
| milliseconds | Milliseconds (0-999) |
| afterNoon | Indicates whether the event occurs before or after noon (boolean) |
| afterNoonOrEqual | Indicates whether the event occurs before or after noon (boolean) |
| beforeNoon | Indicates whether the event occurs before or after noon (boolean) |
| beforeNoonOrEqual | Indicates whether the event occurs before or after noon (boolean) |
| noon | Indicates whether the event occurs exactly at noon (boolean) |
Sun-based start and end times are represented as follows:
| Attributes | |
|---|---|
| offsetInSeconds | Offset with the sun-based event in seconds. A negative number indicates a number of seconds before the event, while a positive number indicates a number of seconds after the event |
| sunEvent | SUNRISE or SUNSET |
| afterNoon | Indicates whether the event occurs before or after noon (boolean) |
| afterNoonOrEqual | Indicates whether the event occurs before or after noon (boolean) |
| beforeNoon | Indicates whether the event occurs before or after noon (boolean) |
| beforeNoonOrEqual | Indicates whether the event occurs before or after noon (boolean) |
| noon | Indicates whether the event occurs exactly at noon (boolean) |
10.01 Add a sun-based schedule event
Adding a turn on event at 100% five minutes after sunset to schedule ID 9
import requests
payload = {
'scheduleId': 9,
'level':100,
'startSunEvent':'SUNSET',
'startOffsetInSeconds':300,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/addSunEventDayTimeScheduleEvent", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": 21
}
To add a sub-based schedule event, use the method addSunEventDayTimeScheduleEvent available at /api/dimmingscheduler. This method returns the event ID generated by the server.
| Arguments | |
|---|---|
| scheduleId (required) | Schedule ID (int) |
| startSunEvent (required) | Type of start event: SUNRISE or SUNSET |
| startOffsetInSeconds (required) | Offset with the start event in seconds. A negative number indicates a number of seconds before the event, while a positive number indicates a number of seconds after the event |
| level (required) | Dimming level (0 - 100) |
| endSunEvent | Type of end event: SUNRISE or SUNSET |
| endOffsetInSeconds | Offset with the end event in seconds. A negative number indicates a number of seconds before the event, while a positive number indicates a number of seconds after the event |
| parentEventId | Parent event ID when the event is a child of another event |
| name | Name of the event |
| Available with the following applications |
|---|
| Scheduling Manager |
10.02 Add an absolute schedule event
Adding a dimming event to 78% at 22:30:00 to schedule ID 9
import requests
payload = {
'scheduleId': 9,
'level':78,
'startHour':22,
'startMinute':30,
'startSecond':0,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/addAbsoluteDayTimeScheduleEvent", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": 24
}
To add an absolute schedule event, use the method addAbsoluteDayTimeScheduleEvent available at /api/dimmingscheduler. This method returns the event ID generated by the server.
| Arguments | |
|---|---|
| scheduleId (required) | Schedule ID (int) |
| startHour (required) | Hour (0-23) |
| startMinute (required) | Minutes (0-59) |
| startSecond (required) | Seconds (0-59) |
| level (required) | Dimming level (0 - 100) |
| parentEventId | Parent event ID when the event is a child of another event |
| name | Name of the event |
| Available with the following applications |
|---|
| Scheduling Manager |
10.03 Retrieve schedule events
Retrieving all events of the schedule ID 1
import requests
payload = {
'scheduleId': 1,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/dimmingscheduler/getScheduleEvents", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": [
{
"end": {
"afterNoon": false,
"afterNoonOrEqual": false,
"beforeNoon": true,
"beforeNoonOrEqual": true,
"noon": false,
"offsetInSeconds": -300,
"sunEvent": "SUNRISE"
},
"events": [
{
"end": null,
"events": [],
"id": 2,
"level": 50,
"name": "",
"start": {
"afterNoon": false,
"afterNoonOrEqual": false,
"beforeNoon": true,
"beforeNoonOrEqual": true,
"hour": 0,
"milliseconds": 0,
"minutes": 0,
"noon": false,
"seconds": 0
},
"type": null
},
{
"end": null,
"events": [],
"id": 3,
"level": 100,
"name": "",
"start": {
"afterNoon": false,
"afterNoonOrEqual": false,
"beforeNoon": true,
"beforeNoonOrEqual": true,
"hour": 4,
"milliseconds": 0,
"minutes": 0,
"noon": false,
"seconds": 0
},
"type": null
}
],
"id": 1,
"level": 100,
"name": "",
"start": {
"afterNoon": true,
"afterNoonOrEqual": true,
"beforeNoon": false,
"beforeNoonOrEqual": false,
"noon": false,
"offsetInSeconds": 300,
"sunEvent": "SUNSET"
},
"type": null
}
]
}
To retrieve the list of all events in a schedule, use the method getScheduleEvents available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| scheduleId (required) | Schedule ID (int) |
| Available with the following applications |
|---|
| Scheduling Manager |
10.04 Delete schedule events
Deleting schedule event ID 28 from schedule ID 9
import requests
payload = {
'scheduleId': 9,
'scheduleEventId': 28,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/removeScheduleEvent", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": null
}
To delete an event from a schedule, use the method removeScheduleEvent available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| scheduleId (required) | Schedule ID (int) |
| scheduleEventId (required) | Schedule event ID (int) |
| Available with the following applications |
|---|
| Scheduling Manager |
11. Schedulers
The scheduler
A scheduler is a list of rules indicating when devices should follow certain schedules. They are not to be confused with schedules! In the SLV user interface, they are also called dimming groups or calendars.
| Attributes | |
|---|---|
| id | Scheduler ID (int) |
| name | Scheduler name |
| description | Textual description of the scheduler |
| geozonePath | Geozone path attached to the scheduler |
| readOnly | Indicates whether the current user is allowed to edit the scheduler (boolean) |
| type | Always scheduler |
| start | Unused |
| end | Unused |
11.01 Create a scheduler
Creating a new scheduler called "Simple calendar"
import requests
payload = {
'name': 'Simple calendar',
'category': 'STREETLIGHT_DIMMING',
'description': 'My new calendar',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/createScheduler", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": 6
}
To create a new scheduler, use the method createScheduler available at /api/dimmingscheduler. It returns the identifier of the new scheduler.
| Arguments | |
|---|---|
| name (required) | Scheduler name |
| category | Only STREETLIGHT_DIMMING is supported |
| description | Textual description of the scheduler |
| Available with the following applications |
|---|
| Scheduling Manager |
11.02 Retrieve all schedulers
Retrieving all schedules in the category 'STREETLIGHT_DIMMING'
import requests
payload = {
'category': 'STREETLIGHT_DIMMING',
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/dimmingscheduler/getSchedulers", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": [
{
"description": "My new calendar",
"end": null,
"geoZonePath": "GeoZones",
"id": 6,
"name": "Simple calendar",
"readOnly": false,
"start": null,
"type": "scheduler"
}
]
}
To retrieve all schedules, use the method getSchedulers available at /api/dimmingscheduler
| Arguments | |
|---|---|
| category | Only STREETLIGHT_DIMMING is supported |
| Available with the following applications |
|---|
| Scheduling Manager |
11.03 Update a scheduler
Updating scheduler ID 6
import requests
payload = {
'schedulerId': 6,
'name': 'Simple calendar',
'description': 'Updated calendar',
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/updateScheduler", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": null
}
To update an existing scheduler, use the method updateScheduler available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| name | Scheduler name |
| description | Textual description of the scheduler |
| Available with the following applications |
|---|
| Scheduling Manager |
11.04 Add a schedule to a scheduler on a daily basis
Adding schedule ID 120 to the calendar ID 1234 on January 1st, 2019.
import requests
payload = {
'schedulerId': 1268,
'scheduleId': 120,
'start': '01/01/2019',
'end': '01/01/2019',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/dimmingscheduler/addEveryDaySchedulerItemAt", data=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": {
"scheduleId": 120,
"recurrence": {
"id": 771,
"step": 1
},
"start": {
"day": 1,
"month": 1,
"year": 2019
},
"end": {
"day": 1,
"month": 1,
"year": 2019
},
"id": 771
},
"message": null,
"statusOk": true,
"statusError": false
}
To add a schedule to an existing scheduler on a daily basis, use the method addEveryDaySchedulerItemAt available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| scheduleId (required) | Schedule ID (int) |
| start (required) | Beginning of the period during which the specified schedule should be active, in the format DD/MM/YYYY |
| end (required) | End of the period during which the specified schedule should be active, in the format DD/MM/YYYY |
| Available with the following applications |
|---|
| Scheduling Manager |
11.05 Add a schedule to a scheduler on a weekly basis
Adding schedule ID 120 to the calendar ID 1234 every Monday.
import requests
payload = {
'schedulerId': 1234,
'scheduleId': 120,
'onMonday': 'true',
'onTuesday': 'false',
'onWednesday': 'false',
'onThursday': 'false',
'onFriday': 'false',
'onSaturday': 'false',
'onSunday': 'false',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/dimmingscheduler/addEveryWeekSchedulerItemAt", data=payload, headers=token_header)
Adding schedule ID 30 to the calendar ID 1234 to every third Wednesday on the month.
import requests
payload = {
'schedulerId': 1268,
'scheduleId': 30,
'onMonday': 'false',
'onTuesday': 'false',
'onWednesday': 'true',
'onThursday': 'false',
'onFriday': 'false',
'onSaturday': 'false',
'onSunday': 'false',
'rankInMonth': 3,
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/dimmingscheduler/addEveryWeekSchedulerItemAt", data=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": {
"scheduleId": 120,
"recurrence": {
"id": 514,
"step": 1,
"onMonday": true,
"onTuesday": false,
"onWednesday": false,
"onThursday": false,
"onFriday": false,
"onSaturday": false,
"onSunday": false,
"rankInMonth": null,
"lastRankInMonth": false
},
"start": null,
"end": null,
"id": 514
},
"message": null,
"statusOk": true,
"statusError": false
}
To add a schedule to an existing scheduler on a weekly basis, use the method addEveryWeekSchedulerItemAt available at /api/dimmingscheduler.
A schedule can be added on a specified day every week; in that case, do not set lastRankInMonth and rankInMonth.
It can also be added on the specified day on the N-th week every month. To do so, set rankInMonth to N.
Finally, to apply a schedule on the specified day on the last week every month, set lastRankInMonth to true.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| scheduleId (required) | Schedule ID (int) |
| onMonday (required) | Set to true if the specified schedule applies to Mondays |
| onTuesday (required) | Set to true if the specified schedule applies to Tuesdays |
| onWednesday (required) | Set to true if the specified schedule applies to Wednesdays |
| onThursday (required) | Set to true if the specified schedule applies to Thursdays |
| onFriday (required) | Set to true if the specified schedule applies to Fridays |
| onSaturday (required) | Set to true if the specified schedule applies to Saturdays |
| onSunday (required) | Set to true if the specified schedule applies to Sundays |
| lastRankInMonth | When set to true, the specified schedule only applies to the last week of each month. Defaults to false |
| rankInMonth | When set, specifies which week of each month the schedule applies to (int) |
| Available with the following applications |
|---|
| Scheduling Manager |
11.06 Add a schedule to a scheduler on a monthly basis
Adding schedule ID 120 to calendar ID 1234 from the 5th to the 8th every month
import requests
payload = {
'schedulerId': 1234,
'scheduleId': 120,
'fromDayInMonth': 5,
'toDayInMonth': 8,
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/dimmingscheduler/addEveryMonthSchedulerItemAt", data=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": {
"scheduleId": 120,
"recurrence": {
"id": 722,
"step": null,
"fromDayOfMonth": 5,
"toDayOfMonth": 8,
"lastDayOfMonth": null
},
"start": null,
"end": null,
"id": 722
},
"message": null,
"statusOk": true,
"statusError": false
}
To add a schedule to an existing scheduler on a monthly basis, use the method addEveryMonthSchedulerItemAt available at /api/dimmingscheduler.
You may add a schedule to a single day of the month by specifying the same value for fromDayInMonth and toDayInMonth.
You may also add a schedule that only applies to the last day of each month by setting lastDayInMonth to true.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| scheduleId (required) | Schedule ID (int) |
| fromDayInMonth | Beginning of the monthly period during which the specified schedule should be active (1-31) |
| toDayInMonth | End of the monthly period during which the specified schedule should be active. Must be greater or equal to fromDayInMonth |
| lastDayInMonth | When set to true, the specified schedule only applies to the last day of each month. Defaults to false |
| Available with the following applications |
|---|
| Scheduling Manager |
11.07 Add a schedule to a scheduler on a yearly basis
Adding schedule ID 120 to calendar ID 1234 from February 14th to February 20th every year
import requests
payload = {
'schedulerId': 1234,
'scheduleId': 120,
'fromMonth': 2,
'fromDayInMonth': 14,
'toMonth': 2,
'toDayInMonth': 20,
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/dimmingscheduler/addEveryYearSchedulerItemAt", data=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": {
"scheduleId": 120,
"recurrence": {
"id": 757,
"step": null,
"fromMonth": 2,
"toMonth": 2,
"fromDayInMonth": 14,
"toDayInMonth": 20,
"lastDayInMonth": null
},
"start": null,
"end": null,
"id": 757
},
"message": null,
"statusOk": true,
"statusError": false
}
To add a schedule to an existing scheduler on a yearly basis, use the method addEveryYearSchedulerItemAt available at /api/dimmingscheduler.
You may add a schedule to a single day of the year by specifying the same value for the pairs <fromMonth, fromDayInMonth> and <toMonth, toDayInMonth>.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| scheduleId (required) | Schedule ID (int) |
| fromMonth | Month of the beginning of the yearly period during which the specified schedule should be active (1-12) |
| fromDayInMonth | Day of the beginning of the yearly period during which the specified schedule should be active (1-31) |
| toMonth | Month of the end of the yearly period during which the specified schedule should be active (1-12) |
| toDayInMonth | Day of the end of the yearly period during which the specified schedule should be active (1-31) |
| Available with the following applications |
|---|
| Scheduling Manager |
11.08 Remove all items from a scheduler
Removing all items from scheduler ID 42
import requests
payload = {
'schedulerId': 42,
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/dimmingscheduler/removeAllSchedulerItems", data=payload, headers=token_header)
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": null
}
To clear a scheduler, use the method removeAllSchedulerItems available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| Available with the following applications |
|---|
| Scheduling Manager |
11.09 Delete a scheduler
Deleting scheduler ID 6
import requests
payload = {
'schedulerId': 6,
'ser': 'json'
}
r = requests.post(SLV_CMS + "/api/dimmingscheduler/deleteScheduler", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": null
}
To delete a scheduler, use the method deleteScheduler available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| Available with the following applications |
|---|
| Scheduling Manager |
11.10 Retrieve the number of devices using each scheduler
Retrieving the number of devices using each scheduler
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/dimmingscheduler/getDimmingSchedulersUsage", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": [
{
"properties": {
"count": "1"
},
"value": 3
},
{
"properties": {
"count": "0"
},
"value": 5
},
{
"properties": {
"count": "2"
},
"value": 1
},
{
"properties": {
"count": "0"
},
"value": 2
},
{
"properties": {
"count": "10829"
},
"value": 4
}
]
}
To obtain the number of devices associated with each scheduler, you may use the method getDimmingSchedulersUsage available at /api/dimmingscheduler. This method takes no parameter and provides those numbers for all schedulers visible to the current user.
In the server response, value contains the scheduler ID while properties.count provides the corresponding number of devices.
| Available with the following applications |
|---|
| Scheduling Manager |
11.11 Retrieve controllers using a scheduler
Retrieve controllers using the scheduler ID 4
import requests
payload = {
'schedulerId': 4,
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/dimmingscheduler/getDimmingSchedulerUsage", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode" : "0",
"errorCodeLabel" : null,
"message" : null,
"status" : "OK",
"statusError" : false,
"statusOk" : true,
"value" :
{
"properties" :
{
"controllerNames" : "Controller 1, Controller 2",
"count" : "10829",
"controllerStrIds" : "controller1,controller2"
},
"value" : 4
}
}
To retrieve the list of all controllers using a specific scheduler, use the method getDimmingSchedulerUsage available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
The list of controllers is provided in the server response in properties.controllerStrIds and properties.controllerNames. controllerStrIds lists the controllers by their IDs while controllerNames lists them by their display name, all separated by commas. Both variables list controllers in the same order.
value repeats the schedulerId and properties.count contains the total number of devices using the specified scheduler.
| Available with the following applications |
|---|
| Scheduling Manager |
11.12 Retrieve all schedulers used by devices
Retrieving all schedulers used by devices
import requests
payload = {
'ser': 'json'
}
r = requests.get(SLV_URL + "/api/dimmingscheduler/getUsedDimmingSchedulerNames", params=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": [
{
"description": "My new calendar",
"end": null,
"geoZonePath": "GeoZones",
"id": 6,
"name": "Simple calendar",
"readOnly": false,
"start": null,
"type": "scheduler"
}
]
}
To retrieve all schedulers used by at least one device, use the method getUsedDimmingSchedulerNames available at /api/dimmingscheduler. This method takes no argument.
| Available with the following applications |
|---|
| Advanced Search |
| Batch Control |
| Control Center |
| Data History |
| Desktop |
| Device History |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Inventory Verification |
| Real-time Control |
| Scheduling Manager |
11.13 Commission a scheduler
Commissioning scheduler ID 4 on two controllers
controller1andcontroller2
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('schedulerId', 4),
('controllerStrId', 'controller1'),
('controllerStrId', 'controller2'),
('ser', 'json')
])
r = requests.post(SLV_URL + "/api/dimmingscheduler/commissionControllersSchedulers", data=payload, auth=('USERNAME', 'PASSWORD'))
Sample response
{
"batchId": "1490953624522",
"batchProgressMessage": null,
"batchProgressValue": 0,
"batchRunning": true,
"cancelRequested": false,
"cancelled": false,
"errorCode": "0",
"errorCodeLabel": null,
"message": null,
"status": "OK",
"statusError": false,
"statusOk": true,
"value": {
"errorMessagesCount": 0,
"infoMessagesCount": 0,
"login": null,
"status": 0,
"stepResults": [
{
"errorMessages": [],
"errorMessagesCount": 0,
"infoMessages": [],
"infoMessagesCount": 0,
"label": "Task for commissioning schedulers on controller 'controller1'",
"messages": [],
"status": 0,
"stepLabel": "Task for commissioning schedulers on controller 'controller1'",
"stepName": "controller1",
"warningMessages": [],
"warningMessagesCount": 0
},
{
"errorMessages": [],
"errorMessagesCount": 0,
"infoMessages": [],
"infoMessagesCount": 0,
"label": "Task for commissioning schedulers on controller 'controller2'",
"messages": [],
"status": 0,
"stepLabel": "Task for commissioning schedulers on controller 'controller2'",
"stepName": "controller2",
"warningMessages": [],
"warningMessagesCount": 0
}
],
"warningMessagesCount": 0
}
}
To commission a scheduler on a controller, i.e. to ask the server to send the relevant scheduling information to the controller onsite, you may call the method commissionControllersSchedulers available at /api/dimmingscheduler.
| Arguments | |
|---|---|
| schedulerId (required) | Scheduler ID (int) |
| controllerStrId (required) | Controller ID (string) |
It is possible to commission multiple controllers at once by specifying multiple controllerStrId.
This method returns a batch object.
| Available with the following applications |
|---|
| Scheduling Manager |
12. Real-time control
12.01 Retrieve the dimming level of a device
Retrieve the dimming level of
mydeviceassociated with the controllermycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/getDimmingLevel", params=payload, headers=token_header)
Sample response
100.0
To retrieve the dimming level of a device, use the method getDimmingLevel available at /api/dimming. It returns a float between 0 and 100 corresponding to the current dimming level reported by the device.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| maxAge | Maximum age of the value to be returned (float). Support may vary depending on the control technology. Set it to zero to retrieve the dimming level from the device (as opposed to from the SLV database). Defaults to zero. |
| Available with the following applications |
|---|
| Desktop |
| Real-time Control |
12.02 Update the dimming level of a device
Change the dimming level of
mydeviceassociated with the controllermycontrollerto 42%
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'dimmingLevel': '42',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/setDimmingLevel", params=payload, headers=token_header)
Sample response
"OK"
To update the dimming level of a device, use the method setDimmingLevel available at /api/dimming. It returns a string indicating whether the command has been successfully sent to the device.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| dimmingLevel (required) | Target dimming level (integer from 0 to 100) |
| Available with the following applications |
|---|
| Installation |
| Real-time Control |
12.03 Retrieve the dimming mode of a device
Retrieve the dimming mode of
mydeviceassociated with the controllermycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/getDimmingMode", params=payload, headers=token_header)
Sample response
["AUTOMATIC"]
To retrieve the dimming mode of a device, use the method getDimmingMode available at /api/dimming. It returns either AUTOMATIC or MANUAL.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| maxAge | Maximum age of the value to be returned (float). Support may vary depending on the control technology. Set it to zero to retrieve the dimming level from the device (as opposed to from the SLV database). Defaults to zero. |
| Available with the following applications |
|---|
| Desktop |
| Real-time Control |
12.04 Move a device back to automatic mode
Move
mydeviceassociated with the controllermycontrollerback to automatic mode
import requests
payload = MultiDict([
('controllerStrId','mycontroller'),
('idOnController','mydevice'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/dimming/exitManualModes", data=payload, headers=token_header)
Sample response
{
"status": null,
"errorCode": "0",
"errorCodeLabel": null,
"value": [
"OK"
],
"message": null,
"statusError": false,
"statusOk": false
}
To move a device back to automatoc mode, use the method exitManualModes available at /api/dimming. You may specify multiple pairs of controllerStrId and idOnController to move several devices back to automatic mode at once.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Batch Control |
| Desktop |
| Installation |
| Real-time Control |
12.05 Retrieve device metering attributes
Retrieve all metering attributes for the device
mydeviceassociated with the controllermycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/getDeviceMeteringValueDescriptors", params=payload, headers=token_header)
Sample response
[
{
"category": "standard",
"criticity": 0,
"dataFormat": null,
"failure": false,
"help": null,
"label": "Lamp level feedback",
"labelKey": "db.meaning.lamplevel.label",
"name": "LampLevel",
"type": "float",
"unit": "%",
"unitKey": "percent",
"unitLabel": "Percent",
"unitShorthand": "%"
},
...
To retrieve the device metering attributes available for a device, use the method getDeviceMeteringValueDescriptors available at /api/dimming. You can then retrieve their value in real-time using the method getDeviceFormattedMeteringValues.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Batch Control |
| Desktop |
| Installation |
| Real-time Control |
12.06 Retrieve values of device metering attributes
Retrieve the real-time value of
CurrentandMainVoltagefor the devicemydeviceassociated with the controllermycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController', 'mydevice'),
('meteringValueName', 'Current'),
('meteringValueName', 'MainVoltage'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/dimming/getDeviceFormattedMeteringValues", data=payload, headers=token_header)
Sample response
["0.436A","248.8V"]
To retrieve the value of metering attributes on a device, use the method getDeviceFormattedMeteringValues available at /api/dimming. You may retrieve the value of multiple attributes at once by specifying multiple meteringValueName.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| meteringValueName (required) | Name of the attribute to retrieve |
| maxAge | Maximum age of the value to be returned (float). Support may vary depending on the control technology. Set it to zero to retrieve values from the device (as opposed to from the SLV database). Defaults to zero. |
| Available with the following applications |
|---|
| Batch Control |
| Desktop |
| Failure Tracking |
| Installation |
| Real-time Control |
12.07 Retrieve device failure attributes
Retrieve all failure attributes for the device
mydeviceassociated with the controllermycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/getDeviceFailureDescriptors", params=payload, headers=token_header)
Sample response
[
{
"category": "standard",
"criticity": 1,
"dataFormat": null,
"failure": true,
"help": null,
"label": "Lamp failure",
"labelKey": "db.failuremeaning.lampfailure.label",
"name": "LampFailure",
"type": "boolean",
"unit": null
},
...
To retrieve the device failure attributes available for a device, use the method getDeviceFailureDescriptors available at /api/dimming. You can then retrieve their value in real-time using the method getDeviceFailureOnValues.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Desktop |
| Real-time Control |
12.08 Retrieve values of device failure attributes
Retrieve the real-time value of Lamp failure and Low lamp voltage for the device
mydeviceassociated with the controllermycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController', 'mydevice'),
('failureName', 'LampFailure'),
('failureName', 'LowLampVoltage'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/dimming/getDeviceFailureOnValues", data=payload, headers=token_header)
Sample response
[false,false]
To retrieve the value of failure attributes on a device, use the method getDeviceFailureOnValues available at /api/dimming. You may retrieve the value of multiple attributes at once by specifying multiple failureName.
It returns an array of boolean values.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| failureName (required) | Name of the attribute to retrieve |
| maxAge | Maximum age of the value to be returned (float). Support may vary depending on the control technology. Set it to zero to retrieve values from the device (as opposed to from the SLV database). Defaults to zero. |
| Available with the following applications |
|---|
| Batch Control |
| Desktop |
| Failure Tracking |
| Real-time Control |
12.09 Retrieve values of metering attributes for multiple devices
Retrieve the real-time value of
CurrentandMainVoltagefor the devicesmydevice1andmydevice2both associated with the controllermycontroller
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController', 'mydevice1'),
('controllerStrId', 'mycontroller'),
('idOnController', 'mydevice2'),
('valueName', 'Current'),
('valueName', 'MainVoltage'),
('maxAge', '0'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/monitoring/getDevicesValues", data=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": [
[
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": 0.829,
"message": null,
"statusError": false,
"statusOk": true
},
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": 233.0,
"message": null,
"statusError": false,
"statusOk": true
}
],
[
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": 0.385,
"message": null,
"statusError": false,
"statusOk": true
},
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": 123.0,
"message": null,
"statusError": false,
"statusOk": true
}
]
],
"message": null,
"statusError": false,
"statusOk": true
}
To retrieve the value of metering attributes for multiple devices at once, use the method getDevicesValues available at /api/monitoring. You may retrieve the value of multiple attributes at once by specifying multiple valueNames.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| valueName (required) | Name of the attribute to retrieve |
| maxAge | Maximum age of the value to be returned (float). Support may vary depending on the control technology. Set it to zero to retrieve values from the device (as opposed to from the SLV database). If not specified, values will be fetched from the database |
| Available with the following applications |
|---|
| Batch Control |
12.10 Update the dimming level of multiple devices
Change the dimming level of the devices
mydevice1andmydevice2both associated with the controllermycontrollerto 42%
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('controllerStrId', 'mycontroller'),
('idOnController', 'mydevice1'),
('controllerStrId', 'mycontroller'),
('idOnController', 'mydevice2'),
('dimmingLevel', '42'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/dimming/setDimmingLevels", data=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": [
"OK",
"OK"
],
"message": null,
"statusOk": true,
"statusError": false
}
To update the dimming level of multiple devices at once, use the method setDimmingLevels available at /api/dimming. You may retrieve the value of multiple attributes at once by specifying pairs of controllerStrId and idOnController. However, only one dimmingLevel is accepted in the request.
In the response, value contains as many items as devices and provides feedback for each specified device, in the same order as specified in the request.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| dimmingLevel (required) | Target dimming level (integer from 0 to 100) |
| Available with the following applications |
|---|
| Batch Control |
| Real-time Control |
12.11 Turn on the relay for cabinet controller
Turn on the relay for a device
mydeviceof category cabinet controller associated with the controllermycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/switchONExt", params=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": true,
"message": null,
"statusOk": true,
"statusError": false
}
To turn on the relay of a cabinet controller device, use the method switchONExt available at /api/dimming. It returns a boolean indicating whether the command has been successfully sent to the device.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Batch Control |
| Real-time Control |
12.12 Turn off the relay for cabinet controller
Turn off the relay for a device
mydeviceof category cabinet controller associated with the controllermycontroller
import requests
payload = {
'controllerStrId': 'mycontroller',
'idOnController': 'mydevice',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/dimming/switchOFFExt", params=payload, headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": true,
"message": null,
"statusOk": true,
"statusError": false
}
To turn off the relay of a cabinet controller device, use the method switchOFFExt available at /api/dimming. It returns a boolean indicating whether the command has been successfully sent to the device.
| Arguments | |
|---|---|
| controllerStrId (required) | Controller to which the device is attached |
| idOnController (required) | Device identifier on the controller |
| Available with the following applications |
|---|
| Batch Control |
| Real-time Control |
13. Scheduled reports
The report object
A report object corresponds to a report definition as visible in the Report Manager application in the SLV UI. It controls the computation on fixed schedules of reports that can be sent by email or FTP. Reports are always defined for a particular GeoZone.
| Attributes | Description |
|---|---|
| id | Report ID (string) |
| name | Report name |
| scheduledReportTemplateImplClassName | Report type (see section Report types below) |
| geoZoneId | Identifier of the GeoZone attached to the report |
| propertyValues | Report properties |
| lastScheduledTime | Time of the last scheduled run |
| nextScheduledTime | Time of the next scheduled run |
| schedulerInfo | Textual description of the report schedule |
| timeZone | Time zone in which lastScheduledTime and nextScheduledTime are expressed |
Report types
Below is the list of default report types available in SLV:
| Name in the SLV UI | scheduledReportTemplateImplClassName |
|---|---|
| Advanced Search Report | com.slv.reporting.scheduledreports.impl.search.AdvancedSearchReportTemplate |
| Citigis report | com.slv.reporting.scheduledreports.impl.citigis.CitigisScheduledReportTemplate |
| Day Burner Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.DayBurner |
| Failures HTML report | com.slv.reporting.scheduledreports.impl.failures.FailuresApplicationReportTemplate |
| Failures processing time | com.slv.reporting.scheduledreports.impl.failures.FailureProcessingTimeReportTemplate |
| Failures report | com.slv.reporting.scheduledreports.impl.failures.DailyFailuresReportTemplate |
| Generic device last values | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesReportTemplate |
| Generic device values | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableValuesReportTemplate |
| Generic device values [Run Once] | com.slv.reporting.scheduledreports.impl.devicevariablevalues.SingleScheduledDateGroupDevicesVariableValuesReportTemplate |
| Latency Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.CommandFeedbackLatencyReportTemplate |
| Lifetime report | com.slv.reporting.scheduledreports.impl.lifetime.ForecastApplicationReportTemplate |
| Location change report | com.slv.reporting.scheduledreports.impl.asset.MapDeviceLocationChangeReportTemplate |
| Low Power Factor Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.PowerFactorTooLow |
| LPC availability | com.slv.reporting.scheduledreports.impl.operations.NetworkOperationsReportTemplate |
| No data ever received | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.DataNeverReceived |
| No power for more than 24 hours | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.NoPowerForMoreThan24Hours |
| OnOff segment report | com.slv.reporting.scheduledreports.impl.onoffsegment.OnOffSegmentReportTemplate |
| Over 140V Voltage Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.OverVoltage140V |
| Over Voltage Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.OverVoltage |
| Over Wattage Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.OverWattage |
| Real-time operations service level | com.slv.reporting.scheduledreports.impl.operations.DeviceOnDemandOperationsServiceLevelReportTemplate |
| Symology report | com.slv.reporting.scheduledreports.impl.symology.SymologyScheduledReportTemplate |
| UMSUG report | com.slv.reporting.scheduledreports.impl.umso.UmsoScheduledReportTemplate |
| Unbalanced 3-Phase Cabinets Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.UnbalancedCabinet |
| Under 110V Voltage Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.UnderVoltage110V |
| Under Voltage Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.UnderVoltage |
| Under Wattage Report | com.slv.reporting.scheduledreports.impl.devicevariablevalues.GroupDevicesVariableLastValuesConfigurableReportTemplate.UnderWattage |
| Weekly Energy Report | com.slv.reporting.scheduledreports.impl.energy.WeeklyEnergyReportTemplate |
This list can also be fetched dynamically by calling the method getRegisteredScheduledReportTemplateImplementations available at /api/reportingmanagement.
Report scheduling
Starting from SLV 7.12, most reports can be scheduled on a daily, weekly or monthly basis. Schedules are controlled by properties, and should be updated using the attributes propertyNameand propertyValue. See the section 13.02 Update a report for more information.
To run a report daily, simply set its property repeat to daily.
To run a report weekly, set repeat to weekly and use onForWeekly to choose the day of the week (in English and lowercase, e.g. monday).
To run a report monthly, set repeat to monthly. If you would like a report to run on a given day of the month, set onForMonthly to dayOfTheMonth and day to the desired number (from 1 to 31). day also accepts the special value last that allows to run a report on the last day of every month. If you would like to run a report monthly but on a particular day of a chosen week (e.g. Tuesday of the second week), set onForMonthly to first, second, third, fourth or last, and dayOfTheWeek to the desired day (in English and lowercase, e.g. monday).
In all cases, the property time controls the time at which reports are computed and should be set in 24-hour format, e.g. 14:00 for 2pm.
13.01 Create a report
Create a new Failures HTML report called
My new reporton the top level GeoZone (geozone ID1)
import requests
payload = {
'name': 'My new report',
'geoZoneId': '1',
'scheduledReportTemplateImplClassName': 'com.slv.reporting.scheduledreports.impl.failures.FailuresApplicationReportTemplate',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/reportingmanagement/createScheduledReportTemplateDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"id": "FailuresApplicationReportTemplate-1585571007024",
"name": "My new report",
"scheduledReportTemplateImplClassName": "com.slv.reporting.scheduledreports.impl.failures.FailuresApplicationReportTemplate",
"geoZoneId": 1,
"propertyValues": {
"onForWeekly": "monday",
"repeat": "weekly",
"time": "13:00",
"detail": 0,
"htmlFormat": false
},
"lastScheduledTime": null,
"nextScheduledTime": null,
"schedulerInfo": "Weekly on Monday at 13:00 [Greenwich Mean Time]",
"timeZone": "GMT"
}
To create a report, use the method createScheduledReportTemplateDefinition available at /api/reportingmanagement. It returns a report object.
| Arguments | |
|---|---|
| name (required) | Report name |
| geoZoneId (required) | GeoZone identifier |
| scheduledReportTemplateImplClassName (required) | Report type |
| Available with the following applications |
|---|
| Report Manager |
13.02 Update a report
Update the report
FailuresApplicationReportTemplate-1585571007024to set its time to 8 a.m. on Tuesdays
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('id', 'FailuresApplicationReportTemplate-1585571007024'),
('propertyName', 'time'),
('propertyValue', '08:00'),
('propertyName', 'onForWeekly'),
('propertyValue', 'tuesday'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/reportingmanagement/updateScheduledReportTemplateDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"id": "FailuresApplicationReportTemplate-1585571007024",
"name": "My new report",
"scheduledReportTemplateImplClassName": "com.slv.reporting.scheduledreports.impl.failures.FailuresApplicationReportTemplate",
"geoZoneId": 1,
"propertyValues": {
"onForWeekly": "tuesday",
"time": "08:00",
...
},
"lastScheduledTime": "3/30/20 1:00:00 PM UTC",
"nextScheduledTime": "3/31/20 8:00:00 AM CEST",
"schedulerInfo": "Weekly on Tuesday at 08:00 [Central European Time]",
"timeZone": "Europe/Paris"
}
To update a report, use the method updateScheduledReportTemplateDefinition available at /api/reportingmanagement. It returns the specified report object with its updated parameters. This method takes an arbitrary number of key/value pairs, each pair corresponding to one parameter to update.
| Arguments | |
|---|---|
| id (required) | Report identifier |
| name | Report name |
| propertyName (required) | Parameter name |
| propertyValue (required) | New parameter value |
| Available with the following applications |
|---|
| Report Manager |
13.03 Delete a report
Delete the report
FailuresApplicationReportTemplate-1585571007024
import requests
payload = {
'id': 'FailuresApplicationReportTemplate-1585571007024',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/reportingmanagement/deleteScheduledReportDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": null,
"message": null,
"statusOk": true,
"statusError": false
}
To delete a report, use the method deleteScheduledReportDefinition available at /api/reportingmanagement.
| Arguments | |
|---|---|
| id (required) | Report identifier |
| Available with the following applications |
|---|
| Report Manager |
13.04 Retrieve all report parameters available
Report parameters that can be specified in updateScheduledReportTemplateDefinition vary by report type. The method getScheduledReportTemplateEditablePropertyDescriptors available at /api/reportingmanagement allows clients to retrieve all report parameters available for a given report.
The reponse is a long list of objects. Each object has at least a name which should be used as the parameter propertyName in updateScheduledReportTemplateDefinition. For report parameters that only accept specific values, the corresponding object in the response will contain another object enumValues which lists all acceptable values.
| Arguments | |
|---|---|
| id (required) | Report identifier |
Retrieve all report parameters available for the report
FailuresApplicationReportTemplate-1585571007024
import requests
payload = {
'id': 'FailuresApplicationReportTemplate-1585571007024',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/reportingmanagement/getScheduledReportTemplateEditablePropertyDescriptors", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"dataFormat": {},
"enumValues": null,
"format": "",
"label": "description",
"labelKey": null,
"name": "description",
"type": "string"
},
...
]
If the specified report does not exist, this method returns an SLVResult object with a status of ERROR and the error code 613.
Sample response when the specified report does not exist
{
"status": "ERROR",
"errorCode": "613",
"errorCodeLabel": "Item not found",
"value": "streetlight.util.ItemNotFoundException: Item 'FailuresApplicationReportTemplate-158557063012' not found as 'interface com.slv.reporting.scheduledreports.ScheduledReport'!",
"message": "Item 'FailuresApplicationReportTemplate-158557063012' not found as 'interface com.slv.reporting.scheduledreports.ScheduledReport'!",
"statusOk": false,
"statusError": true
}
| Available with the following applications |
|---|
| Report Manager |
13.05 Retrieve a report
To retrieve a report, use the method getScheduledReportTemplateDefinition available at /api/reportingmanagement. It returns the corresponding report object.
| Arguments | |
|---|---|
| id (required) | Report identifier |
Retrieve the report
FailuresApplicationReportTemplate-1585571007024
import requests
payload = {
'id': 'FailuresApplicationReportTemplate-1585571007024',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/reportingmanagement/getScheduledReportTemplateDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"id": "FailuresApplicationReportTemplate-1585571007024",
"name": "My new report",
"scheduledReportTemplateImplClassName": "com.slv.reporting.scheduledreports.impl.failures.FailuresApplicationReportTemplate",
"geoZoneId": 1,
"propertyValues": {
...
},
"lastScheduledTime": "3/30/20 1:00:00 PM UTC",
"nextScheduledTime": "3/31/20 8:00:00 AM CEST",
"schedulerInfo": "Weekly on Tuesday at 08:00 [Central European Time]",
"timeZone": "Europe/Paris"
}
If the specified report does not exist, this method returns an SLVResult object with a status of ERROR and the error code 613.
Sample response when the specified report does not exist
{
"status": "ERROR",
"errorCode": "613",
"errorCodeLabel": "Item not found",
"value": "streetlight.util.ItemNotFoundException: Item 'FailuresApplicationReportTemplate-158557063012' not found as 'interface com.slv.reporting.scheduledreports.ScheduledReport'!",
"message": "Item 'FailuresApplicationReportTemplate-158557063012' not found as 'interface com.slv.reporting.scheduledreports.ScheduledReport'!",
"statusOk": false,
"statusError": true
}
| Available with the following applications |
|---|
| Report Manager |
13.06 Retrieve all reports
To retrieve all reports , use the method getAllScheduledReportTemplateDefinitions available at /api/reportingmanagement. It returns all report objects visible to the current user.
| Arguments | |
|---|---|
| propertyDescriptors | Set to true to obtain report properties. When it is set to false, only the common basic report attributes are provided in the response. Defaults to false |
| includeScheduledTimes | Set to true to obtain the last and next report execution times. Defaults to false |
Retrieve all reports without their properties or execution times
import requests
payload = {
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/reportingmanagement/getAllScheduledReportTemplateDefinitions", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"id": "AdvancedSearchReportTemplate-1585346157508",
"name": "Report 1",
"scheduledReportTemplateImplClassName": "com.slv.reporting.scheduledreports.impl.search.AdvancedSearchReportTemplate",
"geoZoneId": 197,
"propertyValues": null,
"lastScheduledTime": null,
"nextScheduledTime": null,
"schedulerInfo": "Daily at 15:00 [Pacific Standard Time]",
"timeZone": "America/Los_Angeles"
},
{
"id": "DeviceOnDemandOperationsServiceLevelReportTemplate-1585328418088",
"name": "Report 2",
"scheduledReportTemplateImplClassName": "com.slv.reporting.scheduledreports.impl.operations.DeviceOnDemandOperationsServiceLevelReportTemplate",
"geoZoneId": 197,
"propertyValues": null,
"lastScheduledTime": null,
"nextScheduledTime": null,
"schedulerInfo": "Daily at 15:00 [Pacific Standard Time]",
"timeZone": "America/Los_Angeles"
}
]
| Available with the following applications |
|---|
| Report Manager |
14. Alarms
The alarm object
An alarm object corresponds to an alarm definition as visible in the Alarm Manager application in the SLV UI. Alarms are always defined under a particular GeoZone.
| Attributes | Description |
|---|---|
| id | Alarm ID (string) |
| name | Report name |
| triggerConditionImplClassName | Alarm type (see section Alarm types below) |
| geoZoneId | Identifier of the GeoZone attached to the alarm |
| propertyValues | List of alarm properties |
| alarmStateChangeActionImplClassNames | Action to be performed when the alarm triggers |
Alarm types
Below is the list of alarm types available in SLV:
| Name in the SLV UI | triggerConditionImplClassName |
|---|---|
| Controller alarm: comparison between four I/Os | com.slv.alarming.trigger.SCMultipleIOStateAlarmTriggersGenerator |
| Controller alarm: comparison between three I/Os | com.slv.alarming.trigger.SCMultipleIOStateComparisonAlarmTriggersGenerator |
| Controller alarm: comparison between two I/Os | com.slv.alarming.trigger.SCIOStateComparisonAlarmTriggersGenerator |
| Controller alarm: last known state of an I/O | com.slv.alarming.trigger.ControllerInputStateCondition |
| Controller alarm: ON/OFF at dusk/dawn | com.slv.alarming.trigger.ControllerSunEventSwitchTriggerGenerator |
| Controller alarm: ON/OFF times vs previous day | com.slv.alarming.trigger.SCSwitchingOnAndOffAlarm |
| Controller alarm: no data received | com.slv.alarming.trigger.ControllerUpdateTimeAlarm |
| Controller alarm: state of the I/Os in the last hours | com.slv.alarming.trigger.ControllerInputCondition |
| Device alarm: critical failure or warning on a single device | com.slv.alarming.trigger.DeviceFailureCondition |
| Device alarm: data analysis vs previous day | com.slv.alarming.trigger.SmartMeteringDeviceAnalyticsAlarmTriggersGenerator |
| Device alarm: data analysis vs previous day (fixed time) | com.slv.alarming.trigger.SmartMeteringDeviceDayTimeAnalyticsAlarmTriggersGenerator |
| Device alarm: failure ratio in a group | com.slv.alarming.trigger.GroupFailureRatioCondition |
| Device alarm: multiple failures on multiple devices | com.slv.alarming.trigger.MultiAlarmMultiDeviceFailureCondition |
| Device alarm: No data received | com.slv.alarming.trigger.DevicesUpdateTimeRatioTriggersGenerator |
| Device alarm: single failure on multiple devices | com.slv.alarming.trigger.MonoAlarmMultiDeviceFailureCondition |
| Device alarm: too many failures in an area | com.slv.alarming.trigger.DevicesInAreaTriggersGenerator |
| Generic alarm: multiple triggered alarms | com.slv.alarming.trigger.MetaAlarmTriggersGenerator |
| Meter alarm: comparison to a trigger | com.slv.alarming.trigger.SmartMeteringValueAlarmTriggersGenerator |
| Meter alarm: data analysis vs previous day | com.slv.alarming.trigger.SmartMeteringAnalyticsAlarmTriggersGenerator |
| Meter alarm: data analysis vs previous day (at fixed time) | com.slv.alarming.trigger.SmartMeteringDayTimeAnalyticsAlarmTriggersGenerator |
This list can also be fetched dynamically by calling the method getRegisteredTriggerConditionImplementations available at /api/alarmmanagement.
Alarm actions
Below is the list of alarm actions available in SLV:
| Name in the SLV UI | alarmStateChangeActionImplClassNames |
|---|---|
| Notify by eMail | com.slv.alarming.action.SendEMailAction |
| Send HTTP request | com.slv.alarming.action.HttpRequestAction |
| Send report | com.slv.alarming.action.TriggerScheduledReportAction |
This list can also be fetched dynamically by calling the method getRegisteredAlarmStateChangeActionImplementations available at /api/alarmmanagement.
14.01 Create an alarm
To create an alarm, use the method createSingleActionAlarmDefinition available at /api/alarmmanagement. It returns an alarm object.
| Arguments | |
|---|---|
| name (required) | Report name |
| triggerConditionImplClassName (required) | Alarm type |
| alarmStateChangeActionImplClassName (required) | Alarm action |
| geoZoneId (required) | GeoZone identifier |
Create a new alarm of type
Device alarm: no data receivedcalledNew alarm 1on the top level GeoZone (geozone ID1) with the actionNotify by email
import requests
payload = {
'name': 'New alarm 1',
'geoZoneId': '1',
'triggerConditionImplClassName': 'com.slv.alarming.trigger.DevicesUpdateTimeRatioTriggersGenerator',
'alarmStateChangeActionImplClassName': 'com.slv.alarming.action.SendEMailAction',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/createSingleActionAlarmDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"alarmStateChangeActionImplClassNames": [
"com.slv.alarming.action.SendEMailAction"
],
"id": "DevicesUpdateTimeRatioTriggersGenerator",
"name": "New alarm 1",
"geoZoneId": 1,
"triggerConditionImplClassName": "com.slv.alarming.trigger.DevicesUpdateTimeRatioTriggersGenerator",
"propertyValues": {
"autoAcknowledge": false,
"triggerCondition.timeMode": 0,
"newAlarmWhenAcknowledged": true,
"refreshRate": 0,
"action[0].message": "${TC}",
"alarmName": "New alarm 1",
"disabled": false,
"alarmPriority": 0,
"triggerCondition.triggeredDevicesRatioLimitPercent": 0,
"triggerCondition.delayTriggeringValueInMinutes": 120,
"triggerCondition.meaningCategories": [
0
]
}
}
If the specified alarm name is already used or the specified alarm action or type do not exist, this method returns an SLVResult object with a status of ERROR and the error code 500.
| Available with the following applications |
|---|
| Alarm Manager |
14.02 Update an alarm
To update an alarm, use the method updateAlarmDefinition available at /api/alarmmanagement. It returns the specified alarm object with its updated parameters. This method takes an arbitrary number of key/value pairs, each pair corresponding to one parameter to update.
| Arguments | |
|---|---|
| id (required) | Alarm identifier |
| name | Alarm name |
| propertyName (required) | Parameter name |
| propertyValue (required) | New parameter value |
Update the alarm
DevicesUpdateTimeRatioTriggersGeneratorto set its refresh rate to 5 minutes and enable auto-acknowledgement
import requests
from webob.multidict import MultiDict
payload = MultiDict([
('id', 'DevicesUpdateTimeRatioTriggersGenerator'),
('propertyName', 'refreshRate'),
('propertyValue', '300000'),
('propertyName', 'autoAcknowledge'),
('propertyValue', 'true'),
('ser', 'json')
])
r = my_session.post(SLV_URL + "/api/alarmmanagement/updateAlarmDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"alarmStateChangeActionImplClassNames": [
"com.slv.alarming.action.SendEMailAction"
],
"id": "DevicesUpdateTimeRatioTriggersGenerator",
"name": "New alarm 1",
"geoZoneId": 1,
"triggerConditionImplClassName": "com.slv.alarming.trigger.DevicesUpdateTimeRatioTriggersGenerator",
"propertyValues": {
"autoAcknowledge": true,
"triggerCondition.timeMode": 0,
"newAlarmWhenAcknowledged": true,
"refreshRate": 300000,
"action[0].message": "${TC}",
"alarmName": "New alarm 1",
"disabled": false,
"alarmPriority": 0,
"triggerCondition.triggeredDevicesRatioLimitPercent": 0,
"triggerCondition.delayTriggeringValueInMinutes": 120,
"triggerCondition.meaningCategories": [
0
]
}
}
If the specified alarm does not exist, this method returns random HTML code.
| Available with the following applications |
|---|
| Alarm Manager |
14.03 Delete an alarm
To delete an alarm, use the method deleteAlarmDefinition available at /api/alarmmanagement.
| Arguments | |
|---|---|
| id (required) | Alarm identifier |
Delete the alarm
DevicesUpdateTimeRatioTriggersGenerator
import requests
payload = {
'id': 'DevicesUpdateTimeRatioTriggersGenerator',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/deleteAlarmDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": null,
"message": null,
"statusOk": true,
"statusError": false
}
| Available with the following applications |
|---|
| Alarm Manager |
14.04 Retrieve all alarm parameters available by alarm type and action
Alarm parameters that can be specified in updateAlarmDefinition vary by alarm type. The method getVirtualSingleActionAlarmDefinitionEditablePropertyDescritors available at /api/alarmmanagement allows clients to retrieve all alarm parameters available for a given combination of alarm type and action.
The reponse is a long list of objects. Each object has at least a name which should be used as the parameter propertyName in updateAlarmDefinition. For alarm parameters that only accept specific values, the corresponding object in the response will contain another object enumValues which lists all acceptable values.
| Arguments | |
|---|---|
| triggerConditionImplClassName (required) | Alarm type |
| alarmStateChangeActionImplClassName (required) | Alarm action |
| geoZoneId | GeoZone identifier |
Retrieve all alarm parameters available for the alarm type Controller alarm: no data received and the action Notify by eMail
import requests
payload = {
'triggerConditionImplClassName': 'com.slv.alarming.trigger.ControllerUpdateTimeAlarm',
'alarmStateChangeActionImplClassName': 'com.slv.alarming.action.SendEMailAction',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/getVirtualSingleActionAlarmDefinitionEditablePropertyDescritors", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"dataFormat": {
"mainGroup": "common",
"mainGroup.labelKey": "dataformat.alarmbundle.group.common.label",
"min": "0",
"max": "9",
"mainGroup.label": "General"
},
"enumValues": null,
"format": "min=0&max=9",
"label": "Priority",
"labelKey": "alarmbundle.property.alarmPriority.label",
"name": "alarmPriority",
"type": "integer"
},
...
]
If the specified alarm type or action does not exist, this method returns an SLVResult object with a status of ERROR and the error code 500.
Sample response when the specified alarm action does not exist
[
{
"status": "ERROR",
"errorCode": "500",
"errorCodeLabel": "Internal error",
"value": "java.lang.ClassNotFoundException: com.slv.alarming.action.SendEMailAction_nonexistent",
"message": "com.slv.alarming.action.SendEMailAction_nonexistent",
"statusOk": false,
"statusError": true
}
]
| Available with the following applications |
|---|
| Alarm Manager |
14.05 Retrieve all alarm parameters available for an existing alarm
Alarm parameters that can be specified in updateAlarmDefinition vary by alarm type. The method getAlarmDefinitionEditablePropertyDescriptors available at /api/alarmmanagement allows clients to retrieve all alarm parameters available for a given alarm
The reponse is a long list of objects. Each object has at least a name which should be used as the parameter propertyName in updateAlarmDefinition. For alarm parameters that only accept specific values, the corresponding object in the response will contain another object enumValues which lists all acceptable values.
| Arguments | |
|---|---|
| id (required) | Alarm identifier |
Retrieve all alarm parameters available for the alarm ID DevicesUpdateTimeRatioTriggersGenerator
import requests
payload = {
'id': 'DevicesUpdateTimeRatioTriggersGenerator',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/getAlarmDefinitionEditablePropertyDescriptors", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"dataFormat": {
"mainGroup": "common",
"mainGroup.labelKey": "dataformat.alarmbundle.group.common.label",
"min": "0",
"max": "9",
"mainGroup.label": "General"
},
"enumValues": null,
"format": "min=0&max=9",
"label": "Priority",
"labelKey": "alarmbundle.property.alarmPriority.label",
"name": "alarmPriority",
"type": "integer"
},
...
]
If the specified alarm does not exist, this method returns an SLVResult object with a status of ERROR and the error code 613.
Sample response when the specified alarm does not exist
{
"status": "ERROR",
"errorCode": "613",
"errorCodeLabel": "Item not found",
"value": "streetlight.util.ItemNotFoundException: Item 'InexistentAlarm' not found as 'class com.slv.alarming.AlarmBundle'!",
"message": "Item 'InexistentAlarm'' not found as 'class com.slv.alarming.AlarmBundle'!",
"statusOk": false,
"statusError": true
}
| Available with the following applications |
|---|
| Alarm Manager |
14.06 Retrieve an alarm
To retrieve an alarm , use the method getAlarmDefinition available at /api/alarmmanagement. It returns the corresponding alarm object.
| Arguments | |
|---|---|
| id (required) | Alarm identifier |
Retrieve the alarm ID DevicesUpdateTimeRatioTriggersGenerator
import requests
payload = {
'id': 'DevicesUpdateTimeRatioTriggersGenerator',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/getAlarmDefinition", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"alarmStateChangeActionImplClassNames": [
"com.slv.alarming.action.SendEMailAction"
],
"id": "DevicesUpdateTimeRatioTriggersGenerator",
"name": "My alarm 1",
"geoZoneId": 1,
"triggerConditionImplClassName": "com.slv.alarming.trigger.DevicesUpdateTimeRatioTriggersGenerator",
"propertyValues": {
"disabled": false
}
}
]
If the specified alarm does not exist, this method returns an SLVResult object with a status of ERROR and the error code 613.
Sample response when the specified alarm does not exist
{
"status": "ERROR",
"errorCode": "613",
"errorCodeLabel": "Item not found",
"value": "streetlight.util.ItemNotFoundException: Item 'InexistentAlarm' not found as 'class com.slv.alarming.AlarmBundle'!",
"message": "Item 'InexistentAlarm'' not found as 'class com.slv.alarming.AlarmBundle'!",
"statusOk": false,
"statusError": true
}
| Available with the following applications |
|---|
| Alarm Manager |
14.07 Retrieve all alarms
To retrieve all alarms , use the method getAllAlarmDefinitions available at /api/alarmmanagement. It returns all alarm objects visible to the current user.
| Arguments | |
|---|---|
| propertyDescriptors | Set to true to obtain alarm properties. When it is set to false, only the common basic alarm attributes are provided in the response. Defaults to false |
Retrieve all alarms
import requests
payload = {
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/getAllAlarmDefinitions", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"alarmStateChangeActionImplClassNames": [
"com.slv.alarming.action.SendEMailAction"
],
"id": "DevicesUpdateTimeRatioTriggersGenerator",
"name": "My alarm 1",
"geoZoneId": 1,
"triggerConditionImplClassName": "com.slv.alarming.trigger.DevicesUpdateTimeRatioTriggersGenerator",
"propertyValues": {
"triggerCondition.deviceIds": [
1807
],
"triggerCondition.timeMode": 0,
"newAlarmWhenAcknowledged": false,
"action[0].from": "slv@mycompany.com",
"alarmName": "My alarm 1",
"alarmPriority": 0,
"action[0].subject": "My alarm 1",
"triggerCondition.triggeredDevicesRatioLimitPercent": 10,
"autoAcknowledge": true,
"refreshRate": 3600000,
"action[0].to": [
"john.doe@mycompany.com"
],
"action[0].message": "My alarm 1 is currently active",
"disabled": false,
"triggerCondition.delayTriggeringValueInMinutes": 120,
"triggerCondition.meaningCategories": [
0
]
}
}
| Available with the following applications |
|---|
| Alarm Manager |
14.08 Retrieve all possible master alarms
To retrieve all alarms that can be used as master alarms, use the method getAlarmsForNotificationTrigger available at /api/alarmmanagement. It does not take any argument.
To define a master alarm for an alarm to suppress its email notifications, set the property action[0].dependsOnAlarm to value of the desired master alarm, as returned by this method.
Retrieve all possible master alarms
import requests
payload = {
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarmmanagement/getAlarmsForNotificationTrigger", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"value": "DevicesUpdateTimeRatioTriggersGenerator",
"properties": null,
"label": "My alarm 1 Geozone: GeoZones",
"dependentFields": null
}
]
| Available with the following applications |
|---|
| Alarm Manager |
15. Alarm instances
The alarm instance
An alarm instance corresponds to an alarm as visible in the Alarms application in the SLV UI.
| Attributes | Description |
|---|---|
| id | Alarm instance ID (int) |
| generator | Identifier of the alarm that generated the alarm instance |
| name | Name of the alarm that generated the alarm instance |
| groupId | Identifier of the GeoZone where the alarm instance was generated |
| groupName | Name of the GeoZone where the alarm instance was generated |
| creationTime | Creation date of the alarm instance |
| lastStateChangeTime | Date of the last alarm state change |
| lastStateChangeInfo | Last acknowledgement message |
| lastStateChangeSrc | User responsible for the last ackknowledgement |
| priority | Alarm priority |
| stateKey | State of the alarm, TRIGGERED or ACKNOWLEGED |
| changes | Unused |
| description | Unused |
15.01 Retrieve alarm instances by GeoZone
To retrieve all alarm instances by GeoZone, use the method getGeoZoneAlarms available at /api/alarm. It returns a list of alarm instances.
| Arguments | |
|---|---|
| geoZoneId (required) | GeoZone identifier (int) |
| recurse | Set to true to include alarm instances belonging to sub-geozones. Defaults to false |
| priorityMin | Filters the results to include only alarms that have a priority higher than the specified value. Defaults to 0 |
| includeAcknowledgedAlarms | Set to true to include alarms that have been acknowledged. Defaults to false |
| includeLastTrigger | Unused |
Retrieve the alarms instances at the root GeoZone
import requests
payload = {
'geoZoneId': '1',
'includeLastTrigger': 'true',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/api/alarm/getGeoZoneAlarms", params=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
[
{
"creationTime": "2020-04-02 09:00:16",
"description": null,
"generator": "DevicesUpdateTimeRatioTriggersGenerator",
"groupId": 1,
"groupName": "GeoZones",
"id": 1,
"lastStateChangeInfo": null,
"lastStateChangeSrc": "-",
"lastStateChangeTime": "2020-04-02 14:05:52",
"name": "My alarm 1",
"priority": 0,
"stateKey": "TRIGGERED",
"changes": null
}
]
If no GeoZone is specified, this method returns an SLVResult object with a status of ERROR and the error code 500.
If an inexistent GeoZone is specified, this method returns an SLVResult object with a status of ERROR and the error code 630.
| Available with the following applications |
|---|
| Alarms |
15.02 Acknowledge an alarm instance
To manually acknowledge an alarm instance, use the method acknowledgeAlarms available at /api/alarm. It returns an SLVResult object with the specified alarm instance with its updated properties inside value.
| Arguments | |
|---|---|
| id (required) | Alarm instance ID |
| comment | Acknowledgement message |
Acknowledge the alarm instance
1with the messageOk
import requests
payload = {
'id': '1',
'comment': 'Ok',
'ser': 'json'
}
r = my_session.post(SLV_URL + "/api/alarm/acknowledgeAlarms", data=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
Sample response
{
"status": "OK",
"errorCode": "0",
"errorCodeLabel": null,
"value": [
{
"creationTime": "2020-04-02 09:00:16",
"description": null,
"generator": "DevicesUpdateTimeRatioTriggersGenerator",
"groupId": 1,
"groupName": "GeoZones",
"id": 1,
"lastStateChangeInfo": "Ok",
"lastStateChangeSrc": "admin",
"lastStateChangeTime": "2020-04-02 15:21:22",
"name": "My alarm 1",
"priority": 0,
"stateKey": "ACKNOWLEGED",
"changes": null
}
],
"message": null,
"statusOk": true,
"statusError": false
}
If an inexistent GeoZone is specified, this method returns an SLVResult object with a status of ERROR and the error code 613.
| Available with the following applications |
|---|
| Alarms |
16. On demand reports
16.01 Device status
Retrieve device status for non-OK devices in the top level GeoZone (geozone ID
1) and below
import requests
payload = MultiDict([
('groupId', '1'),
('reportBuilderClassName', 'MapFailureReport'),
('ser', 'MapFailureReportBinaryMapDataSerializer'),
('propertyName', 'recurse'),
('propertyValue', 'true'),
('propertyName', 'includeOkValues'),
('propertyValue', 'false')
])
r = my_session.get(SLV_URL + "/api/reporting/getRawReport", params=payload, auth=('USERNAME', 'PASSWORD'), headers=token_header)
i = 0
while i < len(r.content):
device_id = int.from_bytes(r.content[i:i + 4], byteorder='big', signed=False)
status = r.content[i + 4]
i += 5
print("Device ID: {}, Status: {}".format(device_id, status))
Sample response
\x00\x00\x00\x01\x01\x00\x00\x1eb\x02\x00\x00\x89\xc3\x01\x00\x00...
You may retrieve device status information in a binary payload by using the method getRawReport available at /api/reporting. It returns data serialized in binary format in the following order: device ID in a 4 bytes integer and device status in a 1 byte integer.
Device status can take the following values:
| Status | Description |
|---|---|
| 0 | ok |
| 1 | blank MAC address |
| 2 | commissioning problem |
| 3 | warning |
| 4 | critical failure |
This method takes an arbitrary number of (propertyName, propertyValue) pairs.
| Arguments | |
|---|---|
| groupId (required) | GeoZone ID |
| reportBuilderClassName (required) | Type of report - always set to "MapFailureReport" |
| ser (required) | Serialization (always set to "MapFailureReportBinaryMapDataSerializer") |
| propertyName (optional) | Configuration property name |
| propertyValue (optional) | Configuration property value |
All possible values for propertyName below are boolean, optional and default to true.
| propertyName | Description |
|---|---|
| recurse | Set to true to obtain devices belonging to the whole geozone tree under the specified geozone |
| includeNonCriticalValues | Set to true to include devices with non-critical failures (warnings) as well |
| includeOkValues | Set to true to include devices without failures -- the only way to get back statuses with 0/ok |
| includeCommissioningStatus | Set to true to include devices with commissioning problems -- the only way to get back statuses with 3/commissioning problem |
| Available with the following applications |
|---|
| Batch Control |
| Energy |
| Equipment Inventory |
| Failure Analysis |
| Failure Tracking |
| Installation |
| Monthly Energy Saving |
| Inventory Verification |
17. Helper methods
17.01 Retrieve version number
Retrieve SLV version number
import requests
payload = {
'property': 'build',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/public/api/publicconfig/getPublicConfigProperty", params=payload, headers=token_header, verify=False)
print(r.text)
Sample response
"7.17.0-132234"
Retrieve SLV UI build and version number
import requests
payload = {
'property': 'clientBuild',
'ser': 'json'
}
r = my_session.get(SLV_URL + "/public/api/publicconfig/getPublicConfigProperty", params=payload, headers=token_header, verify=False)
print(r.text)
Sample response
{"build":"202107151755","version":"7.18.0-dev1"}
You may retrieve the SLV version number by using the method getPublicConfigProperty available at /public/api/publicconfig.
| Arguments | |
|---|---|
| property (required) | Set to build to obtain the SLV version number, Set to clientBuild to obtain the SLV UI build and version numbers |
This method is available to all valid SLV user accounts.