Remote System creating/updating orders in a Pruvan account

In this exercise you will learn how to remotely set various fields in a Pruvan account that are available in the User Interface.   

Remote Systems that wish to create or update orders in a Pruvan account should be aware of data fields that they can always update, and fields that are shared, and may not be able to update after order is created.

User Fields owned by Remote System's integrated orders  

These fields are always available for remote update.  If created remotely, they can not be edited by the User Interface.

• Client Due Date
• Client Status
• Client Instructions

User Fields shared

User Fields can be set on remote order creation, but may or may not be available for remote system update(s).  Users or configured workflows can update these fields.

• Description
• Reference
• Work Order Info
• Project Options
• Project Instructions
• Status
• Due Date
• Tasks
  • Name
  • Instructions
  • Options

Auto-Admin

When an integration is setup in a Pruvan account the account owner can configure the integration to enable or disable Auto-Admin.  Auto-Admin refers to automatic administration of Pruvan orders by a remote system.  Auto-Admin is ON by default, and allows order updates from the remote order system to update and overwrite Pruvan fields if these fields are changed by account users.   Automatic updating by remote systems can cause confusion if Pruvan users wish to have their order changes persist.   The remedy is for users who wish to control data fields managed by Auto-Admin to set Auto-Admin to OFF on the integration setup screen.   Learn more here:  Auto-Admin settings

Pruvan Status field vs Client Status field.

Remote systems should be aware of how to set Pruvan Status field in conjunction with Client Status field.  The Pruvan Status field is a shared field, therefore not all statuses available should be used by remote system.  

On Order Create, a Remote System should only set Status field to one of the following:

• Not Set (leave Status field out of order update)
• RUSH
• REWORK

Remote system should always set Client Status field to remote system's current order status.  Be sure you send the minimum fields for each order to be created.

For Example: Post payload to a valid PushKey to create one order (read more).  
Minimum fields required for CREATE, valid address and 1 service/task.
{
 "workOrders": [{
 "workOrderNumber": "TESTPOST",
 "address1": "111 East Main ",
 "city": "Round Rock",
 "state": "TX",
 "zip": "78664",
 "workOrderInfo": "Call Office 555-111-2222",
 "clientDueDate": "2020-05-28 1200 +0",
 "clientStatus": "Order Created",
 "dueDate": "2020-05-25 1200 +0",
 "services": [{
 "serviceName": "Task-01 Mow Grass"
 }]
 }]
}

Response back from account showing successful remote order create.
{
 "response": {"created": 1,"updated": 0,"deleted": 0},
 "error": null
}

On Order Update, the only the following Status field updates are recommended

• Not Set (leave Status field out of order update)
• RUSH
• REWORK
• CANCEL 
• CLOSED 

For Example:  Status not set, only clientStatus updated.
{
 "workOrders": [{
 "workOrderNumber": "TESTPOST",
 "clientStatus": "Order Late"
  }]
}

Response back showing successful remote update.
{
 "response": {"created": 0,"updated": 1,"deleted": 0},
 "error": null
}
  

As always, Remote System should set Client Status field to remote system's current order status at a minimum, and not set shared fields in a manner that confuses or arrests (stops) the account user from completing order.

Valid Status and Client Status combinations

Below are all possible combinations of Status field updates along with recommended Client Field message.  If your remote system updates a single Pruvan account you control, you have an Internal Integration, if not you have an External Integration.  Learn more about Internal vs. External integrations here.

Integration Mode	Remote Action	Desired Status Field	Client Field suggestion	assignedTo	Notes
Internal/External	Create	No Particular Status (not set)	"Order Created"		Status Field "Unassigned", Client Status "Order Created"
Internal Only	Create	unassigned	"Order Created"	Null	Not advised for External Integrations
Internal Only	Create	assigned	"Order Assigned"		Not advised for External Integrations
NOT ADVISED	Create	accepted	Not advised on remote Create		Set by Portal User or local workflow only
NOT ADVISED	Create	rejected	Not advised on remote Create		Set by Portal User or local workflow only
Internal/External	Create	rush	"Rush Order"		Status Field "Rush", Client Status "Rush Order"
Internal/External	Create	rework	"Rework Required"		Status Field "Rework", Client Status "Rework Required"
NOT ADVISED	Create	canceled	Not advised on remote Create
NOT ADVISED	Create	complete	Not advised on remote Create
NOT ADVISED	Create	invoiced	Not advised on remote Create
NOT ADVISED	Create	submitted	Not advised on remote Create
NOT ADVISED	Create	closed	Not advised on remote Create
NOT ADVISED	Create	deleted	Not advised on remote Create
Internal/External	Update	No Change to Status (not set)	"Remote Order Status is….."		Update Client Status field only (pending, closed, canceled, etc..)
Internal Only	Update	unassigned	"Temporarily Unassigned"	Null	Not advised for External Integrations
Internal Only	Update	assigned	"Assignment Change from/to…."		Not advised for External Integrations
NOT ADVISED	Update	accepted	Not advised on remote Update		Set by Portal User Only
NOT ADVISED	Update	rejected	Not advised on remote Update		Set by Portal User Only
Internal/External	Update	rush	"Order updated to Rush"		Status Field "Rush", Client Status "Order updated to Rush"
Internal/External	Update	rework	"Order updated to Rework"		Status Field "Rework", Client Status "Order Closed"
Internal/External	Update	canceled	"Order Canceled"		Status Field "Canceled", Client Status "Order Canceled"
NOT ADVISED	Update	complete	Not advised on remote Update		Set by Portal User or local workflow only
NOT ADVISED	Update	invoiced	Not advised on remote Update		Set by Portal User or local workflow only
NOT ADVISED	Update	submitted	Not advised on remote Update		Set by Portal User or local workflow only
Internal/External	Update	closed	"Order Closed"		Status Field "Closed", Client Status "Order Closed"
NOT ADVISED	Update	deleted	"Order Deleted"		Not advised by remote system.  Use with caution.

Note:

• "Status" field is shared by remote system and Pruvan users or local workflow.  "Client Status" field is always available for update by remote system.
• For Internal Integrations, if assignedTo is not set to valid User/Sub-User for related account, only visible to Admin and Staff roles in Portal. 
• External Integrations do not set assignedTo field. Order is created unassigned and may be automatically assigned by workflow or assigned manually by account user.
• Previous assignedTo will be notified order has been reassigned, unassigned, closed, canceled or deleted on Mobile.
• Remote Update possible on shared fields if Auto-Admin=ON.  See Auto-Admin fields that can/cannot be updated by remote system.
• Orders deleted are visible in Deleted View in Portal.
• If user credentials are valid and relay is permitted all queued orders and collected content, regardless of order Status, will be sent to the order originator.
• Deleted orders that have queued data published will be recreated with a different Key1 field.  Remote systems must discard unwanted queued data received.