Concepts

The platform is multi-tenanted and hierachical, meaning that for any given account, the platform can be partitioned up into a logical tree structure to suit the client's needs. For example, the parent tenant can create one or more sub-tenants, each with their own security boundary. These may typically be a distribution chain for device resellers or organisational units within an enterprise.

Each tenant can have one or more devices associated with it. Each device is typically assigned to an end-user. A tenant can be configured to register multiple device types at the same time within the scope of the tenancy. A tenant administrator can also create sub-tenants and create users within that sub-tenant. Users within that sub-tentant cannot see other users or devices outside of the sub-tenant security boundary. The tenant adminstrator can also delegate administrator permissions to the sub-tentant to permit the sub-tenant to manage devices and users independently.

Message Processing

A device can send a message to GAP via various mechanisms. Depending on the device, this can be via a proprietary connection to a telecomms provider, SMTP, a Short Messaging Service (SMS) or via this REST API.

The semantics of the message are specific to the device type and are often proprietary. However, almost all messages share a set of common properties, including a geographical location, a text message, one or more recipients and a set of flags. GAP supports generic devices through an advanced protocol. This permits devices of any type to send messages containing virtually any parameters (for more information, please contact us). On reciept of a message, GAP decodes the message, stores it and passes it to a routing engine. The routing engine determines the recipients (if any) of the message from a configurable address book and then translates the format to suit the recipient device or devices, be it email, SMS or another proprietary device. The API client does not have to be concerned with how this is achieved, but merely calls the API and GAP takes care of the processing! The API exposes methods to retrieve the messages sent into GAP as well as methods to retrieve messages sent from GAP as a result of the inbound message. The inbound messages are referred to a "mobile orginiated (MO)" and outbound messages as "mobile terminated (MT)". MT messages are read-only as they are generate by GAP as a result of the message processing and routing.

Message Routing and the Address Book

In order to route a message from a device to a recipient, you need to set up one more address book rules. Address book rules are based on specific message type defined in the address book events and address book distribution list containing individual recipients. Each distribution list can contain multiple entries and each entry can be an email address, or a mobile telephone number for SMS messages (if enabled for your account). When a message is received from a device, the message is inspected to determine if the recipient is a valid email address. If it is, then the message is forwarded to the specified address. If not, the recipient specified in the message is compared to the distribution lists for the device. If a match is found, the message is sent to all the addresses in the distribution list. For example, if you create a distribution list called "Friends", and add one or more reciepients to that distribution list, then if you address your message to "Friends" your message will be routed to those recipients. Different type of message, defined by address book event, can be routed to different distribution list. For example emergency messages (Event id: Other-Emergency) can be routed to 'Emergencies' distribution list. You can add new distribution lists and address book entries via the portal or via the API.

Address Type Definition
mail:<emailaddress> Sends the message to the email address e.g. mail:bob@aol.com
<device type>:<imei> Sends a message to an Iridium Short Burst Data device e.g. shout:303412345678901.
sms:<mobilenumber> Routes the message to a mobile phone number via SMS e.g. sms:+447720296325. Please note that extra charges may apply.
 
contact:<contactId>/<entryId> Sends the message to the address book contact. The "contactId" is a GUID and can be found in the AddressBookContact object. The "entryId" is a GUID and can be found in the AddressBookContactEntry object. This address format can be used only when creating Address Book List Entry.

Geofences

A geofence is a virtual perimeter around a geographic region. As your device reports its location, the platform monitors the reports and determines whether the device has crossed into or out of the geofence. When the geofence is crossed, you have the option to send a notification to one or more recipients.

There are 2 supported types of geofence: circular, where the fenced-in area is a circle, or polygon, where the fenced in area is defined by a line joining separate coordinates. Multiple geofences are supported per device at any one time.

Check In Schedules

Check-in schedules can be used to specify times when a device must check in. A device that hasn’t reported according to its schedule will be marked as overdue and a message will be sent to specified recipients. You can create a schedule based on “Selected Times” or “Intervals”. For selected times, you specify the times that a device must check in. For intervals, you specify the start and end time. In addition, the “Buffer Period” is the grace period either side of check in time before the Portal will send an overdue message.