Reference¶
This section contains reference documentation for the Work Management web services.
Job Management¶
The Job Management services provide interfaces that allow external systems to connect to GeoManager, and to:
- Create and update tasks.
- Cancel tasks.
- Fetch task details.
- Retrieve a list of tasks that have been closed or changed during a specific time period.
- Close tasks.
- Set and retrieve the list of parts that are associated with a particular task.
- Retrieve a list of changes that have occurred to tasks.
- Close tasks as incomplete.
- Retrieve the reasons for rejecting a task, cancelling a task, or closing a task as incomplete.
- Progress tasks.
- Retrieve the list of timesheet approvals for a work order.
- Retrieve the list of tasks for a work order.
Note
Some of the Job Management services are SOAP-based (they use the Simple Object Access Protocol), while some follow the Representational State Transfer (REST) architectural style.
SOAP APIs¶
The SOAP APIs provide operations that allow you to:
- Create and update tasks.
- Cancel tasks.
- Fetch task details.
- Retrieve a list of tasks that have been closed during a specific time period.
- Close tasks.
REST APIs¶
These APIs follow the REST architectural style:
- Parts API: The Parts API allows you to set and retrieve the list of parts that are associated with a particular task.
- Get Task Updates API: The Get Task Updates API enables you to retrieve a list of changes that have occurred to tasks during a specified period.
- Close Incomplete API: The Close Incomplete API enables the specified task to be closed as incomplete so that it can be reassigned and completed by the same or a different employee.
- Customer Configuration API: The Customer Configuration API enables you to retrieve the predefined reasons needed for rejecting a task, cancelling a task or closing a task as incomplete.
- Progression API: The Progression API enables tasks to be progressed from the field.
- Work Order Timesheet Approval API: The Work Order Timesheet Approval API returns the timesheet approvals for the specified work orders or the specified employees, or all the work orders that were approved between two specified times.
- Removing employee information from work order approvals: The Work Order Remove Employee Info API removes the employee information for the specified work orders.
- Retrieving tasks for a work order: The Search API returns the tasks that belong to a work order.
Parts API¶
In Work Management, tasks can often only be completed when the right parts are available.
You can use the Parts API to set and retrieve the list of parts that are associated with a particular task.
The following table lists the HTTP methods that are supported by the Parts API:
| Operation (HTTP method) | API support in GeoManager? | Comment |
|---|---|---|
Create (POST) |
Yes | Provides the ability to associate parts with a task. |
Read (GET) |
Yes | Provides the ability to retrieve information about the parts that are associated with particular tasks. |
Update (PUT) |
No | Updating task-parts associations is not supported. |
Delete (DELETE) |
Yes | Provides the ability to delete the information about the parts that are associated with a particular task. |
The URL for the Parts API is:
https://<server_name>/wm-rest/v1/jobmanagement/parts
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Associating parts with a task¶
To associate parts with a task, you must use the HTTP POST method.
Note
Each time you use this service in relation to a particular task, any part information that has previously been stored against that task will be completely replaced with the new information.
HTTP request header¶
Include these lines in the header:
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
where:
<token>
is the access token obtained by calling the Access Token API.
Attributes¶
The following table describes the attributes that can be present in a request to associate parts with a task. The whole Parts JSON is limited to 4000 characters. There are no limits on individual attributes.
| Attribute | Mandatory? | Description |
|---|---|---|
| guid | No | The unique identifier of a part. This will typically be the catalog number for the part. |
| description | Yes | A description of the part. |
| measurementType | No | The unit of measurement (for example Count, Length or Volume) that is used when specifying the quantity of the part that was needed for a task. |
| unplanned | No | A boolean attribute that is used to specify that the part was not originally planned for the task, and was associated with the task by the technician in the field. Unplanned parts could either be selected from the catalogue, or bought-in.
If a part is unplanned, you should include this attribute and give it the value true. |
| quantityPlanned | Yes | The quantity of the part that is anticipated to be needed for the task. |
| quantityUsed | No | The quantity of the part that was actually used by the technician who carried out the task. |
| taskId | Yes | The identifier of the task with which the part is to be associated. |
| temporary | No | A boolean attribute that indicates that the part that was added by the technician is a non-catalogue part. |
| Cost | No | A numeric value that specifies the cost of non-catalogue parts that were added by the technician. The cost cannot include a currency symbol. |
Planned parts for a task¶
Often, the parts that are needed for a particular task are known in advance.
HTTP request body
Here is an example of the request body that would be used to specify the planned parts for a task:
{
"parts": [
{
"partInfo": {
"map": {
"guid": "1A144368-6E3B-0641-9C3D-8231D3A71046",
"description": "1 1/4\" CONDUIT - PVC40",
"measurementType": "Length",
"quantityPlanned": 4,
"quantityUsed": 4
}
}
},
{
"partInfo": {
"map": {
"guid": "4G1A144368-6E3B-0641-9C3D-8231D3A71046",
"description": "100A-120V IF LAMP",
"measurementType": "Count",
"quantityPlanned": 2,
"quantityUsed": 2
}
}
}
],
"taskId": {
"taskId": 492017
}
}
Sample JSON response
If the request was successful, the response header will contain the HTTP status code 200 . The HTTP response body will contain the ID of the task that has successfully had the parts associated with it:
{
taskId: 492017
}
Adding parts from the catalogue¶
For some tasks, it is sometimes necessary to add unplanned parts from the parts catalogue.
HTTP request body
Here is an example of the request body that would be used to add parts from the parts catalogue to a task. Note that because the parts being added to the task were unplanned when the task was initially created, the attribute ” unplanned ” is present and has a value of ‘ true ‘:
{
"parts": [
{
"partInfo": {
"map": {
"guid": "4G1A144368-6E3B-0641-9C3D-8231D3A71046",
"description": "1 1/4\" CONDUIT - PVC40",
"measurementType": "Length",
"unplanned": true,
"quantityPlanned": 0,
"quantityUsed": 3
}
}
}
],
"taskId": {
"taskId": 474743
}
}
Sample JSON response
If the request was successful, the response header will contain the HTTP status code 200 . The HTTP response body will contain the ID of the task that has successfully had the parts associated with it:
{
taskId: 474743
}
Adding parts that have been bought¶
Sometimes, parts that have been bought elsewhere (in other words, they are not in the catalogue) need to be added to a task. For example, a technician may need to buy a part from a local store.
HTTP request body
Here is an example of the request body that would be used to add parts that have been bought elsewhere. Note the presence of the attributes ” temporary ”, ” cost ”, and ” unplanned ”:
{
"parts": [
{
"partInfo": {
"map": {
"temporary": true,
"cost": 40,
"guid": "",
"description": "Synthetic 5W-30 Engine Oil",
"measurementType": "Litres",
"unplanned": true,
"quantityPlanned": 0,
"quantityUsed": 5
}
}
}
],
"taskId": {
"taskId": 474743
}
}
Sample JSON response
If the request was successful, the response header will contain the HTTP status code 200 . The HTTP response body will contain the ID of the task that has successfully had the parts associated with it:
{
taskId: 474743
}
Retrieving the parts that are associated with specific tasks¶
To retrieve information about the parts that are associated with particular tasks, you must use the HTTP GET method.
HTTP request header¶
Include these lines in the header:
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
where:
<token>
is the access token obtained by calling the Access Token API.
Retrieving the parts details for a single task¶
To retrieve the parts details for a single task you can use the following URL, appending the ID of the task for which you would like to retrieve the parts details. For example, to retrieve the parts information for task 474743:
https://<server_name>/wm-rest/v1/jobmanagement/parts?taskId=474743
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Sample JSON response
If the request was successful, and the header contained the content type application/json , the response header will contain the HTTP status code 200 . The HTTP response body will contain the parts information in JSON format:
{
"parts": [
{
"partInfo": {
"map": {
"guid": "",
"unplanned": true,
"quantityPlanned": 0,
"description": "Synthetic 5W-30 Engine Oil",
"measurementType": "Litres",
"temporary": true,
"quantityUsed": 5,
"cost": 40
}
}
}
],
"taskId": {
"taskId": 474743
},
"lastUpdatedDateTimeInMins": 1429613969
}
Retrieving the parts details for multiple tasks¶
To retrieve the parts details for more than one task you can use the following URL, appending the IDs of the tasks for which you would like to retrieve the parts details. For example, to retrieve the parts information for tasks 474743 and 492017:
https://<server_name>/wm-rest/v1/jobmanagement/parts/multi?taskId=474743&taskId=492017
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Sample JSON response
If the request was successful, and the header contained the content type application/json, the response header will contain the HTTP status code 200 . The HTTP response body will contain the parts information in JSON format:
[
{
"parts": [
{
"partInfo": {
"map": {
"temporary": true,
"cost": 40,
"guid": "",
"unplanned": true,
"description": "Synthetic 5W-30 Engine Oil",
"measurementType": "Litres",
"quantityPlanned": 0,
"quantityUsed": 5
}
}
}
],
"taskId": {
"taskId": 474743
},
"lastUpdatedDateTimeInMins": 1429613969
},
{
"parts": [
{
"partInfo": {
"map": {
"guid": "1A144368-6E3B-0641-9C3D-8231D3A71046",
"description": "1 1/4\" CONDUIT - PVC40",
"measurementType": "Length",
"quantityPlanned": 4,
"quantityUsed": 4
}
}
},
{
"partInfo": {
"map": {
"guid": "4G1A144368-6E3B-0641-9C3D-8231D3A71046",
"description": "100A-120V IF LAMP",
"measurementType": "Count",
"quantityPlanned": 2,
"quantityUsed": 2
}
}
}
],
"taskId": {
"taskId": 474743
},
"lastUpdatedDateTimeInMins": 1429613764
}
]
Deleting the parts that are associated with a task¶
To delete the information about the parts that are associated with a particular task, you must use the HTTP DELETE method.
You must use the following URL, appending the ID of the task for which you would like to delete the parts details. For example, to delete the parts information for task 474743:
https://<server_name>/wm-rest/v1/jobmanagement/parts?taskId=474743
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
HTTP request header¶
Include these lines in the header:
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
where:
<token>is the access token obtained by calling the Access Token API.
Sample JSON response¶
If the request was successful, the response header will contain the HTTP status code 200 . The HTTP response body will contain the ID of the task that has successfully had the parts information removed from it:
{
taskId: 474743
}
Get Task Updates API¶
The Get Task Updates API enables you to retrieve a list of changes that have occurred to tasks during a specified period.
The results that are returned can be filtered according to attributes that you supply in the request.
The URL for the Get Task Updates API is:
https://<server_name>/wm-rest/v1/jobmanagement/updates
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Retrieving a list of task updates¶
To retrieve a list of changes that have occurred to tasks, you must use the HTTP POST method.
The service reports only a single event per task.
This means that, in the event of multiple types of change being applied to a particular task over the period of time in question, the following order of precedence will be used to determine which event will be reported (in descending order of precedence):
- Task progressions
- Task updates
- Task creations
- Changes to task scheduling attributes
For example, if a particular task was both progressed and updated during the period of time that is of interest, the service will return the information that pertains to the task progression (rather than the task update). If you want to know about the task update, you should explicitly set the taskUpdates attribute to true when you make the request.
Support for crews¶
The service ensures that the closure of any sub-tasks results in both a task progression and an update change record being generated for the master task. Note that these change records will still contain the current status of the master task. Its presence in the reported list of updates signifies that one of the sub-tasks in the overall package of work has closed. The updateDateTime attributes of the task progression and update records will be set to the completion time of the sub-task (the time that the task moved to COM status).
This approach supports the service’s caller in its handling of the master task’s closure. The caller will be notified of changes to the master and sub-tasks via reference to the master task. When closures occur in any part of the package of work, the caller will be notified that the master task has changed. It will then be able to use the JobManagement service to assess if all the components of the package are complete, by sending a GetTaskDetailsRequest . The response will include details of any associated tasks, and the status of each of them.
If you want to retrieve a list of crew sub-tasks that have changed, you should explicitly set the crewChildTaskUpdates attribute to true when you make the request.
HTTP request header¶
Include these lines in the header:
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
where:
<token>
is the access token obtained by calling the Access Token API.
HTTP request body¶
The following table summarizes the filtering attributes that can be included in the request. They will modify the response so that only the specified subset of updated tasks will be returned.
| Attribute | Mandatory? | Description |
| sourceSystems | No | A list of names. Only updates to tasks that have been created by these source systems will be returned. If a value is not provided, updates to tasks from any source system will be returned. Tasks created by the WM product itself are known as system tasks. The SourceSystem attribute of these tasks can have one of the following default values:
When an external system creates a task, it can optionally provide a value for the SourceSystem attribute. If the external system does not provide a value, then the attribute will be given one of the following default values:
|
| orgUnitNames | No | A list of names. Only updates to tasks that are associated with the specified organizational units will be returned. If a value is not provided, updates to tasks from any organizational units will be returned. |
| fromDateTime | Yes | The number of minutes since the UNIX epoch time. |
| toDateTime | Yes | The number of minutes since the UNIX epoch time. |
| taskCreationUpdates | No | Boolean. When set to true, task update records will be returned for tasks that were created during the specified period. Crew sub-tasks will not be returned. When set to false, task creations occurring during the given period will not be reported. |
| taskProgressionUpdates | No | Boolean. When set to true, task update records will be returned for tasks that were progressed (tasks with a progression record representing a changed state) during the specified period. Only the last status change during the period will be reported. When set to false, task progressions will not be reported. |
| taskUpdates | No | Boolean. When set to true, task updates (changes to the attributes of a task) will be reported. When set to false, they will be ignored. |
| taskSchedulingUpdates | No | Boolean. When set to true,changes to the scheduling attributes of a task (such as the earliest start time, earliest completion time, and assigned employee) will be reported. When set to false, they will be ignored. Note: If changes to the scheduling attributes of a task are reported, then you can make use of the getTaskDetails() service to establish what has actually changed (i.e. the earliest start time, earliest completion time, or assigned employee). This is because if the task is part of a tour, and another task in the tour has been moved, all the tasks in the tour might have been marked as updated even though only the moved task has actually been updated. |
| crewChildTaskUpdates | No | Boolean. When set to true, changes to crew sub-tasks (tasks that have been assigned to technicians who are supporting the crew leader) will be reported. The reference or ID of the crew sub-task will be returned in the list of tasks that have changed during the specified time period. When set to false, crew sub-tasks will be ignored. |
| systemTasks | No | Boolean. When set to true,changes (task creation, progressions or updates) to tasks that have been generated by the system will be reported. System tasks are tasks where the value of the SourceSystem attribute is equal to WMUI , WMField or WM . When set to false, changes to system tasks will not be reported. |
Here is an example of the request body that would be used to retrieve all changes that occurred between 12:00 am (UTC) on April 1st 2015, and 12:00 AM (UTC) on April 22nd 2015.:
{
"fromDateTime": 23797440,
"toDateTime": 23827680
}
Here is an example of the request body that would be used to retrieve information about tasks that have been created, progressed, or updated between 12:00 AM (UTC) on April 1st 2015, and 12:00 AM (UTC) on April 22nd 2015. Note the presence of the attributes ” taskCreationUpdates ”, ” taskProgressionUpdates ”, and ” taskUpdates ”:
{
"sourceSystems": [
"T&M"
],
"orgUnitNames": [
"meporg"
],
"fromDateTime": 23797440,
"toDateTime": 23827680,
"taskCreationUpdates": false,
"taskProgressionUpdates": true,
"taskUpdates": true,
"systemTasks": true
}
Sample JSON response¶
The response that is received to the last request will look similar to this:
{
"taskUpdateList": [
{
"taskId": 487587,
"externalTaskReference": "TASK-001",
"sourceSystem": "WMUI",
"taskStatus": "COM",
"updateType": "P",
"updatedDateTime": 1429093800
},
{
"taskId": 487618,
"externalTaskReference": "TASK-002",
"sourceSystem": "T&M",
"taskStatus": "INC",
"updateType": "P",
"updatedDateTime": 1429266600
},
{
"taskId": 487588,
"externalTaskReference": "TASK-003",
"sourceSystem": "WMUI",
"taskStatus": "COM",
"updateType": "P",
"updatedDateTime": 1429353000
},
{
"taskId": 487625,
"externalTaskReference": "TASK-004",
"sourceSystem": "T&M",
"taskStatus": "FDS",
"updateType": "U",
"updatedDateTime": 1429525800
}
]
}
| Attribute | Description |
|---|---|
| taskId | The ID of the task. |
| externalTaskReference | The reference that has been give to the task by the donor system that created it. |
| sourceSystem | The identifier for the donor system from where the task has come. |
| updateType | The value will be U for task updates, P for task progressions, and C for task creation change records. |
| taskStatus |
|
| updatedDateTime |
|
Close Incomplete API¶
The CloseIncomplete web service enables the specified task to be closed as incomplete so that it can be reassigned and completed by the same or a different employee.
The external task reference or the task ID must be specified.
The employee identity, closure notes, reason for incomplete closure, time remaining and service-restored time are optional.
The start date and time, the finish date and time and the service restored time must be specified in ISO format.
For example:
2017-01-01T13:10:25.000Z
If one of these times is in the incorrect format, then the error 400 Bad Request is returned. The reason body will specify the attribute that was incorrect.
The reason for incomplete closure must exactly match one of the reasons that has been defined for this customer account. Note that the reason for incomplete closure is case sensitive.
If no match has been found for the specified reason for incomplete closure in this customer account, then the error 400 Bad Request is returned. The reason body will contain the error string:
incompleteReason[INCOMPLETE_REASON_2] is not defined
The time remaining is specified in minutes and can be greater than, less than, or equal to the original task duration. If the time remaining is outside the range, then the error 400 Bad Request is returned. The reason body will contain the error string:
timeRemaining should be between 1 and 59,999 minutes
This web service returns true when the task is closed successfully. This service supports both the GeoManager and the Trimble Identity tokens. To close a task as incomplete, you must use the HTTP POST method.
The URL for the Close Incomplete API is:
https://<server_name>/wm-rest/v1/jobmanagement/field/closeincomplete
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
{
"taskIdentity":
{
"externalTaskReference":"30512-010-BD-FEB"
},
"employeeIdentity":
{
"employeeId":"BDJG941"
},
"startDateTime":"2017-08-09T06:21:25.000Z",
"finishDateTime":"2017-08-09T11:24:25.000Z",
"closureNotes":"This task was closed from the API",
"incompleteReason":"INCOMPLETE_REASON_2",
"timeRemaining":180,
"serviceRestoredDateTime":"2017-08-09T13:54:34.000Z"
}
Customer Configuration API¶
The Customer Configuration API enables you to retrieve the predefined reasons needed for rejecting a task, cancelling a task or closing a task as incomplete. You can choose whether to include the deleted reasons. By delete the deleted reasons are not included.
The reasons must be defined on the Administration pages in GeoManager. They cannot be created, updated or deleted through the API.
To retrieve the reasons for rejecting a task, cancelling a task or closing a task as incomplete, you must use the HTTP GET method.
The URLs for the Customer Configuration API are:
https://<server_name>/wm-rest/v1/customerconfiguration/incompleteclosurereasons
https://<server_name>/wm-rest/v1/customerconfiguration/cancellationreasons?
includeDeletedReasons=true
https://<server_name>/wm-rest/v1/customerconfiguration/rejectionreasons?
includeDeletedReasons=true
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
Sample JSON response for reasons for incomplete closure¶
[
{
"name": "No one home",
"isActive": true,
"isDefault": false
},
{
"name": "Didn't have the equipment",
"isActive": true,
"isDefault": false
},
{
"name": "Needed assistance",
"isActive": true,
"isDefault": false
},
{
"name": "No access",
"isActive": true,
"isDefault": false
}
]
Sample JSON response for reasons for cancellation¶
[
{
"name": "No longer required",
"isActive": true,
"isDefault": true
},
{
"name": "Duplicate",
"isActive": true,
"isDefault": false
}
]
Sample JSON response for reasons for rejection¶
[
{
"name": "Road closure",
"isActive": true,
"isDefault": true
},
{
"name": "No equipment",
"isActive": true,
"isDefault": false
}
]
Progression API¶
The Progression API enables technicians to progress tasks from the field by using a third-party application instead of FieldMaster Technician. The status change is reflected in the schedule to enable the dispatcher to see the latest status.
The technician can perform the following actions through the REST API:
- Accept a task.
- Reject a task (specifying a reason for rejection, if needed).
- Indicate that the technician is en route to the task.
- Indicate that the technician is aborting the travel to the task (task returns to the Accepted status).
- Indicate that the technician is on the site of the task.
- Suspend a task (task returns to the Accepted status).
A task can be identified by the task ID or by the external task reference. The task ID takes precedence if it is specified.
The following values are accepted for the fieldProgression attribute:
- Accept
- Reject
- EnRoute
- EnRouteAborted
- OnSite
- Suspend
To progress a task, you must use the HTTP PUT method.
The URL for the Progression API is:
https://<server_name>/wm-rest/v1/jobmanagement/field/progression
The payload is the same for all progression actions, except for Reject, where the rejection reason is also given.
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
{
"taskIdentity":
{
"externalTaskReference":"QA3Unit113DEC219"
},
"fieldProgression":"Reject",
"rejectionReason" : "TASK\_REJECT\_REASON\_5"
}
Sample JSON response¶
true
Work Order Timesheet Approval API¶
The Work Order Timesheet Approval API takes one or more work order references and returns the timesheet approvals for those work orders. You can also specify one or more employees and return the timesheet approvals that were requested by those employees. Alternatively, you can return all the work orders that were approved between two specified times. For example, you could retrieve all the work orders that were approved on a particular day.
Note the following:
- The work order reference is not case sensitive but must be an exact match.
- You can specify the employees by employee ID or by internal resource ID. If both the employee ID and the internal resource ID are specified, then the internal resource ID takes precedence.
- This service supports both the GeoManager and the Trimble Identity tokens.
- The “from” and “to” times are specified as the number of minutes since the UNIX epoch (January 1, 1970 (midnight UTC/GMT)).
To retrieve the timesheet approvals, you must use the HTTP POST method.
https://<server_name>/wm-rest/v1/jobmanagement/workorder-timesheet-approval
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body using work order references¶
{
"workOrderReferences": ["<work_order_reference1>", "<work_order_reference2>"]
}
HTTP sample request body using employee identities¶
{
"employeeIdentities": [{"employeeId": "1121S"},{"resourceId": 527162}]
}
HTTP sample request body using approval times¶
Here is an example of the request body that would be used to retrieve all the work orders that were approved between 12:00 AM on September 11, 2017 and 11:59:59 PM on September 17, 2017:
{
"fromDateTime": 1505088000,
"toDateTime": 1505692799
}
Sample JSON response¶
[{
"workOrderReference": "work_order_reference1",
"workOrderTimesheetApprovals": [{
"approvalStartTimeGMT": "2017-09-08T05:40:00.000Z",
"approvalFinishTimeGMT": "2017-09-08T18:29:00.000Z",
"approvedTimeGMT": "2017-09-12T08:41:21.000Z",
"approvalId": 62,
"approverName": "ApproverAlison",
"approverSignature": "/files/5877413084aeb587fa242d8e",
"requesterName": "Emp1",
"requesterSignature": "/files/5877413184aeb587fa242d91",
"notes": "Notes made by Fred",
"taskTimes": [{
"taskId": 549242,
"externalTaskReference": "549242",
"timeType": "HRS",
"timeOfUpdateGMT": "2017-09-06T12:08:32.000Z",
"timeOfCreationGMT": "2017-09-06T12:07:32.000Z",
"dateTimeValue": "2017-09-06T01:00:00.000Z",
"duration": 35,
"subTimeType": {
"name": "NORMAL",
"id": 3
}
}]
"employeeIdentity": { "employeeId": "1019", "resourceId": 520520 }
}]
}, {
"workOrderReference": "work_order_reference2",
"workOrderTimesheetApprovals": [{
"approvalStartTimeGMT": "2017-09-05T08:00:00.000Z",
"approvalFinishTimeGMT": "2017-09-06T09:04:00.000Z",
"approvedTimeGMT": "2017-09-11T12:56:35.000Z",
"approvalId": 1,
"approverName": "ApproverArchie",
"approverSignature": "/files/58762b7f84aeb587fa242d17",
"requesterName": "TechnicianTheresa",
"requesterSignature": "/files/58762b8184aeb587fa242d1a",
"notes": "first from andrpid at 12:57 on 11_Jan",
"taskTimes": [{
"taskId": 547290,
"externalTaskReference": "547290",
"timeType": "HRS",
"timeOfUpdateGMT": "2017-09-04T11:30:35.000Z",
"timeOfCreationGMT": "2017-09-04T11:30:34.000Z",
"dateTimeValue": "2017-09-04T10:29:00.000Z",
"duration": 61,
"subTimeType": {
"name": "OTHER",
"id": 42
}
}, {
"taskId": 547298,
"externalTaskReference": "547298",
"timeType": "HRS",
"timeOfUpdateGMT": "2017-09-04T08:55:20.000Z",
"timeOfCreationGMT": "2017-09-04T08:54:37.000Z",
"dateTimeValue": "2017-09-03T16:30:00.000Z",
"duration": 300,
"subTimeType": {
"name": "WEEK_END",
"id": 2
}
}]
"employeeIdentity": { "employeeId": "1234", "resourceId": 874625 }
}, {
"approvalStartTimeGMT": "2017-09-11T00:00:00.000Z",
"approvalFinishTimeGMT": "2017-09-16T23:59:59.000Z",
"approvedTimeGMT": "2017-09-16T11:08:46.000Z",
"approvalId": 222,
"approverName": "ApproverAnne",
"approverSignature": "/files/587ca9bc84ae30257bf97cd2",
"requesterName": "TechnicianTerence",
"requesterSignature": "/files/587ca9bd84ae30257bf97cd5",
"notes": null,
"taskTimes": [{
"taskId": 547292,
"externalTaskReference": "547292",
"timeType": "HRS",
"timeOfUpdateGMT": "2017-09-04T12:40:06.000Z",
"timeOfCreationGMT": "2017-09-04T12:39:39.000Z",
"dateTimeValue": "2017-09-04T08:00:00.000Z",
"duration": 60,
"subTimeType": {
"name": "BREAK",
"id": 41
}
}]
"employeeIdentity": { "employeeId": "5634", "resourceId": 976543 }
}, {
"approvalStartTimeGMT": "2017-09-15T18:30:00.000Z",
"approvalFinishTimeGMT": "2017-09-16T10:30:00.000Z",
"approvedTimeGMT": "2017-09-17T11:56:51.000Z",
"approvalId": 241,
"approverName": "ApproverAlf",
"approverSignature": "/files/587e065a84ae30257bf97dfb",
"requesterName": "TechnicianTessa",
"requesterSignature": "/files/587e065f84ae30257bf97dfe",
"notes": null,
"taskTimes": [{
"taskId": 550546,
"externalTaskReference": "550546",
"timeType": "HRS",
"timeOfUpdateGMT": "2017-09-16T12:14:06.000Z",
"timeOfCreationGMT": "2017-09-16T12:14:07.000Z",
"dateTimeValue": "2017-09-16T10:30:00.000Z",
"duration": 60,
"subTimeType": {
"name": "NORMAL",
"id": 3
}
}]
"employeeIdentity": { "employeeId": "8764", "resourceId": 562436 }
}]
}]
Removing employee information from work order approvals¶
The Remove Employee Info web service removes the employee information for the work orders specified by one or more work order approval IDs. From FieldMaster Technician 1.12, the employee ID is included in work order timesheet approvals. This web service enables you to delete the employee information from approvals created with earlier versions of FieldMaster Technician, where the employee ID was not included.
To delete the employee information from work order approvals, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/jobmanagement/workorder-timesheet-approval/remove-employee-info
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
{ "woApprovalIds": [ 41,42,43 ] }
Retrieving tasks for a work order¶
The Search web service enables you to search for tasks based on a work order reference and at least one organizational unit name. This search returns the task IDs and the (external) task references of the tasks in the work order, sorted based on the task IDs.
Note the following:
- The work order reference is not case sensitive but must be an exact match.
- At least one organizational unit name must be specified.
- The organizational unit names are not case sensitive but must be an exact match.
- This service supports both the GeoManager and the Trimble Identity tokens.
To retrieve the list of tasks that belong to a work order, you must use the HTTP POST method.
https://<server_name>/wm-rest/v1/jobmanagement/search
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
{
"orgUnitNames":[ "MyOrgUnit" ],
"workOrderReference": "work_order_reference3"
}
Sample JSON response¶
[
{
"taskId": 529628,
"externalTaskReference": "529628"
},
{
"taskId": 541281,
"externalTaskReference": "541281"
}
]
Schedule Management¶
The ScheduleManagement Service provides a SOAP-based interface that allows CRM systems to assign and sequence work to employees (members of your mobile workforce). Specifically, it allows these third-party systems to:
- Assign tasks to employees.
- Unassign tasks from employees.
- Dispatch tasks to employees.
Field Employees¶
Field Employees API¶
The FieldEmployees API enables you to retrieve (GET) or update (PUT) the field employee information for one or more employees. This is the additional information about employees that is used by Work Management.
The field employee information contains the capabilities and work areas of an employee, together with the Work Management settings. The Work Management settings specify, for example, the employee’s efficiency, whether the employee is on call, and whether tasks are automatically dispatched to this employee. You can identify the employees by their employee IDs or by their internal resource IDs.
There are three types of information that can be updated for a field employee:
- Work areas
- Capabilities
- Work Management settings.
This information can be updated individually for a given field employee, or all at the same time.
For each type of information, you can decide to overwrite what is currently set for the chosen field employee, or to first perform a check, in case someone else has updated the field employee since it was last retrieved (optimistic update). Note that a dispatcher could be making changes to the field employee via the Work Management UI, at the same time as the API is also making changes.
You can update multiple field employees in a single request.
Note
If you update information for multiple employees in a single request, then the changes are applied in order. If one of the changes results in an error, then the update stops. The changes that have been updated before the error are retained but the changes after the error are not applied.
Note
Note that when you update work areas or capabilities for a field employee, all the current work areas or capabilities are replaced.
However, when you update the Work Management settings, only the specified attribute is updated. The other attributes are not changed.
For example, if you specify the following, only the calloutEnabled attribute is updated:
“wmSettings”: { “calloutEnabled”: true }
Field Employees API methods¶
The following table lists the HTTP methods that are supported by the Field Employees API:
| Operation (HTTP method) | API support in GeoManager? | Comment |
|---|---|---|
Create (POST) |
No | Creating field employee information is not supported. |
Read (GET) |
Yes | Provides the ability to retrieve field employee information. |
Update (PUT) |
Yes | Provides the ability to update field employee information. |
Delete (DELETE) |
No | Deleting field employee information is not supported. |
The URL for the Field Employees API is:
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Attributes¶
The following table describes the attributes that can be passed in a request to update field employee information.
| Attribute | Description |
|---|---|
| wmSettings | The Work Management settings for this field employee. |
| lastUpdatedDateTimeGMT | The last time this attribute was updated. This is given in ISO date format and in GMT. |
| autoDispatchEnabled | Whether “Dispatch tasks automatically” is enabled for this employee. |
| rollingTourSize | The number of tasks that are dispatched to this employee at any one time. This is the same as setting “Maintain x tasks on device” in Edit Employee in the user interface. |
| efficiencyFactor | The efficiency of the employee, expressed as a positive integer, which represents a percentage. |
| calloutEnabled | Whether the employee is on call. This setting is either true or false. |
| capabilities | The capability settings for this employee. |
| caps | Introduces the list of capabilities for this employee. |
| capabilityName | The name of the capability. If you specify a new capability name, ensure that you specify all the attributes. The new capability is added to the list of capabilities. |
| isAutoAssociated | Whether this attribute has been automatically associated (true) with the employee by a tool (such as the learner or an external tool) or by the dispatcher (false). The default is false. |
| ranking | The ranking of the capability. This setting is the same as setting 0, 1 or 2 stars on a capability in Edit Employee in the user interface. |
| workAreas | The work area settings for this employee. |
| areas | Introduces the list of work areas for this employee. |
| employeeIdentity | Identifies the employee by the employee ID (or by the internal resource ID of the employee, if required). |
| employeeID | The employee ID for the employee. |
| resourceID | The internal resource ID (driver key) for the employee. |
Errors reported by the Field Employees API¶
The following errors can be reported by the Field Employees API:
| Error | Description |
| 400 Bad Request | This is returned if the given JSON payload is structurally invalid or if the given request contains invalid data. The accompanying message describes the error. |
| 401 Unauthorized | This is returned if the caller has not provided the appropriate user credentials. |
| 404 Not Found | This is returned if the specified employee does not exist. |
| 422 Unprocessable Entity | This is returned if the request action violates business rules that have been set up to preserve the integrity of the employee’s data. |
| 500 Server Error | This is returned if the server has encountered an error while processing the request. |
Retrieving field employee information for two employees¶
To retrieve the field employee information for one or more employees, append the employee ID or the resource ID of each employee whose details you want to retrieve.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees?employeeId=QA3EMP3&
employeeId=QA3EMP2
or
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees?resourceId=459079&resourceId=459087
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
Sample JSON response¶
If the request was successful, the response header will contain the HTTP status code 200 . The HTTP response body will contain the field employee information in JSON format:
[
{
"wmSettings": {
"lastUpdatedDateTimeGMT": "2016-11-16 05:36:52",
"autoDispatchEnabled": true,
"rollingTourSize": 3,
"efficiencyFactor": 100,
"calloutEnabled": false
},
"capabilities": {
"lastUpdatedDateTimeGMT": "2017-02-24 18:27:29",
"caps": [
{
"capabilityName": "R104",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "R103",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "R104-DHG",
"isAutoAssociated": false,
"ranking": 1
}
]
},
"workAreas": null,
"employeeIdentity": {
"employeeId": "QA3EMP3"
}
},
{
"wmSettings": {
"lastUpdatedDateTimeGMT": "2017-02-21 22:27:00",
"autoDispatchEnabled": true,
"rollingTourSize": 4,
"efficiencyFactor": 150,
"calloutEnabled": false
},
"capabilities": {
"lastUpdatedDateTimeGMT": "2017-02-24 18:27:17",
"caps": [
{
"capabilityName": "R104-DHG#2",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "R102",
"isAutoAssociated": false,
"ranking": 2
},
{
"capabilityName": "R101",
"isAutoAssociated": false,
"ranking": 2
}
]
},
"workAreas": {
"lastUpdatedDateTimeGMT": "2016-12-30 13:37:18",
"areas": [
{
"workAreaName": "ip3000",
"isAutoAssociated": false
},
{
"workAreaName": "ip2000",
"isAutoAssociated": false
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2"
}
}
]
Updating the capabilities of an employee¶
This example sets the capabilities of the employee identified by employee ID QAEMP2 to AAA and BBB .
Note
This update includes the attribute lastUpdatedDateTimeGMT. If the value of this attribute is different in the database then the update will not go ahead and the exception TRMB_RESMGT_00003 will be returned.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"capabilities": {
"lastUpdatedDateTimeGMT": "2017-03-31 18:27:17",
"caps": [
{
"capabilityName": "AAA",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "BBB",
"isAutoAssociated": false,
"ranking": 1
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Updating the capabilities of an employee without optimistic checking¶
This example sets the capabilities of the employee identified by employee ID QAEMP2 to CCC and DDD . Note that this update does not include the attribute lastUpdatedDateTimeGMT . This means the update will go ahead, even if the data has been updated since the caller last read it.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"capabilities": {
"caps": [
{
"capabilityName": "CCC",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "DDD",
"isAutoAssociated": false,
"ranking": 1
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Updating the work areas of an employee¶
This example sets the work areas of the employee identified by employee ID QAEMP2 to ip3 and ip4 .
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"workAreas": {
"lastUpdatedDateTimeGMT": "2016-12-30 13:37:18",
"areas": [
{
"workAreaName": "ip3",
"isAutoAssociated": true
},
{
"workAreaName": "ip4",
"isAutoAssociated": false
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Updating the work areas of an employee without optimistic checking¶
This example sets the work areas of the employee identified by employee ID QAEMP2 to ip3 and ip4 .
In this case, no optimistic update token is provided and the call will overwrite the current values, even if updated by someone else since the caller read the values.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"workAreas": {
"areas": [
{
"workAreaName": "ip3",
"isAutoAssociated": true
},
{
"workAreaName": "ip4",
"isAutoAssociated": false
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Removing all the work areas from an employee¶
This example removes all the work areas from the employee identified by employee ID QAEMP2 .
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"workAreas":
{
"areas": []
},
"employeeIdentity":
{
"employeeId": "QA3EMP2"
}
}
]
Sample JSON response¶
OK
Updating the “Work Management Settings” of an employee¶
This example updates all the Work Management settings of employee QA3EMP2 . Note that this update includes the attribute lastUpdatedDateTimeGMT .
If the value of this attribute is different in the database, then the update will not go ahead and the exception TRMB_RESMGT_00003 will be returned.
Instead of updating all the settings, you can update a single attribute. See the next example for details.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"wmSettings": {
"lastUpdatedDateTimeGMT": "2017-02-21 22:27:00",
"autoDispatchEnabled": true,
"rollingTourSize": 5,
"efficiencyFactor": 120,
"calloutEnabled": true
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Updating the ‘rollingTourSize’ of an employee¶
This example updates the rollingTourSize attribute of the wmSettings for employee QA3EMP2 .
Only the value of rollingTourSize needs to be specified.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"wmSettings": {
"lastUpdatedDateTimeGMT": "2017-02-21 22:27:00",
"rollingTourSize": 7,
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Updating ‘efficiencyFactor’ without optimistic checking¶
This example updates the efficiencyFactor attribute of the wmSettings for employee QA3EMP2 . Only the value of efficiencyFactor needs to be specified. The efficiency factor is a positive number representing a percentage. The default efficiency is 100. This update does not include the attribute lastUpdatedDateTimeGMT , which means that the update will go ahead and overwrite the current value, even if the value has changed since it was read by the caller.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"wmSettings": {
"efficiencyFactor": 50
},
"employeeIdentity": {
"employeeId": "QA3EMP2",
"resourceId": -1
}
}
]
Sample JSON response¶
OK
Updating ‘calloutEnabled’ for many employees without optimistic checking¶
This example updates the calloutEnabled attribute of the wmSettings for employees QA3EMP2 and QAEMP3 . Only the value of calloutEnabled needs to be specified.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"wmSettings": {
"calloutEnabled": true
},
"employeeIdentity": {
"employeeId": "QA3EMP2"
}
},
{
"wmSettings": {
"calloutEnabled": true
},
"employeeIdentity": {
"employeeId": "QA3EMP3"
}
}
]
Sample JSON response¶
OK
Updating multiple aspects of an employee¶
This example updates the calloutEnabled attribute, the capabilities, and the work areas for employee QA3EMP2 .
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"wmSettings": {
"calloutEnabled": false
},
"capabilities": {
"lastUpdatedDateTimeGMT": "2017-03-02 09:49:06",
"caps": [
{
"capabilityName": "CAP1",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "CAP2",
"isAutoAssociated": false,
"ranking": 1
}
]
},
"workAreas": {
"lastUpdatedDateTimeGMT": "2017-03-02 12:27:11",
"areas": [
{
"workAreaName": "ip20",
"isAutoAssociated": false
},
{
"workAreaName": "ip21",
"isAutoAssociated": true
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2"
}
}
]
Sample JSON response¶
OK
Updating multiple aspects for multiple employees¶
This example updates the wmSettings , the capabilities, and the work areas for employees QA3EMP2 and QA3EMP3 .
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"wmSettings": {
"calloutEnabled": true
},
"capabilities": {
"lastUpdatedDateTimeGMT": "2017-03-02 14:18:10",
"caps": [
{
"capabilityName": "CAP1",
"isAutoAssociated": true,
"ranking": 1
},
{
"capabilityName": "CAP2",
"isAutoAssociated": true,
"ranking": 1
}
]
},
"workAreas": {
"lastUpdatedDateTimeGMT": "2017-03-02 14:18:10",
"areas": [
{
"workAreaName": "ip22",
"isAutoAssociated": false
},
{
"workAreaName": "ip23",
"isAutoAssociated": true
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2"
}
},
{
"wmSettings": {
"calloutEnabled": true
},
"capabilities": {
"lastUpdatedDateTimeGMT": "2017-03-02 14:16:49",
"caps": [
{
"capabilityName": "CAP1",
"isAutoAssociated": false,
"ranking": 1
},
{
"capabilityName": "CAP2",
"isAutoAssociated": false,
"ranking": 1
}
]
},
"workAreas": {
"lastUpdatedDateTimeGMT": "2017-03-02 14:16:49",
"areas": [
{
"workAreaName": "ip20",
"isAutoAssociated": false
},
{
"workAreaName": "ip21",
"isAutoAssociated": true
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP3"
}
}
]
Sample JSON response¶
OK
Updating multiple work areas for multiple employees, with an error in one of the updates¶
This example updates the work areas for employees QA3EMP2 and QA3EMP3 , but with an incorrect optimistic token for the second employee.
An error is generated for the second employee and its data is not updated. Any successful updates for the employees listed before this error will have been applied and committed to the database.
The error returned indicates the employee for which the error was raised. See the response section for details.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"workAreas": {
"lastUpdatedDateTimeGMT": "2017-03-07 14:16:37",
"areas": [
{
"workAreaName": "ip20",
"isAutoAssociated": true
},
{
"workAreaName": "ip21",
"isAutoAssociated": true
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP2"
}
} ,
{
"workAreas": {
"lastUpdatedDateTimeGMT" : "2017-03-07 14:16:00",
"areas": [
{
"workAreaName": "ip1",
"isAutoAssociated": true
},
{
"workAreaName": "ip2",
"isAutoAssociated": true
}
]
},
"employeeIdentity": {
"employeeId": "QA3EMP3"
}
}
]
Sample JSON response¶
{
"errorCode": "TRMB_RESMGT_00003",
"errorObject": {
"employeeId": "QA3EMP3",
"resourceId": 459079
}
}
Removing all work areas from an employee¶
This example removes all the work areas from the specified employee.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"workAreas":{
"areas":[
{
}
]
},
"employeeIdentity":{
"employeeId": "991726"
}
}
]
Sample JSON response¶
OK
Removing all work capabilities from an employee¶
This example removes all the work capabilities from the specified employee.
To update the field employee information, you must use the HTTP PUT method.
https://<server_name>/wm-rest/v1/fieldemployee/fieldemployees
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
HTTP sample request body¶
[
{
"capabilities": {
"caps": []
},
"employeeIdentity": {
"employeeId": "IWAAA01"
}
}
]
Sample JSON response¶
OK
Customer Configuration¶
The Customer Configuration Service follows the REST architectural style:
- Capabilities API: Get the list of employee capabilities that are currently configured for a GeoManager account.
Capabilities API¶
In Work Management, particular types of task can only be performed by employees who have specific capabilities, or skills.
You can use the Capabilities API to retrieve the list of employee capabilities that are currently defined.
The following table lists the HTTP methods that are supported by the Capabilities API:
| Operation (HTTP method) | API support in GeoManager? | Comment |
|---|---|---|
Create (POST) |
No | Creating employee capabilities via the web service is not supported. |
Read (GET) |
Yes | Provides the ability to get all the employee capabilities that are defined for the user’s account. |
Update (PUT) |
No | Updating an employee capability is not supported. |
Delete (DELETE) |
No | Deleting an employee capability is not supported. |
The URL for the Capabilities API is:
https://<server_name>/wm-rest/v1/customerconfiguration/capabilities
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Capabilities API methods¶
Reading employee capabilities¶
To retrieve all the employee capabilities that have been defined for your account, you must use the HTTP GET method.
HTTP request header¶
Include these lines in the header:
Content-Type: <type>
Authorization: Bearer <token>
where:
<type>is eitherapplication/jsonorapplication/xml, depending upon the format in which you would like the employee capability information to be returned.<token>is an access token that has been obtained by calling the Access Token API.
Sample XML response¶
If the request was successful, and the header contained the content type
application/xml
, the response header will contain the HTTP status code
200
. The HTTP response body will contain the employee capability information in XML format:
<xml version="1.0" encoding="UTF-8" standalone="yes"?>
<capabilitiesResponse>
<capabilities>
<capability>
<capabilityName>111</capabilityName>
</capability>
<capability>
<capabilityName>222</capabilityName>
</capability>
</capabilities>
</capabilitiesResponse>
Sample JSON response¶
If the request was successful, and the header contained the content type application/json, the response header will contain the HTTP status code
200
. The HTTP response body will contain the employee capability information in JSON format:
{
"capabilities":[
{"capabilityName":"111"},
{"capabilityName":"222"}
]
}
Employee Absence¶
The Employee Absence Service follows the REST architectural style:
- Absences API: Create, retrieve and delete periods of in-day absence for employees.
Absences API¶
The Absences API enables you to create, retrieve and delete periods of in-day absence for employees.
The following table lists the HTTP methods that are supported by the Employee Absence API:
| Operation (HTTP method) | API support in GeoManager? | Comment |
|---|---|---|
Create (POST) |
Yes | Provides the ability to create a single period of absence for a number of specified employees. |
Read (GET) |
Yes | Provides the ability to retrieve information about the absence of a specified employee, or all employees, during a particular period of time. |
Update (PUT) |
No | Updating a period of absence is not supported. |
Delete (DELETE) |
Yes | Provides the ability to delete a single period of absence, for a number of specified Employees. |
The URL for the Employee Absence API is:
https://<server_name>/wm-rest/v1/employeeabsence/absences
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Absences API methods¶
Retrieving employee absence details¶
To retrieve details of the periods of absence that have been taken by a specified employee (or all employees) over a certain timespan, you must use the HTTP GET method.
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
Request parameters¶
The following table summarizes the parameters that can be passed in the request.
| Parameter | Mandatory? | Description |
|---|---|---|
| employeeId | No | The identifier of the employee whose absences you would like to retrieve. If this parameter is not present in the request then absences for all employees over the specified timespan will be returned. |
| fromDateTime | Yes | The beginning of the timespan for which you would like to retrieve the absences, specified as the number of minutes since the UNIX epoch. |
| toDateTime | Yes | The end of the timespan for which you would like to retrieve the absences, specified as the number of minutes since the UNIX epoch. |
Retrieving the absence details for a single employee¶
To retrieve the absence details for a single employee you can use the following URL, appending the ID of the employee for whom you would like to retrieve the absence details. For example, to retrieve the information about the absences that employee BDAAA04 took between 12:00 AM on 10th June 2015 and 12:00 AM on 30th June 2015:
https://<server_name>/wm-rest/v1/employeeabsence/absences?employeeId=BDAAA04&fromDateTime=23898240&toDateTime=23927040
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Errors
You may receive the following error messages if there is a problem with the request that you send:
| Error | Description |
|---|---|
| “TRMB_RESMGT_RESOURCE_DOES_NOT_EXIST” | The specified employee ID is invalid. |
| “TRMB_EMPABS_INVALID_ABSENCE_TIMERANGE” | An invalid timespan was specified. |
Retrieving the absence details for all employees¶
To retrieve the absence details for all employees you can use the following URL. For example, to retrieve the information about the absences that all employees took between 12:00 AM on 10th June 2015 and 12:00 AM on 30th June 2015:
https://<server_name>/wm-rest/v1/employeeabsence/absences?fromDateTime=23898240&toDateTime=23927040
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Errors
You may receive the following error message if there is a problem with the request that you send:
| Error | Description |
|---|---|
| “TRMB_EMPABS_INVALID_ABSENCE_TIMERANGE” | An invalid timespan was specified. |
Sample JSON response
If the request was successful, the response header will contain the HTTP status code 200 . The HTTP response body will contain the employee absence information in JSON format:
[
{
"absences":[
],
"employeeIdentity":{
"employeeId":"BDAAA02",
"resourceId":517528
}
},
{
"absences":[
],
"employeeIdentity":{
"employeeId":"BDAAA03",
"resourceId":517529
}
},
{
"absences":[
{
"fromDateTime":23899560,
"toDateTime":23901000,
"absenceTypeString":"PERSONAL ABSENCE"
},
{
"fromDateTime":23918280,
"toDateTime":23919719,
"absenceTypeString":"Annual leave"
},
{
"fromDateTime":23920320,
"toDateTime":23920560,
"absenceTypeString":"Meeting"
},
{
"fromDateTime":23921160,
"toDateTime":23922599,
"absenceTypeString":"Meeting"
}
],
"employeeIdentity":{
"employeeId":"BDAAA04",
"resourceId":517530
}
}
]
Creating employee absences¶
To create a single period of absence for one or more specified employees, you must use the HTTP POST method.
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
Attributes¶
The following table summarizes the attributes that can be present in the request.
| Attribute | Mandatory? | Description |
|---|---|---|
| employeeId | Yes | The identifier of an employee to whom the specified period of absence applies. The request can contain more than one employee ID. |
| absenceTypeString | Yes | A string that specifies the type of absence that you want to create. The absence type must already be defined within GeoManager. |
| fromDateTime | Yes | The beginning of the period of absence that you would like to create, specified as the number of minutes since the UNIX epoch. |
| toDateTime | Yes | The end of the period of absence that you would like to create, specified as the number of minutes since the UNIX epoch. |
HTTP request body¶
Here is an example of the request body that would be used to create an absence relating to a meeting attended by employees QA3EMP2 and QA3EMP3 between 10:00 AM and 11:00 AM on 25th June 2015:
{
"absenceRecord":{
"fromDateTime":23920440,
"toDateTime":23920500,
"absenceTypeString":"Meeting"
},
"employeeIdentities":[
{
"employeeId":"QA3EMP2"
},
{
"employeeId":"QA3EMP3"
}
]
}
If the request is successful, then the HTTP status code 200 OK will be returned.
Errors
You may receive the following error messages if there is a problem with the request that you send:
| Error | Description |
|---|---|
| “TRMB_EMPABS_INVALID_REQUEST” | A generic error that indicates that the request body was malformed in some way. For example, this error will be raised if there are no employeeId attributes in the request. |
| “TRMB_RESMGT_RESOURCE_DOES_NOT_EXIST” | One or more of the employee identifiers that were in the request are invalid. The error response will include an array that contains the invalid identifiers. |
| “TRMB_EMPABS_INVALID_ABSENCE_TIMERANGE” | An invalid timespan was specified. |
| “TRMB_EMPABS_INVALID_ABSENCE_TYPE” | The request contained an absence type that has not been defined in GeoManager. |
| “TRMB_EMPABS_NO_ABSENCE_TYPES” | No absence type was specified. |
| “TRMB_EMPABS_INVALID_ABSENCE_TYPE_ID_STRING” | The request contained an absence type that has not been defined in GeoManager. |
Deleting employee absence details¶
To delete a specific period of absence for one or more employees, you must use the HTTP DELETE method.
HTTP request header¶
Include these lines in the header:
Content-Type: application/json
Accept : application/json
Authorization: Bearer <token>
where:
<token>is an access token that has been obtained by calling the Access Token API.
Request parameters¶
The following table summarizes the parameters that can be passed in the request.
| Parameter | Mandatory? | Description |
|---|---|---|
| employeeId | Yes | The identifier of an employee for whom you would like to delete the absence details. |
| absStartTime | Yes | The start time of the period of absence, specified as the number of minutes since the UNIX epoch. |
| absEndTime | Yes | The end time of the period of absence, specified as the number of minutes since the UNIX epoch. |
To delete a specific period of absence for one or more employees you can use the following URL. For example, to delete the information about the period of absence that employees QA3EMP2 and QA3EMP3 took between 8:00 AM and 9:00 AM on 13th July 2015:
https://<server_name>/wm-rest/employeeabsence/absences?absStartTime=23946240&absEndTime=23946300&employeeId=QA3EMP2&employeeId=QA3EMP3
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
If the request is successful, then the HTTP status code 200 OK will be returned.
Errors
You may receive the following error messages if there is a problem with the request that you send:
| Error | Description |
|---|---|
| “TRMB_RESMGT_RESOURCE_DOES_NOT_EXIST” | One or more of the employee identifiers that were in the request are invalid. The error response will include an array that contains the invalid identifiers. |
| “TRMB_EMPABS_INVALID_ABSENCE_TIMERANGE” | An invalid timespan was specified. |
Template¶
The Trimble Template services enable customers to build dynamic form templates, based on their current business needs and their information workflow. These forms can then be filled in by field workers when they are working on tasks, and sent back to the server.
Templates can be created from within the Closure Template Editor in Work Management or via web services.
Template identifiers appear in the Work Management messages getTaskDetails
and getTaskClosures. While the task is active (not closed or historic) the
formDataDetailList node in the template structure appears in getTaskDetails.
Once the task has been closed, the template structure disappears from
getTaskDetails and appears in getTaskClosures.
A template can consist of a collection of fields, other embedded templates, and a template header.
Terminology¶
The following table describes the terms used in the Templates API:
| Term | Description |
| Application | The application that will use this template. |
| Template | The collection of nodes that make up a form. |
| Node | A field, an embedded template, or a template header. |
| Field | An individual field in a form. |
| Field option | A field option can be, for example, a radio button, a check box, or a combo box. |
| Content block | The template header. |
| Rule | The rules that govern the field, such as its default value, minimum value, and maximum value. |
| Rule action | Describes the operation that will be carried out on a field based on the evaluation of the rule. For example, a field or an embedded template could be hidden when a particular field is filled. |
Templates API methods¶
The following table lists the HTTP methods that are supported by the Templates API:
| Operation (HTTP method) | API support in GeoManager? | Comment |
Create (POST) |
Yes | Provides the ability to create a template and to post template data. |
Read (GET) |
Yes | Provides the ability to retrieve a template by name or ID, and to retrieve template data. |
Update (PUT) |
Yes | Provides the ability to update a template and publish a template. |
Delete (DELETE) |
Yes | Provides the ability to delete a template. |
The URL for the Templates API is:
https://<server_name>/wm-rest/v1/templates
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Template Data API methods¶
The following table lists the HTTP methods that are supported by the Template Data API:
| Operation (HTTP method) | API support in GeoManager? | Comment |
Create (POST) |
Yes | Provides the ability to post template data. |
Read (GET) |
Yes | Provides the ability to retrieve template data. |
Update (PUT) |
No | Updating template data is not supported. |
Delete (DELETE) |
No | Deleting template data is not supported. |
The URL for the Template Data API is:
https://<server_name>/wm-rest/v1/templatedata
where
<server_name> is
www.road.comfor Region 1 (Americas) accounts, andeugm.road.comfor Region2 (Europe, Middle East, Africa, Australia, Asia Pacific) accounts.
Request attributes¶
The following tables summarize the attributes that can be passed in the request.
Template attributes¶
| Attribute | Mandatory? | Description |
|---|---|---|
| id | No | The template ID. |
| application | Yes | The name of the application that will use this template. Minimum 2 characters, maximum 255 characters. |
| category | Yes | The category of this template within the application that uses it. Minimum 2 characters, maximum 255 characters. |
| version | No | The version of the template. Minimum 1 character. |
| published | Yes | Boolean. Indicates whether this template has been published. The default is false. |
| embeddable | Yes | Boolean. Indicates whether this template can be embedded in another template. The default is false. |
| name | Yes | The name of the template. This must be unique across the templates and is for internal use only. Minimum 2 characters, maximum 255 characters. |
| label | Yes | The display name of the template. This can be used to identify the template or as a localization lookup key. Minimum 2 characters, maximum 255 characters. |
| rules | No | The list of rules for this template. The rules specify for example whether the field is mandatory, the default value, or a dynamic rule. |
| jsonSchema | No | This can be ignored. |
| xmlSchema | No | This can be ignored. |
| nodes | No | The list of nodes (fields, embedded templates, content headers) for this template. |
Rule attributes¶
| Attribute | Mandatory? | Description |
| configurable | Yes | Indicates whether this rule is configurable. For example, you could deactivate the rule at the template level. |
| label | Yes | The display name of the rule. This can be used to identify the rule or to describe its purpose. |
| description | No | The description of the rule and its purpose. This could include some implementation details. |
| errorMessage | No | The error message that will be displayed if the rule is not satisfied. |
| errorCode | No | The error code that will be used to display a localized error message if the rule is not satisfied. |
| evaluation | No | The evaluation that will be carried out, such as required, min, or max. There can only be one evaluation for each rule. |
| operations | No | A list of operations that make up the rule, such as showing and hiding related items. |
Rule action attributes¶
| Attribute | Mandatory? | Description |
| type | Yes | The type of rule action, which can be OPERATION or EVALUATION. |
| task | No | The JSON string representation of the function that will be executed to implement this rule. |
| taskRef | Yes | The name of the function on the client that executes the rule. If the function is stored in the task, then this reference will be SELF. For example, the function could be called exists, which would test whether the field value exists. |
| async | No | This indicates whether this rule uses asynchronous function calls. |
| source | Yes | The source ID of the rule action. It is the ID of the field. |
| target | Yes | The target of the rule action, which can either be the ID of another item, or the string SELF, depending on the application. |
| targetType | Yes | The target type of the rule action, which can be FIELD, TEMPLATE or CONTENTBLOCK. |
| parameters | No | A list of the parameters involved in the execution of this rule action. |
Rule action parameter attributes¶
| Attribute | Mandatory? | Description |
| label | Yes | The display name of the parameter. |
| value | Yes | The value of the parameter. |
| type | Yes | The type of rule action parameter, which can be INTERNAL or EXTERNAL. |
| description | No | A description of the purpose of the parameter. |
Node attributes¶
| Attribute | Mandatory? | Description |
| type | Yes | The type of template node being described, which can be FIELD, TEMPLATE or CONTENTBLOCK. Minimum 2 characters, maximum 255 characters. |
| nestable | Yes | Boolean. Indicates if the node can have other nodes contained within it. The default is true. |
| field | No | The list of attributes that describe the field. This attribute is required if the node type is FIELD. |
| template | No | The list of attributes that describe the template. This attribute is required if the node type is TEMPLATE. |
| contentBlock | No | The list of attributes that describe the content block. This attribute is required if the node type is CONTENTBLOCK. |
| nodes | No | The list of nodes contained within this node. |
Field attributes¶
| Attribute | Mandatory? | Description |
|---|---|---|
| id | No | The field ID. |
| application | Yes | The name of the application that will use this field. Minimum 2 characters, maximum 255 characters. |
| category | Yes | The category of this field within the application that uses it. Minimum 2 characters, maximum 255 characters. |
| name | Yes | The internal name of the field. This can be the same as the label. |
| version | No | The version of the field. Minimum 1 character. |
| published | No | Boolean. Indicates whether this field has been published. The default is false. |
| label | Yes | The display name of the field. |
| code | No | The localization lookup key for this field. This can be ignored. |
| valueType* | Yes | The type of values accepted by the field, which can be INTEGER, FLOAT, DATE, DATETIME or STRING. |
| inputType | Yes | Indicates the type of construct used to capture the field data, such as a directive name. |
| optionType | No | The type of option values for this field, which can be SINGLE or MULTIPLE. |
| options | No | The list of options for this field. Each option can be, for example, a radio button, a check box, or a combo box. |
| rules | No | The list of rules for this field.” |
Field option attributes¶
| Attribute | Mandatory? | Description |
|---|---|---|
| label | Yes | The display name of the option. |
| value | Yes | The value that will be stored when this option is selected. |
| code | Yes | The localization lookup key for this option. |
Content block attributes¶
| Attribute | Mandatory? | Description |
|---|---|---|
| id | Yes | The ID of this content block, which is set by the client. This allows rules to target this block. |
| content | Yes | The content of the block. |
| renderer | Yes | The renderer of the content of the block. |
Creating a template¶
To create a template, you must use the HTTP POST method.
https://<server_name>/wm-rest/v1/templates
HTTP request header¶
Include these lines in the header:
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
where:
<token>
is the access token obtained by calling the Access Token API.
HTTP sample request body¶
{
"application": "FieldService",
"category": "WMTaskClosure",
"version": 1,
"published": true,
"embeddable": false,
"name": "Parts Information-12-12-2016 15:53:45",
"label": "Parts Information",
"rules": [
],
"jsonSchema": null,
"xmlSchema": null,
"nodes": [
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "model",
"label": "MODEL",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [ ]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
},
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "serialNumber",
"label": "Serial Number",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [
]
},
{
"label": "Default...",
"description": "Default value",
"errorMessage": "",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "default",
"parameters": [
{
"label": "default",
"value": "1000"
}
]
},
"operations": [ ]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
},
{
"type": "TEMPLATE",
"nestable": false,
"field": null,
"template": {
"id": "56a8aec42b4891a66613d989",
"name": "MeterReading",
"label": "Meter Reading",
"rules": [
{
"label": "Multiple...",
"description": "Multiple values are accepted",
"errorMessage": "",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "multiple",
"parameters": [
]
},
"operations": [ ]
}
],
"jsonSchema": "null",
"xmlSchema": "null",
"nodes": [
{
"type": "FIELD",
"nestable": true,
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "partNumber",
"label": "Part Number",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [
]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
},
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "model",
"version": 1,
"published": false,
"label": "Quantity",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [
]
},
{
"label": "Default...",
"description": "Default value",
"errorMessage": "",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "default",
"parameters": [
{
"label": "default",
"value": "0",
}
]
},
"operations": [
]
},
{
"label": "Greater than or equal to...",
"description": "Field value must be greater than or equal to the specified threshold",
"errorMessage": "Please provide a value.",
{
"application": "FieldService",
"category": "WMTaskClosure",
"version": 1,
"published": true,
"embeddable": false,
"name": "Parts Information-12-12-2016 15:53:45",
"label": "Parts Information",
"rules": [
],
"jsonSchema": null,
"xmlSchema": null,
"nodes": [
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "model",
"label": "MODEL",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [ ]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
},
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "serialNumber",
"label": "Serial Number",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [
]
},
{
"label": "Default...",
"description": "Default value",
"errorMessage": "",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "default",
"parameters": [
{
"label": "default",
"value": "1000"
}
]
},
"operations": [ ]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
},
{
"type": "TEMPLATE",
"nestable": false,
"field": null,
"template": {
"id": "56a8aec42b4891a66613d989",
"name": "MeterReading",
"label": "Meter Reading",
"rules": [
{
"label": "Multiple...",
"description": "Multiple values are accepted",
"errorMessage": "",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "multiple",
"parameters": [
]
},
"operations": [ ]
}
],
"jsonSchema": "null",
"xmlSchema": "null",
"nodes": [
{
"type": "FIELD",
"nestable": true,
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "partNumber",
"label": "Part Number",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [
]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
},
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "model",
"version": 1,
"published": false,
"label": "Quantity",
"code": "",
"valueType": "STRING",
"inputType": "text",
"optionType": null,
"options": [
],
"rules": [
{
"label": "Must exist...",
"description": "Field value must exist",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists",
"parameters": [
]
},
"operations": [
]
},
{
"label": "Default...",
"description": "Default value",
"errorMessage": "",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "default",
"parameters": [
{
"label": "default",
"value": "0",
}
]
},
"operations": [
]
},
{
"label": "Greater than or equal to...",
"description": "Field value must be greater than or equal to the specified threshold",
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "gte",
"parameters": [
{
"label": "threshold",
"value": "1",
"description": "Enter the minimum value for this field"
}
]
},
"operations": [
]
}
]
},
"template": null,
"contentBlock": null,
"nodes": [
]
}
]
},
"contentBlock": null,
"nodes": [
]
}
]
}
Examples of different input types¶
Creating a text box¶
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "partNumber",
"label": "Part Number",
"valueType": "STRING",
"inputType": "text",
"rules": [
{
"errorMessage": "Please provide a value.",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists"
}
}
]
}
}
Creating a drop-down list¶
{
"type": "FIELD",,
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "part Qty",
"label": "Part Qty",
"valueType": "SELECT",
"inputType": "dropdown",
"optionType": "NUMBER",
"options": [
{
"label":"p1",
"value":1
},
{
"label":"p2",
"value":2
}
],
"rules": [
{
"errorMessage": "Please provide a value.",
"errorCode": "undefined",
"evaluation": {
"type": "EVALUATION",
"taskRef": "exists"
}
}
]
}
}
Creating a date selector¶
{
"type": "FIELD",
"field": {
"id": "56a8ad4a2b4891a66613d987",
"name": "Date",
"label": "Installed Date",
"valueType": "DATE",
"inputType": "date",
"rules": [
{
"errorMessage": "Dates cannot be in the past",
"evaluation": {
"type": "EVALUATION",
"taskRef": "past",
"parameters": [
"label": "past",
"value": false,
]
}
}
]
}
}
Creating a task closure template¶
Note that the employees can enter data in the closure template without closing the task. This data is available to external callers before the task is closed.
{
"application":"FieldService",
"category":"WMTaskClosure",
"name":"Parts Information-12-12-2016 15:53:45",
"label":"Parts Information",
"nodes":[
{
"type":"FIELD",
"field":{
"id":"56a8ad4a2b4891a66613d987",
"name":"model",
"label":"MODEL",
"valueType":"STRING",
"inputType":"text",
"rules":[
{
"errorMessage":"Please provide a value.",
"evaluation":{
"type":"EVALUATION",
"taskRef":"exists"
}
},
{
"evaluation": {
"type": "EVALUATION",
"taskRef": "default",
"parameters": [
{
"label": "default",
"value": "0",
}
]
}
]
}
}
]
}
Posting template data¶
To post template data, you must use the HTTP POST method.
https://<server_name>/wm-rest/v1/templatedata
HTTP request header¶
Include these lines in the header:
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
where:
<token>
is the access token obtained by calling the Access Token API.
HTTP sample request body¶
{
"templateId": "urn:trmb-gsp:template-74695",
"templateLabel": "METER READING",
"values": {
"cfde70220ebd50583c66b359dbe2ccd3": {
"valueType": "STRING",
"label": "Model",
"value": "Hammer"
},
"cfde70220ebd50583c66b359dbe2ccd4": {
"valueType": "STRING",
"label": "SerialNumber",
"value": "SE12312"
},
"cfde70220ebd50583c66b359dbe2ccd5": {
"valueType": "TEMPLATE",
"label": "MeterReading",
"value": [
{
"cfde70220ebd50583c66b359dbe2ccd6": {
"valueType": "STRING",
"label": "PartNumber",
"value": "Hammer11"
},
"cfde70220ebd50583c66b359dbe2ccd7": {
"valueType": "STRING",
"label": "QUANTITY",
"value": "2"
}
},
{
"cfde70220ebd50583c66b359dbe2ccd6": {
"valueType": "STRING",
"label": "PartNumber",
"value": "Hammer22"
},
"cfde70220ebd50583c66b359dbe2ccd7": {
"valueType": "STRING",
"label": "QUANTITY",
"value": "5"
}
}
]
}
}
}