Skip to main content
Sign in

Tasks-management

Marisa Potgieter
  • Updated

Using tasks with API

Tasks management

When using API to create new tasks it is mandatory to have external ID assigned to task type which will be created using API call. Task type external ID acts as a link between FC+ and task API.

Make sure to use Latin standard alphabet, letters a-z, A-Z and numbers 0-9. Unicode letters like õ, ß, æ etc, are not accepted by API.

Configuring Task types

Every task type has External ID field. Fill it to be able to refer to data and forms under that task type.

Forms

If task type sent via API also uses task forms, then forms and their form fields must have external IDs assigned to them as well. External ID value must be unique.

Using Document editor

Fields are referred like this:

{formsData::Installation::fields::notes} Here, Installation is form name, and notes form field.

API

Once task type and task forms are properly configured you can start using the API. Adding new tasks and updating tasks is managed via the addXml/updateAsXml commands.

Reference to API testing/and doc page:

https://app.ecofleet.com/seeme/services/apidoc/seeme#Tasks-POST-Add-new-task

https://app.ecofleet.com/seeme/services/apidoc/seeme#Tasks-POST-Update-existing-task-data

Since the tasks structure is highly configurable, it is hard to provide all-inclusive XML example, but below we listed some generic POST XML examples covering the main use scenarios.

The simplest XML for a task that can be added via API:

2

type_id

2023-09-01 08:00:00+0300

TODO

This is some name for the job This is some long description

<-- Do not use location, if you use Customers already with defined locations -->

Kivila 15, 13917 Tallinn, Eesti

59.445075099047 

24.873046875

1 

But since mostly tasks will have forms, then here is how to add task with form:

    4  

simple_task_test  

2023-01-01 16:00 

new test task    

Test

1 Test Address, 12345 Tallinn, Estonia

 

                               

1

Use post method to add new task(s)

The minimal POST parameters:

key - API key

ver - 2

xml - string that contains the task XML from above.

In the case of success system returns a created task within similar XML structure.

Please sees some Postman screenshots illustrating the process.

Success case:

In case of fail an error message wil be returned:

Add task attachment

When sending task with attachment(s) via API, attachment MUST be sent with a separate command, AFTER Api/Tasks/addXml command is successfully executed.

Attachment(s) can be added using POST command Api/Tasks/uploadAttachments 

Parameters needed to add task attachment(s)

key = API_KEY

version = 2

taskId = TASK_ID_TO_ADD_ATTACHMENT_TO

Attachment is added as file in the body of the request.

Body type should be selected as 'Form data'

name= file

type =file

then the actual file added.

Tasks driver location

Tasks automatically reopen if the driver's location at the time of closure differs from the task address by a predefined distance. E.g. if task address is StreetOne 123 and when task is closed driver location is showing Street 10 12345, that means that driver has closed the task without actually arriving to the task location. In such case task will be automatically reopened and can only be closed when driver is within certain distance of task address, or can only be closed by dispatcher.

Feature works using callback functionality where call back for request task type needs to be setup.

service url: https://app.ecofleet.com/services/api/caverion/checkUserLocationtype: JSON POST with optional parameters hook: Task status change to done key → API_KEY

optional: distance → integer - defines distance, by default 500m description → possible to overwrite default description message if task is reopened

Powered by Zendesk