Script Appendix

Advanced Configuration for Forms and Classification

In Advanced Configurations, three types of script can be configured.

  • Post Load: Initialize the fields when new form/domain item is created in mobile.
  • Pre Save: Do some action before saving the form like validate or calculate new values based on other values. This script is supported on mobile and not web client.
  • onAttributeChanged: Action performed when any field value is changed during new form creation/edit. Example: Create scoring values for survey reports based on values entered.

Configure the Script

  1. Open Advanced Configurations for a form within the Form Manager.

The script should be in the following format.

  1. Enter your own form values, validate, and calculate or set other fields in the script.
Copy 
{
var result = {};
result.data = {};
result.result= "success";
// Write the steps here. Implement what you want to do.
return result;
}

The following is an example of the script with form values added.

Copy

Pre Save Script

{
var result = {};
result.data = {};
var formData = data.customForm;
var workOrderData = data.workOrder;
var parentWorkOrderData = data.parentWorkOrder;
if (data.customForm.water_depth == 4) {
result.data.substantial_indicators = 1;
}else if (data.customForm.water_flow == 4) {
result.data.substantial_indicators = 1;
} else if (data.customForm.water_cloudiness == 4) {
result.data.substantial_indicators =1;
}else if(data.customForm.other_comtaminants == 4) {
result.data.substantial_indicators = 1;
}
result.result = "success";
return result;
}

Post Load and Default Value Expression

If the default value expression is added for a field, the post load script is automatically generated in the back end when the form is saved.

If the post load script is entered manually by a user in the UI, then the auto-generated script is appended to the user defined script.

A user can edit and modify the post load script without touching the auto-generated part. If the auto-generated script has to be removed, remove the default value expression for the fields.

In the Post Load script, use the keywords workOrder and asset as well as the values from work and assets.

Example: workOrder.externalId, asset.FACILITYID

NOTE: These keywords and values are case sensitive.

Context Sensitive Data Object

The data object structure passed into the functions varies depending on the script being called and the location of the form in question on the workflow. For example, is it on the work order level or on the asset level?

Post Load and Pre Save data objects have the same structure at the same level.

Work Order Level

Copy

Post Load and Pre Save Data Object Structure

{
"customForm": {},
"currentUserId": 20408038,
"currentAppId": 20408095,
"attachments": [],
"signatures": [],
"workOrder": {},
"listOfWorkOrderAssets": [] //at wo level, this list is always empty
}
Copy

Example: WO Level Post Load/Pre Save Data Object

{
"customForm": {
"note_from_workorder": null,
"inspection_comments": null,
"on_site": 1669306950848,
"all_turbidity_values_within_limits": null,
"flow_duration_min": null,
"flow_ls": null,
"total_flow": null,
"off_site": null,
"form_updated_date": null,
"form_last_updated_by": null,
"geometry": null,
"objectid": null,
"workorder": null,
"creation_date": null,
"last_update_date": null,
"meta_data": null,
"object_guid": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036834367692": null
},
"currentUserId": 20408038,
"currentAppId": 20408095,
"attachments": [],
"signatures": [],
"workOrder": {
"monitoringSites": null,
"rtus": null,
"referenceId": null,
"closedDate": null,
"externalId": "BDScriptWO1",
"organisationalUnit": 0,
"workOrderType": 20408081,
"workOrderStatus": 20369455,
"workOrderReason": 18,
"workOrderPriority": null,
"createdBy": 20408038,
"assignedTo": 20408038,
"object_guid": "d4344b95-61e7-11ed-b793-27b3ce7acf5c",
"creationDate": 1668188384796,
"associatedAssets": null,
"lastUpdated": 1668188429957,
"lastUpdatedBy": 20408038,
"notes": "This is a note from the parent/main work order",
"address": {
"address1": "403 Stafford Ave",
"address2": null,
"address3": null,
"address4": null,
"address5": null,
"address6": null,
"city": "Naperville",
"county": "DuPage County",
"state": "Illinois",
"postCode": "60540",
"id": null
},
"geometry": "4326;POINT (-88.12582828699998 41.768369218000025)",
"copiedForms": null,
"dispatched": true,
"projectedStartDate": null,
"projectedEndDate": null,
"custom_problem_code": "PC1",
"custom_string_field": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036854775800": null
},
"listOfWorkOrderAssets": []
}
Copy

OnAttribute Changed Data Object Structure

