Concepts

This section covers important concepts that you should be familiar with before using the Work Management Web Services.

Security

The Work Management Web Services use OAuth, over HTTPS, to control access. An OAuth access token should be included in the HTTP header in every request that is made to the web services.

To obtain an OAuth access token, you must use the Token API. The Token API is a REST-style API that is provided by the API Manager, which is part of your deployment.

The URL for the Token API will be of the following form (where <machine> is the name or IP address of the web server that is exposing the Token API):

https://{<machine>/wsapi/v3/tokens

The following HTTP request header should be supplied:

Accept: application/json

The HTTP request payload should look like this:

{"identity":{"username":"gmuser", "password":"ada191"}}

Warning

User names should not contain uppercase letters.

Note

For privacy of information, Transport Layer Security (HTTPS) is used to encrypt each request.

A successful request will receive an HTTP response payload, similar to this, which contains an OAuth token:

{"token":{"bearer":"rkBsZZjrowJDGwSxWQCW55fEYvka","crtdDt":"2014-10-02T14:27:47.000Z","exprDt":"2014-10-03T14:27:47.000Z"}}

If invalid user name and password credentials are present in the request, then an HTTP 401 (“Unauthorized”) response will be received.

Once an access token has been retrieved, it must be supplied in the header of subsequent web service requests. For example:

POST /soapapi/JobManagementV6/v1 HTTP/1.1

Content-Type: text/xml; charset=utf-8

Authorization: Bearer rkBsZZjrowJDGwSxWQCW55fEYvka

SOAPAction: ""

Host: www.road.com

Content-Length: 2488

Expect: 100-continue

Accept-Encoding: gzip, deflate

JobManagement

The JobManagement Service allows you to:

  • Create and update tasks.
  • Cancel tasks.
  • Fetch the details of an existing task.
  • Retrieve the list of tasks that have been closed during a specific period of time.

A task is a piece of work that is to be carried out by an employee (a member of your mobile workforce). Each successfully completed task follows the same general lifecycle:

100000000000040B0000006339CADAF6_jpg

Note

There are some other, transient task statuses (such as ‘en route’ and ‘in progress’) that are not shown in the diagram above.

A task can be cancelled at any time up to the point it has been closed. Once a task has been closed (its status is COMPLETE ), it cannot be cancelled.

When a task is created, some important information about the task must be provided:

  • The location where the task must be carried out.
  • The time zone in which the location is situated.
  • The task duration.
  • Details of important time-related commitments that apply to the task (such as when it must be started or completed by).

Optimistic locking

The taskUpdate operation uses optimistic locking to ensure that attempts to update a task don’t conflict with each other.

Before sending an UpdateTaskRequest message, you should send a GetTaskDetailsRequest message to retrieve the details of the task that you want to update. The GetTaskDetailsResponse message that you receive will include a lastUpdateDateTime element that contains the date and time when the task was last updated. You should pass this value within the lastUpdateDateTime element of the UpdateTaskRequest message that you subsequently send.

Task location

Each CreateTaskRequest must include a taskAddressList element. This mandatory element contains details of the task’s location. The locations can be specified as street addresses or as latitude and longitude coordinates.

Note

If you supply both a street address and latitude and longitude values for a particular location, then the latitude and longitude values will take precedence. You must always supply a value for the <addressType> element (currently, the only supported address type is Work ), whether you are specifying location by street address, latitude and longitude, or both.

If a location is specified by latitude and longitude, then both latitude and longitude coordinates must be provided. If you are specifying the location of a task by latitude and longitude only, you also need to provide a value for the <countryCode> element within the <address> element.

If you specify a street address, the address fields that you must provide depend upon the country in which the address is located. This is summarized in the following table:

  street city county zipCode state* countryCode**
