AerAdmin – Device Management API (SOAP and XML)

AerAdmin follows the SOAP and XML protocol standards, available at the World Wide Web Consortium (W3C) web site http://www.w3c.org. A Web Services Definition Language (WSDL) file defines the interface between the AerAdmin system and your client processes. The WSDL file can be extracted from the AerAdmin servers using the URLs listed in the Table below.

The IP addresses and the secure/non-secure ports for the test and production servers are shown in Table 1 below. Access to the AerAdmin servers is restricted to Customers using Static IP addresses, a Virtual Private Network (“VPN”) connection , or over Leased Lines. Information on these options is available at the Aeris web site (see http://www.aeris.net for more information).

The Figure 1, “Device Management State Diagram,” shows the states that a Device has in the AerAdmin system. This state diagram also illustrates a few of the operations that affect a Device state — these requests are detailed later on this page. Each Device has associated properties. Some requests change the state from one to another (for example, an ActivateRequest moves a Device from Initial to Active-Billed); other requests change the property of a Device within that state (for example, an ChangeRatePlanRequest modifies the Rate Plan for a Device).

Figure 1. Device State Management Diagram

The five elements <CustomField1>, <CustomField2>, <CustomField3>, <CustomField4> and <CustomField5> are fields that you can use to store and retrieve information in the AerAdmin databases. Aeris does not use or process these fields for any purpose other than to store and retrieve them on your behalf. These fields are optional and, if used, must only contain printable ASCII characters—i.e., each byte of the string must range between 0x20 and 0x7E (inclusive). In general, specifying an empty string “”, or the value NULL, clears the AerAdmin database for that field.

In certain query operations, the request requires the technology for which the information is desired. This is specified in <Technology>. The following table displays allowable values for this field:

Table 4: Technology Values

The Device Identifier(s) in <DeviceID> must be clarified with the type of identifier being provided. This type is selected from the possible values shown in the following table.

Not all values of can be used with every request, since the value(s) in <DeviceID> may not be possible in the current state of the Devices. For example, specifying a type of “IMSI”, “MDN”, or “MIN” (and providing the IMSI, MDN or MIN in <DeviceID>) when requesting a Module to be provisioned using ProvisionRequest is not possible since the Module does not yet have an IMSI or MIN assigned to it!

Thus, you must make sure to provide the correct Device Identifiers and correct Device Identifier Type for the request.

Table 5: Device Identifier Type Values

In the requests, the formats allow one of several possible values to specify the Device or Devices.

Since only one of any value is provided to ensure that the correct Device is specified, this is in <DeviceID>, and the type of information is in <DeviceIDType>, as shown in section 4.5 “Device Identifier Type”.

For the bulk requests, more than one Device can be provided in <DeviceIDList>, but they must all be of the same type specifically, as specified in <DeviceIDType>.

Once a Device is cancelled, and stays cancelled for the retention period, the Device Identifiers of that Device are returned to the number pools for re-assignment to other Devices. Thus, to query for the history of a cancelled Device, you must use its ESN or its MEID. Regardless, the returned Device history contains information on pre-cancellation Device Identifiers that were used for the Device, even though they may now be assigned to other Customers or other Devices.

This requirement is vital, since the old Devices may interfere with the operation of new Devices, even though they will be denied service and network access, by the Aeris systems.

Your client process can send its own Request Identification in <RequestID>. This is often an integer value you specify, but it can be any string that serves the purpose of identification.

If your client process does not provide a <RequestID> in a request message, the AerAdmin system response does not include a <RequestID> in the response.

Since requests can be transmitted without any need to wait for a response to the request before sending the next request, using this element to correlate the requests and the responses is strongly recommended even for Heartbeats requests to ensure that the action is complete.

When required, your client process must specify a valid Service Name for the Device in <ServiceName>. This Service Name must be valid for your Account ID, sent in <AccountID>. You cannot specify a Service Name that is associated with another customer’s Account ID. If you do not know your assigned Service Names, you can use GetServiceName to retrieve the one, or more, Service Names assigned to you. If more than one Service Name is returned by this operation, you must select the correct one for use in <ServiceName>.

The responses from the AerAdmin system to queries and updates, also provide the Service Name associated with the Device in , for operation on the Aeris network. This value may be different from the Service Name in the requests to the AerAdmin system, particularly if you have more than one Service Name assigned.

The status of the Device is returned in <DeviceStatus> in responses to certain requests. This following table lists current return values:

Table 6: Device Status Return Values

DEFINITIONS:

• A “Device” is the complete remote unit deployed in the network (sometimes also called a Modem or a Terminal Device).
• A “Radio” or “Module” is the cellular radio module inside a Device.

OTHER COMPONENTS AND VERSIONS:In addition to the Radio, the Device generally also contains processors, memory, firmware, circuit boards, I/O connectors, sensors, power-supply, antennas, case, etc. The Device can have firmware and hardware versions. These are separately identified in the elements used for AerAdmin operations: <Device>, <softwareVersion>.

Pool Name refers to the name assigned to Rate Plan Pools. Accounts have Rate Plans and Rate Plan Pools defined. Rate Plan associated with an account can be pooled together. Aeris provides two types of pooling.

• In-Plan Pooling – This pooling option is available to customers with one rate across multiple devices. For example, if a customer has 2 devices each with a 5MB plan, there will be no overage charge if one device uses 7MB and the other device uses 2MB, since the total is less than the combined 10MB pool.
• Cross-Plan Pooling – This option is available to customers with different rates over multiple devices. For example, if a customer has 1 device with a 10MB plan and another device with a 5MB plan, there will be no overage charge if 1 device uses 13MB and the other device uses 1MB, since the total is less than the combined 15MB pool.

Each Device can be optionally placed into a Report Group, specified in <ReportGroup> as an unsigned 32 bit integer, i.e., a value from 0 to 4,294,967,295, inclusive. This has no effect on the transport of data to and from the Device, and is only used for creating summary reports (such as billing subtotals) grouped by Devices within each Report Group.

Since the billing reports are generated at the end of the billing period, Report Groups are used at that time to generate the summary reports and bills by the AerBill system, and for intermediate reports (i.e., not just at the end of the billing period from the AerTraffic system).

Thus, even though you can move Devices from one Report Group to another at any time during the billing period, only the Report Group assigned at the end of the billing period, or at the moment when an AerTraffic report is generated, is relevant for a Device. There is no “proration” of a Device presence within a Report Group during the billing period. Using Report Groups is optional. If a value is not specified in <ReportGroup>, a default integer value of 0 (zero) is used for the Device, and summary reports thus include all Devices associated with the entire Account. The value in <ReportGroup> is an unsigned 32-bit integer you select (even though it is sent in xsd:string format). It is strongly recommended that only a small number of Report Groups be used, since each grouping creates a separate summary for the reports that are generated. The AerAdmin system currently allows up to 256 Report Groups per Customer. You must understand and distinguish the value of a Report Group, ranging from 0 to over 4 billion, from the number or count of Report Groups that may be in use, up to 256 groups.

Therefore, when the number of Devices in a given application is expected to exceed 10,000, using Report Groups from the first operation submitted to the AerAdmin system is strongly recommended.

You systems must keep track of the Report Group to which a Device belongs and which Report Group values are used by your systems.

Each Account can have multiple Report Groups to which the Devices of that Account can be assigned, and these report Group values (and subsequent summaries) are separate and independent from similar values in other Accounts. This independence applies even when you have multiple Accounts with Aeris (each Account has separate, independent Report Groups).

With prior agreement by Aeris, you can request a Private Static IP address for a Device in <ReqStaticIP> when provisioning or activating the Device, using an ProvisionRequest or ActivateRequest. If the prior agreement does not exist, a request for a Private Static IP address is rejected with an error message. In addition, an existing Device without a Private Static IP address can be assigned one using an AssignStaticIPRequest operation (again with a prior agreement with Aeris). The number of available Private Static IP addresses is limited.

Dynamic IP addresses (the default) provide far more flexibility for your applications and address assignments particularly if it is a Mobile Application that moves to different locations (i.e., operating on different carriers) as part of the normal operation of the Application behavior. Thus, you should only use Private Static IP addresses if the Device is in a fixed location, and only if the Application requires this feature.

In various request responses values for <Profile0_*>, <Profile1_*> and the <AuthenticationKey> elements are not returned for Aeris SKU Radio Modules, since these are pre-programmed by the Radio Module Manufacturer. If these values are returned by the AerAdmin system, you must verify — and, if necessary, set or program — these parameter values into the Modules using the commands and tools provided by the Radio Module Manufacturer for this purpose.

Your client process submits a request to the AerAdmin system for a particular Device. The AerAdmin system returns a response, identifying if the request was processed successfully (or not) and other information relevant to the request result. Some of the APIs return the subset of attributes contained in the response object. For such APIs, the attributes that are returned are marked with an *. For example, your client process submits a request to change the Rate Plan for a Device. The AerAdmin system returns a response that confirms that the Rate Plan has been changed for that Device (if successful) or not (if unsuccessful).

All the device state change operations now return a unique transaction ID which is used for further references for the device state change operation been done. All the services are either Asynchronous or Synchronous in nature. All the bulk operations are asynchronous in nature and uses the <CallbackURL> to return the asynchronous responses.

The following table shows the operations for single and bulk devices grouped by the Service types and Request/Responses are further detailed in section 6. “Request/Response Descriptions.”

Device Attribute Services:

Table 7: Operations for single and bulk devices - Device Attribute Services

State Change Services

Table 8: Operations for single and bulk devices - State Change Services

Monitoring Services

Table 9: Operations for single and bulk devices - Monitoring Services

Device Query Services

Table 10: Operations for single and bulk devices - Device Query Services

The following tables describe the Request, Response objects for all the operations currently supported by AerAdmin.

Device Attribute Services

Table 11: Request, Response objects for Device Attribute Services

Learn more about Device Attribute Services request response elements or the Device Attribute Service XSD.

State Change Services

Table 12: Request, Response objects for State Change Services

Learn more about State Change Services request response elements or the Device State Service XSD.

Table 13: Request, Response objects for Monitoring Services

Learn more about Monitoring Services request response elements or the Device Monitor Service XSD.

Query Services

Table 14: Request, Response objects for Query Services

Learn more about Query Services request response elements or the Device Query Service XSD.