Integrating Pruvan with Northsight Management

Transcription

1 Integrating Pruvan with Northsight Management This document is a step-by-step guide on how to integrate your Pruvan account with Northsight Management s (NSM) order system. Create an NSM Client In order for your Work Orders to be automatically downloaded from PPW to Pruvan, you need to create a Pruvan Client record for PPW. 1. Login to your Pruvan account at and click on the Clients tab. 2. Click the button. 3. You will be presented with the following dialog: 4. Enter a name for your client record, something like NSM and then select Northsight Management in the drop-down box. 5. Click the button.

2 6. You will be presented with the following dialog: 7. Enter your NSM Username and Password. 8. The Push apikey is the URL that you will need to call in order to trigger a project import. You can test the apikey by simply entering it in to a browser and then checking Pruvan for new / updated projects. 9. Click on to test your login information. If it works, you should see the message: Connected successfully! 10. If you want your photos to be automatically sent back to NSM when you publish in Pruvan set the Auto Relay Photos dropdown box to Yes. The photos will sent to your NSM account. 11. Click to save the Client record. Auto-Assignment Work orders that are imported will have the status of assigned in Pruvan as long as a valid user is passed on the assigned to item. Otherwise the project will be unassigned. Importing Orders To import your NSM orders into Pruvan click on the button. This will start the order import and launch the log viewer. You can press the F5 key to refresh the log viewer if it doesn t refresh fast enough. The apikey URL can also be used to trigger a project import. The apikey will be useful for coding an automatic import from the NSM side. When using the apikey, only incremental updates should be sent to Pruvan. When getworkorders is requested Pruvan will send a UNIX timestamp of the last request. If full refreshes are sent every time an update is made the apikey may be disabled.

3 On Refresh New orders will be processed in to the system, and current orders will be updated with any chan ges made to the mapped fields. Mobile Configuration Options You can pass options at the Work Order and Service level to configure what is available on the device. This is done by adding the element options to either level. Options should be passed as a JSON string, with all appropriate quote escapes necessary. A malformed options payload will cause that work order to fail on import without affecting any good work orders. You can read all about the Mobile Configuration Options here: Example Options payload: "options":"\"camera_icon_hidden\":true,\"complete_icon_hidden\":false,\"photo_timest amp\":\"time\",\"camera_orientation\":\"auto\",\"all_required_tasks_complete\":true,\ "allow_manual_work_order_creation\":false,\"photo_size\":\"small\",\"evidencetypes\": [\"larry\",\"moe\",\"curly\"],\"upload_pics_only_when_wo_complete\":false,\"mark_comp lete_mode\":\"off\",\"mark_complete_label\":\"push Now!\",\"auto_relay\":\"on\"}" NSM Web Services Specification validate Pruvan will POST to a URL named exactly: BASE_URL/validate.html Pruvan will send the following JSON string in the POST variable named payload "username":"bigvend","password":"d28069c d2cba15f10ffdd996ec6f5"} If the username and password are valid, you should return the following as a JSON string: "error":"","validated":true} If the username and password are invalid, you should return the following as a JSON string: "error : invalid username or password","validated":false}

4 getworkorders Pruvan will POST to a URL named exactly: BASE_URL/getWorkOrders.html Pruvan will send the following JSON string in the POST variable named payload "username":"bigvend","password":"d28069c d2cba15f10ffdd996ec6f5","timestam p":" :57:50","workOrders":null} If the username and password are valid, you should return the following JSON string of orders (dates should be in UNIX timestamp format). Here s an example of two orders: "workorders": [ "workordernumber": , "state": "TX", "country": "USA", "duedate": , "reference": "XYZ Bank", "description": "Rekey", "city": "Round Rock", "zip": "78664", "instructions":"the gate key is XXXX, rekey locks" "assignedto": "nmbobr", "address1": "110 East Main Street", "address2": "", "action": "close", "gpslatitude": , "gpslongitude": , "attribute7":"internal reference", "attribute8":null, "attribute9":null, "attribute10":null, "attribute11":null, "attribute12":null, "attribute13":null, "attribute14":null, "attribute15":null, "options":"\"auto_relay\":true}" "services": [ "servicename": "rekey", "survey": "", "instructions":"on this task, do this", "attribute1":"internal reference", "attribute2":null, "attribute3":null, "attribute4":null,

5 } "attribute5":null, "attribute6":null, "attribute7":null, "attribute8":null, "attribute9":null, "attribute10":null, "attribute11":null, "attribute12":null, "attribute13":null, "attribute14":null, "attribute15":null, "options":"\"evidence_types\":[\"front\",\"back\"]}" } ] }, "workordernumber": , "state": "GA", "country": "USA", "status": "Open", "city": "Duluth", "zip": "30096", "assignedto": "nmbobr", "address1": "2975 Breckinridge Blvd", "address2": "", "action":"open", "gpslatitude": , "gpslongitude": , "services": [ "servicename": "Grasscut", "survey": "grasscut-v2", "options":"\"required\":true}" } ] } ], "error": ""