Australia M 1 N/A 1 M AU
Bahrain M 1 N/A 1 N/A BH
Belgium M 1 N/A 1 N/A BE
Canada M 1 O 1 M CA
Denmark M 1 N/A 1 N/A DK
El Salvador M 1 N/A 1 N/A SV
Finland M 1 N/A 1 N/A FI
France M 1 N/A 1 N/A FR
Germany M 1 N/A 1 N/A DE
Honduras M M N/A O N/A HN
India M 1 N/A 1 N/A IN
Ireland M 1 N/A 1 N/A IE
Kuwait M 1 N/A 1 N/A KW
Malaysia M 1 N/A 1 N/A MY
Netherlands M 1 N/A 1 N/A NL
New Zealand M 1 N/A 1 N/A NZ
Norway M 1 N/A 1 N/A NO
Oman M 1 N/A 1 N/A OM
Saudi Arabia M 1 N/A 1 N/A SA
Singapore M M N/A O N/A SG
South Africa M 1 N/A 1 N/A ZA
Spain M 1 N/A 1 N/A ES
Sweden M 1 N/A 1 N/A SE
Switzerland M 1 N/A 1 N/A CH
United Arab Emirates M M N/A N/A N/A AE
United Kingdom M 1 O 1 N/A GB
United States M 1 O 1 M US

Key:

M : The field is mandatory

1 : For the specified country, at least one of these fields must be populated

2 : For the specified country, at least two of these fields must be populated

O : The field is optional

N/A : The field is not applicable

* Where a value is provided for the state field, it must consist of the two-letter or three-letter abbreviation, or the full state name.

** A value must be provided for the countryCode field, and should consist of the two-letter country code that is specified in the table above.

Geofences

When you specify the street address for a task, you can also specify a geofence around that address. A geofence is an imaginary circular boundary around the address, which is used to indicate when a vehicle enters or leaves the vicinity of the address. It must be specified in meters. Geofences are used to detect vehicles stopping at tasks, and this information forms part of the Performance Management metrics.

Access time restrictions

Sometimes, tasks are located at sites to which employees only have access at certain times. For example, it might only be possible to enter a task’s location between 12.00 AM and 6.00 AM on Monday, Tuesday and Wednesday; or the site might be closed every day from 1 February to 14 February.

When you create or update a task, you can therefore specify any access time restrictions that apply to the task’s location.

The list of access restrictions that apply to a task are also returned when you send a GetTaskDetailsRequest message to retrieve the details of the task.

The access restrictions for a task are defined within its accessTimeRestrictionList, which contains one or more accessTimeRestriction elements. Each accessTimeRestriction element defines a specific access restriction, and can contain the following fields:

Element name Description
accessAllowed The type of access restriction that applies. The value ‘true’ specifies that the access restriction defines periods when the task’s location is accessible. The value ‘false’ specifies that the access restriction defines periods when the task’s location is not accessible.
fromDate The date from which the access restriction applies.
fromTime The time from which the access restriction applies (specified as the number of minutes after midnight).
toDate The date up until which the access restriction applies.
toTime The time up until which the access restriction applies (specified as the number of minutes after midnight).
onMonday Specifies whether or not the access restriction applies on a Monday. The value ‘true’ specifies that the access restriction does apply on a Monday.
onTuesday Specifies whether or not the access restriction applies on a Tuesday. The value ‘true’ specifies that the access restriction does apply on a Tuesday.
onWednesday Specifies whether or not the access restriction applies on a Wednesday. The value ‘true’ specifies that the access restriction does apply on a Wednesday.
onThursday Specifies whether or not the access restriction applies on a Thursday. The value ‘true’ specifies that the access restriction does apply on a Thursday.
onFriday Specifies whether or not the access restriction applies on a Friday. The value ‘true’ specifies that the access restriction does apply on a Friday.
onSaturday Specifies whether or not the access restriction applies on a Saturday. The value ‘true’ specifies that the access restriction does apply on a Saturday.
onSunday Specifies whether or not the access restriction applies on a Sunday. The value ‘true’ specifies that the access restriction does apply on a Sunday.

Note

If a task has more than one access restriction defined for it (in other words, its accessTimeRestrictionList contains more than one accessTimeRestriction element), the accessAllowed field must contain the same value for all of the access restrictions. All values must be either ‘true’ or ‘false’; there must not be a mixture of both.

