SFA API

SCADA Final Aggregator SFA API is called through URL request

http://<IP_address_SFA:Port>/sfa-api/function

If SSL is allowed in the controller configuration file, you can also use https calls.

All functions can be called using GET and POST methods. When POST method is used, the parameters can be passed to functions either as www-form or as JSON.

Note

Object creation and modification functions don’t save configurations automatically unless you specify save parameter in API request. The system is designed to work this way to let you discard the changes in case of serious problems by killing the controller process.

If you need to save any changes made without this parameter, restart the controller gracefully or use SYS API save function.

Functions passed to the remote controllers

The following functions are passed to the connected remote controllers and return the result as-is.

Note

Function result is used to return both unit action results and macro execution results.

Units control

Logic variables control

Macros control

  • run - LM API call to execute logic control macro
  • result - LM API call to get macro execution result by macro oid (lmacro/group/id) or uuid

Decision rules control

test - test API/key and get system info

Test can be executed with any valid API KEY

Parameters:

  • k valid API key

Returns JSON dict with system info and current API key permissions (for masterkey only ‘master’:true is returned)

{
    "acl": {
        "allow": {
            "cmd": true
        },
        "groups": [
            "system/#",
            "service",
            "security/+"
        ],
        "items": [],
        "key_id": "key1",
        "master": false,
        "sysfunc": false
    },
    "product_build": 2017082101,
    "product_code": "sfa",
    "product_name": "EVA SCADA Final Aggregator"
    "result": "OK",
    "system": "eva3-test1",
    "time": 1504489043.4566338,
    "version": "3.0.0"
}

Errors:

  • 403 Forbidden the key has no access to the API

reload_clients - ask connected clients to reload

This function sends reload event to all connected clients asking them to reload the interface.

All the connected clients receive the event with subject=”reload” and data=”asap”. If the clients use SFA Framework, they must define eva_sfa_reload_handler function.

Parameters:

  • k masterkey

Returns result=”OK” if the reload event is sent, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

notify_restart - notify about server restart

This function sends a server restart event to all connected clients asking them to prepare for server restart.

All the connected clients receive the event with subject=”server” and data=”restart”. If the clients use SFA Framework, they must define eva_sfa_server_restart_handler function.

Server restart notification is sent automatically to all connected clients when the server is restarting. This API function allows to send server restart notification without actual server restart, which may be useful e.g. for testing, handling frontend restart etc.

Parameters:

  • k masterkey

Returns result=”OK” if the reload event is sent, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

state - get item state

State of the known item or all the items of the specified type can be obtained using state command.

