The task manager

This page has been updated on the 8 June 2010.

What is this document about?

This document is a description of the supported features and specifications of the task manager application. The aim of the document is to help you use this application.

The features

The features of this application are:

  • Receiving messages
    • Type of message: NEW, UPDATE, DELETE
  • Manage list of tasks
  • Task have:
    • List of steps
    • Status manager
  • Send report
  • Save / Load Tasks on device

The tasks

Tasks are data which are stored on devices. A task contains a list of steps and attributes. This paragraph describes attributes of tasks / steps, those attribute are used in messages to add new task on the device.

In TaskManager there is only one current task and one current step per task. The driver works only on the current task, and only on the current step.

DB variables are all the details of the current step, this means that another service can get all those details using the DB. For example, an application of navigation can find address of the current step using the DB variables to start the navigation to this address.

The attributes

This is the task attributes when it is displayed on the platform.

Name Type Description
Id Int (unsigned) Id of task, all id must be different
label Char* Use as title
Info Char* Information summary of the task
Priority Int (unsigned) Priority (0 → highest priority)
Version Int Version of task (use for update) (not implemented)
StatusTask STANDBY
REFUSED
WAIT
SUSPENDED
TERMINATED
Status of task
Globals List List of globals (not used)
Steps List List of steps

DB variables

This is the DB variable which is set for the current Task. You can have several tasks in the application but only one is the current task. The others applications might use this variable to know which is the current application.

Attribute Type DB name Description
Id Int SAMPLE_TM_TASK_ID The current task in the application task manager.

Steps

A step contains all information to get an address, a phone number and other details.

Attributes

Name Type Description
Id Int (unsigned) Id of step
label Char* Use as step
Info Char* Information summary the step
Priority Int (unsigned) Priority (0 → highest priority)
StatusStep STANDBY
REFUSED
WAIT
SUSPENDED
TERMINATED
The task is on the platform
The task has been refused by the user.
The task has been accepted by the user
The task has been reactivated.
The task is finished
PhoneNumber Char* The phone number used to call
State Char* State
Country Char* Country
Street Char* Street
StreetNumber Char* Street number
PostalCode Char* Postal code
City Char* City
DateStart Char* Date of start step (Timestamp)
DateEnd Char* Date of end step (Timestamp)
Latitude Int GPS latitude
Longitude Int GPS longitude

Start the navigation

To start the navigation to the destination, the application checks the GPS coordinates (latitude, longitude), if those coordinate are invalid, the application will try to get the position using the address. When using the address to get the position, if the street is not filled, it will start navigation to the city center.

When matching an address, checks are made on:

  1. Country,
  2. City when nothing is available it checks on postalCode,
  3. Street.

When matching an element (Country, City or PostalCode, Street), if no choice or multiple choice are available, it displays a popup to modify the field previously filled unless no field is precise the address on addressSearch application.
If the address is completely empty (no country, no city, no postal code, no street, no streetNumber), then the button “start navigation” is disabled.
The navigation starts only on the current step of the current task.

DB variables

Name Displayed DB name Description
Id Yes SAMPLE_TM_STEP_ID
Label Yes SAMPLE_TM_STEP_LABEL
Info Yes SAMPLE_TM_STEP_INFO
PhoneNumber Yes SAMPLE_TM_STEP_PHONE_NUMBER
State Yes SAMPLE_TM_STEP_STATE
Country Yes SAMPLE_TM_STEP_COUNTRY
Street Yes SAMPLE_TM_STEP_STREET
StreetNumber Yes SAMPLE_TM_STEP_STREET_NUMBER
PostalCode Yes SAMPLE_TM_STEP_POSTAL_CODE
City Yes SAMPLE_TM_STEP_CITY
DateStart No SAMPLE_TM_STEP_DATE_START
DateEnd Yes SAMPLE_TM_STEP_DATE_END Display depends on your general Timezone, and the general Format that you use.
Configuration Application defines Timezone and Format.
Latitude No SAMPLE_TM_STEP_LATITUDE
Longitude No SAMPLE_TM_STEP_LONGITUDE

How does the application work?

The application works with
messages sent from our server to the device to create new tasks and steps, and
messages sent from the device to the server to update the status of a task (for example)

Messages

From the server to the device

All message between server and devices are in JSON.
The message gate use the channel 16 (configurable parameter “mgChannel”).

Information

  • After a shutdown Report are saved in the PDM.
  • After loading the all saved reports, they might not be sent in the order of creation. (but you can find the date of creation of the report).