Examples

  1. To specify that access is restricted to limited times, on certain days of the week (indefinitely):
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <fromTime>540</fromTime>
      <toTime>1020</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
   </accessTimeRestriction>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <fromTime>540</fromTime>
      <toTime>720</toTime>
      <onFriday>true</onFriday>
   </accessTimeRestriction>
</accessTimeRestrictionList>

The above example shows two access restrictions. One restriction applies between Monday and Thursday, and the other applies on Friday. Overall, this specifies that access to the task’s site is allowed between the hours of 9 AM and 5 PM on Mondays to Thursdays, and between the hours of 9 and 12 on Fridays. There is no access on Saturdays and Sundays. The access restriction applies indefinitely.

  1. To specify that access is restricted to limited times, on certain days of the week, from a given start date:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <fromDate>2015-09-20</fromDate>
      <fromTime>540</fromTime>
      <toTime>1020</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
      <onFriday>true</onFriday>
   </accessTimeRestriction>
</accessTimeRestrictionList>

The above example specifies that there is no access before the 20th September. From 20th September onwards, access is allowed between the hours of 9 AM and 5 PM on Monday to Friday.

  1. To specify that access is restricted to limited times, on certain days of the week, until a given end date:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <toDate>2015-09-20</toDate>
      <fromTime>540</fromTime>
      <toTime>1020</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
      <onFriday>true</onFriday>
   </accessTimeRestriction>
</accessTimeRestrictionList>

The above example specifies that access is allowed between the hours of 9 AM and 5 PM on Monday to Friday, up to and including the 20th September. After the 20th September, no access is allowed.

  1. To specify that access is restricted to limited times, on certain days of the week, between two dates:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <fromDate>2015-09-10</fromDate>
      <toDate>2015-09-20</toDate>
      <fromTime>540</fromTime>
      <toTime>1020</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
      <onFriday>true</onFriday>
   </accessTimeRestriction>
</accessTimeRestrictionList>

The above example specifies that access is only allowed between the 10th and 20th September (inclusive), between the hours of 9 AM and 5 PM on Monday to Friday.

  1. To specify that access is not allowed between two dates:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>false</accessAllowed>
      <fromDate>2015-09-10</fromDate>
      <toDate>2015-09-20</toDate>
   </accessTimeRestriction>
</accessTimeRestrictionList>

The above example specifies that access is not allowed from 12:00 AM on the 10th September to 23:59 PM on the 19th September. It is shorthand for the following XML, which is also what would actually be returned in response to a GetTaskDetailsRequest message:

<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>false</accessAllowed>
      <fromDate>2015-09-10</fromDate>
      <toDate>2015-09-20</toDate>
      <fromTime>0</fromTime>
      <toTime>1439</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
      <onFriday>true</onFriday>
      <onSaturday>true</onSaturday>
      <onSunday>true</onSunday>
   </accessTimeRestriction>
</accessTimeRestrictionList>
  1. To specify that access is allowed between two dates:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <fromDate>2015-09-10</fromDate>
      <toDate>2015-09-20</toDate>
   </accessTimeRestriction>
</accessTimeRestrictionList>

The above example specifies that access is allowed from 12:00 AM on the 10th September to 23:59 PM on the 20th September.

  1. To specify that access is allowed from a particular date onwards:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>true</accessAllowed>
      <fromDate>2015-09-10</fromDate>
   </accessTimeRestriction>
</accessTimeRestrictionList>
  1. To specify that no access is allowed after a particular date:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>false</accessAllowed>
      <fromDate>2015-09-10</fromDate>
   </accessTimeRestriction>
</accessTimeRestrictionList>
  1. To specify that access is restricted during the weeks commencing 1st September and 15th September 2015, but is allowed during the week commencing 8th September:
