API – POST Task

The POST Task API

allows you to create a new Task 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.

If you use XML format, you must ensure that every XML element in your request payload is ordered alphabetically.

This requirement does not apply to JSON payloads.

Using the STask API

The STask API allows you to work with a single Task at a time.

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

POST Request

The POST verb allows you to create a single Task which will then immediately send out to the specified User.

You may use either JSON or XML formats in your request.
You indicate this by setting the ContentType HTTP header as “application/json” or “application/xml”. If no ContentType is specified, XML format is assumed.

The required and optional parameters for a POST to the Tasks API are outlined below.

Parameter Name	Data Type	Required	Description
Task	STask	Yes	The Task that you wish to create.  See the STask type definition from the GET above.

 

STask (<STask>) Required Fields

The following fields must be specified when issuing a POST request to the STask API.

All other fields are optional.  Task completion fields (e.g. Status, ActualCompleteLat) will be ignored.

Field Name	Data Type	Description
IntegrationKey	String	Your unique Integration Key found on the Organisation Setup page of the secure website (under My Account)
ProviderId	Integer	Your unique Provider Id found on the Organisation Setup page of the secure website (under My Account)
Name	String	The name/title of the Task
UserEmail OR UserExternalId	String	The email address of the target App User External identifier for the target 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.
STaskActivities	STaskActivities	Collection of the Task’s activities. At least one Activity MUST be specified

STaskActivity (<STaskActivity>) Required Fields

At least one Task Activity must be specified when issuing a POST request to the STask API.

Activity completion fields (OutcomeId, CompleteTime) will be ignored.

Field Name	Data Type	Description
FormCode or DocCode or Instruction	String String String	To create a “Fill Out Form” activity. Must be a valid, published Form code or To create a “Read Doc” activity. Must be a valid, published Doc code or To create an “Instruction” activity, can be any instructional text.
PresetAnswers	Collection	Collection of Answer elements that are to be pre-populated into the Form entry involved in a “Fill Out Form” activity. This property is only processed when FormCode is set (i.e. for a “Fill Out Form” activity). Your Answers will be validated and the API will return errors if validation fails.

PresetAnswers and Answer (<Answer>)

Answers must be structured to match the related Form’s question structure.

When setting answers for Choices questions, you must ensure that the answer value you provide exists as a value in the Choices question’s list of options.

Note that Page Groups must be included as the parent Answer if you wish to set Answers for questions inside a Page Group.

Field Name	Data Type	Description
Name	String	The data name of the Form question or page group that this Answer element relates to
Value	String	The value of this Answer – will be pre-populated onto the Form entry that is sent to the user.
Answers	Collection	Collection of child Answer elements. Use this option to create the necessary hierarchy to match your Form’s question structure when your Form contains Page Groups.

As an example, consider a Form with a Page Group as follows:

To pre-populate the children Page Group, one would do the following (XML example):      

Note that you must use ISO-8601 format (YYYY-MM-DDTHH:MI:SSZ) for dates and times.

If you want to provide multiple pre-populated answers for a repeatable Page Group, simply specify the Page Group answer set multiple times as seen above.

POST Response

The data returned from a STask POST 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>) Response Fields
The STask returned is only populated with the following fields:

Field Name	Data Type	Description
Id	GUID	Unique identifier of the Task
Status	String	Status of this Task which will be set to Sent

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 POST example which creates a Task, using the XML format.

XML Response