Connecting to NAS Events

New in SDK 0.7, requires NASOS ≥ 4.2.

This section will teach you how to:

• Connect you app to NAS events so it can react to [meaningful events
• Have your app define its own events and send them to the NAS Device Manager

Receiving NAS Events

To receive NAS events, an app has to:

• Register to a list of events by declaring them in the registered_events property
• Write the events script to handle the events

Registering Events

Update the app’s package.json file to contain the list of events it needs, to register, for example:

{
"registered_events": [
    "appmanager.install_ok",
    "appmanager.remove_ok"
    ]
}

Please refer to the NAS Events Reference for a full list of events and their arguments.

Writing the Event Script

In the scripts directory of the app’s project, create an executable script name events, for example:

#!/bin/sh -e

if [ "$1" = "appmanager.install_ok" ]; then
    echo "$(date): $app_name installed." >> /var/log/events.log
    echo $@ >> /var/log/events.log
fi

if [ "$1" = "appmanager.remove_ok" ]; then
    echo "$(date): $app_name removed." >> /var/log/events.log
    echo $@ >> /var/log/events.log
fi

exit 0

As the script shows, the $1 argument contains the event name. The event’s arguments are passed to the script as environment variables. In this example, the $app_name argument of the appmanager.install_ok and appmanager.remove_ok events is available.

Please refer to the NAS Events Reference for a full list of events and their arguments.

This script is simply given as a mean to demonstrate how events can be received. It does nothing except logging the events as they happen. It is up to the developper to define the events they want to handle, and implement the required actions.

Sending NAS Events

Enabling the NAS API

You will need to enable the NAS API for you app. See the API Utility Package section for details on how to add the com.nasos.unicorn_api to your app’s depends property

You will also need to enable the v7.0.appstore.EventsManager capability in your unicorn_api.conf file:

{
    "mandatory_perms": ["v7.0.appstore.EventsManager"], 
}

Defining the Events

Events are defined in the package.json file, in the events section. Here is a sample event definition:

{
    "events": [
        {
            "name": "hello",
            "args": [
                ["msg", "unicode"]
            ]
        }
    ]
}

Events Localization

Events localization is defined in the package-extra.json file, in the locales section.

Here is an example event localization definition:

{
    "locales": {
        "en": {
            "hello": "Hello {msg}!"
        },
        "fr": {
            "hello": "Bonjour {msg}!"
        }
    }
}

Here we have the event hello, which takes the argument msg. As can be seen, we can use the argument in the message.

Sending the Events

Sending events is done using the appstore.EventsManager NAS API.

See the Calling the NAS API section for details. Here is a sample Python code to send the hello event defined above:

from unicorn_api.v7.sv0.appstore.EventsManager import EventsManager
from transformer.plugins.application import ApplicationClientAuthentication
from transformer.transport.client_http import HTTPClient
import json
def get_client(host='127.0.0.1', port=8888, username=None, password=None):
    config = json.load(open('/etc/unicorn_api.conf'))
    client = HTTPClient(host, port)
    app_auth = ApplicationClientAuthentication()
    app_auth.set_app_id(config["install_id"])
    app_auth.set_app_token(config["token"])
    client.set_authentication(app_auth)
    app_session_token = app_auth.open_session()["session_token"]
    return client
client = get_client()
manager = EventsManager()
manager.send_event('hello',{'msg':'world'},get_client())

After the usual API initialization, all is required is instantiating an EventsManager object, and call its send_event method with the appropriate arguments.

In the next section, you’ll learn more about deploying and debugging your app.