<accessTimeRestrictionList>
   <accessTimeRestriction>
      <accessAllowed>false</accessAllowed>
      <fromDate>2015-09-01</fromDate>
      <fromTime>0</fromTime>
      <toDate>2015-09-07</toDate>
      <toTime>1439</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
      <onFriday>true</onFriday>
      <onSaturday>true</onSaturday>
      <onSunday>true</onSunday>
   </accessTimeRestriction>
   <accessTimeRestriction>
      <accessAllowed>false</accessAllowed>
      <fromDate>2015-09-15</fromDate>
      <fromTime>0</fromTime>
      <toDate>2015-09-21</toDate>
      <toTime>1439</toTime>
      <onMonday>true</onMonday>
      <onTuesday>true</onTuesday>
      <onWednesday>true</onWednesday>
      <onThursday>true</onThursday>
      <onFriday>true</onFriday>
      <onSaturday>true</onSaturday>
      <onSunday>true</onSunday>
   </accessTimeRestriction>
</accessTimeRestrictionList>

Time zones

The following time zones are supported. They can be included (as written in the Time Zone Name column of the table below) in the timezoneName element that is part of CreateTaskRequest and UpdateTaskRequest messages:

Time Zone Name Description
Pacific/Honolulu (GMT-10:00) Hawaii
America/Adak (GMT-10:00) Aleutian
America/Anchorage (GMT-9:00) Alaska
America/Los_Angeles (GMT-8:00) Pacific Time (US & Canada)
Pacific/Pitcairn (GMT-8:00) Pacific Time (no DST)
America/Phoenix (GMT-7:00) Arizona
America/Denver (GMT-7:00) Mountain Time (US & Canada)
America/Regina (GMT-6:00) Saskatchewan
America/Chicago (GMT-6:00) Central Time (US & Canada)
America/El_Salvador (GMT-6:00) Central Time (no DST)
America/Panama (GMT-5:00) Eastern Time (no DST)
America/New_York (GMT-5:00) Eastern Time (US & Canada)
America/Indianapolis (GMT-5:00) Indiana (East)
America/Puerto_Rico (GMT-4:00) Puerto Rico (no DST)
America/Halifax (GMT-4:00) Atlantic Time (Canada)
America/St_Johns (GMT-3:30) Newfoundland
Europe/London (GMT+0:00) London (UK)
GMT (0:00) GMT
Europe/Dublin (GMT+0:00) Dublin (Ireland)
Europe/Paris (GMT+1:00) Paris (France)
Europe/Amsterdam (GMT+1:00) Amsterdam (Netherlands)
Europe/Berlin (GMT+1:00) Berlin (Germany)
Europe/Brussels (GMT+1:00) Brussels (Belgium)
Europe/Copenhagen (GMT+1:00) Denmark
Europe/Oslo (GMT+1:00) Norway
Europe/Stockholm (GMT+1:00) Sweden
Europe/Zurich (GMT+1:00) Switzerland
Europe/Helsinki (GMT+2:00) Finland
Africa/Johannesburg (GMT+2:00) South Africa
Asia/Bahrain (GMT+3:00) Bahrain
Asia/Kuwait (GMT+3:00) Kuwait
Asia/Riyadh (GMT+3:00) Saudi Arabia
Asia/Dubai (GMT+4:00) United Arab Emirates
Asia/Muscat (GMT+4:00) Oman
Asia/Calcutta (GMT+5:30) Chennai, Kolkata, Mumbai, NewDelhi
Asia/Kuala_Lumpur (GMT+8:00) Kuala Lumpur
Asia/Singapore (GMT+8:00) Singapore
Australia/Perth (GMT+8:00) Western Australia
Australia/Adelaide (GMT+9:30) South Australia
Australia/Darwin (GMT+9:30) Northern Territory
Australia/Brisbane (GMT+10:00) Queensland
Australia/Sydney (GMT+10:00) ACT, New South Wales, Victoria
Australia/Hobart (GMT+10:00) Tasmania
Pacific/Auckland (GMT+12:00) Auckland

Contact lists

