Create Delivery
createDelivery
Creates a new delivery for a list of vehicles identified by id and or list of MMS group names.
Upon successful creation the method returns the delivery Id of the newly created delivery in the response.
In case of failure a delivery Id of "-1" and a list of errors are returned to the client.
In case of where one or more vehicles or groups cannot be validated, the delivery will be created using only the valid vehicles and groups, which will include the vehicles and/or groups that did not validate.
If the sendImmediate is true, the delivery is sent and individual vehicles will report status of the delivery via T.8.01.0 ESS transactions.
CreateDeliveryResponse createDelivery(CreateDeliveryRequest request)
Elements of CreateDeliveryRequest:
- fileName: The name of the file uploaded into the system. Required for creating a new delivery.
- vehicleIds: Zero or more vehicles to send the file to. At least one vehicleId or groupName is required.
- groupNames: Zero or more groups to send the file to. At least one vehicleId or groupName is required.
- sender: who is sending the file. Required.
- subject: The subject of the delivery. Required.
- deliveryOption: One of WIFI, TERR or SCHEDULE
- WIFI: Delivery will only be delivered when WiFi is available
- TERR: Delivery will be delivered by any means possible.
- SCHEDULE: Delivery will be delivered according to a schedule. Try Wifi for some interval, then deliver via any means possible.
- deliverySchedule: The period of time to wait before trying to deliver via terrestrial. Required when deliveryOption = SCHEDULE
- interval: The number of units to wait.
- units: Which units to specify the interval. One of: MINUTES, HOURS, DAYS
- expireDateTime: If specified, when the file should be removed from the vehicles.
- availableDateTime: If specified, when the file should be visible to the end user. The file is still sent immediately, it will not be visible until the specified time. If not specified, the file will be available as soon as it is delivered.
- description: An option description of the delivery.
- sendImmediately: If set to true, the delivery is initiated immediately. If not, the client must call sendDelivery in order for the delivery to be initiated.
Sample XML Request
Only the SOAP body is shown. To see a sample SOAP Envelope and Header, click here.
<SOAP-ENV:Body> <ns2:createDeliveryRequest xmlns:ns2="http://www.qualcomm.com/mms"> <ns2:fileName>testcontent.wmv</ns2:fileName> <ns2:vehicleIds>Vehicle0001</ns2:vehicleIds> <ns2:sender>test sender</ns2:sender> <ns2:subject>test banner</ns2:subject> <ns2:deliveryOption>WIFI</ns2:deliveryOption> <ns2:expireDateTime>2011-09-30T21:11:23.105Z</ns2:expireDateTime> <ns2:availableDateTime>2011-09-29T21:11:23.099Z</ns2:availableDateTime> <ns2:description>test descr</ns2:description> <ns2:sendImmediately>false</ns2:sendImmediately> </ns2:createDeliveryRequest> </SOAP-ENV:Body>
Sample XML Response
The response will contain information about the delivery.
Success Response
<SOAP-ENV:Body> <ns2:createDeliveryResponse xmlns:ns2="http://www.qualcomm.com/mms"> <ns2:deliveryId>1981</ns2:deliveryId> <ns2:deliveryStatuses> <ns2:statusType>SUCCESS</ns2:statusType> <ns2:code>mms.ws.createdelivery.success</ns2:code> <ns2:reason/> </ns2:deliveryStatuses> </ns2:createDeliveryResponse> </SOAP-ENV:Body>
Sample Failed Response
<SOAP-ENV:Body> <ns1:createDeliveryResponse> <ns1:deliveryId>-1</ns1:deliveryId> <ns1:deliveryStatuses> <ns1:statusType>ERROR</ns1:statusType> <ns1:code>error.reason.request.sender.length</ns1:code> <ns1:reason>Sender allowed characters limit of 80</ns1:reason> </ns1:deliveryStatuses> <ns1:deliveryStatuses> <ns1:statusType>ERROR</ns1:statusType> <ns1:code>error.reason.request.vehicles.groups.bothempty</ns1:code> <ns1:reason>Both vehicleIds and group names cannot be empty</ns1:reason> </ns1:deliveryStatuses> </ns1:createDeliveryResponse> </SOAP-ENV:Body>
Sample Exception Response
<SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring xml:lang="en">mms.ws.error.fatal - Invalid Create Delivery Request</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body>
Error and Warning Messages
The following one or more error/warning messages will be sent in "DeliveryStatuses" element in the response body.
These are in additions to the common error messages described in main page.
Error Code |
Description |
Remarks |
---|---|---|
error.reason.request.nofile |
No file was provided in this delivery request |
The fileName is required for createDelivery. |
error.reason.request.file.invalid |
No valid file is sent in this delivery request |
The provided fileName was not found. |
error.reason.request.description.length |
Description exceeds allowed characters limit of 255 |
|
error.reason.request.sender.null |
Sender is required. |
|
error.reason.request.sender.length |
Sender exceeds allowed characters limit of 80 |
|
error.reason.request.banner.null |
Subject cannot be null |
|
error.reason.request.banner.length |
Subject exceeds allowed characters limit of 64 |
|
error.reason.request.vehicles.groups.bothempty |
Both vehicle IDs and group names are empty |
You must provide at least one vehicle or group. |
error.reason.request.expiration.time.inpast |
Expiration Time cannot be in the past. |
|
error.reason.request.expiration.time.error |
Expiration Time cannot be before Available Time. |
|
warning.reason.groupnames.nomatchfound |
These group names were not found: <comma delimited un-matched group names> |
Success with warning: The groups that were found are associated in delivery. |
warning.reason.groupname.empty |
This group contains no vehicles. It will not be added to the delivery. |
|
warning.reason.devices.nomatchfound |
These vehicles were not found: <comma delimited un-matched vehicle ids.> |
Success with warning: The vehicles that were found are associated in delivery. |
error.reason.novaliddevicesorgroupsfound |
No valid groups or devices found. |
Must have at least on valid group or vehicle. A valid group must exist and have at least one vehicle in it. |
error.reason.request.deliveryoption.noschedule |
No schedule provided for 'SCHEDULE' Delivery Option. |
Client to provide Schedule ( interval and Unit) for this delivery option. |
error.reason.request.unit.interval |
Missing or invalid units or interval. Both unit and interval values are required for 'SCHEDULE' type Delivery Option. |
|
error.reason.request.unit.invalid |
Invalid delivery Unit option. Should be MINUTES, HOURS or DAYS. |
|
error.reason.request.deliveryinterval.invalid |
Delivery Interval cannot be less than 15 minutes. |
|
error.reason.request.deliveryoption.invalid |
Invalid Delivery option. Valid options are WIFI, TERR or SCHEDULE |
|