Warning
JSON token and “type” must not contain End Of Line character. If they do the message will not be understood by the application and will be rejected.

Date and time field

The Date/Time format used in all messages is timestamp. Timestamp is the number of milliseconds since 1st January 1970. Link http://www.timestamp.fr/
(Warning the timestamp of this site is in second).

Example
The number 1220890442944 represents 8/9/2008 at 18:14:02.
In the report message send by the devices, if the RTC is not synchronized then it would write NOT_SYNCHRONIZED.

TimeStamp Corresponding Date
1223589600000 09/10/08 00h00
1223503200000 10/10/08 00h00
Task message

Messages can be sent to the devices to add, update or delete the tasks on the devices, below is a list of the fields in use.

{
	"MESSAGE":
	{
		"TYPE":"NEW|UPDATE|DELETE", 
		"VERSION_MSG":"int",
		"VERSION":"int", 
		"PACKET":"int",
		"PACKET_TOTAL":"int",
		"ID":"int",
		"LABEL":"string",
		"INFO":"string",
		"PRIORITY":"int", 
		"GLOBALS": 
		[
			{
				"ID":"int",
				"LABEL":"string", 
				"VALUE":"string" 
			}
		],
		"STEPS": 
		[
			{
				"ID":"int",
				"LABEL":"string" 
				"INFO":"string", 
				"CITY":"string", 
				"STREET":"string", 
				"STATE":"string", 
				"COUNTRY":"string", 
				"STREET_NUMBER":"string", 
				"POSTAL_CODE":"string", 
				"LATITUDE":"string", 
				"LONGITUDE":"string", 
				"PHONE_NUMBER":"string", 
				"DATE_START":"long", 
				"DATE_END":"long", 
				"PRIORITY":"int", 
			}
		]
		}
}
Fields
Field Description
TYPE NEW – Add a new task
UPDATE – Make an update on a task (Not implemented yet)
DELETE – Delete a task (Not implemented yet)
ID Id of the task must be in every PACKET
LABEL Label of the task
INFO Info of the task
GLOBALS Globals data of the task
PRIORITY Priority of the task
STEPS Steps of the task
VERSION Version of the task (Use for the date)
VERSION_MSG Version of the message, this is used to check if the application can handle this version.
PACKET Message can be cut into multiple packet;
To Be Integrated (All Packet must have been received)
ID of task must be sent in every packet in order to create the Task.
1 <= PACKET <= PACKET_TOTAL
Steps and Globals must have different IDs (if not Task is rejected, WARNING no information on the server).
Label, Info, Priority, Version display for the Task are retrieve in the PACKET number 1.
PACKET_TOTAL Total number of total packets
PACKET_TOTAL >= 1.
Task is not displayed until all packets are received.

Example: adding a task

{
	"MESSAGE":
	{
		"TYPE":"NEW",
		"ID":"1",
		"VERSION_MSG":"1",
		"VERSION":"12",
		"PACKET":"1",
		"PACKET_TOTAL": "1",
		"LABEL":"Moving in Paris",
		"INFO":"resume of task",
		"GLOBALS":
		[
			{
				"ID":"2",
				"LABEL":"title",
				"VALUE":"value"
			}
		],
		"STEPS":
		[
			{
				"ID":"1",
				"LABEL":"Start from New York",
				"INFO":"resume"
			},
			{
				"ID":"2 ",
				"LABEL":"Move to Californie",
				"CITY":"San Diego",
				"STREET":"street",
				"INFO":"resume of step",
				"STATE":"Los angeles",
				"COUNTRY":"USA",
				"STREET_NUMBER": "12",
				"POSTAL_CODE": "45213 ",
				"LATITUDE": "4513221",
				"LONGITUDE": "1321010",
				"PHONE_NUMBER":"0121435478",
				"DATE_START":"1223503200000",
				"DATE_END":"1223589600000"
			}
		]
	}
}

From the device to the server

Messages are sent to the server when an error occurs or when task / step status change.
For example when a step terminates then a message with the id of the task and the id of the step is send with the type END_SUCCESS.

The format of this message is:

{
	"REPORT":
	{
		"TYPE":"char*",
		"CREATION_DATE":"char*",
		"ID_TASK":"int", 
		"ID_STEP":"int", 
		"REPORT_MSG": 
		[
			{
				"TYPE":"char*",
				"MSG":"char*"
			},
			{
				"TYPE":"char*",
				"MSG":"char*"
			}
		]
	}
}
Field of reports
Field Description
TYPE Type of the message (see table)
CREATION_DATE Date of creation, timestamp UNIX in Milliseconds as an integer: example 1220890442944 (for 8/9/2008 at 18:14:02).
NOT_SYNCHRONIZED when RTC is not synchronized and date could not be filled.
SEE: http://www.timestamp.fr/
ID_TASK Id of the task
ID_STEP Id of the step
REPORT_MSG List of reports fields
Report type
Type Id to put Info
DELETE Task Task has been deleted from device
REFUSE Task Task has been refused
ACCEPT Task Task has been accepted
RECEIVE Task Task has been received
NO_CUR_TASK No current task (when there are no current tasks, ie: after the current task ended)
CHANGE_CUR_TASK Task The current task has been changed
CHANGE_CUR_STEP Task, Step The current step has been changed.
Happens when the user selects a step. This happens automatically when there is only one step in the task.
CANCEL_END Task, Step Cancel the termination of the step
END_SUCCESS Task, Step Terminate a step with success
END_FAILED Task, Step Terminate a step with failure
ERROR_SERVER_NEW_ID_TASK Task This task id already exists
ERROR_MSG_CAN_NOT_BE_PARSED The message could not be understood by the application.
ERROR_TASK_IS_NOT_VALID Rules to check on task valid:
1. Id of the task must be positive.
2. PACKET must be between 1 and PACKET_TOTAL.
START_NAVIGATION When starting a new navigation
Fields of REPORT__MSG

Some reports can contain REPORT_MSG, it is an array of the table described below

Field Info
TYPE Key of this field
MSG Value

Type of REPORT_MSG:

TYPE Report Type MSG Description
END_SUCCESS
END_FAILED
MESSAGE When terminating a step with success / with failure then the driver can write a message.
ERROR_CODE END_FAILED When ending fails, the driver can choose a generic error code.
ERROR ERROR_MSG_CAN_NOT_BE_PARSED
ERROR_TASK_IS_NOT_VALID
Content of the message, in the field MSG.
Task is not valid;
Reasons of why the task is not valid.
START_NAVIGATION LONGITUDE
LATITUDE
Longitude of the destination in thousands of degrees
Latitude of the destination in thousands of degrees.

The user fills type MESSAGE (the field MSG might be empty) when sending:

  • END_SUCCESS;
  • END_FAILED

The user fills type ERROR_CODE when sending the report type:

  • END_FAILED

The devices type ERROR is sent when sending a report type:

  • ERROR_TASK_IS_NOT_VALID send in the MSG the content of the ERROR.
  • ERROR_MSG_CAN_NOT_BE_PARSED send in MSG the content of the Message received.

The user fills type START_NAVIGATION when sending the report of start navigation. Both report types are sent in the message vector:

  • LONGITUDE the destination longitude destination in thousands of degrees
  • LATITUDE the destination latitude in thousands of degrees

Error code file

You can add a file to enter specific ERROR_CODE when the driver could not finish successfully the step. It contains the CODE that will be sent to the server, and the label that the user would see on the application.
The file must be at a certain location to be used in the platform (see the table below). The name of the file must be “taskManager_errorCodes.txt”.

Platform Path Description
Windows data/input Put in path of simulator data/input directory.
Linux data/input Put in path of simulator data/input directory.
M*4 Input Put in SD card in input directory.

You can find an example file in the project Task Manager in the directory “date/input/EXAMPLE1_taskManager_errorCodes.txt”; you have to rename the file in order to use it. The ERROR_CODE is empty when not filled by the user.