Each task can have a list of contact details for somebody who is at the task’s site or a related location. A contact list should contain one or more <contact> elements, each of which contains a specific type of contact detail (for example a mobile phone number, office phone number or e-mail address).

All contact elements within a particular contact list must relate to the same contact (the <contactName> within each <contact> element must contain the same name). Here is an example:

<taskContactList>

   <contact>

      <contactSeqNo>1</contactSeqNo>

      <contactName>Fred Smith</contactName>

      <contactType>Mobile</contactType>

      <contactDetails>9876543210</contactDetails>

   </contact>

   <contact>

      <contactSeqNo>1</contactSeqNo>

      <contactName>Fred Smith</contactName>

      <contactType>Office Phone</contactType>

      <contactDetails>0123456789</contactDetails>

   </contact>

   <contact>

      <contactSeqNo>1</contactSeqNo>

      <contactName>Fred Smith</contactName>

      <contactType>e-mail</contactType>

      <contactDetails>fred.smith@example.com</contactDetails>

   </contact>

</taskContactList>

Task commitments

Each CreateTaskRequest  must also contain a commitmentType element, which specifies the time-related commitments that apply to the task that is being created or updated. One of the following values must be specified:

  • A for a task that has an appointment associated with it.
  • C for tasks that must be completed by a certain certain time
  • S for tasks that must be started by a certain certain time

Whilst the commitmentType element itself is mandatory, some sibling elements that the XSD defines as optional actually become mandatory according to the commitment type that you specify. These sibling elements are:

  • commitmentDateTime
  • earliestStartDateTime
  • latestStartDateTime

commitmentDateTime

This element must contain a value if the commitmentType element contains the value S or C .

For tasks that have a commitmentType of S , then the value that is specified should be the date and time by which the task must be started.

For tasks that have a commitmentType of C , then the value that is specified should be the date and time by which the task must be completed.

For tasks that have a commitmentType of A , no value need be specified; the system will automatically assume the latestStartDateTime .

Note

Commitment times can be historic. They must also be specified according to the time zone that is provided for the timezoneName field.

earliestStartDateTime

This element contains the earliest time at which the task should be started. The value that is provided must not be later than the latestStartDateTime , and must conform to the time zone that is specified in the timezoneName field.

For tasks that have a commitmentType of A (appointment tasks) this value represents the appointment window start time, and must be provided.

latestStartDateTime

This element contains the latest time by which the task should be started. The value that is provided must not be earlier than the earliestStartDateTime , and must conform to the time zone that is specified in the timezoneName field.

For tasks that have a commitmentType of A (‘appointment’ tasks) this value represents the appointment window end time, and must be provided.

Task completion times

For each task closure that is returned by the getTaskClosures operation, there will be a list of task times that are associated with the closure. Each task time will be of a particular type, signified by one of the following three-letter status codes:

  • STA This time type represents the reported start time of the task, and is specified when the Task was closed (in both complete or incomplete cases). Generally, the start time is specified by the technician.
  • CLO This time type represents the reported closure time of the task, and is specified when the task was closed. Generally, the closure time is specified by the technician.
  • COM This time type represents the system time at which the task was closed complete.
  • ICL This time type represents the reported incomplete closure time that was specified when the task was closed incomplete by the technician.
  • INC This time type represents the system time at which the task was closed incomplete.
  • HRS This time type represents the period of time that was worked on the task, indicated by the start of the period and its duration.

Retrieving task details

To retrieve the details of a particular task, you can send a GetTaskDetailsRequest . The response will contain the task’s attributes, including a <taskStatus> element that contains a three-letter acronym indicating the status that the task is currently in. The following table describes the acronyms that might be returned:

Task status acronym Description
NAS The task has not yet been assigned to an employee.
ASS The task has been assigned to an employee.
FDS The task has been dispatched to an employee, but is yet to be accepted.
DIS The task has been dispatched, and has been accepted by the employee.
ONR The employee is en route to the task’s location.
INP The task is being progressed by the employee.
COM The task has been completed and closed.
INC The task has been closed, but is incomplete.
CAN The task has been cancelled.
RET The employee has rejected the task.
HIS The task has been completed and has automatically been progressed to the HISTORICAL state. This happens approximately 31 days after the task has been closed.

