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.

See also

  • Reference documentation for the Job Management SOAP APIs can be found here.
  • The WSDL and schema files can be downloaded in a self-contained zip file.

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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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:

  • WMField: This value indicates that a task was created via the FieldMaster Technician app.
  • WM: This value indicates that a task was created as part of the creation of a crew.
  • WMUI: This value indicates that a task was created via the Work Management user interface.

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:

  • WMSoapService: This value indicates that a task was created by the SOAP Web Services.
  • WMUpload: This value indicates that a task was created via the task upload mechanism.
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
  • For a task update and task creations change records, this value will be the task status at the time of calling this web service.
  • For task progression change records, this value will be set to the status of the task at the end of the specified time window.
updatedDateTime
  • For task creation change records, this value will be the task creation time.
  • For task progression change records, this value will be the latest progression timestamp in the specified time window.For task update change records, this value will be set to the latest time that the task was updated during the specified time period.

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"
}
Sample JSON response

If the task closure was successful, the following response is returned:

true

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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.

See also

  • Reference documentation for the Schedule Management SOAP APIs can be found here.
  • The WSDL and schema files can be downloaded in a self-contained zip file.

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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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 either application/json or application/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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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.com for Region 1 (Americas) accounts, and
  • eugm.road.com for 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"
                    }
                  }
            ]
          }
    }
  }