See also: https://pruvan.com/clientDocs/std2.pdf
The getWorkOrders Web Service
The getWorkOrders web service call is initiated from Pruvan. You respond to this call with a JSON object that contains the work orders you wish to load into Pruvan for a specified user. The getWorkOrders web service is a “pull” request from Pruvan to your system. Pruvan also supports “push” requests from your system through the Pruvan Push API. See the Pruvan Push API section later here for more details.
getWorkOrders web service call
The getWorkOrders web service will receive the JSON payload below when the “Import Orders” button is clicked on the Integrations form. It will be sent to {web service url}/getWorkOrders.{web service extension} in the POST variable “payload”:
{
"username": "someuser",
"password": "d28069c84398483874d2cba15f10ffdd996ec6f5",
"token": "dda25c60-4fce-11e4-916c-0800200c9a66",
"timestamp": 1393278236
}
getWorkOrders Modes
The getWorkOrders web service supports incremental and full modes for synchronizing/refreshing work orders. To initiate a full refresh click “Full Refresh” on the Create/Edit Integrations form. To initiate an incremental refresh click “Import Orders” on the Integrations form.
In incremental mode, the timestamp field will be set to a valid timestamp and you should only return orders that have been changed or created since that time for the specified username. In full refresh mode, the timestamp will be set to null and you should return all current work orders for the specified username.
getWorkOrders JSON object
If the user is valid you should respond to getWorkOrders with an array of Pruvan workOrder JSON objects. The simplest form of a Pruvan workOrder creation is this:
{
"workOrders": [
{
"workOrderNumber": "Simple",
"address1": "110 East Main Street",
"city": "Round Rock",
"state": "TX",
"zip": "78664",
"services": [{"serviceName": "Task"}]
}
],
"error": ""
}
Note that the workOrder objects are returned in a workOrders array. The simple example above represents the minimum required set of fields for a valid Pruvan workOrder object.
API details
If a getWorkOrders request is made and there are no updates to send simply return an empty workOrders array:
{"workOrders": [],"error": ""}
If the username and password are invalid or there is an exception, you should return the following as a JSON string with an appropriate error message:
{"error":"error message"}
Available workOrder Object Fields
The workOrder object allows you to specify most work order/project properties in Pruvan. Once a work order is created only updatable fields can be updated.
Available workOrder service Object Fields
The workOrder object’s service element allows you to specify service/task properties in Pruvan. Once a service is created it cannot be updated. Services can be deleted/added to an existing work order by sending a new complete services payload (see the example below). You cannot currently update a survey template ID by updating the services element. If the serviceName is the same as the existing one then the template ID will not update. You must either make 2 calls; one to delete the survey service and one to create it again with the new survey template ID, or change the serviceName of the service with the new template ID.
Numbered Attributes
Numbered attributes (ie attribute7) will follow a Work Order, or Service, and attach themselves to any resultant objects; such as pictures, CSRs, and Surveys. Attributes 1-6 are reserved for the Work Order address fields. Work Order attributes 7-15, and Service attributes 1-15, are available for internal reference data. If you assign attributes 1-6 at the Work Order level they will be over-written.
Updates
Fields identified as updatable in workOrder object reference above can be updated. The minimal update is the workOrderNumber and a single field.
The services element is not required in an update. If the services element is included in an update it is considered a full replacement. This means that if you have service1 and service2 on a workOrder and you send an update with only service1 – service2 will be deleted. No fields on a service are updatable.
Requirements
The workOrderNumber must be unique. Duplicate workOrderNumbers will be rejected.
Limits
A maximum of 5000 work orders can be retrieved in a single call. If you have the need to load more than this limit the Push API can be used to synchronously load orders, n orders at a time.
Standard Driver Integrations are limited to 5000 inserts/updates per hour, and limits may change without notice. Named drivers are available for purchase and have higher import thresholds available; contact Pruvan Sales for more information.
General
All strings sent should only contain ASCII characters. UNICODE strings and/or characters are not accepted.
All errors should be returned invalid JSON format in the appropriate error element, containing a message that is appropriate for an end user. Error messages will be displayed as-is in the Pruvan UI.
Date Fields
UNIX timestamps are accepted as well as fully qualified date strings. When sending a date string you should include the time zone in number offset format, that is “-06” for CST or “+00” for UTC. For any date fields that you do not supply a time, the system will assume midnight Central Time (CST / CDT).
dueDate Field (JSON element)
Specifically for the dueDate field, there is a special consideration. We will alter the time on import so that the same date is displayed in most of the world. This is done by taking your timestamp, converting it to UTC, and setting the time to 1200hrs. Therefore you need to ensure that the date you want to be displayed, in the dueDate field in Pruvan, is the date you want after conversion to UTC. The easiest way to do this is to just send the date in UTC already. For example; if you want “5/25/2016” displayed, then send “2016-05-25 1200 +0”. This is to avoid potential date-shifting pitfalls. For instance, if you sent “2016-05-25 2359 -07”, that would convert to “2016-05-26 0659 +0”, and then we would set the time to noon “2016-05-26 1200 +0”, and you would have 5/26 displayed everywhere as opposed to 5/25.
Comments