Multi-day tasks

Multi-day tasks, also known as long tasks , are tasks that cannot be carried out in a single day and are therefore spread over multiple days (starting on one day, and finishing on another).

When you send a GetTaskDetailsRequest or GetTaskClosuresRequest , you may be able to see, for long tasks, information about the number of hours that were worked on the task each day. For such tasks, the response will contain a sequence of <completionTimeDetails> elements, each of which in turn contain a <taskDuration> element that specifies the number of hours that were worked on the task during a particular day.

File attachments

Tasks can have files associated with them. For example, while carrying out a task an employee may take photographs or electronically capture other information such as a customer’s signature. The files can then be attached to the task for later retrieval.

Details about the files that are associated with a task are stored, as part of the task, in custom fields. A custom field is a label-value pair.

To retrieve the details of the files that are associated with a task, you must send a GetTaskDetailsRequest. If there are any files associated with the task, the response will contain a customFieldList element, which will contain one or more customField elements. Each customField contains a label element and a value element. The label contains the name of the file, and the value contains the file’s unique ID.

For example, if a task has an image named Bottle.jpg associated with it, the response to the GetTaskDetailsRequest will contain a customFieldList like this:

<ns18:customFieldList>

   <ns9:customField>

      <ns9:label>Bottle.jpg</ns9:label>

      <ns9:value>/files/568a89e924acc4abc7a89a01</ns9:value>

   </ns9:customField>

</ns18:customFieldList>

To retrieve the image, you can pass the label or value information to the Files Web Service.

Signature images are stored in a similar way. The customFieldList will contain two custom fields that relate to the signature:

<ns9:customField>

   <ns9:label>Signatory</ns9:label>

   <ns9:value>James Wilson</ns9:value>

</ns9:customField>

<ns9:customField>

   <ns9:label>Signature.jpg</ns9:label>

   <ns9:value>/files/568a94db24acc4abc7a89ba9</ns9:value>

</ns9:customField>

One of the custom fields, which has the label ‘Signatory’, contains the name of the person to whom the signature graphic belongs. The other custom field contains the details of the signature graphic itself. It is called Signature.jpg, and can be retrieved by passing the ID that is in the value field to the Files Web Service.

Linking tasks

Certain types of work may require you to create multiple tasks, and link those tasks to indicate that there is a dependency between them.

To link tasks, you can:

  • Include a parentTaskLink element when you send a CreateTaskRequest message. This allows you to specify that an existing task should become the new task’s parent.
  • Send a LinkTasksRequest. This will create a link between two existing tasks.

Linked tasks can be grouped together under the same work order reference, indicating that they are part of the same package of work.

Tasks can be unlinked by sending an UnlinkTasksRequest.

There are four different types of task linkage: follow-on tasks, assistance tasks, co-operation tasks, and dependent tasks.

Follow-on tasks

With this type of task linkage, a single employee performs two tasks one after the other.

For example, Employee A needs to perform two or more tasks sequentially. Task 1 is “Repair the generator”; then task 2 is the follow-on task “Perform a load test”. So in other words, Task 2 can only be started once Task 1 has been completed.

Furthermore, it might be that Task 2 can only be started a specific amount of time after the completion of Task 1. So in this example, load balancing can only begin one hour after the generator has been repaired.

Task linking enables you to create follow-on tasks that can be performed by a single employee, and specify how much time must elapse in between tasks (the link delay, in minutes, which you specify by including a linkDelay element when you create the link).

The two tasks can be at the same location, or two separate locations.

To create a follow-on task link, the linkType element must contain the value ‘F’ when the link is created.

Assistance tasks

With this type of task linkage, two employees work on linked tasks at the same location.

It may be that one task can only be started a specific amount of time after the other task has started. You can therefore include a linkDelay element when you create the link, to specify the link delay, in minutes, between the start times of the two tasks.

