You will learn how to authenticate, get list meta-data, and get and create records. It is meant as a limited general guide that will be improved and expanded with time. For more formal and comprehensive documentation.

Resources:

Authentication

First we start by authenticating with the Workiom backend server. This will give us a bearer accessToekn that we will send in the Authorization header of every subsequent request.

  • POST /api/TokenAuth/Authenticate
  • Content-Type "application/json"
  • Body
{
"userNameOrEmailAddress": "string",
"password": "string",
"tenantName": "string"
}
  • Response
{
"accessToken": "string",
"encryptedAccessToken": "string",
"expireInSeconds": 0,
"shouldResetPassword": true,
"passwordResetCode": "string",
"userId": 0,
"requiresTwoFactorVerification": true,
"twoFactorAuthProviders": [
"string"
],
"twoFactorRememberClientToken": "string",
"returnUrl": "string"
}

Get List Meta Data

Most actions you might want to take on a list will probably require getting the list’s meta-data first. The meta-data response will contain a lot of useful information like the list’s fields and views along with their IDs.

  • GET /api/services/app/Lists/Get
  • Content-Type "application/json"
  • HeadersAuthorization Bearer \*your-access-token\*
  • Parameters
  • id: string
  • expand: array[string] (any combination of: “Fields”, “Views”, “Filters”)
  • Response
{
"appId": "string",
"fields": [
{
"name": "string",
"description": "string",
"dataType": 0,
"summaryType": 0,
"listId": "string",
"staticListValues": [
{
"id": "string",
"label": "string",
"order": 0
}
],
"isPrimary": true,
"isRequired": true,
"isVisible": true,
"isMainPicture": true,
"format": "string",
"order": 0,
"allowMultiple": true,
"linkedAppId": "string",
"linkedListId": "string",
"linkedFieldId": 0,
"dateType": 0,
"rollupFieldId": 0,
"rollupSummaryType": 0,
"isComputed": true,
"expression": "string",
"isDeleted": true,
"deleterUserId": 0,
"deletionTime": "2018-12-04T17:29:08.144Z",
"lastModificationTime": "2018-12-04T17:29:08.144Z",
"lastModifierUserId": 0,
"creationTime": "2018-12-04T17:29:08.144Z",
"creatorUserId": 0,
"id": 0
}
],
"name": "string",
"description": "string",
"defaultView": {
"name": "string",
"description": "string",
"viewType": 0,
"fieldId": 0,
"isDefault": true,
"listId": "string",
"filters": [
{
"fieldId": 0,
"operator": 1,
"value": {},
"viewId": 0,
"id": 0
}
],
"state": "string",
"lastModificationTime": "2018-12-04T17:29:08.144Z",
"lastModifierUserId": 0,
"creationTime": "2018-12-04T17:29:08.144Z",
"creatorUserId": 0,
"id": 0
},
"icon": "string",
"order": 0,
"isVisible": true,
"views": [
{
"name": "string",
"description": "string",
"viewType": 0,
"fieldId": 0,
"isDefault": true,
"listId": "string",
"filters": [
{
"fieldId": 0,
"operator": 1,
"value": {},
"viewId": 0,
"id": 0
}
],
"state": "string",
"lastModificationTime": "2018-12-04T17:29:08.145Z",
"lastModifierUserId": 0,
"creationTime": "2018-12-04T17:29:08.145Z",
"creatorUserId": 0,
"id": 0
}
],
"lastModificationTime": "2018-12-04T17:29:08.145Z",
"lastModifierUserId": 0,
"creationTime": "2018-12-04T17:29:08.145Z",
"creatorUserId": 0,
"id": "string"
}

Get List Records

Getting records from a list is simple and flexible. You have to specify a listId to get its records, but you can also specify sorting options, and use maxResultCount and skipCount for pagination, or pass an array of filter objects to have much more granular control over what records you get.

  • POST /api/services/app/Data/All
  • Content-Type "application/json"
  • HeadersAuthorization Bearer \*your-access-token\*
  • Body
{
"listId": "string",
"filter": [
{
"fieldId": 0,
"operator": 1,
"value": 0
}
],
"linkedItemsLimit": 0,
"projectedFields": [
0
],
"sorting": "string",
"maxResultCount": 0,
"skipCount": 0
}
  • Response
{
"summary": {
"additionalProp1": 0,
"additionalProp2": 0,
"additionalProp3": 0
},
"totalCount": 0,
"items": [
{}
]
}

Creating Records

Records are simple JSON objects in which each key is a fieldId and each value is that record’s value for the field. Different fields might have different data-types, you can find a field’s id and dataType from the list’s meta-data response.

  • POST /api/services/app/Data/Create
  • Content-Type "application/json"
  • HeadersAuthorization Bearer \*your-access-token\*
  • ParameterslistId: string
  • Body
{
// This is an example of a record

/*
fieldId: value
*/
"1186": "2018-11-13T00:00:00.000+00:00",
"1251": "[email protected]",
"1421": [
{
"_id": "r29jrg8hgg48g33nig",
"label": "linked record"
},
{
"_id": "1354535tregrfrwni2",
"label": "another linked record"
}
],
"1425": "Ahmad Lam",
"1532": 132,
"1563": {
"id": "14372839",
"label": "static list item"
},
"1591": {
"id": "28349232",
"label": "Khaled Sameeh"
}
}

Filters

Filters can be used when requesting data. Usually an array of filter objects containing the fieldId to filter on, the filter operator and a filter value. For example, a filter property in a Data/All request might be:

{
"filters": [
{
"fieldId": 1425,
"operator": 1,
"value": "Ahmad Masa"
}
]
}

The filter operators are:

  • Contains: 1
  • Does Not Contain: 2
  • Is: 3
  • Is Not: 4
  • Greater Than: 5
  • Less Than: 6

Sorting

Sorting can be done using a sort string containing the fieldId to sort on and a sorting direction. For example, ascending sort on field 11284 is:

  • sorting: "11284 ASC"

For descending sort on the same field:

  • sorting: "11284 DESC"

Data Types

Workiom supports many field data-types, fields with different data-types accept values of different types. A Date field would only accept dates, while a LinkedList field would only accepts an array of objects containing the linked record IDs. Data-types are represented by the following numbers:

  • Text: 0
  • Number: 1
  • DateTime: 2
  • Boolean: 3
  • StaticSelect: 4
  • LinkList: 5
  • User: 6
  • Website: 7
  • Email: 8
  • File: 9
  • Rollup: 10
  • PhoneNumber: 11

For any question, please reach us on [email protected].




Did this answer your question?