Inspection Report Management
Inspection Report Management Web Services
The methods and objects described in this section are related to report management.
The WSDL for the inspection report management web service are available by URLs:
https://vir.omnitracs.com/dvirws/UpdateMaintenancePkgForVIR.wsdl (Recommended)
Note: For all new development we recommend using the Omnitracs URL.
There is a single Web Service Method that is provided to allow integrations the ability to manage the inspection reports.
The UpdateVIR method allows the integration to set the report Status, Vendor, Resolution or FixNotes fields.
Overview
As drivers perform vehicle inspection reports on their trucks or trailers, they are routed to the VIR Host Application. What happens then depends on if there is a defect reported in the inspection or not. If there is no defect, the inspection report is closed and no further action is required. If the report has at least one defect reported, the defect is left in the OPEN state, and a T.7.01.0 ESS Transaction is published.
This transaction contains all the information about the defects reported.
When the defects are resolved, or the report is ready to be updated or closed, then the user will call the VIR Host Web Service to update the report. During the update, the report may be simply updated and left in a PENDING state, or it may be closed. Closing a report with a defect will cause a Message to be sent to the mobile unit in the truck which created the inspection report, passing the defect's disposition back to the driver.
The process of sending a message back to the mobile unit will generate additional ESS Transactions. Transaction Type T.7.02.0 will be published when the message is submitted to the network, and Transaction Type T.7.03.0 will be published when the mobile unit receives the message. Completion Codes within these transactions indicate the success or failure of each one. These are documented below.
When the Inspection Report is closed a forward message is sent to the mobile. There will be 2 additional ESS transactions published when this occurs.
T.7.02.0 - Message Sent Confirmation
This event is published when the messaging system accepts the forward message.
See T.7.02.0 for reference and example of format.
The <key> element holds the inspection report ID as reported in T.7.01.0 and used in the web service call to UpdateVIR.
T.7.02.0 Valid Completion Codes
Status values that can occur in response to a send request include the following:
0 - Success / OK
1 - Unknown/Other Error
2 - NMC Internal Error
3 - XML Syntax Error
4 - Missing or Bad XML Element
5 - Reached NMC Limit
6 - Invalid element value / validation failure
Status of 0 indicates that the message was handled properly and forwarded off to the mobile unit.
T.7.02.0 Recommendations based on Completion Code
Status = 1 - retry the message up to 3 times with the retry interval set to be at least 1X of the max ESS polling interval.
Status = 2, 5 - notify technical support.
Status = 3, 4 and 6 should never be encountered during standard production operation as this layer of messaging handling is provided by the VIR Host application. If they are encountered, notify technical support. Provide the completionDetails value if it is available.
T.7.03.0 - Message Received Confirmation
This event is published up the mobile acknowledging that it has received the forward message.
See T.7.03.0for reference and example of format.
The <key> element holds the inspection report ID as reported in T.7.01.0 and T.7.02.0 and used in the web service call to UpdateVIR.
T.7.03.0 Completion Codes
Status values that can occur in response to a send request include the following:
0 - Message status not available
1 - Message Queued
2 - Message Sent OTA, not acknowledged yet
3 - Message Acknowledged
4 - Message Sent, reached max transmission count
5 - Message Sent, not acknowledged yet
6 - Message NACKed (negative ack)
7 - Service Unavailable
8 - Message Canceled
9 - Message Rejected by gateway
10 - Message Not Found
11 - Message Completed
12 - Message Transport ACKed
Completion Code of 3 indicates mobile unit received and processed the message successfully.
T.7.03.0 Recommendations based on Completion Code
Status = 0, 1, 2, 5, 10, 11 - These scenarios should not occur. They should be recorded for diagnostic purposes, but no further action is required. Retry may or may not work. If scenario persists, contact technical support.
Status = 4 - This is a valid timeout scenario. In this case, the message could not be delivered to the mobile device. The most likely scenario is that the mobile unit is off or communication to the mobile unit is not available. The message should be retried. (Timeout is 35 minutes.)
Status = 6, 7, 8, 9, 12 - These scenarios should not occur. They should be recorded. Retry the message up to 3 times with the retry interval set to be at least 1X of the ESS polling interval. If scenario persists, contact technical support.
Errors and Success Messages
The MMS Web Services responses will include detail information of any errors or warning. Errors in which case no processing can occur will be immediately sent to the client as SoapFault. In case of other errors the web service methods will send collection of errors and/or warnings . These are covered for each method on the method's name link.