6 uploadpictures Pruvan will POST to a URL named exactly: BASE_URL/uploadPictures.html Pruvan will send, the following JSON string in the POST variable named payload } "timestamp": , "serviceid": "14631", "workorderid": "5018", "evidencetype": "before", "filetype": "picture", "csrcertifiedphoto": "1", "csrcertifiedtime": "1", "csrcertifiedlocation": null, "csrpicturecount": null, "uuid": "A13A55E C38-AE6F-D9D5434C9A88", "parentuuid": "5018", "filename": " jpg", "gpslatitude": " ", "gpslongitude": " ", "gpstimestamp": " ", "gpsaccuracy": " ", "key2": " ", "key4": "Rekey", "username": "bigvend", "password": " d28069c d2cba15f10ffdd996ec6f5" Pruvan will send the picture file in the POST and the information about that file will be located in the $_FILES session variable. If the username and password are valid, you should return the following as a JSON string: "status":true,"error":null}

7 Data Mapping Element Table for getworkorders Work Order Level: Data Element action address1 Address line 1 address2 Address line 2 assignedto attribute7 attribute8 attribute9 attribute10 attribute11 attribute12 attribute13 attribute14 attribute15 city country description duedate gpslatitude gpslongitude instructions options reference services state workordernumber zip Pruvan Project Field / Description 2 supported values; open will create / update a project in the system, close will set the project status to closed in Pruvan (causing it to fall off of a vendors project list) Pruvan user to assign to; this name is not verified against your sub-user list City Country Description; only viewable in Pruvan Project Management tab Due Date Coordinate latitude used to calculate location certification; if blank Pruvan will use Google to lookup the coordinates of the address entered. Coordinate longitude, same as gpslatitude Project Instructions; viewable on device A JSON string for Mobile Configuration Options set at the Work Order level Reference; only viewable in Pruvan Project Management tab An object containing the Project's Tasks; at least one service is required State Project ID Zip

8 Service Level: Data Element attribute1 attribute2 attribute3 attribute4 attribute5 attribute6 attribute7 attribute8 attribute9 attribute10 attribute11 attribute12 attribute13 attribute14 attribute15 instructions options servicename survey Description Task Instructions; visible on device A JSON string for Mobile Configuration Options set at the Service level Task Name Survey template ID

9 Element Table for uploadpictures Data Element creationdate csrcertifiedlocation csrcertifiedtime csrcertifiedphoto csrpicturecount csrtimestampsource evidencetype filename filetype gpsaccuracy gpslatitude gpslongitude gpstimestamp key2 key4 notes parentuuid password serviceid timestamp username uuid workorderid Description The date and time the file was created If the filetype = "picture", then the photo location is certified if value is "1", not certified if value is "null". If filetype = "csr", then it s a count of the number of certified location photos for the CSR. If the filetype = "picture", then the photo time is certified if value is "1", not certified if value is "0". If filetype = "csr", then it s a count of the number of certified time photos for the CSR. If the filetype = "picture", then the value is 1. If filetype = "csr", then it s a count of the number of total photos for the CSR. If the value is "mobile" or "Mobile2" then the photo was taken with the Pruvan app. The evidence type to which the photo is associated. Typical values include "before", "during" and "after." These can be altered using Mobile Configuration Options. Photos taken on a survey will have the evidencetype = survey. The low-level name of the file on Pruvan s filesystem. The filetype of the file. If the filetype = "picture", then the file is a photo. If the filetype = "csr", then the file is a Certified Service Record. The radius of uncertainty for the location, measured in meters. The latitude where the photo, CSR or survey was completed. The longitude where the photo, CSR or survey was completed. The timestamp given by the GPS receiver. The project ID visible to the user. The task name visible to the user. Notes added to the photo from the device in the field. The UUID of the parent object. For photos from assigned work orders this will equal key1, for survey photos this will equal the UUID of the survey instance they were taken on. The password for this request to authenticate to an external web service. The task ID as it is stored in the Pruvan database. The current time in UNIX timestamp. The username for this request to authenticate to an external web service. The UUID of the file. The project ID as it is stored in the Pruvan database.

10 Optional Elements not implemented at this time: Data Element attribute1 attribute2 attribute3 attribute4 attribute5 attribute6 attribute7 attribute8 attribute9 attribute10 attribute11 attribute12 attribute13 attribute14 attribute15 attribute16 attribute17 attribute18 attribute19 attribute20 attribute21 attribute22 attribute23 attribute24 attribute25 attribute26 attribute27 attribute28 attribute29 attribute30 Description Reserved for address1 from the project Reserved for address2 from the project Reserved for city from the project Reserved for state from the project Reserved for zip from the project Reserved for country from the project Work Order level attribute7 Work Order level attribute8 Work Order level attribute9 Work Order level attribute10 Work Order level attribute11 Work Order level attribute12 Work Order level attribute13 Work Order level attribute14 Work Order level attribute15 Service level attribute1 Service level attribute2 Service level attribute3 Service level attribute4 Service level attribute5 Service level attribute6 Service level attribute7 Service level attribute8 Service level attribute9 Service level attribute10 Service level attribute11 Service level attribute12 Service level attribute13 Service level attribute14 Service level attribute15