{
"customForm": {},
"formDefinition": [
],
"domains": {
},
"categoryValues": {},
"categories": {},
"attachments": [],
"signatures": [],
"changedAttribute": "flow_ls",
"create": true,
"trigger": "AttributeChanged",
"currentUserId": 20408038,
"currentAppId": 20408095
}
Copy

Example: WO Level OnAttribute Changed Data Object

{
"customForm": {
"note_from_workorder": null,
"inspection_comments": "403 Stafford Ave",
"on_site": "1669306950848",
"all_turbidity_values_within_limits": 2,
"flow_duration_min": 99,
"flow_ls": 10,
"total_flow": null,
"off_site": null,
"form_updated_date": null,
"form_last_updated_by": 20408038,
"geometry": null,
"objectid": null,
"workorder": null,
"creation_date": null,
"last_update_date": null,
"meta_data": null,
"object_guid": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036834367692": null,
"mapLayerUrl": "https://usstable.dev.trimbleunity.com/unity/arcgis/rest/services/UnityForms/FeatureServer
/919"
},
"formDefinition": [
{
"flow_ls": {
"type": "FieldTypeInteger",
"weighting": 100,
"mapService": -1
},
"flow_duration_min": {
"type": "FieldTypeInteger",
"weighting": 100,
"mapService": -1
},
"total_flow": {
"type": "FieldTypeInteger",
"weighting": 100,
"mapService": -1
},
"inspection_comments": {
"type": "FieldTypeString",
"weighting": 100,
"mapService": -1
},
"off_site": {
"type": "FieldTypeDate",
"weighting": 100,
"mapService": -1
},
"creation_date": {
"type": "FieldTypeDate",
"weighting": 0,
"mapService": -1
},
"all_turbidity_values_within_limits": {
"type": "CODED_VALUE",
"domain": "domain_f_scriptexamplewolevelall_turbidity_values_within_limits",
"weighting": 100,
"mapService": -1
},
"object_guid": {
"type": "FieldTypeString",
"weighting": 0,
"mapService": -1
},
"form_updated_date": {
"type": "FieldTypeDate",
"weighting": 100,
"mapService": -1
},
"form_last_updated_by": {
"type": "CODED_VALUE",
"weighting": 100,
"mapService": -1
},
"meta_data": {
"type": "FieldTypePositionMetaData",
"weighting": 0,
"mapService": -1
},
"geometry": {
"type": "FieldTypeGeometry",
"weighting": 100,
"mapService": -1
},
"note_from_workorder": {
"type": "FieldTypeString",
"weighting": 100,
"mapService": -1
},
"workorder": {
"type": "FieldTypeInteger",
"weighting": 0,
"mapService": -1
},
"on_site": {
"type": "FieldTypeDate",
"weighting": 100,
"mapService": -1
},
"objectid": {
"type": "FieldTypeInteger",
"weighting": 0,
"mapService": -1
},
"last_update_date": {
"type": "FieldTypeDate",
"weighting": 0,
"mapService": -1
}
},
{
"ANDROID_DUMMY_PLACEHOLDER9223372036834367692": {
"type": "FieldTypePhotos",
"weighting": 0,
"mapService": -1
}
}
],
"domains": {
"domain_f_scriptexamplewolevelall_turbidity_values_within_limits": {
"1": {
"domainName": "domain_f_scriptexamplewolevelall_turbidity_values_within_limits",
"id": 1,
"description": "N/A",
"score": 0,
"sortOrder": 0,
"active": true
},
"2": {
"domainName": "domain_f_scriptexamplewolevelall_turbidity_values_within_limits",
"id": 2,
"description": "Yes",
"score": 0,
"sortOrder": 1,
"active": true
},
"3": {
"domainName": "domain_f_scriptexamplewolevelall_turbidity_values_within_limits",
"id": 3,
"description": "No",
"score": 0,
"sortOrder": 2,
"active": true
}
}
},
"categoryValues": {},
"categories": {},
"attachments": [],
"signatures": [],
"changedAttribute": "flow_ls",
"create": true,
"trigger": "AttributeChanged",
"currentUserId": 20408038,
"currentAppId": 20408095
}

Asset Level

Copy

Post Load and Pre Save Data Object Structure

{
"customForm": {},
"currentUserId": 20408038,
"currentAppId": 20408095,
"attachments": [],
"signatures": [],
"workOrder": {},
"parentWorkOrder": {},
"listOfWorkOrderAssets": [] //this will only have 1 asset in it at asset level
}
Copy

Example: Asset Level Post Load/Pre Save Data Object

