Devices

Overview

The device type determines how you receive notifications. It is an abstraction of an end-user's target device for receiving notifications. The main example of a device is an email address, which is currently the only type of device which is supported.

Note: Future versions of the Platform will support other device types, such as browser installation or a physical device such as a mobile phone.

How Devices work

Each device is owned by a particular user, and by default, each user's registered email address (in the Passport Service) will be automatically created as a new EMAIL type device. However, a user may also add and administer additional devices.

Note: The same device identity (for example, email address) cannot be created multiple times for the same owning user.

Using the Device API

APIs for devices are permissioned differently from the other entities in the Notification Service. A normal user can only perform operations on devices that they own. However, a Platform Manager user can perform operations on devices for all users.

Device properties

When you create a device, the following properties are supported:

• _owner._irn: The IRN of the owning user. This must be in the form of: passportsvc:user:<user id> where <user id> is the ID of the calling user.
• _transport: Currently only EMAIL is supported.

When transport is EMAIL, just one property is supported: _email.address, which is the target email address.

Note: All device properties are immutable.

Device API examples

This section lists some useful examples of using the Notification Service API to perform operations on devices.

For a full reference to the Device API, refer to the Device Rest API page.

How to create a device

To create an EMAIL type device, refer to the sample code shown below.

const device = await IafNotification.createDevice({
    _owner: {
   		_irn: "passportsvc:user:<user id>"
    },
    _transport: "EMAIL",
    _email: {
    	_address: "me@example.com"
    }
}, ctx);

How to list devices

To list devices, you must provide a query. The query must include at a minimum, the owner IRN of the calling user.

The following query properties are supported:

• transport
• owner.irn

Note: These properties map to the same properties used when creating or updating templates.

Refer to the sample code below.

const devices = await IafNotification.listDevices({
    owner: {
    	irn:  "passportsvc:user:<user id>"
    }
}, ctx);

How to delete a device

To delete a device, with a given ID, refer to the sample code below.

await IafNotification.deleteDevice(device._id, ctx);