Parameters:

  • k valid API key
  • p item type (U for unit, S for sensor, LV for lvar, required
  • i full item id (group/id), optional
  • g group filter, optional mqtt masks can be used, for example group1/#, group1/+/lamps) virtual, status_labels and action_enabled for unit)

optionally:

  • full=1 get full item state info (description, action labels and etc.)

Returns item status in JSON dict or array of dicts:

[
    {
        "expires": 0,
        "full_id": "service/test",
        "group": "service",
        "id": "test",
        "set_time": 1506345719.8540998,
        "status": 1,
        "type": "lvar",
        "value": "33"
    }
]

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found item doesn’t exist, or the key has no access to the item

state_history - get item state history

State history of one item or several items of the specified type can be obtained using state_history command.

Parameters:

  • k valid API key
  • i item ID, or multiple IDs, comma separated
  • a notifier ID which keeps history for the specified item(s) (default: db_1)
  • s time frame start, ISO or Unix timestamp
  • e time frame end, optional (default: current time), ISO or Unix timestamp
  • l limit history records (optional)
  • x item property (status or value)
  • t time format (iso or raw for Unix timestamp)
  • w fill frame with the specified interval (e.g. 1T - 1 minute, 2H - 2 hours etc.), optional
  • g output format, list (default) or dict

Returns state history for the chosen item(s) in the specified format.

To get state history for multiple items:

  • w param is required
  • g should be specified as list

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found item doesn’t exist, the key has no access to the item, or the history database is not found

groups - get item group list

Get the list of the item groups. Useful e.g. for custom interfaces.

Parameters:

  • k valid API key
  • p item type (U for unit, S for sensor, LV for lvar), required

optionally:

Returns JSON array:

[
    "parent_group1/group1",
    "parent_group1/group2"
]

Errors:

  • 403 Forbidden invalid API KEY

groups_macro - get macro groups list

Get the list of the macro groups.

Parameters:

  • k valid API key

Returns JSON array:

[
    "parent_group1/group1",
    "parent_group1/group2"
]

Errors:

  • 403 Forbidden invalid API KEY

list_macros - get macro list

Get the list of all available macros.

Parameters:

  • k valid API key
  • g filter by group, optional (MQTT masks may be used, i.e. group1/#, group1/+/service)

Returns JSON array:

[
    {
       "action_enabled": true,
       "description": "description",
       "full_id": "group/macro_id",
       "group": "group",
       "id": "macro_id",
       "oid": "lmacro:group/macro_id",
       "type": "lmacro"
    }
]

Errors:

  • 403 Forbidden invalid API KEY

list_remote - get a list of items from connected controllers

Get a list of the items loaded from the connected controllers. Useful to debug the controller connections.

Parameters:

  • k masterkey

optionally:

Returns the JSON array of units, sensors loaded from the remote controllers. Additional field controller_id is present in any item indicating the controller it’s loaded from.

Errors:

  • 403 Forbidden invalid API KEY

list_controllers - get controllers list

Get the list of all connected controllers.

Parameters:

  • k valid API key
  • g controller type (uc or lm, optional)

Returns JSON array:

[
    {
    "build": "BUILD",
    "connected": true,
    "description": "<controller_description>",
    "full_id": "<type/controller_id>",
    "group": "<type>",
    "id": "<controller_id>",
    "oid": "remote_<type>:<type>/<controller_id>",
    "type": "remote_<type>",
    "version": "VERSION"
    }
]

Errors:

  • 403 Forbidden invalid API KEY

test_controller - test connection to remote controller

Allows to test connection to the controller.

  • k masterkey
  • i controller id

Returns result=”OK” if the test is passed, or result=”ERROR”, if failed.

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found controller doesn’t exist

list_controller_props - get editable controller parameters

Allows to get all editable parameters of the connected controller.

  • k masterkey
  • i controller id

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found controller doesn’t exist

set_controller_prop - set controller parameters

Allows to set configuration parameters of the connected controller.

Parameters:

  • k masterkey
  • i controller id
  • p controller configuration param
  • v param value

Returns result=”OK” if the parameter is set, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

append_controller - connect remote controller

Connects remote controller to the local.

Parameters:

  • k masterkey
  • uri API uri (proto://host:port)
  • a remote controller API key ($key to use local key)

optionally:

  • m MQTT notifier to exchange item states in real time
  • s True/False (1/0) verify remote SSL certificate or pass invalid
  • t timeout (seconds) for the remote controller API calls
  • save=1 save connected controller configuration on the disk immediately after creation

Returns result=”OK” if the controller is connected, or result=”ERROR”, if an error occurred.

The remote controller id is obtained and set automatically according to its hostname or name field in the controller configuration. The remote controller id can’t be changed.

Errors:

  • 403 Forbidden invalid API KEY

remove_controller - disconnect remote controller

Disconnects the remote controller.

Parameters:

  • k masterkey
  • i controller id

Returns result=”OK” if the controller is disconnected, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

reload_controller - reload items from UC

Allows to immediately reload all the items, macros and their status from the remote controller.

Parameters:

  • k masterkey
  • i controller id

Returns result=”OK” if the controller is deleted, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

User authorization using login/password

Third-party apps may authorize users using login and password as an alternative for authorization via API key.

login - user authorization

Authorizes user in the system and and opens a new authorized session. Session ID is stored in cookie.

Attention! Session is created for all requests to API, even if login is not used; web-browsers use the same session for the host even if apps are running on different ports. Therefore, when you use web-apps (even if you use the same browser to simultaneously access system interfaces or other apps) each app/interface should be associated with different domains/alias/different host IP addresses.

Parameters:

  • u user name
  • p user password

Returns JSON dict { “result” “OK”, “key”: “APIKEY_ID” }, if the user is authorized.

Errors:

  • 403 Forbidden invalid user name / password

logout

Finishes the authorized session

Parameters: none

Returns JSON dict { “result” : “OK” }

Errors:

  • 403 Forbidden no session available / session is already finished