{
"customForm": {
"facility_id": null,
"main_workorders_note": null,
"hydrant_id": null,
"on_site": 1669307034817,
"all_turbidity_values_within_limits": null,
"flow_duration_min": null,
"flow_ls": null,
"total_flow_l": null,
"inspection_comments": null,
"off_site": null,
"form_updated_date": 1669307034817,
"form_updated_by": null,
"geometry": "3857;POINT (-9810007.117 5126470.086000003)",
"objectid": null,
"workorder": null,
"creation_date": null,
"last_update_date": null,
"meta_data": null,
"object_guid": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036834367667": null
},
"currentUserId": 20408038,
"currentAppId": 20408095,
"attachments": [],
"signatures": [],
"workOrder": {
"geometry": "4326;POINT (-88.12479330499997 41.76920608900008)",
"objectId": null,
"workOrder": null,
"lastUpdated": 1669307027839,
"creationDate": 1668188384796,
"metaData": null,
"workOrderType": 20408060,
"workOrderStatus": 20369479,
"workOrderPriority": null,
"referenceId": null,
"assignedTo": 20408038,
"syncStartDate": null,
"organisationalUnit": 0,
"externalId": "20408192",
"notes": "This is a note from the parent/main work order",
"createdBy": 20408038,
"reason": null,
"displayName": "HYD-891",
"displayType": "Water Hydrants",
"object_guid": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036834405857": null
},
"parentWorkOrder": {
"monitoringSites": null,
"rtus": null,
"referenceId": null,
"closedDate": null,
"externalId": "BDScriptWO1",
"organisationalUnit": 0,
"workOrderType": 20408081,
"workOrderStatus": 20369458,
"workOrderReason": 18,
"workOrderPriority": null,
"createdBy": 20408038,
"assignedTo": 20408038,
"object_guid": "d4344b95-61e7-11ed-b793-27b3ce7acf5c",
"creationDate": 1668188384796,
"associatedAssets": null,
"lastUpdated": 1669307027839,
"lastUpdatedBy": 20408038,
"notes": "This is a note from the parent/main work order",
"address": {
"address1": "403 Stafford Ave",
"address2": null,
"address3": null,
"address4": null,
"address5": null,
"address6": null,
"city": "Naperville",
"county": "DuPage County",
"state": "Illinois",
"postCode": "60540",
"id": null
},
"geometry": "4326;POINT (-88.12582828699998 41.768369218000025)",
"copiedForms": null,
"dispatched": true,
"projectedStartDate": null,
"projectedEndDate": null,
"custom_problem_code": "PC1",
"custom_string_field": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036854775800": null
},
"listOfWorkOrderAssets": [
{
"__type": "Water Hydrants",
"__url": "https://services.arcgis.com/X3EAXocno9eyvCvV/arcgis/rest/services
/TrimbleUnity_Sales_CleanWaterNetwork/FeatureServer/3/838",
"formid": null,
"operable": 1,
"facilityid": "HYD-891",
"installdate": 94694400000,
"lastservice": 1220400000000,
"rotation": 94.7494,
"globalid": "d164adae-67b6-488c-89db-bf821b17f464",
"pressure": null,
"lasteditor": "Esri",
"enabled": 1,
"activeflag": 1,
"pressuretimestamp": null,
"manufacturer": "Waterous",
"site": null,
"managedby_other": null,
"maintby": 1,
"lastupdate": 1430920345000,
"locdesc": null,
"ownedby_other": null,
"ownedby": 1,
"objectid": 838,
"flow": 250,
"manufacturer_other": null
}
]
}
Copy

On Attribute Changed Data Object Structure

{
"customForm": {},
"formDefinition": [],
"domains": {
},
"categoryValues": {},
"categories": {},
"attachments": [],
"signatures": [],
"changedAttribute": "flow_duration_min",
"create": true,
"trigger": "AttributeChanged",
"currentUserId": 20408038,
"currentAppId": 20408095
}
Copy

Example: Asset Level onattributechanged Data Object

