What’s Here?
The AerAdmin Web Service interface is used to provision, activate, and manage devices. This page describes the Simple Object Access Protocol (SOAP) and extensible Markup Language (XML) formats used to provision and manage the billing options for your application devices in the field.
AerAdmin Sections
This article is divided into following sections:
Overview
The WSDL File
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.
Test Server to Production Server
The Test AerAdmin server is available after you’ve completed development, internal testing, and you’re ready for Aeris Qualification. The Production AerAdmin servers are only available to customers with Aeris Qualified Client process implementations.
AerAdmin supports all BULK device operations as asynchronous services. When a device is processed via API call, the service pushes a send response to the requester. To make this call-back service work, Aeris provides an asynchronous service definition which you need to host at your end. The URL for this Async service is provided in the “CallBackURL” field in all AerAdmin BulkOperations. The WSDL file for this Async service can be extracted from the Aeris servers using the URLs listed in Table 2 below.
IP Connection
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).
Endpoint | Information |
Service Name: {soap.aeradmin.service.aeris.com}AerAdminService Port Name: {soap.aeradmin.service.aeris.com}AerAdminPort | Address: http://aeradminapi.aeris.com:80/AerAdmin_WS_5_0/ws
WSDL: http://aeradminapi.aeris.com:80/AerAdmin_WS_5_0/ws?wsdl Implementation class: com.aeris.service.aeradmin.soap.AerAdminImpl |
Two-Way Connectivity Required
Two-way connectivity with Aeris networks is required. A ping operation is supplied with this Async WSDL to diagnose connectivity. Once you host this service, the callback URL can be shared and Aeris can attempt a “ping” operation to validate connectivity.
Device States
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).
Initial State
State Description:
The Initial state is where each Device starts, before being enabled for service on the Aeris network. In this state, the Device is completely unknown to the AerAdmin, AerBill and Aer Frame systems. The Device cannot operate in the Aeris network, does not have Device Identifiers, cannot be billed for services, and cannot be reached through Aeris Network Services.
State Moves:
From the Initial state, a Device can move to:
- the Provision state, using an ProvisionRequest
- the Active Billed state, using an ActivateRequest
Provision State
State Description:
In the Provision state, the Device is capable of operating in the network and can transmit and receive data, but it is not expected to provide you with active service or revenue. The Device does have a Rate Plan assigned to it, but is not being actively billed by Aeris or generating revenue for you. However, you do incur transmission costs for services, using the assigned Rate Plan that is charged if it is used in the Aeris network prior to being activated (i.e. in the Active Billed state).
State Moves:
From the Provision state, a Device can move to:
- the Active Billed state, using a StartBillingRequest.
- the Active Billed state, automatically on certain parameters being exceeded.
- the Cancelled state, using a CancelRequest.
Move from Provision to Active Billed: Device in the Provision state may be automatically moved to the Active Billed state.
If the Device in the Provision state exceeds certain parameters (such as the number of MicroBurst or SMS packets transceived, or IP data bytes transmitted, or the Device has been in the Provision state for more than a number of billing periods), it is automatically moved to the Active Billed state by the AerBill system.
Essentially, in the Provision state, the Device is known to, and can operate in, the AerFrame systems, but is not yet in an Active Billed state.
Active Billed State
State Description:
In the Active Billed state, the Device is active and operating in the network as expected, delivering service and generating revenue.
State Moves:
From the Active Billed state, a Device can move to:
- the Suspended state, using an SuspendRequest.
- the Cancelled state, using an CancelRequest.
Active Billed Means Generating Revenue
This is the normal operational state for deployed Devices that are generating revenue for you and for Aeris.
The Active Billed Device has a Rate Plan assigned to it, and the AerBill system is generating detailed billing records from the data messages being transceived by the Device. At the end of each billing period, the AerBill system generates an invoice to you, using the pricing arrangements contracted under your Pricing Attachment.
Active Devices and Their Identifiers
You must record and maintain knowledge of the association between the ESN, MEID, and all Device Identifiers (IMSI, MDN, MIN, etc.) and information of active Devices.
This association is necessary to provide service to the Device and the Aeris Customer databases must be updated, as needed, when the information is changed.
Essentially, the Device is known to, and operating normally in, the Aeris network.
Suspended State
State Description:
In the Suspended state, the Device is capable of operating on the network and can transmit and receive data, but it is not expected to provide active service to, or generate revenue for, the Customer. The Device has a Rate Plan assigned to it (from its presence in the previous Active Billed state), but it is not being billed by Aeris or actively generating revenue. While in the Suspended state, the Device retains its Device Identifiers.
State Moves:
From the Suspended state, a Device can move to:
- the Active Billed state, using an UnsuspendRequest.
- the Active Billed state, automatically on certain parameters being exceeded.
- the Cancelled state, using an CancelRequest.
Automatic Move to Active Billed
A Device in the Suspended state may automatically be moved to the Active Billed state.
If the Device in the Suspended state transmits any data during a billing period, it is automatically moved back into the Active Billed state, and the Device bill is calculated for that entire billing period.
You can also move the Device from the Suspended state to the Active Billed state by using an UnsuspendRequest or cancel the Device (i.e., move to the Cancelled state) using an CancelRequest. While a Device is in a Suspended state, you may change the Rate Plan of the Device and also query/update the information associated with the Device. These operations do not place the Device back into the Active Billed state; you must explicitly use the Unsuspend operation for this purpose.
Single and BULK Device State Moves
In these state descriptions, a Device can be moved from one state to another using both the single Device operations (as shown in the sections on “State Moves” above) and the bulk Device operations that can operate on more than one Device at a time, for the same functionality as above. For example, ProvisionRequest and BulkProvisionRequest provide the single and bulk Device functionality. However, the responses from these Bulk operations may be different in their structure from the single Device operations, since more than one Device can be modified in the bulk operations.
Elements
The request and response messages use the elements listed in the following Table "Element Descriptions". References to these elements are made in the rest of this document.
The elements in the following table are listed alphabetically. Whether an element is Mandatory or Optional depends on the AerAdmin operation, which is described under “Request/Response Descriptions.”
Element Descriptions
Element and Type |
Description |
---|---|
<AccountID> “xsd:string” |
A unique value that identifies the Customer in the AerAdmin databases with an account. |
<ActivationDate> “xsd:string” |
The date on which a Device was first placed into the AerAdmin system (i.e., moved from the Initial state to the Provisioned or Active-Billed states). All dates in the AerAdmin system follow the formats specified in Aeris Standard Date and Time Format Specification. |
<ApplicationType> “xsd:string” |
The Customer must identify whether their Application is fixed or mobile. This element must be:
|
<AuthenticationKey> “xsd:string” |
The device Authentication Key that is programmed into the Module inside the Device. |
<AerisDeviceID> “xsd:string” |
Aeris device identification string. |
<CallbackURL> “xsd:string” |
Generic URL Type used by all the bulk asynchronous services and is used to return response data asynchronously. |
<CancelCode> “xsd:string” |
A Cancel Code is a special value used to specify the reason that a Device was cancelled. |
<CurrentLocation> “xsd:string” |
The Latitude, Longitude and Elevation of a Device. See section 4.3 “Current Location” for more information. |
<CustomField1> <CustomField2> <CustomField3> <CustomField4> <CustomField5> “xsd:string” |
These five fields are available for use by the Customer as general storage of information about the Device. See section 4.2 “Custom Fields” for more information on the maximum length of these elements. |
<Date> “xsd:dateTime” |
The generic date type, represents specific instance of time. |
<Description> “xsd:string” |
A more detailed description of the Cancel Code. |
<Device> “xsd:string” |
The name of the Device (or Modem) used by the Customer for this Application. |
<DeviceID> “xsd:string” |
The value of the Device Identification number. |
<DeviceIDList> “xsd:string” array |
An array containing one or more Device Identification numbers. |
<DeviceIDType> “xsd:string” |
Used only in responses to queries and updates, this is the actual Service Name where data transmissions from the Device are transmitted (i.e., to the Customer Host systems). The value may be different from the value specified in requests in <ServiceName>—that element value is used for these operations in the AerAdmin system. |
<DeviceServiceName> “xsd:string” |
Used only in responses to queries and updates, this is the actual ServiceName where data transmissions from the Device are transmitted (i.e., to the Customer Host systems). The value may be different from the value specified in requests in <ServiceName>—that element value is used for these operations in the AerAdmin system. |
<DeviceStatus> “xsd:string” |
The status of the Device. See section 4.11 “Device Status” for more information on the values returned in this element. |
<Email> “xsd:string” |
Email will be used to notify the bulk operation completion status along with the transactionId. |
<ESN> “xsd:string” |
The Electronic Serial Number of the Device. The ESN is permanently programmed into a Module by the Manufacturer of that Module. In new CDMA Devices, this is replaced by the Mobile Equipment IDentifier (“MEID”) in <MEID>, since the cellular industry has fully started using MEID due to ESN number exhaust. See section 4.6 “Device Identifiers” for more information. Important: Using an ESN in requests for a Device that has an MEID could result in errors—the effective “ESN” (called a Pseudo ESN or pESN) for this Device may not be unique. |
<ICCID> “xsd:string” |
The Integrated Circuit Chip IDentifier (“ICCID”). This is only used for any GSM Devices that may be reported in certain functions. |
<IMSI> “xsd:string” |
The International Mobile Subscriber Identity of the Device. The IMSI is programmed into the Module inside the Device. |
<MDN> “xsd:string” |
The Mobile Directory Number of a Device that is operational in the Aeris network. The Customer must program the MDN received from Aeris, into the Module inside the Device. In some Aeris Network Services, the MDN may be identical to the MIN (or MSID). Important: Customers must store both the MIN (or MSID) and the MDN as separate MDN as separate Device Identifiers, for separation of the MIN from the MDN, in their Device databases. |
<MEID> “xsd:string” |
The Mobile Equipment IDentification number of the Device. In CDMA Devices that contain an MEID, this must be used by the Customer instead of the pESN, to identify a specific radio Module. See section 4.6 “Device Identifiers” . |
<MIN> “xsd:string” |
The Mobile Identification Number associated with a Device that is operational in the Aeris network. The Customer must program the MIN received from Aeris into the Module inside the Device. In some Aeris Network Services, the MIN may be identical to the MDN. Note: The term MIN is now deprecated—the new term Mobile Station IDentifier (“MSID”) is the replacement term for MIN and serves the same purpose. The AerAdmin systems have not yet been updated for this new term, but will do so in a future release. Important: Customers must store both the MIN (or MSID) and the MDN as separate Device Identifiers, for separation of the MIN from the MDN, in their Device databases. |
<MSISDN> “xsd:string” |
Mobile station Integrated Services Digital Network Type. |
<NAI> “xsd:string” |
Master Subsidy Lock Code. |
<MSLCode> “xsd:string” |
Network Access Identifier String Type. |
<NewLogin> “xsd:string” |
The login associated with the new Service Name to which the Customer’s data is routed for that Device, after an ChangeServiceNameRequest is complete. The <NewLogin> is used in combination with the <NewPassword> and <NewServiceName> to validate the identity of the Customer client process. |
<NewPassword> “xsd:string” |
The password associated with the new Service Name to which the Customer’s data is routed for that Device, after an ChangeServiceNameRequest is complete. The <NewPassword> is used in combination with the <NewLogin> and <NewServiceName> to validate the identity of the Customer. |
<NewRatePlan> “xsd:string” |
The new Rate Plan to be assigned to a given Device. Once the effective date of the new Rate Plan (in <NewRatePlan-Date>) has passed, <NewRatePlan> is no longer returned, since the new Rate Plan becomes current and is then returned in <RatePlan>. The <NewRatePlan> value is one of the Rate Plans listed on the Customer’s Pricing Attachment and loaded in the AerBill system. |
<NewRatePlanDate> “xsd:dateTime” |
The date on which a new Rate Plan will take effect (i.e., the first day of the billing period following the request for a new Rate Plan). Once the date has passed, this element is not returned if a Rate Plan change is not pending. All dates in the AerAdmin system follow the formats specified in Aeris Standard Date and Time Format Specification. |
<NewPoolName> “xsd:string” |
The new Pool Name that will be assigned to a given Device. The new Pool Name will become effective as of <NewPoolNameDate>. Once the effective date has passed, this element is not returned. The <NewPoolName> value is one of the Data Plan Pools listed on the Customer’s Pricing Attachment and loaded in the AerBill system. |
<NewPoolNameDate> “xsd:dateTime” |
The date on which a new Pool Name will become effective (i.e., the first day of the billing period following the request for a new Pool Name). Once the date has passed, this element is not returned unless a Pool Name change is pending. All dates in the AerAdmin system follow the formats specified in Aeris Standard Date and Time Format Specification. |
<NewServiceName> “xsd:string” |
The new logical connection name where the Customer’s data is routed by the Aeris Network Services, after an ChangeServiceNameRequest is completed. The <NewServiceName> is used in combination with the <NewLogin> and <NewPassword> to validate the identity of the Customer,and also in the response ChangeServiceNameResponse. After the <NewServiceName> is received in an ChangeServiceNameResponse, this value must then be used in all subsequent <ServiceName> elements for messages for that Device. |
<OTKSLC> “xsd:string” |
One Time Keypad Subisidy Lock Code Type. |
<RatePlan> “xsd:string” |
The current Rate Plan associated with the Device. A RatePlan has a name and a list of pool names it may be associated with. The <RatePlan> value is one of the Rate Plans listed on the Customer’s Pricing Attachment and loaded in the AerBill system. |
<PoolName> “xsd:string” |
The current Pool Name associated with the Device. The <PoolName> value is one of the Pool Names listed on the Customer’s Pricing Attachment and loaded in the AerBill system. |
<ReportGroup> “xsd:unsignedInt” |
The Report Group associated with a Device. This is a Device grouping within an account (specified by <AccountID>) for the purpose of creating summary reports (such as billing summaries). |
<ResultCode> “xsd:int” |
A numerical success/error code, returned by the AerAdmin system. The list of possible result codes is provided in the document AerAdmin Return Codes Specification. If the response contains an array of results, then <ResultCode> contains the overall success/error code—each individual operation is instead contained in <IndCode>. |
<ResultMessage> “xsd:string” |
A more detailed explanation of the success/error reason, returned by the AerAdmin system. The list of possible result messages is provided in the document AerAdmin Return Codes Specification. If the response contains an array of results, then <ResultMessage> contains the overall success/error code—each individual operation is instead contained in <IndMessage>. |
<ServiceName> “xsd:string” |
The logical connection name to where the Customer’s messaging data is routed by the Aeris Network Services. |
<SoftwareVersion> “xsd:string” |
The software version for the AerAdmin system code.The format is “w.x.y.z”(although not every number may be present). |
<StaticIP> “xsd:string” |
A private Static IP address assigned to the Device. Important:
Private Static IP addresses are only provided to Customers who have made prior arrangements with Aeris for this purpose. |
<Technology> “xsd:string” |
For some operations, the technology of choice must be specified. This is set as either “CDMA” or “GSM”. |
<TransactionID> “xsd:string” |
Unique transaction id which is returned in Device State change Service operation responses. This transaction id can be used for further references for the state change operation done for the devices. |
<TrafficTypeEnum> <restriction> <enumeration value="Packet" <enumeration value="SMS" <enumeration value="Voice" <enumeration value="All" </restriction> |
Traffic Type ENUM supports following valid values: "Packet", "SMS", "Voice" or "All". |
<blockTraffic> <xsd:TrafficTypeEnum> </blockTraffic> |
0 to 3 repetitions of Traffic Type ENUM supported. |
<unblockTraffic> <xsd:TrafficTypeEnum> </unblockTraffic> |
0 to 3 repetitions of Traffic Type ENUM supported. |
<"TrafficPolicyEnum"> <restriction base="xsd:string"> <maxLength value="7"/> <enumeration value="BLOCK"/> <enumeration value="UNBLOCK"/> </restriction> |
TrafficPolicyEnum supports two valid values: BLOCK and UNBLOCK. |
<SCLID> xsd:string |
Generic Device Identifier with max length 40. It is used when one wants to provision a generic (Aercloud) devices. |
<"cancelCode"> <restriction base="xsd:int"> <totalDigits value="9"/> </restriction> </Code> |
CancelCode is an integer field with different cancel reasons. |
Custom Fields
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.
Field Length > 64 bytes is Truncated
Each of these fields can be up to 64 bytes in length. If the string value sent in these elements is longer than 64 bytes, it is truncated to 64 bytes without notice or warning.
Current Location
Fixed Applications
When troubleshooting Devices, it is often important to know the exact physical location of the unit particularly for Devices that may not have Global Positioning System (“GPS”) capability, or other location determination mechanisms.
Record Current Location
Recording the Current Location information for Fixed Devices is strongly recommended.
For Fixed Applications you should provide (or update the AerAdmin servers after actual installation is complete) the physical location of the Device in <CurrentLocation>. This enables Aeris to assist you in troubleshooting problems with the Device at the specific location where the Device is installed.
Mobile Applications
For Mobile Applications you should provide the physical location where the installation was completed, or the physical location of the end-user address (clearly, the Device may move, and this initial location information in the AerAdmin system for mobile Devices can become inaccurate fairly quickly). As an alternative, it is recommended that you provide the physical location of your, or your end-user’s, office address, in this field. For Mobile Applications, you may also choose to leave this field empty.
Current Location Format
The <CurrentLocation> must be formatted as a 25-byte ASCII string: “HtT1T2.T3T4T5T6T7HnN1N2N3.N4N5N6N7N8SzZ1Z2Z3Z4Z5” where: HtT1 – T7 : Latitude of the Current Location. This is transmitted in ASCII, in decimal notation, using the format ±T1T2.T3T4T5T6T7 (including the byte containing the period ‘.’ between T2 and T3). Byte Ht represents the hemisphere (‘+’ for North or ‘-’ for South) of the latitude. HnN1 – N8 : Longitude of the Current Location. This is transmitted in ASCII, in decimal notation using the format ±N1N2N3.N4N5N6N7N8 (including the byte containing the period ‘.’ between N3 and N4). Byte Hn represents the hemisphere (‘-’ for West or ‘+’ for East) of the longitude. HnN1 – N8 : SzZ1 – Z5 : Sign and elevation of the Current Location in meters. This is transmitted in ASCII, in decimal notation using the format Z1Z2Z3Z4Z5. There is no decimal period since the resolution of the format is 1 meter i.e., the elevation is Z1Z2Z3Z4Z5 meters. Byte Sz represents whether the location height is above (‘+’) or below (‘-’) sea level. For example, Aeris’ offices are located at 37° 22’ 15.55” N, 121° 55’ 31.28” W, at an elevation of 31 meters above sea level. This is a physical location of +37.370986, -121.925356 in decimal notation5 and an elevation of +00031.
Technology
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:
Technology |
Meaning |
---|---|
CDMA |
The Device uses a Code Division Multiple Access ("CDMA") Module. |
GSM |
The Device uses a Global System for Mobile ("GSM") Module. |
Generic |
The Device should use this for dealing with AerCloud-only device Operations. |
Table 4: Technology Values
Device Identifier Type
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.
The type of identifiers allowed in depends on the specific request.
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.
Identifier |
Identifier Type |
---|---|
ESN |
The Electronic Serial Number (“ESN”) of the Module inside the Device. |
IMSI |
The International Mobile Subscriber Identity (“IMSI”) set in the Module inside the Device. |
MDN |
The Mobile Directory Number (“MDN”) of the Device in the cellular network—this is also used within the Module and Device. |
MEID |
The Mobile Equipment IDentifier (“MEID”) of the Module inside the Device. |
MIN |
The Mobile Identification Number (“MIN”) set in the Module inside the Device. |
Table 5: Device Identifier Type Values
Device Identifiers
In the requests, the formats allow one of several possible values to specify the Device or Devices.
Single device requests: For single Device requests one, and only one, of the values must be provided to ensure that the correct Device is specified.
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>.
‘Cancel’ changes some identifiers: After a Device is cancelled, it cannot be accessed in the AerAdmin system by its pre-cancellation MIN, MDN or IMSI after a retention period has elapsed.
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.
Your responsibilities regarding a cancelled device: It is your explicit responsibility to ensure that cancelled Devices do not power up on the Aeris network with old Device Identifier values still intact within the Radio Modules contained inside the 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.
USE OF PSEUDO-ESN (“PESN”) IN <ESN> IS NOT ALLOWED
A radio that uses an MEID does not contain a True ESN (“tESN”). Rather, the radio calculates (using a hashing algorithm) a Pseudo ESN (“pESN”) from the MEID for use with network elements and transmissions formats that need an “ESN” in any field. Since the pESN is a 32 bit number calculated from a 56 bit MEID, it is quite possible to get pESN “collisions” where more than one Device, with different MEID values, can have the same pESN. The 8-bit Manufacturer field of a pESN is always 0x80 (decimal 128).
Radio module that use MEID: For Devices with Radio Modules that use MEID, you must use the <MEID>.
Request Date and Time
COORDINATED UNIVERSAL TIME (UTC)
The AerAdmin system performs requests as received from your client process. Depending on the request, the time of execution is reported in <UTCTime>. These times are always specified as an absolute time in UTC, without any compensation for local time adjustments (such as Daylight Savings Time, etc.).
- Timestamps reflect UTC: The dates of all requests and responses are referenced to UTC.
- UTC not equal to GPS time: UTC is not the same as Global Positioning System (“GPS”) Time.
EFFECTIVE DATES AND TIMES FOR REQUESTS
Request time granularity: If the granularity of a particular request result is 1 day, the execution of that request effectively occurs at 00:00:00Z (i.e. the start of the day in UTC) on that date.
For example, a Device cancellation sent at 12:00:00Z on a particular day is recorded as occurring at 00:00:00Z that same day, at an effective earlier time. This allows you to receive the appropriate reduced proration for that billing period.
However, during the billing calculations at the end of the billing period, traffic sent earlier than 12:00:00Z, on that same day (for example, at 09:00:00Z), may cause the Device to be automatically re-activated if the transmission exceeds contracted data thresholds, even though the Device cancellation request was actually sent after the traffic transmission time. You must understand this effective date and time granularity and the potential effect on monthly bills accordingly, and/or ensure that the cancellation occurs on a day when no traffic has occurred.
Request Identification
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.
Request ID storage: The value in <RequestID> is never stored in the AerAdmin system. If provided in a request, it is simply copied to (i.e., “reflected” in) the response for the request in which it is sent. It is never stored in the AerAdmin system. The AerAdmin system does not check for uniqueness or validity in the Request Identification value. It is always your responsibility to assure uniqueness as required.
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.
<RequestID> is recommended: Use of <RequestID> is strongly recommended, to correlate requests and responses.
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.
Maximum ID length: The length of the Request Identifier should be limited to a maximum of 60 characters. Although longer lengths can be sent, this is not recommended as it may hurt throughput and performance unnecessarily.
Service Name
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>.
Incorrect Service Name: If you provide an incorrect Service Name, the request fails with an error message. Please see the “Device Service Name” section for additional information.
Device Service Name
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.
Device Status
The status of the Device is returned in <DeviceStatus> in responses to certain requests. This following table lists current return values:
Value |
Description |
---|---|
Billed |
The Device is in the Active-Billed state, and is operational on the Aeris network. It is being billed for network services. |
Cancelled |
The Device is in the Cancelled state, and is not operational on the Aeris network, although it has an activation/cancellation history and its status can be queried. It is not being billed for network services. |
Provisioned |
The Device is in the Provisioned state. In this state, the Device is capable of operating on the network and transceive data. It is not being billed for network services however, if it transceives data, it may be automatically moved to the Active-Billed state. |
Suspended |
The Device is in the Suspended state. In this state, the Device is capable of operating on the network and transceive data. It is not being billed for network services however, if it transceives data, it may be automatically moved to the Active-Billed state. |
Unknown |
The Device is entirely unknown to the AerAdmin system (it may be in the Initial state). This is not likely to be returned to an AerAdmin request for a valid Device, and Customers must contact Aeris Customer Support for assistance. |
Table 6: Device Status Return Values
Radio and Device
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 Names
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.
Report Groups
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.
Report Group usage: The Report Group to which a Device belongs is only used at the end of the billing period and when generating reports from the AerTraffic system (note: the AerTraffic system is different from the AerAdmin system described here).
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.
Report Records limit: The AerTraffic system has a 10,000 record limit on reports.
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.
Report Group Scope: A Report Group can only be used for summaries within each Account.
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).
Private Static IP Addresses
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 or Static IP?: Aeris strongly recommends using Dynamic IP addresses.
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.
Aeris SKU Radio Modules
Aeris SKU Radio Modules: If the Radio is an Aeris SKU Radio Module, the Profile parameter values are not returned.
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.
AerAdmin Operations
The AerAdmin system enables your client processes to use various operations to manage your Devices.
AerAdmin Single and Bulk Operations
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:
Operation |
Bulk Operation |
Description |
---|---|---|
ChangeRatePlan |
BulkChangeRatePlan |
Change the current Rate Plan and Pool Name for Device/Devices. |
ChangeServiceName |
BulkChangeServiceName |
Change the Service Name associated with a number of Devices. |
ClearDeviceRegistration |
NA |
ClearDeviceRegistration is used to cancel (i.e. clear) the Device's "network location" in the event that the Device cannot find itself in the network.This operation is currenty supported only for GSM devices. |
UpdateDeviceAttr |
BulkUpdateDeviceAttr |
Update the information on a Device/Devices in the AerAdmin system. |
Table 7: Operations for single and bulk devices - Device Attribute Services
State Change Services
Operation |
Bulk Operation |
Description |
---|---|---|
Activate |
BulkActivate |
Activate a number of Initial or Cancelled state Device/Devices and begin billing for those Device/Devices. |
Cancel |
BulkCancel |
Cancel a Device/Devices currently in an Active-Billed, Provisioned or Suspended state. |
Provision |
BulkProvision |
Provision a device or number of Devices, that are in Initial or Cancelled state, in the AerAdmin system. |
Reprovision |
BulkReprovision |
Reprovision a device or number of Devices after they were cancelled (move from Cancelled state to Provisioned state). |
StartBilling |
BulkStartBilling |
Start billing for a Device/Devices (move from Provisioned state to Active-Billed state). |
Suspend |
BulkSuspend |
Suspend a device or a number of active Devices (move from the Active-Billed state to the Suspended state). |
Unsuspend |
BulkUnsuspend |
Unsuspend a device or a number of suspended Devices (move from Suspended state to Active-Billed state). |
SwapSubscription |
NA |
This allows user to move the subscription from one device to another. The operation is currently supported only for GSM devices. |
TrafficPolicy |
BulkTrafficPolicy |
This allows user to block or unblock specific traffic type(s) for a Device(s). |
Table 8: Operations for single and bulk devices - State Change Services
Monitoring Services
Operation |
Bulk Operation |
Description |
---|---|---|
NA |
GetBulkServiceStatus |
Gets the bulk service status of a number of devices. Returns whether device change requests are processed successfully, processed successfully but not acknowledged, still being processed, failed services and failed but not acknowledged. |
HeartBeat |
NA |
Check that the AerAdmin API service is online. |
Table 9: Operations for single and bulk devices - Monitoring Services
Device Query Services
Operation |
Bulk Operation |
Description |
---|---|---|
GetAvailableDeviceNumbers |
NA |
Retrieves the available device numbers. This operation is currenty supported only for CDMA devices. |
GetDeviceLocation |
NA |
Retrieves the current location of the device. |
GetDeviceDetail |
NA |
Retrieves the device details like activation date, service name, device status, etc. |
GetDeviceNetworkStatus |
NA |
Retrieves the devices network status. |
GetRatePlan |
NA |
Retrieve the list of Rate Plans along with associated Pool Names contractually available for the Customer. |
GetServiceName |
NA |
Retrieve the list of Service Names assigned to the Customer. |
Table 10: Operations for single and bulk devices - Device Query Services
Request/Response Descriptions
This section describes the operations and the elements used in the requests and responses.
Complete documentation on request response elements can be viewed at AAA50-XSD_Documentation.
Request Response Objects
The following tables describe the Request, Response objects for all the operations currently supported by AerAdmin.
Device Attribute Services
Operation |
Request Object |
Response Object |
---|---|---|
AssignStaticIP |
AssignStaticIPRequest |
AssignStaticIPResponse |
BulkAssignStaticIP |
BulkAssignStaticIPRequest |
BulkAssignStaticIPResponse |
ChangeRatePlan |
ChangeRatePlanRequest |
ChangeRatePlanResponse |
BulkChangeRatePlan |
BulkChangeRatePlanRequest |
BulkChangeRatePlanResponse |
ChangeServiceName |
ChangeServiceNameRequest |
ChangeServiceNameResponse |
BulkChangeServiceName |
BulkChangeServiceNameRequest |
BulkChangeServiceNameResponse |
ClearDeviceRegistration |
ClearDeviceRegistrationRequest |
ClearDeviceRegistrationResponse |
RemoveStaticIP |
RemoveStaticIPRequest |
RemoveStaticIPResponse |
BulkRemoveStaticIP |
BulkRemoveStaticIPRequest |
BulkRemoveStaticIPResponse |
UpdateDeviceAttr |
UpdateDeviceAttrRequest |
UpdateDeviceAttrResponse |
BulkUpdateDeviceAttr |
BulkUpdateDeviceAttrRequest |
BulkUpdateDeviceAttrResponse |
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
Operation |
Request Object |
Response Object |
---|---|---|
Activate |
ActivateRequest |
ActivateResponse |
BulkActivate |
BulkActivateRequest |
BulkActivateResponse |
Cancel |
CancelRequest |
CancelResponse |
BulkCancel |
BulkCancelRequest |
BulkCancelResponse |
Provision |
ProvisionRequest |
ProvisionResponse |
BulkProvision |
BulkProvisionRequest |
BulkProvisionResponse |
Reprovision |
ReprovisionRequest |
ReprovisionResponse |
BulkReprovision |
BulkReprovisionRequest |
BulkReprovisionResponse |
StartBilling |
StartBillingRequest |
StartBillingResponse |
BulkStartBilling |
BulkStartBillingRequest |
BulkStartBillingResponse |
Suspend |
SuspendRequest |
SuspendResponse |
BulkSuspend |
BulkSuspendRequest |
BulkSuspendResponse |
Unsuspend |
UnsuspendRequest |
UnsuspendResponse |
BulkUnsuspend |
BulkUnsuspendRequest |
BulkUnsuspendResponse |
SwapSubscription |
SwapSubscriptionRequest |
SwapSubscriptionResponse |
TrafficPolicy |
TrafficPolicyRequest |
TrafficPolicyResponse |
BulkTrafficPolicy |
BulkTrafficPolicyRequest |
BulkTrafficPolicyResponse |
Table 12: Request, Response objects for State Change Services
Learn more about State Change Services request response elements or the Device State Service XSD.
Operation |
Request Object |
Response Object |
---|---|---|
GetBulkServiceStatus |
GetBulkServiceStatusRequest |
GetBulkServiceStatusResponse |
HeartBeat |
HeartBeatRequest |
HeartBeatResponse |
Table 13: Request, Response objects for Monitoring Services
Learn more about Monitoring Services request response elements or the Device Monitor Service XSD.
Query Services
Operation |
Request Object |
Response Object |
---|---|---|
GetAvailableDeviceNumbers |
GetAvailableDeviceNumbersRequest |
GetAvailableDeviceNumbersResponse |
GetDeviceLocation |
GetDeviceLocationRequest |
GetDeviceLocationResponse |
GetDeviceDetail |
GetDeviceDetailRequest |
GetDeviceDetailResponse |
GetDeviceNetworkStatus |
GetDeviceNetworkStatusRequest |
GetDeviceNetworkStatusResponse |
GetRatePlan |
GetRatePlanRequest |
GetRatePlanResponse |
GetServiceName |
GetServiceNameRequest |
GetServiceNameResponse |
Table 14: Request, Response objects for Query Services
Learn more about Query Services request response elements or the Device Query Service XSD.
Return Codes Details
Result Code |
Result Message |
---|---|
0 |
Success |
613 - 630 |
Aeris Reserved |
1000 |
Invalid device ID |
1001 |
Missing required field |
1002 |
Invalid service name/login/password value |
1003 |
Invalid date |
1004 |
Invalid application ID |
1005 |
Invalid application type value |
1006 |
Invalid primary MIN |
1007 |
Primary MIN does not belong to the account ID submitted |
1008 |
Primary MIN and ESN does not to the account ID submitted |
1009 |
Device not provisioned/cancelled |
1010 |
Device already activated |
1011 |
Primary MIN is already provisioned with another ESN |
1012 |
Incorrect ESN |
1013 |
Incorrect IMSI |
1014 |
IMSI does not belong to the account id generated in the request |
1015 |
Invalid radio and or firmware value |
1016 |
Radio/firmware/application type value does not match the value stored in aeradmin db |
1017 |
Duplicate shared secondary MIN(s) |
1018 |
Duplicate unique secondary MIN(s) |
1019 |
Invalid secondary MIN(s) |
1020 |
Secondary MIN(s) does not belong the account ID submitted |
1021 |
Mismatched shared secondary MIN(s) |
1022 |
Mismatched unique secondary MIN(s) |
1023 |
Missing shared secondary MIN(s) |
1024 |
Missing unique secondary MIN(s) |
1025 |
Secondary MIN(s) are not allowed |
1026 |
Too many secondary MIN(s). A maximum of 9 secondary MIN(s) are allowed |
1027 |
Invalid rate plan |
1028 |
Missing rate plan |
1029 |
The request results in no change for the device |
1030 |
Unable to generate authentication key |
1031 |
Unable to generate IMSI |
1032 |
Unable to generate primary MIN |
1033 |
The credit period for the pre-paid device has expired |
1034 |
AerAdmin internal error |
1035 |
Error while provisioning device |
1036 - 1039 |
Aeris Reserved |
1040 |
Database connection problem |
1041 |
Error in the carrier system |
1042 |
Invalid current location format |
1043 |
Missing current location |
1044 |
Invalid radio technology |
1045 |
Invalid ICCID |
1046 |
Device already Activated |
1047 |
Device not Activated |
1048 |
Invalid MSISDN |
1049 |
Device Not Found (Not activated/Cancelled/Not owner) |
1050 |
General device activation error |
1051 |
General Device Deactivation Error |
1052 |
General Device Rate Plan Change Error |
1053 |
General device query error |
1054 |
General device update error |
1055 |
General service name change error |
1056 |
General start billing error |
1057 |
General reprovision error |
1058 |
Start billing error - no rate plan |
1059 |
Suspend device billing error |
1060 |
Radio is not voice capable |
1061 |
Activate error - no rate plan |
1062 |
Device does not have AKEY SSD (Shared Secret Data) information |
1063 |
Retrieve device AKEY SSD (Shared Secret Data) error |
1064 |
Unable to generate SSD (Shared Secret Data) |
1065 - 1071 |
Aeris Reserved |
1072 |
Invalid device ID format |
1073 |
Invalid device ID type |
1074 |
Pseudo ESN is not a valid device type, please use MEID |
1075 |
Device is not authorized for packet data |
1076 |
Device AKEY and SSD (Shared Secret Data) already exist |
1077 |
Invalid MEID |
1078 - 1087 |
Aeris Reserved |
1088 |
MIN not available |
1089 |
Cannot change device state |
1090 |
Cannot assign static IP to device |
1091 |
Device not authorized to receive a static IP address |
1092 |
IP address already assigned |
1093 |
Private IP address not available |
1094 |
Static IP address not available |
1096 |
Invalid start date |
1097 |
Invalid end date |
1098 |
Device ID not provided |
1099 |
Aeris Reserved |
1100 |
Device not provisioned for 1XRTT capability |
1101 |
Invalid device ID type |
1102 |
Invalid technology type |
1103 |
NGP not available |
1104 |
Static IP request error |
1105 |
Device Reprovision Error |
1106 |
Re-Provision Carrier Error |
1107 |
Device Suspend Error |
1109 |
Invalid Report Group |
1110 |
Multiple Services Device |
1111 |
EDF not in Sprint |
1112 |
Invalid Carrier |
1131 |
Only Cancel Code ID can be updated |
1132 |
Cannot update Cancel Code ID |
1133 |
Unknown Cancel Code ID |
1134 |
Device in Pending Mode |
1135 |
DeviceIDList too long |
1136 |
Mandatory input field missing |
1137 |
Incorrect number of Devices |
1138 |
Must have a non-null value |
1139 |
No StaticIP to be removed |
1140 |
General Remove StaticIP error |
1141 |
Error while validating xml. Please verify if the request is valid or contact the administrator. |
1142 |
XML Validation Error |
1143 |
Transformation Exceptions |
1144 |
Unable to fetch API key |
1145 |
Async Handling Error |
1146 |
Invalid Operation |
1147 |
Unable to service your request. Fatal error while processing your request |
1148 |
Requested Operation Not Supported |
1149 |
AerAdmin Internal Error |
1150 |
Invalid TransactionID |
1151 |
Database connection problem! Error saving request. Try again. |
1152 |
Carrier system access error |
1153 |
Invalid current location format |
1154 |
Missing current location |
1155 |
AerTraffic report records exceed maximun size |
1156 |
Too many sessions - Try again later |
1157 |
Exceeds maximum in record count |
1158 |
Exceeds maximum out record count |
1159 |
Invalid operation - service not allowed |
2000 |
Device Provision Error |
2001 |
Device Reprovision Error |
2002 |
Device Cancel Error |
2003 |
Device Change Rate Plan Error |
2004 |
Device Suspend Error |
2005 |
Device Unsuspend Error |
2006 |
Device Clear Device Registration Error |
* Partner ResultMessages may contain additional details |
0 Comments