The Tasks API
allows you to retrieve, create and delete Tasks on the platform. This enables scenarios where jobs created/maintained in other systems (e.g. SAP, Salesforce) can be delivered through to your app users automatically.
Any new Task created will be automatically synchronised to the target User’s devices.
On the Cloud this API is available using the REST GET, POST and DELETE verbs:
http://secure.formsfly.com/api/v1/stask?format=[xml|json]
To search for and retrieve multiple Tasks at once, use a GET with the search API found at:
http://secure.formsfly.com/api/v1/stask/search?format=[xml|json]
The format query string parameter controls the desired response format. Specify either xml or json.
GET Request
The GET verb allows you to retrieve a single Task, identified by its unique Id.
The required and optional parameters for a GET call to the Tasks API are outlined below.
| Parameter Name | Data Type | Required | Description |
| Format | String | Yes | Specifies the desired format of the response. Must either JSON or XML. |
| ProviderId | Integer | Yes | Your unique Provider Id found on the Organisation Setup page of the secure website (under My Account) |
| Integrationkey | String | Yes | Your unique Integration Key found on the Organisation Setup page of the secure website (under My Account) |
| Id | GUID | Yes | The unique identifier of the Task you wish to retrieve |
GET Response
The data returned from a STask GET is provided as follows:
STask Response (<STaskResponse>)
| Field Name | Data Type | Description |
| STask | STask | The returned STask object |
| ResponseStatus | ResponseStatus | Details of any errors that may have occurred |
STask (<STask>)
| Field Name | Data Type | Description |
| Id | GUID | Unique identifier of the Task |
| ProviderId | Integer | The Provider identifier for this Task |
| ExternalId | String | External identifier of the Task. Used to link this Task to external systems. Can be null/empty. |
| UserExternalId | String | The external identifier of the App User assigned to the Task. This is for linking app users into other systems by a common ID. Can be null/empty. |
| UserEmail | String | Email address of the App User assigned to this Task |
| Name | String | Name/title of this Task |
| Status | String | Status of this Task. Status options are: Draft – Task has been created but not yet sent Sent – Task has been sent to the App User Accepted – Task has been accepted by App User Rejected – Task has been rejected by App User. Check the History for the rejection reason. In Progress – Task has been started by App User Completed – Task has been completed by App User |
| CompleteBy | DateTime (YYYY-MM-DDTHH:MI:SS) |
Date and time the Task must be completed by. Time zone is UTC; time is in 24 hour values. The “T” in the format is a delimiter. |
| CompleteAtLat | Double (Decimal Degrees) |
Latitude of the location at which the Task should be performed. |
| CompleteAtLon | Double (Decimal Degrees) |
Longitude of the location at which the Task should be performed. |
| CompleteAtText | String (Max length 200 chars) |
Description of the location at which the Task should be performed – e.g. the street address or directions. |
| PerformWithin | Integer (Metres – min 5, no max) |
The maximum distance from the CompleteAt location that the App User can be when performing the Task. The app will enforce this by using the device GPS. |
| AdditionalInfo | String (Max length 1000 chars) |
Any additional information relating to the Task, will be visible to the App User on the device. |
| STaskActivities | Array of STaskActivity | Collection of the Task’s activities, see STaskActivity type definition below |
| STaskHistories | Array of STaskHistory | The Task’s status change history, see STaskHistory type definition below. Only available on GET requests. |
| StartTime | DateTime (YYYY-MM-DDTHH:MI:SS) |
Date and time the Task was started by the App User. Time zone is UTC; time is in 24 hour values. The “T” in the format is a delimiter. |
| CompleteTime | DateTime (YYYY-MM-DDTHH:MI:SS) |
Date and time that the Task was completed. Time zone is UTC; time is in 24 hour values. The “T” in the format is a delimiter. |
| ActualCompleteLat | Double (Decimal Degrees) |
Latitude of the user when completing the Task. This value will be null or 0 when GPS is turned off or fails to capture. |
| ActualCompleteLon | Double (Decimal Degrees) |
Longitude of the user when completing the Task. This value will be null or 0 when GPS is turned off or fails to capture. |
| IntegrationKey | String | Your unique Integration Key found on the Organisation Setup page of the secure website (under My Account) |
STaskActivity (<STaskActivity>)
| Field Name | Data Type | Description |
| FormCode | String | The code of the Form to be filled out by the App User. This value is only set for “Fill out Form” activities. |
| DocCode | String | The code of the Doc to be read by the App User. This value is only set for “Read Doc” activities. |
| Instruction | String | The Instruction to be performed by the App User. This value is only set for “Instruction” activities. |
| OutcomeId | GUID | The unique identifier of the Form Entry resulting from this Activity. Only set when the App User has completed a “Fill out Form” activity. You can use this identifier to retrieve the Form Entry via the Form Entries API |
| CompleteTime | DateTime (YYYY-MM-DDTHH:MI:SS) |
Date and time that the Activity was completed. Time zone is UTC; time is in 24 hour values. The “T” in the format is a delimiter. |
STaskHistory (<STaskHistory>)
| Field Name | Data Type | Description |
| EventDate | DateTime (YYYY-MM-DDTHH:MI:SS) |
Date and time of the history event. Time zone is UTC; time is in 24 hour values. The “T” in the format is a delimiter. |
| Status | String | Status of this Task at the time of the event. Status options are:
Draft – Task has been created but not yet sent |
| StatusReason | String | The reason entered by the App User for the status change. Only used for Rejected status events at present. |
Response Status (<ResponseStatus>)
| Input Name | Data Type | Description |
| ErrorCode | String | The error code/message for the failure |
| Message | String | Description of the error |
| Errors | Collection | Collection of ResponseErrors compiled during the request |
Response Error (<ResponseError>)
| Input Name | Data Type | Description |
| ErrorCode | String | The error code/message for the failure |
| FieldName | String | Name of field involved in error, if any |
| Message | String | Error message |
API Usage Example
Given that the API is REST based, you can access the API directly via your web browser to test it. Obviously for actual integration works, you will need to make a web request to the given REST URL and then parse the response.
Below is a simple GET example which gets a Task, using both the XML response types.
GET Request
http://secure.formsfly.com/api/v1/stask? id=e2098623-4753-4c0b-816c-5b4efaa64be4& integrationkey=xxxxxxxxxxxx&providerid=1&format=xml
XML Response
HTTP/1.1 200 OK Content-Type: application/xml Content-Length: length <STaskResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.servicestack.net/types"> <ResponseStatus> <ErrorCode>String</ErrorCode> <Message>String</Message> <StackTrace>String</StackTrace> <Errors> <ResponseError> <ErrorCode>String</ErrorCode> <FieldName>String</FieldName> <Message>String</Message> </ResponseError> </Errors> </ResponseStatus> <STask> <ActualCompleteLat>0</ActualCompleteLat> <ActualCompleteLon>0</ActualCompleteLon> <AdditionalInfo>String</AdditionalInfo> <CompleteAtLat>0</CompleteAtLat> <CompleteAtLon>0</CompleteAtLon> <CompleteAtText>String</CompleteAtText> <CompleteBy>0001-01-01T00:00:00</CompleteBy> <CompleteTime>0001-01-01T00:00:00</CompleteTime> <ExternalId>String</ExternalId> <Id>00000000-0000-0000-0000-000000000000</Id> <IntegrationKey>String</IntegrationKey> <Name>String</Name> <PerformWithin>0</PerformWithin> <ProviderId>0</ProviderId> <STaskActivities> <STaskActivity> <CompleteTime>0001-01-01T00:00:00</CompleteTime> <DocCode>String</DocCode> <FormCode>String</FormCode> <Instruction>String</Instruction> <OutcomeId>00000000-0000-0000-0000-000000000000</OutcomeId> </STaskActivity> </STaskActivities> <StartTime>0001-01-01T00:00:00</StartTime> <Status>String</Status> <UserEmail>String</UserEmail> <UserExternalId>String</UserExternalId> </STask> <ResponseStatus> <ErrorCode>String</ErrorCode> <Message>String</Message> <Errors> <ResponseError> <ErrorCode>String</ErrorCode> <FieldName>String</FieldName> <Message>String</Message> </ResponseError> </Errors> </ResponseStatus> </STaskResponse>
Using the STaskSearch API
The STaskSearch API allows you to search for multiple Tasks at a time
GET Request
The GET verb allows you to retrieve many Tasks, according to the filtering parameters you specify.
The required and optional parameters for a GET call to the Tasks API are outlined below.
| Parameter Name | Data Type | Required | Description |
| Format | String | Yes | Specifies the desired format of the response. Must either JSON or XML. |
| ProviderId | Integer | Yes | Your unique Provider Id found on the Organisation Setup page of the secure website (under My Account) |
| Integrationkey | String | Yes | Your unique Integration Key found on the Organisation Setup page of the secure website (under My Account) |
| UserEmail | String | No | Specify if you want to search for Tasks assigned to a specific App User by email |
| UserExternalId | String | No | Specify if you want to search for Tasks assigned to a specific App User by their External Id |
| Status | String | No | Specify a specific Task Status to search for. Defaults to Completed if not specified. Status options are:Draft – Task created but not yet sent Sent – Task sent to the App User In Progress – Task started by App User Completed – Task completed by App User |
| FromDate | DateTime (YYYY-MM-DDTHH:MI:SS) |
No | Only return Tasks last updated after or on the given Date and optional Time |
| ToDate | DateTime (YYYY-MM-DDTHH:MI:SS) |
No | Only return Tasks last updated on or before the given Date and optional Time |
GET Response
The data returned from a STaskSearch GET is provided as follows:
STask Response (<STaskSearchResponse>)
| Field Name | Data Type | Description |
| STasks | Collection | Collection of STask objects |
| ResponseStatus | ResponseStatus | Details of any errors that may have occurred |
API Usage Example
Given that the API is REST based, you can access the API directly via your web browser to test it. Obviously for actual integration works, you will need to make a web request to the given REST URL and then parse the response.
Below is a simple GET example which searches for Tasks, using both the XML response types.
GET Request
http://secure.formsfly.com/api/v1/stask/search? integrationkey=xxxxxxxxxxxx&providerid=1&format=xml
XML Response
HTTP/1.1 200 OK Content-Type: application/xml Content-Length: length <STaskSearchResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.servicestack.net/types"> <STasks> <STask> <ActualCompleteLat>0</ActualCompleteLat> <ActualCompleteLon>0</ActualCompleteLon> <AdditionalInfo>String</AdditionalInfo> <CompleteAtLat>0</CompleteAtLat> <CompleteAtLon>0</CompleteAtLon> <CompleteAtText>String</CompleteAtText> <CompleteBy>0001-01-01T00:00:00</CompleteBy> <CompleteTime>0001-01-01T00:00:00</CompleteTime> <ExternalId>String</ExternalId> <Id>00000000-0000-0000-0000-000000000000</Id> <IntegrationKey>String</IntegrationKey> <Name>String</Name> <PerformWithin>0</PerformWithin> <ProviderId>0</ProviderId> <STaskActivities> <STaskActivity> <CompleteTime>0001-01-01T00:00:00</CompleteTime> <DocCode>String</DocCode> <FormCode>String</FormCode> <Instruction>String</Instruction> <OutcomeId>00000000-0000-0000-0000-000000000000</OutcomeId> </STaskActivity> </STaskActivities> <StartTime>0001-01-01T00:00:00</StartTime> <Status>String</Status> <UserEmail>String</UserEmail> <UserExternalId>String</UserExternalId> </STask> </Tasks> <ResponseStatus> <ErrorCode>String</ErrorCode> <Message>String</Message> <StackTrace>String</StackTrace> <Errors> </Errors> </ResponseStatus> </STaskSearchResponse>