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”.

API methods filtered

The following API methods can be filtered:

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.


To enable API call filtering:

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

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/ file directly or using eva edit xc/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'

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