Filtering HMI API calls

HMI service service provides custom layer for API call filtering which can be used by various restriction policies.

Filtering is implemented using a custom lmacro which checks API call options and can restrict the current call by returning a non-zero exit code.

If filtered, the user gets access denied (-32002) error with a message from either err or out of the execution result payload or the default message “Denied by API filter”.

Contents

• Filtering HMI API calls

  • API methods filtered

  • Execution arguments

  • Example task

    • Preparing

    • The code

API methods filtered

The following API methods can be filtered:

• action

• action.terminate

• action.toggle

• action.kill

• lvar.set

• lvar.reset

• lvar.clear

• lvar.toggle

• lvar.incr

• lvar.decr

• pvt.put

• bus::<TARGET_SVC>::<METHOD>

• x::<TARGET_SVC>::<METHOD>

Execution arguments

The mapped lmacro is executed with the following keyword arguments:

• api_call_method API call method name

• api_call_params API call parameters

• aci API call info

• acl ACL of the current session

Example task

Consider there is a sensor sensor:tests/auto which is set by PLC to 1 when the system is working in automated mode.

When the system is in automated mode, we want to refuse HTTP API methods action and action.toggle, unless called by a user with admin privileges.

Preparing

To enable API call filtering:

• create lmacro, in this example a Python macro is used.

eva item create lmacro:tests/filter
eva item edit lmacro:tests/filter

Make sure Python macros controller is deployed and set lmacro action service field:

oid: lmacro:tests/filter
enabled: true
action:
  svc: eva.controller.py

Edit the HMI service configuration (eva svc edit eva.hmi.default) and set api_filter field to lmacro:tests/filter.

The code

Use the following Python code, which should be put into /opt/eva4/runtime/xc/py/filter.py file directly or using eva edit xc/py/filter.py shell command:

if api_call_method in ['action', 'action.toggle']:
    mode = value('sensor:tests/auto')
    if mode == 1 and not acl.get('admin'):
        out = 'system in auto mode'
        exit(1)

Note that the code does not throw any exception to make error messages less complicated.