Module: isatdatapro-api

Members

inner,constantForwardMessageStatesnumber

Enumerated type for State of Mobile-Terminated message

Properties:

Name	Type	Default	Description
SUBMITTED	number	0
RECEIVED	number	1
ERROR	number	2
DELIVERY_FAILED	number	3
TIMED_OUT	number	4
CANCELLED	number	5

inner,constantWakeupPeriodsnumber

Enumerated type for TerminalWakeupPeriod

Properties:

Name	Type	Default	Description
None	number	0
Seconds30	number	1
Seconds60	number	2
Minutes3	number	3
Minutes10	number	4
Minutes30	number	5
Minutes60	number	6
Minutes2	number	7
Minutes5	number	8
Minutes15	number	9

Methods

async,innercancelForwardMessages(auth, ids){Promise.<CancelForwardMessagesResult>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 880

Requests cancellation of specific Mobile-Terminated message(s)

Name	Type	Description
auth	ApiV1Auth	Mailbox authenticataion
ids	number | Array.<number>	Message id(s) to be cancelled

Returns:

Type	Description
Promise.<CancelForwardMessagesResult>	see CancelForwardMessagesResult

innerdateToIdpTime(date){string}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 183

Returns an IDP message gateway formatted timestamp, defaults to 1970-01-01 00:00:00

Name	Type	Description
date	Object	A Javascript Date object

Returns:

Type	Description
string	An IDP message gateway formatted timestamp 'YYYY-MM-DD hh:mm:ss'

async,innergetBroadcastIds(auth){Promise.<BroadcastIdList>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 987

Returns the list of Broadcast IDs associated with the Mailbox

Name	Type	Description
auth	ApiV1Auth	Mailbox authentication

Returns:

Type	Description
Promise.<BroadcastIdList>	See BroadcastIdList

async,innergetErrorDefinitions(){Promise.<Array.<ErrorDefinition>>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 399

Returns an array of error definitions based on an API error code

Returns:

Type	Description
Promise.<Array.<ErrorDefinition>>	See ErrorDefinition

async,innergetErrorName(errorId){Promise.<string>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 424

Returns a descriptive error name based on an API error code

Name	Type	Description
errorId	string | number	The ErrorID number returned by the API operation

Returns:

Type	Description
Promise.<string>	An error name/description or 'UNDEFINED'

async,innergetForwardMessages(auth, ids){Promise.<GetForwardMessagesResult>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 723

Retrieves Mobile-Terminated messages submitted, by ID(s)

Name	Type	Description
auth	ApiV1Auth	Mailbox authentication see ApiV1Auth
ids	number | Array.<number>	An array of unique ForwardMessageID numbers

Returns:

Type	Description
Promise.<GetForwardMessagesResult>	The requested IDs and/or error code see GetForwardMessagesResult

async,innergetForwardStatuses(auth, filter){Promise.<GetForwardStatusesResult>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 809

Retrieves Mobile-Terminated message state/status by ID(s) and optional time range NOTE: API should support ids as optional if startTimeUtc is specified

Name	Type	Description
auth	ApiV1Auth	Mailbox authentication see ApiV1Auth
filter	ForwardStatusFilter	A set of filter criteria for the query see ForwardStatusFilter

Throws:

If filter does not include ids or startTimeUtc

Type

Error

Returns:

Type	Description
Promise.<GetForwardStatusesResult>	see GetForwardStatusesResult

async,innergetIdpTime(){Promise.<Date>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 248

Returns current UTC time at the MGS

Returns:

Type	Description
Promise.<Date>	UTC time at the message gateway

async,innergetIdpVersion(){Promise.<string>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 118

Returns the Message Gateway System software version details

Returns:

Type	Description
Promise.<string>	IDP Message Gateway System software version

async,innergetMobileIds(auth, filter){Promise.<MobileIdList>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 931

Returns a list of MobileID metadata

Name	Type	Description
auth	ApiV1Auth	Mailbox authentication
filter	Object	optional Filters for ID (next ID for sequential query) and size Name Type Description mobileId string optional Set the only/first Mobile ID to query, if present pageSize number optional Maximum number of results to return (1..1000) defaults to 1000

Returns:

Type	Description
Promise.<MobileIdList>	A response list with error code see MobileIdList

async,innergetReturnMessages(auth, filter){Promise.<GetReturnMessagesResponse>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 513

Returns a response object containing retrieved messages that match the filter

Name	Type	Description
auth	ApiV1Auth	Mailbox authentication parameters see ApiV1Auth
filter	FilterGetMobileOrigintated	See FilterGetMobileOrigintated

Returns:

Type	Description
Promise.<GetReturnMessagesResponse>	See GetReturnMessagesResponse

innergetStateDefinition(state){string}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 768

Returns the enumerated string of the state value

Name	Type	Description
state	number	The state value returned in ForwardStatus

Returns:

Type	Description
string	see ForwardMessageStates

innergetWakeupPeriod(period){string}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 595

Returns the enumerated string of the WakeupPeriod

Name	Type	Description
period	number	The TerminalWakeupPeriod

Returns:

Type	Description
string	see WakeupPeriods

inneridpTimeToDate(idpTimeUtc){Date}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 235

Returns a Javascript Date object by converting an IDP message gateway formatted timestamp

Name	Type	Description
idpTimeUtc	string	An IDP message gateway formatted timestamp 'YYYY-MM-DD hh:mm:ss'

Throws:

If the passed in value is not a valid IDP datestamp

Type

Error

Returns:

Type	Description
Date	Javascript Date object

async,innersubmitForwardMessages(auth, messages){Promise.<SubmitForwardMessagesResult>}

/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 639

Submits Mobile-Terminated message(s) to remote modem(s)

Name	Type	Description
auth	ApiV1Auth	Mailbox authentication see ApiV1Auth
messages	Array.<ForwardMessage>	An array of messages see ForwardMessage

Returns:

Type	Description
Promise.<SubmitForwardMessagesResult>	An error code and metadata see SubmitForwardMessagesResult

Type Definitions

ApiV1AuthObject

An authentication pair for the IDP Messaging API V1, used for various operations

Properties:

Name	Type	Description
accessId	string	The mailbox unique access_id
password	string	The mailbox password

BroadcastIdListObject

Response structure for a BroadcastID query

Properties:

Name	Type	Description
errorId	number	An error code for the get_mobiles_paged operation
broadcastGroups	Array.<BroadcastInformation>	A list of BroadcastInformation objects

BroadcastInformationObject

Metadata for a BroadcastID

Properties:

Name	Type	Description
mobileId	string	The unique Broadcast ID
description	string	A description as provisioned on the MGS

CancelForwardMessagesResultObject

Response structure for cancellation request of Mobile-Terminated message(s)

Properties:

Name	Type	Description
errorId	number	An error code for the submit_cancelations operation
submissions	Array.<ForwardCancelation>	The list of submitted messages to cancel

ErrorDefinitionObject

Describes an error code returned by the IDP Messaging API

Properties:

Name	Type	Description
id	number	The unique error number
name	string	The unique name
description	string	A verbose description of the error

FieldObject

A data structure containing various content and metadata within a message, present if a codec is provisioned on the Mailbox

Properties:

Name	Type	Argument	Description
name	string		A descriptive name of the field, usually in camelCase notation
dataType	string	<optional>	Supported types   'enum' is presented as string on decode, may be number or string on encode   'boolean' is presented as a string Value   'unsignedint', 'signedint' are presented as a string Value   'string'   'data' is a string, base64 encoded   'array' is an object with Elements instead of Value   'message' is an object with Message instead of Value   'dynamic' TBC   'property' TBC
stringValue	string	<optional>	Present if Type is 'enum', 'boolean', 'unsignedint', 'signedint', 'string', 'data'
elements	Array.<Object>	<optional>	present if Type is 'array' Properties Name Type Argument Description index number <optional> index of the Elements array fields Array.<Field> <optional> A list of field objects
message	Message	<optional>	present if Type is 'message'

FilterGetMobileOrigintatedObject

A filter to apply when retrieving Mobile-Originated messages

Properties:

Name	Type	Argument	Default	Description
startTimeUtc	string | Date	<optional>		Start time (high water mark from prior nextStartUtc) ISO format 'YYYY-MM-DDTHH:MM:SSZ'   required if startMessageId is not present, ignored if startMessageId is present
startMessageId	number	<optional>		Start message ID (high water mark from prior NextStartID)   required if startTimeUtc is not present
endTimeUtc	string | Date	<optional>		Optional end time if startTimeUtc is used, to return a range of messages rather than all since startTimeUtc
mobileId	string	<optional>		Optional filter to retrieve only messages for a single terminal/modem
includeRawPayload	boolean	<optional>	true	A flag indicating if ReturnMessage.RawPayload should be returned
includeFieldType	boolean	<optional>	true	A flag indicating if ReturnMessage.Payload.Fields should include the Type property

ForwardCancelationObject

Metadata structure for a Mobile-Terminated message submission

Properties:

Name	Type	Argument	Description
errorId	number		An error code returned by the MGS (0 = no errors; 115 = )
messageId	number		A unique number generated by the network for tracking status of delivery (-1 if failed)
userMessageId	string	<optional>	The optional user-supplied message ID to correlate with ForwardMessageID
mobileId	string		A unique Mobile ID or Broadcast ID to send the message to (empty string if failed)
size	number	<optional>	The over-the-air message size, in bytes
stateTimeUtc	string		The ISO timestamp YYYY-MM-DDTHH:MM:SSZ of the last reported state of the message
mobileWakeupPeriod	number		A [something] indicating if the modem is configured for low power sleep
scheduledSendTimeUtc	string		A timestamp YYYY-MM-DDTHH:MM:SSZ for the scheduled message delivery to a low power modem

ForwardMessageObject

Data structure for a Mobile-Terminated (aka To-Mobile aka Forward) message

Properties:

Name	Type	Argument	Description
mobileId	string		A unique Mobile ID or Broadcast ID to send the message to
userMessageId	string	<optional>	An optional ID that may be used by your application to correlate to a system-assigned ForwardMessageID
payloadRaw	Array.<number>	<optional>	Must be present if Payload is not present, an array of bytes as decimal values (0..255)
payloadJson	Message	<optional>	Must be present if RawPayload is not present, see Messsage implies that a Message Definition File is used on the Mailbox

ForwardMessageRecordObject

Metadata structure for a Mobile-Terminated message that has been submitted to the IDP Message Gateway System

Properties:

Name	Type	Description
mobileId	string	A unique Mobile ID or Broadcast ID to send the message to
payloadRaw	Array.<number>	Must be present if Payload is not present, an array of bytes as decimal values (0..255)
payloadJson	Message	Must be present if RawPayload is not present, see Message implies that a Message Definition File is used on the Mailbox
messageId	number	A unique number assigned by the MGS upon submission (get_forward_messages only)
mailboxTimeUtc	string	A timestamp assigned by the MGS upon submission (get_forward_messages only)
stateTimeUtc	string	A timestamp of the most recent State (get_forward_messages only)
state	number	The current state of the message (get_forward_messages only)
errorId	number	An error code for the record retrieval
isClosed	boolean	An indicator if the message is completed/failed (get_forward_messages only)
referenceNumber	number	System generated (get_forward_messages only)

ForwardStatusObject

Metadata for a submitted Mobile-Terminated message state

Properties:

Name	Type	Description
errorId	number	An error code for the Mobile-Terminated message
messageId	number	The unique ID of the message assigned by the system
isClosed	boolean	An indicator whether the message is no longer pending (delivered or failed)
referenceNumber	number
stateTimeUtc	string	The ISO timestamp YYYY-MM-DDTHH:MM:SSZ or Date of the reported state of the message
state	number	The state/status code of the message

ForwardStatusFilterObject

A filter for requesting Mobile-Terminated message(s) states

Properties:

Name	Type	Argument	Description
ids	number | Array.<number>	<optional>	Unique ForwardMessage.ID(s) to query, must be present if startTimeUtc is not
startTimeUtc	string | Date	<optional>	The UTC timestamp YYYY-MM-DD hh:mm:ss for the start of retrieval, must be present if ids is not
endTimeUtc	string | Date	<optional>	The UTC timestamp YYYY-MM-DD hh:mm:ss for the end of retrieval

ForwardSubmissionObject

Metadata structure for a Mobile-Terminated message submission

Properties:

Name	Type	Argument	Description
errorId	number		An error code returned by the MGS (0 = no errors)
messageId	number		A unique number generated by the network for tracking status of delivery
userMessageId	string	<optional>	The optional user-supplied message ID to correlate with ForwardMessageID
mobileId	string		A unique Mobile ID or Broadcast ID to send the message to
size	number		The over-the-air message size, in bytes
stateTimeUtc	string		The ISO timestamp YYYY-MM-DDTHH:MM:SSZ of the last reported state of the message
mobileWakeupPeriod	number		A [something] indicating if the modem is configured for low power sleep
scheduledSendTimeUtc	string		An ISO timestamp YYYY-MM-DDTHH:MM:SSZ for the scheduled message delivery to a low power modem

GetForwardMessagesResultObject

Structure of response to a retrieval of Mobile-Terminated message(s)

Properties:

Name	Type	Description
errorId	number	An error code for the get_forward_messages operation
messages	Array.<ForwardMessageRecord>	An array of records see ForwardMessageRecord

GetForwardStatusesResultObject

Response structure for a query of Mobile-Terminated message state(s)

Properties:

Name	Type	Description
errorId	number	An error code returned for the get_forward_statuses operation
more	boolean	An indicator if additional statuses are available for retrieval
nextStartTimeUtc	string | null	The ISO timestamp YYYY-MM-DDTHH:MM:SSZ for the next retrieval, null if More is false
statuses	Array.<ForwardStatus> | null	An array of ForwardStatus if any were retrieved, otherwise null

GetReturnMessagesResponseObject

The JSON structured response to the retrieving Mobile-Originated messages

Properties:

Name	Type	Description
errorId	number	An API error code (0 means no error)
more	boolean	A flag indicating if more messages are available to retrieve
nextStartTimeUtc	string	An ISO timestamp YYYY-MM-DDTHH:MM:SSZ for the next high water mark retrieval, empty string if none
nextStartId	number	Unique ReturnMessage.ID of the next message available to retrieve from the MGS/Mailbox, -1 if none
messages	Array.<ReturnMessage> | null	An array of ReturnMessage objects or null if none meet the filter/range criteria

MessageObject

A set of metadata encapsulating data transported over the satellite network as a message

Properties:

Name	Type	Argument	Description
isForward	boolean	<optional>	indicates if the message is Mobile-Terminated (aka To-Mobile aka Forward)
codecServiceId	number		Service Identification Number the first byte of payload optionally used for codec
codecMessageId	number		Message Identification Number the second byte of payload optionally used for codec
name	string		A short name for the message, typically using camelCase notation
fields	Array.<Field>		An array of Field types

MobileIdListObject

Structure of response to a MobileID query

Properties:

Name	Type	Description
ErrorID	number	An error code for the get_mobiles_paged operation
Mobiles	Array.<MobileInformation>	A list of MobileInformation objects

MobileInformationObject

Metadata for a queried MobileID

Properties:

Name	Type	Description
mobileId	string	The unique Mobile ID
description	string	A description as provisioned on the MGS
lastRegistrationTimeUtc	string	An ISO timestamp format YYYY-MM-DDTHH:MM:SSZ of the last Registration message
regionName	string	The region/beam on which the last Registration message was received

ReturnMessageObject

A set of metadata relating to a Mobile-Originated (aka From-Mobile aka Return) message

Properties:

Name	Type	Argument	Description
messageId	number		A unique number assigned by the MGS upon receipt of the message
receiveTimeUtc	string		An ISO timestamp YYYY-MM-DDTHH:MM:SSZ when the message was received at the Satellite Access Station
regionName	string		The name of the satellite regional beam the message was received on
size	number		The size of the message received over-the-air, in bytes
mailboxTimeUtc	string		An ISO timestamp YYYY-MM-DDTHH:MM:SSZ when the message is ready for retrieval in the Mailbox
mobileId	string		The unique Mobile ID of the terminal/modem that sent the message
codecServiceId	number		Service Identification Number the first byte of payload optionally used for codec
payloadRaw	Array.<number>	<optional>	An array of bytes as decimal numbers (0..255)   present if requested in the get_return_messages operation
payloadJson	Message	<optional>	A JSON data structured Message   present if the MGS has decoded the raw payload using a Message Definition File on the Mailbox

SubmitForwardMessagesResultObject

Structure of response to a Mobile-Terminated message(s) submission

Properties:

Name	Type	Description
errorId	number	An error code returned by the system (0 = no errors)
submissions	Array.<ForwardSubmission>	An array of ForwardSubmission metadata for Mobile-Terminated messages submitted in the operation