{
	"ERROR_CODES":
	[
	    {"CODE":"AP",LABEL":"Calling Card left"},
		{"CODE":"AP1", LABEL":"Calling Card left – Gate locked"},
		{"CODE":"AP2", LABEL":"Calling Card left  Animals"},
		{"CODE":"AP3", LABEL":" Calling Card left – access to building refused"},
		{"CODE":"AP4", LABEL":" Calling Card left  Payment needed and refused"},
		{"CODE":"RL", LABEL":"Delivery refused"},
		{"CODE":"RL1", LABEL":" Delivery refused, recipient unavailable"},
		{"CODE":"RL2", LABEL":" Delivery refused, recipient present"},
		{"CODE":"LC", LABEL":"Partial delivery requested by recipient"},
		{"CODE":"MA", LABEL":"Wrong address"},
		{"CODE":"NL", LABEL":"Not delivered"},
		{"CODE":"LZ", LABEL":"Partial delivery, out of stock"},
		{"CODE":"RT", LABEL":" Vehicle breakdown "},
		{"CODE":"RC", LABEL":"Driver error"},
		{"CODE":"RC1", LABEL":" Driver error  lost keys"},
		{"CODE":"RC2", LABEL":" Driver error – wrong address"},
		{"CODE":"TL", LABEL":"Limited tonnage"},
		{"CODE":"OL", LABEL":"barred delivery"},
		{"CODE":"IT", LABEL":"Technical fault"},
		{"CODE":"IT1", LABEL":" Technical fault - incident"},
		{"CODE":"IT2", LABEL":" Technical fault  wrong setup"}
	]
}

Start navigation report

The report sent when the navigation starts can be deactivated by setting the parameter value reportOnStartNavigation to false.
By default, this parameter has the value true.

Report examples

This is an example of a valid message send to the server.

{
	"REPORT":
	{
		"TYPE":"END_SUCCESS",
		"ID_TASK":"2",
		"ID_STEP":"3",
		"CREATION_DATE":"1220882032",
		"REPORT_MSG":
		[
			{
				"TYPE":"MESSAGE",
				"MSG":"No problem to deliver the load"
			}
		]
	}
}

You can find here a message where the driver has faced a problem and could not finish the step:

{
	"REPORT":
	{
		"TYPE":"END_FAILED",
		"ID_TASK":2,
		"ID_STEP":"3”,
		"CREATION_DATE":"1220882032",
		"REPORT_MSG":
		[
			{
				"TYPE":"MESSAGE",
				"MSG":"The dog didnt let me go through to deliver."
			},
			{
				"TYPE":"ERROR_CODE",
				"MSG":"AP2"
			}
		]
	}
}

Sending a message TEST in the canal of the Task Manager, This message can not be parsed:

{
	"REPORT":
		{"REPORT_MSGS":[{"TYPE":"ERROR","MSG":"TEST"}],
			"TYPE":"ERROR_MSG_CAN_NOT_BE_PARSED",
			"CREATION_DATE":"1221148768400"
}

Sending a message with a bad ID (< 0) and bad PACKET and PACKET_TOTAL
Message Send:

{"MESSAGE":
	{"TYPE":"NEW",
	"ID":"-1",
	"VERSION_MSG":"1",
	"VERSION":"12",
	"PACKET":"-1",
	"PACKET_TOTAL": "-1",
	"LABEL":"Moving in Paris",
	"INFO":"resuming task",
	"GLOBALS": [{"ID":"2", "LABEL":"title","VALUE":"value"}],
	"STEPS":[{"ID":"1","LABEL":"Start from New York","INFO":"resume"}]
	}
}

Message Received

{"REPORT":
	{"REPORT_MSGS":
		[
			{"TYPE":"ERROR","MSG":"TASK ID:{-1} MUST BE POSITIVE"},
			{"TYPE":"ERROR","MSG":"TASK PACKET_TOTAL:{-1} MUST BE GREATER THAN 0"},
			{"TYPE":"ERROR","MSG":"TASK PACKET:{-1} IS NOT BETWEEN 1 AND PACKET_TOTAL:{-1}"}
		],
		"TYPE":"ERROR_TASK_IS_NOT_VALID",
		"CREATION_DATE":"1221149495099"
	}
}

Trigger to delete task from the device

To not overflow PDM, tasks are deleted automatically. This paragraph explains how task can be deleted from PDM.
When a task is deleted, a message is sent to the server.

Only task in states REFUSED, TERMINATED or WAITING can be deleted automatically. (cf. table Task status).

  • Automatically
    • After a specific time set with param1:
  • timeoutDelTaskRefusedTerminatedHour: tasks in state REFUSED or TERMINATED are deleted after 1 day by default.
  • timeoutDelTaskStandByHour: tasks in state STANDBY are deleted after 7 days by default.
    • If there are more tasks than param (listTasksNumberMax) then tasks are deleted in the following order:
      #TERMINATED
  • REFUSED
  • from oldest to newest (date of reception of task).
    • If there are more messages 2 than param (listTasksPacketNumberMax) then messages are deleted from oldest to newest (date of reception of message).

1 If the task contains some reports not already sent then this task is not deleted. The deleting process is checked when the devices starts and when it shutdowns.

2 The server can send messages in multiple parts (packet) and if all packets are not all sent they are saved.

If the GPS is not synchronized with the date then it will not be able to delete tasks using the date.

Task status:

Status description
REFUSED Task has been refused
TERMINATED All step are terminated
WAITING Task has been accepted and waiting to be current (on this status, task is not deleted automatically)
SUSPENDED Task has been suspended (on this status, task is not deleted automatically)
STANDBY Task has not been accepted or refused