Assignment Web Services
VoiceCheck exposes a web service that allows the creation of an—essentially a data import. This web service enables creating new assignments as well as updating and deleting of existing assignments from the VoiceCheck server.
An assignment specifies a list of sections to perform, and each section contains a list of steps to perform. Each step references a voice-enabled step definition from a VoiceForm.
This service can be used for assignment updates as well as creating new assignments. When VoiceCheck receives this web service message, it checks for existing matches in the system:
- If there is no matching assignment ID and no matching work ID in the system, a new assignment is created.
- If there is a matching assignment ID and the existing assignment is in available status (the assignment has not been started in VoiceCheck), the existing assignment is replaced. If the assignment is in any other state, the import fails.
- If there is no matching assignment ID but there is a matching work ID and the assignment associated with that work ID is in complete status, the existing assignment is replaced. If the existing assignment is in any other status, the import fails. This validation allows for reusing work IDs for assignment updates.
When VoiceCheck receives this message for reading, updating, and deleting of assignments, the following validations are taken into consideration:
- Verify that assignment in progress cannot be deleted using REST over an http server
- Verify that assignment assigned to an operator and not initiated yet should get deleted using REST over an http server
- Verify that assignment in Available state and not assigned to any operator can be deleted using REST over an http
- Verify that a 100% completed assignment cannot be deleted using REST over an http
- Verify that a closed out assignment can be deleted using REST over http server
- Verify that a Re-opened assignment cannot be deleted using Rest over an http server
- Verify that assignment progress is captured using REST over an http server
VoiceCheck prompts technicians to perform each section in the order listed in the sectionsToPerform field and prompts for the steps according to the sequence specified by the sequenceCounter property. Steps may be sent in any order in the web service message; VoiceCheck orders them based on the sequenceCounter property.
Create Assignment Details
REST Web Service
WADL: <http or https>://<host>:<port>/VoiceCheck/services/assignments?_wadl
URL: <http or https>://<host>:<port>/VoiceCheck/services/assignments
Method: POST
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. On failure, the system returns an error. See Fault Handling for Assignment Data for more detail.
SOAP Web Service
WSDL: <http or https>://<host>:<port>/VoiceCheck/services/AssignmentService?wsdl
Service Endpoint: <http or https>://<host>:<port>/VoiceCheck/services/AssignmentService
Operation: createAssignment
Input: A single Assignment object, as described in the tables below.
Output: On success, the system returns an empty response as defined in the WSDL. On failure, the system returns an error. See Fault Handling for Assignment Data for more detail.
READ Assignment DETAILS
REST WEB SERVICE
WADL: <http or https>://<host>:<port>/VoiceCheck/services/assignments?_wadl
URL: <http or https>://<host>:<port>/VoiceCheck/services/assignments/Default/{assignmentId}
Method: GET
Content-Type: application/json;charset=UTF-8
Response: On success, HTTP Status 200 with or without a body. On failure, the system returns an error.
DELETE Assignment DETAILS
REST WEB SERVICE
WADL: <http or https>://<host>:<port>/VoiceCheck/services/assignments?_wadl
URL: <http or https>://<host>:<port>/VoiceCheck/services/assignments/Default/{assignmentId}
Method: DELETE
Response: On success, HTTP Status 200 with or without a body. On failure, the system returns an error.
Input Elements
| Assignment: Header | ||||
|---|---|---|---|---|
| Property | Type | Req'd | Definition | Validation |
| siteName | string | yes | The site name. | Must match an existing site name in VoiceCheck. |
| assignmentId | string | yes | Unique identifier for this assignment within the specified site. | Must be unique for every assignment in VoiceCheck, unless web service record is updating an existing assignment in Available status. |
| workId | string | yes | Unique identifier that a user will enter to request the work. | Must be unique for every assignment in VoiceCheck. |
| metadata | list of key-value pairs | no | A list of additional, pass-through information about the assignment that will be sent back to the host system in the Post Assignment Results message. | No validation. VoiceCheck does not use this pass-through data. |
| operatorId | string | no | Unique identifier of the technician that will be associated with this assignment. | If specified, the value must match an existing operator ID. |
| voiceFormName | string | yes | The name of the VoiceForm from which to look up the voice-enabled step definitions for the stepsToPerform. | Must match an existing VoiceForm name in VoiceCheck. |
| voiceFormVer | string | no | Version of VoiceForm existing in the system | If specified, the value must match an existing VoiceForm version. |
| planName | string | no | The name of the Plan based on which Assignment has to be created | Must match an existing Plan name in VoiceCheck. Must not be included when updating assignment. |
| sectionsToPerform | list of section objects | no | A list of sections to perform, sorted in the order they should be performed. See Section definition below. | At least one section must be specified. Plan definition used if not specified. |
| Assignment: Section | ||||
|---|---|---|---|---|
| Property | Type | Req'd | Definition | Validation |
| sectionId | string | yes | An identifier for the section. The sectionId must be unique within the assignment. | Must be unique within the assignment. |
| sectionDescription | string | yes | Description of the section to be performed. This VoiceApplication speaks this value as the description of the section when a technician starts a new section in the workflow. | |
| sectionIsPart | boolean | yes | Operations on the host system are categorized as either being a part or not being a part. If the operation is a part, this field contains a value of true; otherwise it is false. Sections that are parts have custom behavior associated with them. | |
| partNumber | comma separated list | no * | The part number. If there are multiple known part numbers for the same part, they must be sent in a comma separated list (no spaces) in this field. For example:
100234,100345,100456 If the inspection material is expected to contain more than one of the same part, you must create two identical part sections (with the same partNumber entry) in the assignment. * Required when sectionIsPart = true. |
|
| partDescription | string | no * | The part name.
* Required when sectionIsPart = true. |
|
| stepsToPerform | list of step objects | yes | A set of steps to perform, sent in any order
See Step definition below. |
At least one step must be specified. |
| loop | Boolean | No | Determines if the section is a looping section | Can only be true/false. |
| loopingPrompt | String | No | Message shown to user to confirm whether they want to do another looping iteration of this section | If "loop" = true "loopingPrompt" must have a text value (not null or " ") |
| Assignment: Step | ||||
|---|---|---|---|---|
| Property | Type | Req'd | Definition | Validation |
| sequenceCounter | numeric string | yes | Unique number assigned to the step to determine the order in which the step is performed within the section.
The system converts this value to a number for ordering the steps. |
Must be numeric.
Must be unique within the section. |
| stepId | string | yes | An identifier for the step to perform from the VoiceForm. | Must exist in the VoiceForm referenced by this assignment. |
| isMandatory | boolean | yes | A flag that indicates if this step is mandatory. Valid values:
true = step is mandatory false = step is not mandatory Note that if a step is set as mandatory, the VoiceApplication will not allow a technician to respond with "does not apply." |
Must contain one of the valid values. |
| promptData | list of key-value pairs | no | A list of values to be substituted for variable tokens in this step's prompt and help message. | No validation. |
| metadata | list of key-value pairs | no | A list of additional, pass-through information about the step that will be sent back to the host system in the Post Assignment Results message. | No validation. VoiceCheck does not use this pass-through data. |
Additional validation rules: The createAssignment import messages are subject to additional validation rules for dependent steps and display IDs. VoiceCheck verifies each step to be imported against the existing VoiceForm step definitions to validate that:
- If a step references another step as a display ID, that reference step is found in the assignment import,
- If a step has conditions that are dependent on another step, that reference step is found in the assignment import and follows the rules for step dependencies. See Rules for Step Dependencies.