Post Assignment Results Web Service
VoiceCheck consumes a web service exposed by the host system in order to post results—essentially a data export. For a given assignment, this message can be sent multiple times. It is sent each time a user submits results through the VoiceCheck graphical user interface (GUI).
In order to use this export functionality, the host system must implement a REST or SOAP web service according to the details specified below. VoiceCheck includes both REST and SOAP web service clients that can consume a service built according to the specifications below. For SOAP, the PostAssignmentResults.wsdl WSDL document included in the product package details the contract that the SOAP service must implement. For REST, an example WADL is included in the product package as a reference for implementers developing a REST service.
Note that for REST, the specification is slightly more flexible than what is detailed in the example WADL. In fact, there is no requirement to even use a WADL as long as the service behaves as specified below.
REST Web Service
URL: Completely flexible, can be decided by each server implementation.
The URL can specify either http or https. The VoiceCheck client uses the transport corresponding to the protocol specified. Configure the URL as the Service Endpoint on the Administration > System Configuration page of the user interface.
Example: <http or https>://<server>/assignmentResults
Authentication: HTTP Basic Authentication is supported but not required. Turn authentication on for the VoiceCheck client by checking the Requires Authentication checkbox on the Administration > System Configuration page of the user interface.
Method: POST
Content-Type: application/xml;charset=UTF-8
The VoiceCheck client always sends the results content using this content type, so the host server implementation must accept this content type.
Message Body: XML as outlined in the schema in the WADL, the elements of which are described in the tables below.
Response: On success, HTTP Status 204 (No Content) with an empty body. It is also acceptable for the service to return HTTP Status 200 (Success), with or without a body. If the VoiceCheck client receives a body, it will be ignored.
When returning content, the server should use the content-type: application/xml;charset=UTF-8
Any HTTP status code other than 200 or 204 is considered an error. When possible, the host system should return a body for errors containing a faultInfo element. The information in the faultInfo element will be used to provide additional details about the error to the GUI user. See Fault Handling for Assignment Data for more detail.
SOAP Web Service
WSDL: You must build a server that implements the PostAssignmentResults.wsdl as provided by Honeywell. The input details below describe the data elements in this WSDL.
Service Endpoint: Completely flexible, can be decided by each server implementation.
The URL can specify either http or https. The VoiceCheck client uses the transport corresponding to the protocol specified. Configure the URL as the service endpoint on the Administration > System Configuration page of the user interface.
Example: <http or https>://<server>/AssignmentResultsService
Authentication: HTTP Basic Authentication is supported but not required. Turn authentication on for the VoiceCheck client by checking the Requires Authentication checkbox on the Administration > System Configuration page of the user interface.
Fault Handling: The server may return any SOAP fault. If the server returns the WebServiceException fault specified in the WSDL, the message contained in the WebServiceException will be displayed as part of the error message in the VoiceCheck GUI. All other faults will trigger a generic error message in the GUI.
Input Details
| Assignment Results: Header | |||
|---|---|---|---|
| Property | Type | Req'd | Definition |
| siteName | string |
yes |
The site name. |
| assignmentId | string | yes | The assignmentId that was sent from the host system to VoiceCheck in the Create Assignment message. |
| workId | string | yes | The workId that was sent from the host system to VoiceCheck in the Create Assignment message. |
| user | string | yes | The VoiceCheck GUI user who submitted the results. |
| timeSubmitted | datetime | yes |
The time that the user submitted the results to the external system. Data type: XML schema xs:dateTime type. Format: valid xs:dateTime string value indicating the time in UTC: YYYY-MM-DDThh:mm:ss.sssZ Example: 2014-06-14T19:27:33.152Z |
| metadata | list of key-value pairs | no | A list of additional, pass-through information about the assignment that was sent in the Create Assignment message. |
| sectionResults | list section results | yes | List of section results defined in the following table. |
| Assignment Results: Section Results | |||
|---|---|---|---|
| Property | Type | Req'd | Definition |
| sectionId | string | yes | An identifier for the section that was sent from the host system in the Create Assignment message. |
| stepResults |
list of step results |
yes | List of step results defined in the following table. |
| Assignment Results: Step Results | |||
|---|---|---|---|
| Property | Type | Req'd | Definition |
| sequenceCounter |
numeric string |
yes |
The sequenceCounter sent for the step in the Create Assignment message. |
| stepId | string | yes | The identifier of the step that was performed from the VoiceForm. This value matches the stepId that was sent for the step in the Create Assignment message. |
| user |
string |
yes | Voice inspection user name or technician who last updated the result. |
| metadata | list of key-value pairs | no | A list of additional, pass-through information about the step that was sent in the Create Assignment message. |
| startTime |
datetime |
yes |
The date and time that the step was started in the voice application by the device operator. Data type: XML Schema xs:dateTime type Format: valid xs:dateTime string value indicating the time in UTC: YYYY-MM-DDThh:mm:ss.sssZ Example: 2014-06-14T19:27:33.152Z Results that are system-generated, such as a dependent step marked "does not apply," do not include a start time. The startTime and endTime may not always reflect the actual time spent performing the step because the voice application provides technicians with functions such as skipping steps and redoing steps. |
| endTime | datetime | yes |
The date and time that the step was completed in the voice application by the device operator. Data type: XML Schema xs:dateTime type. Format: valid xs:dateTime string value indicating the time in UTC: YYYY-MM-DDThh:mm:ss.sssZ Example: 2014-06-14T19:27:33.152Z The startTime and endTime may not always reflect the actual time spent performing the step because the voice application provides technicians with functions such as skipping steps and redoing steps. |
| status | integer | yes |
An integer value describing the final status of the step. Valid values: 2 = Does not apply 3 = Complete |
| results | list of strings | no |
A list of results for the step. Each result is specified as a result element containing a string. When the status is "2" (does not apply), no results are sent (the XML does not contain any results elements). When the status is "3" (complete), results may be sent or not, depending on the step type. See the "Results for Completed Steps" table below. |
| Results for Completed Steps | |
|---|---|
| Step Type (from VoiceForm) | Description |
| Prompt Only |
No results sent. |
| Ready | No results sent. |
| Notes | Zero or more results sent. One result is sent for each transcription that is not blank. If all notes for a step have blank transcriptions, no results are sent. |
| Multiple List Selection | One or more results sent. One result is sent for each selection made at the prompt. The value of each result will be the key from the VoiceForm that represents the selection made. |
| Float Value | One result sent. The result is the value spoken by the user. |
| Value Entry | One result sent. The result is the value spoken by the user. |
| Long Value Entry | One result sent. The result is the value spoken by the user. |
| Fraction | One result sent. The result is the value spoken by the user. |
| Date | One result sent. The result is the value spoken by the user and formatted as per the date format specified in the VoiceForm. |
| Photos | One or more results sent. One result is sent for each photo taken. The value of each result will be the URL that can be used by an external system to retrieve the photo using the Get Photo Web Service. |
| Part Number | One result sent. The result is the value chosen or spoken by the user. |