Sometimes saving information generates a warning in the Lucity software, or generates a requirement for more information (like what warehouse should we take the parts from).
By default, the system will not show any warnings and will just ignore them and allow the save. For parts inventory, by default the system will automatically figure out from where to disburse parts.
To have the REST API return warnings or parts inventory prompt information, the following header should be included in the request
LUCITYSF:[a comma delimited list of special features]
Currently 2 types of special features are supported
To have the system return warnings but not parts prompts, the header provided should be:
LUCITYSF:1
To have the system return both parts prompts and warnings, the header provided should be:
LUCITYSF:0,1
When this header is passed, the Lucity REST API may (if required), return a 409 CONFLICT instead of a 200 OK or 201 CREATED. 409 CONFLICT indicates that the server cannot proceed without additional input because of a conflict with the data. The 409 CONFLICT responses will include a body which tells the client application how to get the additional information it needs and how to resubmit the request.
All 409 conflict responses share the same basic information.
This is a flow diagram showing how conflict responses should be addressed:
This is what a conflict response looks like
An Actual Response showing data:
When you get a 409 conflict, you should extract the list of conflicts from the response as well as the object. You should show the user a series of prompts (one for each conflict). For parts inventory these prompts will always be "Choice" prompts, which means that the response will include a message as well as a list of choices for the user to select. We recommend providing a cancel option too which allows the user to abandon the attempt.
If a request returns a 409 conflict response, and the ChoiceType = "OK" then the conflict is a warning. Warnings are dealt with similar to parts inventory, but they are simpler. There is a message to display to the user and there are no choices except OK and CANCEL.
There may be more than one warning returned in the Conflicts list. All warnings need to be acknowledged in order to successfully save.
Re-submit
Once the warnings are acknowledged (and not canceled), the application should attempt to re-submit the request and include the lucityconflict header in the new request. The conflict header should look like this:
lucityconflict:Warranty:OK,Availability:OK
Where Warranty was the conflict Id for the first conflict and Availability was the Id for the second conflict.
Alternately, the request could be re-submitted without the LucitySF header to avoid the conflict response.
Examples:
This is the conflict response (shown in a tree view to make it more readable, the actual response returns XML) that might be returned if an asset is added to a work order and there is already another open work order with that asset
This is the plain text view:
The user should see something like:
BGB0532 is already attached to the following open Work Orders:
Work Order ID: 5140
Work Order ID: 5993
Work Order ID: 6170
Work Order ID: 6322
Work Order ID: 6323
Work Order ID: 6433
Work Order ID: 6480
Work Order ID: 7257
Work Order ID: 7272
Work Order ID: 7274
Work Order ID: 7378
And:
BGB0532 has at least one open warranty.
Supplier: Manufacturer
Warranty Type: 5 Year
Warranty Open Date: 7/14/2011
Expiration Date: 12/1/2014
Review Date:
In order to successfully re-submit for this example, the client application would need to include the following header in the request:
lucityconflict:AssetLinkingID:Ok
OR
The client application could re-submit the request and exclude the header which tells the server to return warning conflicts.
LucitySF:1