{
"customForm": {
"facility_id": "HYD-891",
"main_workorders_note": "This is a note from the parent/main work order",
"hydrant_id": "HYD-891",
"on_site": "1669307034817",
"all_turbidity_values_within_limits": 2,
"flow_duration_min": 55,
"flow_ls": null,
"total_flow_l": null,
"inspection_comments": null,
"off_site": null,
"form_updated_date": "1669307034817",
"form_updated_by": 20408038,
"geometry": "3857;POINT (-9810007.117 5126470.086000003)",
"objectid": null,
"workorder": null,
"creation_date": null,
"last_update_date": null,
"meta_data": null,
"object_guid": null,
"ANDROID_DUMMY_PLACEHOLDER9223372036834367667": null,
"mapLayerUrl": "https://usstable.dev.trimbleunity.com/unity/arcgis/rest/services/UnityForms/FeatureServer
/920"
},
"formDefinition": [
{
"flow_ls": {
"type": "FieldTypeInteger",
"weighting": 100,
"mapService": -1
},
"form_updated_by": {
"type": "CODED_VALUE",
"weighting": 100,
"mapService": -1
},
"flow_duration_min": {
"type": "FieldTypeInteger",
"weighting": 100,
"mapService": -1
},
"hydrant_id": {
"type": "FieldTypeString",
"weighting": 100,
"mapService": -1
},
"inspection_comments": {
"type": "FieldTypeString",
"weighting": 100,
"mapService": -1
},
"off_site": {
"type": "FieldTypeDate",
"weighting": 100,
"mapService": -1
},
"creation_date": {
"type": "FieldTypeDate",
"weighting": 0,
"mapService": -1
},
"all_turbidity_values_within_limits": {
"type": "CODED_VALUE",
"domain": "domain_f_scriptexampleassetlevelall_turbidity_values_within_limits",
"weighting": 100,
"mapService": -1
},
"object_guid": {
"type": "FieldTypeString",
"weighting": 0,
"mapService": -1
},
"total_flow_l": {
"type": "FieldTypeInteger",
"weighting": 100,
"mapService": -1
},
"form_updated_date": {
"type": "FieldTypeDate",
"weighting": 100,
"mapService": -1
},
"meta_data": {
"type": "FieldTypePositionMetaData",
"weighting": 0,
"mapService": -1
},
"facility_id": {
"type": "FieldTypeString",
"weighting": 100,
"mapService": -1
},
"main_workorders_note": {
"type": "FieldTypeString",
"weighting": 100,
"mapService": -1
},
"geometry": {
"type": "FieldTypeGeometry",
"weighting": 100,
"mapService": -1
},
"workorder": {
"type": "FieldTypeInteger",
"weighting": 0,
"mapService": -1
},
"on_site": {
"type": "FieldTypeDate",
"weighting": 100,
"mapService": -1
},
"objectid": {
"type": "FieldTypeInteger",
"weighting": 0,
"mapService": -1
},
"last_update_date": {
"type": "FieldTypeDate",
"weighting": 0,
"mapService": -1
}
},
{
"ANDROID_DUMMY_PLACEHOLDER9223372036834367667": {
"type": "FieldTypePhotos",
"weighting": 0,
"mapService": -1
}
}
],
"domains": {
"domain_f_scriptexampleassetlevelall_turbidity_values_within_limits": {
"1": {
"domainName": "domain_f_scriptexampleassetlevelall_turbidity_values_within_limits",
"id": 1,
"description": "N/A",
"score": 0,
"sortOrder": 0,
"active": true
},
"2": {
"domainName": "domain_f_scriptexampleassetlevelall_turbidity_values_within_limits",
"id": 2,
"description": "Yes",
"score": 0,
"sortOrder": 1,
"active": true
},
"3": {
"domainName": "domain_f_scriptexampleassetlevelall_turbidity_values_within_limits",
"id": 3,
"description": "No",
"score": 0,
"sortOrder": 2,
"active": true
}
}
},
"categoryValues": {},
"categories": {},
"attachments": [],
"signatures": [],
"changedAttribute": "flow_duration_min",
"create": true,
"trigger": "AttributeChanged",
"currentUserId": 20408038,
"currentAppId": 20408095
}

UnityClient Javascript Object

On your mobile device, scripts have access to the UnityClient javascript object that contains numerous functions that can be called. For example, you can query the offline cache for feature details.

UnityClient.log(String message) {}

  • Returns: void
  • Function: Outputs message to mobile log file
  • Note: N/A

UnityClient.getChildren(long workOrderId, boolean includeUnsaved, boolean summary) {}

  • Returns: Stringified JSON
  • Function: Query for a parents child work orders (if summary = false, forms are also returned)
  • Note: This is only valid for classification forms as the workOrder and parentWorkOrder data objects do not contain the work order Id.
Copy

Example

