GET Task

GET Task

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 via SSL secured HTTPS connection using the REST GET, POST and DELETE verbs.
The format query string parameter named format controls the desired response format.  Specify either xml or json.

https://eforms.mobileform.net/api/v1/stask?format=xml/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.

UserCanReject BooleanWhether or not the app user can reject the task on dispatch to them.
Values are True or False.

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
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

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 

https://eforms.mobileform.net/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>

    • Related Articles

    • GET Task

      This request method returns the task matching the given criteria. On the Cloud, this API is available via SSL-secured HTTPS connection using the REST GET verb. The format query string parameter controls the desired response format. Specify either XML ...

    • Get Tasks (Task Search)

      Using the TaskkSearch API The TaskkSearch API allows you to search for multiple Tasks at a time To search for and retrieve multiple Tasks at once, use a GET with the search API found at: ...

    • GET Task (Search)

      This request method allows you to find all tasks matching the given criteria. On the Cloud, this API is available via SSL-secured HTTPS connection using the REST GET verb. The format query string parameter controls the desired response format. ...

    • GET Task Recurring

      This request method allows you to find the recurring task matching the given criteria. On the Cloud, this API is available via SSL-secured HTTPS connection using the REST GET verb. The format query string parameter controls the desired response ...

    • GET Task Recurring (Search)

      This request method lets you find all recurring tasks matching the provided search criteria. On the Cloud, this API is available via SSL-secured HTTPS connection using the REST GET verb. The format query string parameter controls the desired response ...