To create an assistance task link, the linkType element must contain the value ‘A’ when the link is created.

Co-operation tasks

With this type of task linkage, two employees work on linked tasks at different locations.

Again, when you create the link you can supply a linkDelay element to specify the link delay between the start times of the two tasks.

To create a co-operation task link, the linkType element must contain the value ‘C’ when the link is created.

Dependent tasks

With this type of task linkage, two employees work on linked tasks, but the first task must be finished before the second one commences.

For example, Task 1 is the repair of a generator and Task 2 is to test that repair. Task 2 can only commence once Task 1 has been completed, and you can set how much time must elapse before the second task begins. To specify the amount of time that must elapse after Task 1 has been completed, you must include a linkDelay element when you create the link.

The two tasks can be at the same location, or two separate locations.

To create a dependent task link, the linkType element must contain the value ‘D’ when the link is created.

Parts

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. For most tasks, the parts that are needed will be known in advance. These parts are called planned parts. Occasionally, a technician will find that additional parts are needed upon arrival at a task. These are known as unplanned parts.

Parts catalogues

Work Management holds catalogues of parts, from which the parts that are to be associated with a task can be chosen. It is the responsibility of the external donor system (a system outside of Work Management that generates tasks) to maintain and update parts catalogues.

Catalogues can be uploaded and updated via the Files Web Service API. To upload a parts catalogue, you must use the HTTP POST method. The request must also contain a type parameter that has the value PARTS_CATALOG. For example:

http://<server_name>/wsapi/v3/files?name=Batteries&type=PARTS_CATALOG&description=Batteries

The parts catalog itself should be supplied as a file, and the Content-Type header of the request should be multipart/form-data. A minimal parts catalog might look like this:

{
   "partList":[
          {
                 "description":"NBC85300A 1.5 AMP CHARGER",
                 "catalogNumber":"NBC85300A",
                 "cost":"41.8"
          },
          {
                 "description":"3EA97 10' EXTENSION CORDEA",
                 "catalogNumber":"3EA97",
                 "cost":"8.02"
          },
          {
                 "description":"022-0158 ON BOARD CHARGER 24V 3AMP",
                 "catalogNumber":"022-0158",
                 "cost":"80"
          }
   ]
}

The following table shows the attributes that can be specified for each part:

Attribute Mandatory Format Purpose
guid Yes alphanumeric An identifier that is unique across all parts catalogues.
description Yes alphanumeric A description for the part. Can be used in a search.
quickCode No alphanumeric A short code that can be used in searches.
priceCode No alphanumeric The part’s Universal Product Code (UPC)
catalogNumber No alphanumeric A unique identifier for the part (within the catalogue). Can be used in a search.
cost No numeric The price of one unit of the part.

You can use the HTTP GET method to retrieve a list of all the catalogue files that have been uploaded:

https://<server_name>/wsapi/v3/files/list?type=PARTS_CATALOG

The response will look similar to this:

{
        files: [1]
        0: {
                tId: "54806d9584aef56c493df75a"
                name: "PartsCatalog"
                type: "PARTS_CATALOG"
                description: ""
                filename: "PartsCatalog.txt"
                contentType: "text/plain; charset=ISO88591"
                createdBy: "vg2mepuser1"
                createdDt: " 20141204T14:20:05Z"
                size: 1921698
        }
}

It is not possible to directly update a catalogue once it has been uploaded. Instead, you must create a new version of the catalogue and then delete the existing one. The name and filename of the new catalogue must be the same as the existing one.

To delete the existing catalogue you should use the HTTP DELETE method, specifying the tId of the file that you want to delete. For example:

http://<server_name>/wsapi/v3/files/54806d9584aef56c493df75a

Special characters

If the identifiers that you use for tasks contain any special characters, you must replace them with the appropriate character entities when you specify them in a web service request.

Consider the following task identifier:

T&M1

When passing this identifier in, for example, a CreateTaskRequest , you should use this representation:

T&amp;M1

ScheduleManagement

The ScheduleManagement service allows you to assign tasks to specific employees, and to then dispatch them.

Typically, you will use the ScheduleManagement Service to assign a schedule of tasks to each employee for the current day or the following day. You can then assign additional tasks, or unassign tasks, as required.

When you have assigned all the required tasks to an employee, you can then dispatch them to the employee.

To assign a task and dispatch it, you can either:

  • Send an AssignTaskRequest message, followed by a subsequent DispatchTaskRequest message; or
  • Just send a single DispatchTaskRequest message, which will implicitly assign the task to the employee that you specify.

The first of these methods, sending an explicit AssignTaskRequest message followed by a DispatchTaskRequest message, gives you more flexibility by allowing you to pick the day in an employee’s overall sequence of work (which could span several days) where the task will be placed.

Assigning tasks

The term task assignment refers to the sequencing of items of work for a selected employee, prior to the employee actually receiving the work to carry out.

When you send an AssignTaskRequest , you are in effect stating that the specified employee will be performing that task. In other words, it becomes part of the employee’s schedule .

Tasks in an employee’s schedule will not be performed until you have first sent a DispatchTaskRequest message (to put the task into DISPATCHED status), and, subsequently, the task has been actually dispatched.

A task that is in one of the following statuses cannot be assigned:

  • ASSIGNED - Represented by the three-letter acroynm ASS.
  • DISPATCHED - Represented by the three-letter acroynm FDS.
  • ACCEPTED - Represented by the three-letter acroynm DIS.
  • ONROUTE - Represented by the three-letter acroynm ONR.
  • INPROGRESS - Represented by the three-letter acroynm INP.
  • COMPLETE - Represented by the three-letter acroynm COM.
  • HISTORICAL - Represented by the three-letter acroynm HIS.

Schedule date

When you send an AssignTaskRequest message, the date upon which the task will be scheduled for the specified employee is determined by the value that the scheduleOnDate element contains. The task will be inserted at the end of the employee’s tour on the specified date. If there are no tasks in the schedule for that employee on that date, then the task will be first.

If the scheduleOnDate element is empty, then the task will be placed at the end of the employee’s sequence of tasks. If there are no tasks already assigned to the employee, then the task will be scheduled to start straight away.

Unassigning tasks

Tasks that are in the following statuses cannot be unassigned:

  • COMPLETE - Represented by the three-letter acroynm COM .
  • HISTORICAL - Represented by the three-letter acroynm HIS .
  • CANCELLED - Represented by the three-letter acroynm CAN .

If a task that has already been dispatched to an employee is unassigned it will be recalled and put back into an unassigned status, unless it is already in progress (in other words, it is already being worked on by the employee). If it is already in progress then an exception will be raised.

Task dispatch

The dispatchTask operation marks a task as being ready for dispatching to the specified employee; it does not actually cause the task to be physically dispatched to the employee .

When you send a DispatchTaskRequest , the task will get put into DISPATCHED status, meaning that it is ready to send to the specified employee’s handheld device.

If the task is not already assigned to the employee, then this operation will also  implicitly assign the task. Should the dispatch operation ultimately fail, then this implicit task assignment will be reverted.

A task that is in one of the following statuses cannot be dispatched (and hence implicitly assigned):

  • DISPATCHED - Represented by the three-letter acroynm FDS .
  • ACCEPTED - Represented by the three-letter acroynm DIS .
  • ONROUTE - Represented by the three-letter acroynm ONR .
  • INPROGRESS - Represented by the three-letter acroynm INP .
  • COMPLETE - Represented by the three-letter acroynm COM .
  • HISTORICAL - Represented by the three-letter acroynm HIS .
  • CANCELLED - Represented by the three-letter acroynm CAN .

The dispatchTask operation can be used for a task that is already assigned, or can be used on a task that has not been assigned, in which case an implicit assign is done at the very end of the employee’s current work (which could be several days hence).

It is possible to unassign a task that has been dispatched.