var children = UnityClient.getChildren(workorder_id, true, false);
if(children != null && children != ""){
children = JSON.parse(children);
for (c in children){
var child = children[c];
var cwos = child.workOrderStatus;
.
.
.

UnityClient.getFormData(String formType, long formID) {}

  • Returns: Stringified JSON
  • Function: Query
  • Note: If formType is provided, the form of this type will be returned. If formType is not provided and formId is not 0, the form with this Id will be returned.

UnityClient.executeRestRequest(String url, String headers, String body, String method) {}

  • Returns: Stringified JSON
  • Function: This function can execute a rest request with the stringified result returned.
  • Note: N/A
Copy

Example

UnityClient.log("Submitting positive response");
var method = "POST";
var positiveResponseURL = missdigURL_root + missdigURL_positiveResponse;
headers = '{"Content-Type": ["application/json"], "Accept": ["application/json"], "Authorization": ["Bearer ' +
token + '"]}';
bbody = {
requestNumber: "" + requestNumber,
station: "" + station,
locateCode: "" + locateCode,
reason: "" + positiveResponseCodeComments,
isNoteVisibleToContractor: true,
accountNameOfPositiveResponseProvider: "" + accountNameOfPositiveResponseProvider,
trailId: "" + trailId
};
body = JSON.stringify(bbody);
response = JSON.parse(UnityClient.executeRestRequest(positiveResponseURL, headers, body, method));
responseBody = JSON.parse(response.body);

UnityClient.getToken() {}

  • Returns: String
  • Function: Returns a Unity Token for the current user.
  • Note: This may be useful if calling Unity rest end points for some reason.

UnityClient.getGlobalParameter(String key) {}

  • Returns: String
  • Function: Query
  • Note: N/A
Copy

Example

var myJsonGP = JSON.parse(UnityClient.getGlobalParameter("MY_GLOBAL_PARAMETER_NAME1"));
var myStringGP = UnityClient.getGlobalParameter("MY_GLOBAL_PARAMETER_NAME2");

UnityClient.project(String geometry, int outSRID) {}

  • Returns: String
  • Function: Query
  • Note: N/A

UnityClient.getFeatureDetail(String featureUrl) {}

  • Returns: Stringified JSON
  • Function: Query
  • Note: N/A

UnityClient.getReplicaItem(String replicaItemUrl) {}

  • Returns: Stringified JSON
  • Function: Query an offline Replica - i.e., an offline cache of some sort, these are custom offline caches of data.
  • Note: Replicas are SQL Lite databases that can accompany a tenant and contain some custom offline data that many need to be reference where no APIs are available. For example, a list of vehicles with additional available in a replica database.
Copy

Example

var vehicleLookup = UnityClient.getReplicaItem("referenceItems/vehicledetail/" + data.customForm.vehicle);
if (vehicleLookup) {
var vehicleLookupJson = JSON.parse(vehicleLookup); // returns the replica row detail
var vehicleLookupData = JSON.parse(vehicleLookupJson.data); // this specific implementation has a column
'data' that is a stringified json with more detail
result.summary.attributes.make_of_vehicle = { "value": vehicleLookupData.make };
result.summary.attributes.unit_number = { "value": vehicleLookupData.unitid };
result.summary.attributes.license_plate = { "value": vehicleLookupData.license };
.
.
.

UnityClient.getUser(long id) {}

  • Returns: Stringified JSON
  • Function: Query
  • Note: N/A

UnityClient.findReplicaItems(String replicaItemQueryUrl, boolean exact) {}

  • Returns: Stringified JSON
  • Function: Query an offline Replica - i.e., an offline cache of some sort, these are custom offline caches of data.
  • Note: Similar to getReplicaItem but does a partial match on the Id.

UnityClient.triggerSync(String taskSetName, boolean foreground) {}

  • Returns: String
  • Function: Prompt the mobile client to perform a sync.
  • Note: N/A

UnityClient.getDomainItem(long domainItemId) {}

  • Returns: Stringified JSON
  • Function: Query
  • Note: This will return a stringified JSON of the requested domainid (i.e. work order). The work order Id will only be available on classification forms.

UnityClient.cachePut(String key, String value) {}

  • Returns: Void
  • Function: Put/Overwrite an entry in a cache that is available while the client is running.
  • Note: N/A

UnityClient.cacheGet(String key) {}

  • Returns: String
  • Function: Get the value previously added to the cache for the given key.
  • Note: This will also remove the entry, if it is required again it would need to be re-added.

UnityClient.cacheRemove(String key) {}

  • Returns: String
  • Function: Get the value previously added to the cache for the given key.
  • Note: This will also remove the entry, if it is required again it would need to be re-added.