API Documentation

Avatar
Qalcwise Support
Obserwuj

Qalcwise API version: 2.1.0.x

The following documentation demonstrate usage of the most common functionality of Qalcwise API. All the examples assume the API base address BASE_URL is subdomain.qalcwise.com, where "subdomain" is your company subdomain name.

Table of contents:

  1. Basics
  2. data types
  3. basic response
  4. basic request
  5. URL encoding
  6. Authentication
  7. obtaining a token
  8. create a token
  9. Record
  10. get all records
  11. search for records
  12. get single record
  13. get multiple records with given keys
  14. add new records
  15. update records
  16. update or insert records
  17. delete all records
  18. delete single record
  19. delete multiple records with given keys
  20. Application
  21. get application instance
  22. search for application instance
  23. create application instance
  24. execute action in application instance
  25. Attachment
  26. get the list of attachments in application instance or data records
  27. download an attachment, with given id from app instance
  28. download an attachment, with given name, from instance
  29. add an attachment to application instance
  30. add an attachment to data record
  31. delete an attachment with given id from application instance
  32. delete an attachment with given id from data record

 

Basics
Data Types
  1.  

  2. Date is passed like:
      value : "2012-04-23"

    DateTime is passed like:
      value : "2014-05-19T18:25:43.511"

    DateTimeUTC is passed like:
      value : "2012-04-23T18:15:43.511Z"

    Boolean values are passed like:
      value : true
      value : false

    Numbers are passed like:
      value : 22
      value : 3.141592

    Strings are passed like:
      value : "some text"

Basic Response

If the response is different than GET and error is not a default(for example when resource is not found, or the Token is not provided) API error the json is returned. It always contains:

{
  IsSuccess: Boolean,
  ErrorMessage: String
}

If the request was successful the "IsSuccess" is set TRUE.

If there are errors the "IsSuccess" is set FALSE, additionally there may be a custom message in "ErrorMessage" field.

Example:

"IsSuccess": true,

"ErrorMessage": null

 

Basic Request

Each API request has to have "Authorization" header with value Token and "Content-Type" header with value "application-json".

Content-Type: application/json
Authorization ->  Type: Bearer -> Token - eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yM[...] 

IMPORTANT! Each Request to API has to meet the Basic Request requirement.

URL Encoding

When the identifier (id) contains special characters such as spaces, slashes or other chracters that may cause issues in URL's, it is reccommended to encode the ID using URL encoding (e.g. 123/456 becomes 123%2F456).

Example encoding:

  • a&b -> a%26b
  • a:b -> a%3Ab
  • a/b ->a%2Fb

You should use an endpoint where the identifier is passed as a query parameter.

GET /api/record/{name}?id=[ID]

GET /api/record/TABLE_API?id=a%26b

POST /api/attachment?id=[ID]&address=[address]&action=[ActionName]

POST /api/attachment?id=1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d&address=SECTION2.A1&action=Save

DELETE /api/attachment?id=[id]&address=[address]&attachmentID=[id]

DELETE /api/attachment?id=1-DataTable-TEST_TAB_API-2&address=FILE&attachmentID=543008a098144e29aee04dafa99e9

 

Authentication

Method

Path

Description

 POST

 /api/token

 Obtaining token.

 

Obtaining a Token

Endpoint responsible for authenticating provided credentials.

POST /api/token

The user has to POST x-www-form-urlencoded user credentials together with "grant_type" (for now only "password" grant type is supported):

username: user_identifier
password: password
grant_type: password

Together with header:
"Content-Type":"application/x-www-form-urlencoded"

If the authentication request returns an error "401 - Unauthorized", it most likely means that the user is not in group API and is not authorized to use API (User can be added to group API by editing a system datatable SYSUSERINGROUP).

When User is authenticated successfully the endpoint returns the json containing "access_token", together with "token_type", who requested it and expiration information.

For example:

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTM4NCJ9.eyJlbWFpbCI6ImFkbWluQHRlc3QucGwiLCJ1bmlxdWVfbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJodHRwOi8vcWFsY3dpc2UvY2xhaW1zL2RiaWQiOiIxLUxpc3QtU1lTVVNFUi1BRE1JTkBURVNULlBMIiwicm9sZSI6WyIqT3duZXIiLCJBRE1JTklTVFJBVE9SUyIsIkFMTCIsIkRFU0lHTkVSUyIsIlVTRUxPQ0FMQVBQUyQiLCJBUEkiXSwiaXNzIjoiUWFsY3dpc2UiLCJhdWQiOiIqIiwiZXhwIjoxNDk5OTg0OTQzLCJuYmYiOjE0OTk5NDE3NDN9.u0PeBG5nDHnhVooXSQ_X_Rgq5riV4ybETs_7db6L8YcDLG3IMw6zprD--gQ7FqRC",
 "token_type": "bearer",
 "expires_in": 43199
}

"access_token" and "token_type" are the most important. They are used to create the Token value that should be stored by the Client using the API.

 

Create a Token

Concatenate values "token_type" with "access_token" from /api/token JSON response.

IMPORTANT!: The "token_type" with "access_token" have to be space( " " ) separated.

Example token:
"bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTM4NCJ9.eyJlbWFpbCI6ImFkbWluQHRlc3QucGwiLCJ1bmlxdWVfbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJodHRwOi8vcWFsY3dpc2UvY2xhaW1zL2RiaWQiOiIxLUxpc3QtU1lTVVNFUi1BRE1JTkBURVNULlBMIiwicm9sZSI6WyIqT3duZXIiLCJBRE1JTklTVFJBVE9SUyIsIkFMTCIsIkRFU0lHTkVSUyIsIlVTRUxPQ0FMQVBQUyQiLCJBUEkiXSwiaXNzIjoiUWFsY3dpc2UiLCJhdWQiOiIqIiwiZXhwIjoxNDk5OTg0OTQzLCJuYmYiOjE0OTk5NDE3NDN9.u0PeBG5nDHnhVooXSQ_X_Rgq5riV4ybETs_7db6L8YcDLG3IMw6zprD--gQ7FqRC"

Token is the way that the user is authenticated and authorized on the server side. Each API Request which requires authentication has to have it as "Authorization" header.

 

Record

Contains all the basic CRUD functionality for records in definitions.

Method

Path

Description
 GET  /api/record/{name}  Get all records
 GET  /api/searchrecord/{name}  Search for records
 GET  /api/record/{name}/{recordID}  Get single record (deprecated)
 GET  /api/record/{name}?id=[recordID]  Get single record 
 POST  /api/getrecords/{name}  Get multiple records with given keys
 POST  /api/record/{name}  Add new records
 PUT  /api/record/{name}  Update records
 PUT  /api/recordupsert/{name}  Update or insert records
 DELETE  /api/deleteallrecords/{name}  Delete all records
 DELETE  /api/record/{name}/{recordID}  Delete single record (deprecated)
 DELETE  /api/record/{name}?id=[recordID]  Delete single record
 DELETE  /api/record/{name}  Delete multiple records with given keys

 

Deprecated - this method is deprecated and may not work in newer versions of the site.

name - Name of the Definition we want to get records from

recordID - Unique ID of a record

Get all records

Get all records of given definition, offset and limit can be specified.

GET /api/record/{name}?offset=1&limit=2
 

Parameters:

  • offset - how many records should be skipped

      optional: true

      type: integer >=0

  • limit - limits number of returner records

      option: true

      type: integer >=0

json returned:

[
   {
       "_id": "1-List-SYSUSER-JOHN.DOE@GO.COM",
       "IDENTIFIER": "JOHN.DOE@GO.COM",
       "EMAIL": "JOHN.DOE@GO.COM",
       "NAME": "JOHN DOE",
       "ISACTIVE": true,
   },
   {
       "_id": "1-List-SYSUSER-TESTUSERID",
       "IDENTIFIER": "TESTUSERID",
       "EMAIL": "test@go.com",
       "NAME": "Test User"
        "ISACTIVE": true,
   }
]

Explanation:

This Method is responsible for getting rows(records) from the given definition, either List or a Table. If no limit and no offset are specified the Response should contain all the rows stored within that definition. Offset parameter specifies how many initial records should be skipped. Limit parameter limits number of returned rows to given value. Both Parameters are optional and should have values bigger or equal 0.

Example:

GET /api/record/sysuser?offset=5&limit=10 - skipps first 5 records and gets next 10 from sysuser

Get single record

Get single record by id.

GET api/record/{name}/{recordID} - this method is deprecated and may not work in newer versions of the site.
GET api/record/{name}?id=[recordID]

Parameters:

  • name: name of the table or list

         optional: fasle

         type: string

  • id: app instance id

          optional: false

          type: string

json returned: 

{
  "_id": "1-List-SYSUSER-JOHN.DOE@GO.COM",
  "IDENTIFIER": "JOHN.DOE@GO.COM",
  "EMAIL": "JOHN.DOE@GO.COM",
  "NAME": "JOHN DOE",
  "ISACTIVE": true
 }

Explanation:

Gets the uniquely identifiable record from given definition and returns it as json.

404 - record doesn’t exist

Example:

GET /api/record/sysuser/1

GET /api/record/TABLE_API?id=5

Search for records

Search for records of given definition, version > 2.1.0.x.

GET api/recordsearch/{name}?filter=QUERY&select=COLUMN_LIST&limit=LIMIT&bookmark=BOOKMARK

When using parameters sent in a query string, be aware of the limitations:

- Maximum length of the query string 2kB

If these limits are exceeded, the server will return a 404 error.

Parameters:

  • filter - query parameter to retrieve just a subset of a collection - use lookup query syntax

      optional: true

      type: string

  • select - coma separated list of columns that will be returned

      optional: true

      type: string

  • limit - limits number of returned records

      optional: true

      type: integer (max 200)

  • bookmark - bookmark parameter allows to get next page of results

json returned: 

{
   "NextPageUrl": "next page URL with bookmark parameter filled",
   "TotalRecordCount": 2,
   "Records": [
       {
           "_id": "1-List-SYSUSER-JOHN.DOE@GO.COM",
           "EMAIL": "JOHN.DOE@GO.COM",
           "NAME": "John Doe"
       },
       {
           "_id": "1-List-SYSUSER-TESTUSERID",
           "EMAIL": "test@go.com",
           "NAME": "Test User"
       }
   ]
}
 

Explanation:

Search for records from given definition according to filter parameter and returns records data specified. 404 - record doesn’t exist.

Example:

GET /api/recordsearch/sysuser?filter=email>'d'&select=_id,email,name&limit=1

GET /api/recordsearch/sysuser?filter=created>DATE(2020,1,1)&select=_id,email,name

GET /api/recordsearch/TAB_USERS?filter=name='Emma' || name='Olivia' || name='Liam' || name='Lucas' || name='John Doe' || name='Ava' || name='Ethan' || name='Isabella' || name='Emily' || name='Michael' || name='Test User'&select=_id, EMAIL, NAME

An alternative way to send a lot of parameters

As of version 2.3, it is possible to send all parameters as a JSON object in the request body (body -> raw). This method has no size limitation, so it is recommended for complex or long filters.

All parameters must be sent either in the query string or in the request body. Mixing both is not allowed (e.g., filter in body and limit in URL – not supported).

POST api/recordsearch/{name}

Example:

Json

{

“filter”: "name='Emma' || name='Olivia' || name='Liam' || name='Lucas' || name='Logan'
 || name='Ava' || name='Amelia' || name='John' || name='Lily' || name='Jacob' ||
 name='Sophia' || name='Mia' || name='Charlotte' || name='James' || name='Benjamin'
 || name='Ethan' || name='Isabella' || name='Emily' || name='Michael' || name='Daniel'",

"select": "_id, EMAIL, NAME",

"limit": 100

}

Important!

If you send parameters through the URL, you must use the GET method.
If you send parameters in the request body, you must use the POST method.

Example:

POST/api/recordsearch/TAB_USERS

Get multiple records with given keys

POST /api/getrecords/{name}

Explanation:

This method needs a structure which contains rows with single or composite keys for rows. Those rows that have matching records in a provided by {name} definition are returned in a JSON.

Structure (Array of objects):

[
  {
    "KeyField" : value,
    "KeyField2" : value2
  }
]

Gets 2 rows from TEST_TABLE, with given id, first row key(1, abc), second row key(11, abc)

Example:

[
  {
  "ID" : 1,
    "NAME" : "cheapProduct"
  },
  {
    "ID" : 11,
  "NAME" : "elevenProduct"
  }
]

json returned: 

[
   {
         "_id": 1,
         "NAME": "cheapProduct",
         "PRICE": 20
       },
       {
          "_id": 11,
          "NAME": "elevenProduct",
          "PRICE": 10
       }      
 ]

Example:

POST /api/getrecords/TEST_TABLE

Add new records

Add one or more records.

POST /api/record/{name}

Explanation:

Saves the records provided in the model to definition with {name}.

Structure (Array of objects):

[
  {
    "KeyField" : value,
    "KeyField2" : value2,
    "Field" : value3
  }
]

key - column name

Example:

[
  {
    "TYPE" : 2,
    "NAME" : "newProduct",
    "COUNT" : 331
  },
  {
    "TYPE" : 2,
    "NAME" : "newerProduct",
    "COUNT" : 241
  }
]

json returned:

{
"Records": [

      {
           Issuccess": true,
           CreatedId : "1-DataTable-Table_API-7",
           "Errors": []
      },

      {
          "IsSuccess":true,
          "CreatedId": "1-DataTable-TABLE_API-8",
          "Errors":[]
       }

    ],
      "IsSuccess":true,
      "ErrorMessage":null
}

POST /api/record/PRODUCTS

Update records

Update one or more records.

PUT /api/record/{name}

Explanation:

Updates the records provided in the model. If the record is nonexistent it does NOT create it.Update record only if we have an key column. The row to be updated is determined by the key values, they can not be updated. Only the other values which do not belong to the key are updated.

Structure:

[
  {
    "KeyField" : value,
    "KeyField2" : value2,
    "Field" : value3
  }
] 

Example:

The row defined by composite key(2, "newProduct") will have updated non Key Column "count" value to  1337.

[
  {
      "TYPE" : 2,
      "NAME" : "newProduct",
      "COUNT" : 1337
    }
]

json returned:

{
"Records": [

       {
           Issuccess": true,
           CreatedId : "1-DataTable-Table_API-2",
          "Errors": []
       },
   ],
   "IsSuccess":true,
   "ErrorMessage":null
}

Example:

PUT /api/record/PRODUCTS

update or insert records

Upsert (Update or Insert) multiple records.

PUT /api/recordupsert/{name}

Explanation:

Updates or inserts the records provided in the model. If the record is nonexistent it is created it, if it exists it is updated. For the records that exist, the row to be updated is determined by the key values, they can not be updated. Only the other values which do not belong to the key are updated. Records that do not exist are created and added to definition with {name}.

If the record exists the row defined by composite key(3, "someProduct"), will have updated non Key Column "count" value to  300. However if the record does not exists it will be created instead.

Structure:

[
  {
    "KeyField" : value,
    "KeyField2" : value2,
    "Field" : value3
  }
] 

Example:

[
  {
      "TYPE" : 3,
      "NAME" : "someProduct",
      "COUNT" : 300
    }
]

json returned:

{
"Records": [
          {
              Issuccess": true,
              CreatedId : "1-DataTable-PRODUCTS-3",
              "Errors": []
          },
      ],
     "IsSuccess":true,
     "ErrorMessage":null
}

Example:

PUT /api/recordupsert/PRODUCTS

Delete all records

Delete all records from definition.

DELETE api/deleteallrecords/{name}

Explanation:

Deletes all the records that are currently in a definition with given name.

json returned:

{
"Records": [
          {
              Issuccess": true,
              CreatedId : "1-DataTable-TEST_TABLE-1",
              "Errors": []
          },
          {
              Issuccess": true,
              CreatedId : "1-DataTable-TEST_TABLE-2",
              "Errors": []
          },
          {
              Issuccess": true,
              CreatedId : "1-DataTable-TEST_TABLE-3",
              "Errors": []
           },
      ],
     "IsSuccess":true,
     "ErrorMessage":null
}

Example:

DELETE  /api/deleteallrecords/TEST_TABLE

Delete single record

Delete single record.

DELETE /api/record/{name}/{recordID}
DELETE /api/record/{name}?id=[recordID]

Parameters:

  • name: name of the table or list

         optional: false

         type: string

  • id: data record id

         optional: false

         type: string

Explanation:

Deletes an exact record identified by ID,  from definition with given name.

Example:

DELETE  /api/record/TEST_TABLE/1

DELETE /api/record/TEST_TABLE?id=5

json returned:

{
"Records": [

          {
              Issuccess": true,
              CreatedId : "1-DataTable-TEST_TABLE-1",
              "Errors": []
          }
      ],
     "IsSuccess":true,
     "ErrorMessage":null
}
Delete multiple records with given keys

Delete selected rows.

DELETE /api/record/{name}

Explanation:

This method needs a model which contains rows with single or composite keys for rows. Those rows that have matching records in a provided by {name} definition are removed.

This will delete from TEST-TABLE the row with composite key(2,"valuableProduct")

REMARK!: Not all values of columns for the row are necessary, it is enough to provide only row values of columns which are marked as keys.

Structure (Array of objects):

[
  {

    "KeyField" : value,
    "KeyField2" : value2
  }
]

key - name of the column containing key
value - value of a key for given row and column

Example:

[
  {
    "TYPE" : 2,
    "NAME" : "valuable_Product"
  }
]

json returned:

{
"Records": [

          {
              Issuccess": true,
              CreatedId : "1-DataTable-TEST_TABLE-2",
              "Errors": []
          }
      ],
     "IsSuccess":true,
     "ErrorMessage":null
}

Example:

DELETE /api/record/TEST_TABLE

Application

Enables simple Application interaction in forms of, executing actions on instances and distributing applications to users.

Method

Path

Description
 GET  /api/app/{appID}  Get application instance data
 GET  /api/saerchapp/  Search for application instances
 POST  /api/app/  Distribute application to users
 PUT  /api/app/{appID}  Execute action in application instance

 

Get application instance

Get one application data, version > 2.1.0.x

GET/api/app/{appID}

Parameters:

  • appID - application instance ID

      optional: false

      type: string

json returned: 

{
   "_id": "1-App-APISEARCH-3-7526f7cafbeb4e86b7c9b4a7a192cb47",
   "_archived": false,
   "_modified": "2021-05-28T11:20:44.679Z",
   "_editor": "ADMINUSER",
   "_from": "ADMINUSER",
   "_message": "",
   "_state": "saved",
   "ALIAS_TEXT": "some text",
   "ALIAS_NUMBER": 33.0,
   "ALIAS_BOOLEAN": false,
   "_attachments": [
       {
           "Id": "ea3026ad885a443db959f7f52602b715",
           "Name": "logo.pdn",
           "SectionName": "SECTION5"
       },
       {
           "Id": "7fd95218153647c49c667c161fc199c1",
           "Name": "history.png",
           "SectionName": "SECTION5"
       }
   ]
}
 

Explanation:

User can use this method to get one application instance data. Values started with underscore _ are metadata of application instance. Uppercased values are application aliases.

Examples:

GET /api/app/1-App-APISEARCH-3-7526f7cafbeb4e86b7c9b4a7a192cb47

 

Search application instance

Search for application instances of given application, version > 2.1.0.x.

GET api/appsearch/{name}?filter=QUERY&select=COLUMN_LIST&limit=LIMIT&bookmark=BOOKMARK

Query length limit

When using parameters sent in a query string, be aware of the limitations:

- Maximum length of query string: 2kB

If these limits are exceeded, the server will return a 404 error.

Parameters:

  • filter - query parameter to retrive just a subset of a collection - use Lookup query syntax

     optional: true

     type: string

  • select - coma separated list of values that will be returned

      optional: true

      type: string

  • limit - limits number of returned records

      optional: true

      type: integer (max 200)

  • bookmark - bookmark parameter allows to get next page of results

Explanation:

Search for application instances from given definition according to filter parameter and returns records data specified.

404 - record doesn’t exist

json returned: 

{
   "NextPageUrl": "https://DOMAIN/api/appsearch/APP_NAME?bookmark=g2wAAAABaANkABFjb3VjaGRiQGxvY2FsaG9zdGwAAAACYQBuBAD_____amgCRj_1k3lAAAAAYQlq",
   "TotalRecordCount": 10,
   "Records": [
       {
           "_id": "1-App-APP_NAME-1-b80448fa12244fecb88d53de5933c1c3",
           "_archived": false,
           "_modified": "2021-05-26T11:02:15.846Z",
           "_editor": null,
           "_from": "ADMIN",
           "_message": "",
           "_state": "saved",
           "A_TEXT": "AAA",
           "A_DATA": "2021-05-13",
           "A_DATACZAS": "2021-05-29T16:18:00.000",
           "A_UTC": "2021-05-01T05:30:00.000Z",
           "A_NUMBER": 12.34,
           "A_BOOLEAN": true
       },
       {
           "_id": "1-App-APP_NAME-1-98ff54fcd1e049d68579b06e46fdf24d",
           "_archived": false,
           "_modified": "2021-05-26T11:02:31.017Z",
           "_editor": null,
           "_from": "ADMIN",
           "_message": "",
           "_state": "saved",
           "A_TEXT": "BBB",
           "A_DATA": "2021-03-17",
           "A_DATACZAS": "2021-05-13T05:25:00.000",
           "A_UTC": "2021-05-16T14:20:00.000Z",
           "A_NUMBER": 23.0,
           "A_BOOLEAN": false
       }
]
}
 

Example:

GET /api/appsearch/APP_NAME?filter=A_TEXT>'a'&select=_id,_from,A_TEXT&limit=1

GET /api/appsearch/NEW_APP?filter=RESULT_CLIENT='FAIL' || RESULT_CLIENT='ERROR' || RESULT_CLIENT='TIMEOUT' ||  RESULT_CLIENT='BLOCKED' || RESULT_CLIENT='EXPIRED' || RESULT_CLIENT='MISSING' ||  RESULT_CLIENT='REJECTED' || RESULT_CLIENT='UNKNOWN' || RESULT_CLIENT='RETRY' || RESULT_CLIENT='CANCELED' || RESULT_CLIENT='DISABLED' || RESULT_CLIENT='FAILED'&select=_id,RESULT_CLIENT

REMARK:

This returns only production instance!

Alternative way to send many parameters

As of version 2.3, you can send all parameters in the request body as a JSON object (body → raw).
This method has no size limitation, and it is the recommended approach for complex or long filters.

POST/api/appserach/new_app

All parameters must be sent either in the query string or in the request body. Mixing both is not allowed (e.g., filter in body and limit in URL – not supported).

Request Body (JSON):

{
"filter": "RESULT_KLIENT='FAIL' || RESULT_KLIENT='ERROR' || RESULT_KLIENT='TIMEOUT' ||
 RESULT_KLIENT='DENIED' || RESULT_KLIENT='BLOCKED' || RESULT_KLIENT='EXPIRED' ||
 RESULT_KLIENT='MISSING' || RESULT_KLIENT='INVALID' || RESULT_KLIENT='REJECTED' ||
 RESULT_KLIENT='UNKNOWN' || RESULT_KLIENT='SKIPPED' || RESULT_KLIENT='RETRY' ||
 RESULT_KLIENT='CANCELED' || RESULT_KLIENT='PENDING' || RESULT_KLIENT='OVERDUE' ||
 RESULT_KLIENT='INACTIVE' || RESULT_KLIENT='DISABLED' || RESULT_KLIENT='TERMINATED' ||
 RESULT_KLIENT='DELAYED' || RESULT_KLIENT='FAILED'",
"select": "_id,RESULT_CLIENT",
"limit": 100
}

REMARK:

If you send parameters through the URL, you must use the GET method.
If you send parameters in the request body, you must use the POST method.

Example:

POST/api/appsearch/new_app

Create application instance

Distribute application.

POST /api/app

Explanation:

User can use this method to distribute the application to either one or many of the defined groups or to list of users by providing their emails. Application to be distributed is defined using a unique "Identifier", its name. Provided "InputParameters" will be passed as input parameters for each created instance of the application.

User needs to have editor permissions in an app definition in order to be able to distribute it.

Structure:

Identifier: String
CreateDraft: boolean - optional

DestinationUsers: Array of [String] - optional

DestinationGroups: Array of [String] - optional

InputParameters:[
  {
    "ParameterName": Value
  }
]

Examples:

Distributing App with input parameters:

{
  "Identifier" : "PARAMETERSTEST",
  "CreateDraft" true,
  "inputParameters" : {
    "INPUTBOOLEANVALUE" : true,
    "INPUTSTRINGTEXT" : "second parameter"
  },
  "DestinationGroups" : ["All"],
}

json returned: 

{

  "CreatedInstancesCount": 2,

    "CreatedInstances": [

        {

            "AppInstanceId": "1-App-TEST_BUG-4-bf538da014924292987822a533a7f179",

            "UserEmail": "AAATESTER",

            "Success": true,

            "ErrorMessage": null

        },

        {

            "AppInstanceId": "1-App-TEST_BUG-4-e3636276f6b14593bb7e08a55c7a4676",

          "UserEmail": "Jan.kowalski@QALCWISE.COM",

            "Success": true,

            "ErrorMessage": null

      }
    ],

    "Errors": [],

    "IsSuccess": true,

    "ErrorMessage": null

}

Examples:

POST /api/app

Execute action in application instance

Execute workflow Action.

PUT /api/app/{appID}

Explanation:

User can use this method to execute a defined workflow action. There are multiple requirements that have to be met to execute this. User needs to be an editor at current state. Current State has to have defined workflow step for the action trying to execute. 

Remark: It doesn't matter if the action is visible or not, as long as the execution condition is met it will be executed.

Structure:

Action: String

Action is the case sensitive name of the action we want to execute.
{AppID} from URL  is an actual ID of an instance of application(can be viewed for example when visiting a saved instance of an application from the main stream, the ID is part of the url).

Example:

{
  "Action" : "actionname",
}

json returned: 

{

    "CurrentWorkflowState": "saved",

    "PreviousWorkflowState": "added",

    "AppInstanceId": "1-App-TEST_API_APP-1-28a09849c30b45229d2168493c5080fb",

    "IsSuccess": true,

    "ErrorMessage": ""

}

PUT /api/app/1-App-TESTAPP-1-743bf042411c405d91588317c82d5c55

Attachment

Enables simple attachment management in application instances.

Method Path Description
GET /api/attachment/{attachmentID} Get the list of attachments in instance or data record (deprecated)
GET /api/attachment?id=[attachmentID] Get the list of attachments in instance or data record
GET /api/attachment/{instanceID}?attachmentId={attachmentId} Download an attachment with given id from app instance 
GET /api/attachment/{instanceID}?attachmentName=Name Download an attachment, with given name, from instance (deprecated)
GET /api/attachment?id=[instanceID]&attachmentName=Name Download an attachment, with given name, from instance
POST /api/attachment/{instanceID}/{sectionAddress}?action=[ActionName] Add attachment to given section and save the instance by executing a workflow action (deprecated)
POST /api/attachment?id=[instanceID]&address=[sectionAddress]&action=[ActionName] Add attachment to given section and save the instance by executing a workflow action
POST /api/attachment/{id}/{address} Add attachment to given column on data record (deprecated)
POST /api/attachment?id=[id]&address=[address] Add attachment to given column on data record
DELETE /api/attachment/{instanceID}/{sectionName}?action=ActionName&attachmentName=Name Delete an attachment, with given name, from section and save the instance by executing a workflow action (deprecated)
DELETE /api/attachment/{id}/{address}?attachmentId={ID} Delete an attachment, with given id, from section and save the instance by executing a workflow action (deprecated)
DELETE /api/attachment?id=[ID]&address=[address]&attachmentID=id&action=[actionName] Delete an attachment, with given id, from section and save the instance by executing a workflow action
DELETE /api/attachment/{id}/{address}?attachmentId={ID} Delete an attachment, with given id, from data record (deprecated)
DELETE /api/attachment?id=[ID]&address=[address]&attachmentID=[attachmentID] Delete an attachment, with given id, from data record

Deprecated - this method is deprecated and may not work in newer versions of the site.

Get the list of attachments in application instance or data record

Get a list of attachments from an instance or data record

GET /api/attachment/{id} - this method is deprecated and may not work in newer versions of the site.
GET /api/attachment?id=[ID]

Patameters:

  • id: app instance id

      optional: false

      type: string

Explanation:

This method returns the list of attachments currently stored in an application instance.

json returned:

{

  "Attachments: [

        {

          "SectionName": "SECTION1",

          "Address": "SECTION1.B1",

          "Id": "7c72fbdfaa4e4b978d60b97417356ca2",

          "Name": "Dokument01.docx"

        },

        {

          "SectionName": "SECTION1",

          "Address": "SECTION1.B2",

            "Id": "8d546e53184d404ea342b8766212b523",

            "Name": "Dokument02.docx"

        },

        {

          "SectionName": "SECTION1",

          "Address": "SECTION1.B3",

            "Id": "b142bdb2fef441ffa5d69fe4c17d457f",

            "Name": "Dokument03.docx"

        }

    ],

  "IsSuccess": true,

  "ErrorMessage": null

Example:

Instance

GET /api/attachment/1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d (deprecated)

GET /api/attachment?id=1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d

DataTable

GET/api/attachment/1-DataTable-TAB_INCOIVE-5 (deprecated)

GET/api/attachment?id=1-DataTable-TAB_INVOICE-5

GET/api/attachment/1-List-LIST_USERS-1 (deprecated)

GET/api/attachment?id=1-List-LIST_USERS-1

REMARK: This returns attachments stored in all sections of type Attachment and Image.

 

Download an attachment, with given id from app instance

Download a specific attachment from application instance 

GET /api/attachment/{id}?attachmentId={id}

Parameters:

  • id: instanceID

      optional: false

      type: string

  • id: attachmentId

      optional: false

      type: string

Explanation:

This method downloads the attachment specified by attachmentId parameter.

Example:

GET /api/attachment/1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d?attachmentId=ea3026ad885a443db959f7f52602b715

REMARK!: To know the exact name of the attachment it is best to first get using API the list of all attachments stored in the given application instance.

Download an attachment, with given name, from instance

Download a specific attachment from application instance 

GET /api/attachment/{id}?attachmentName=name - this method is deprecated and may not work in newer versions of the site.
GET /api/attachment?id=[ID]&attachmentName=name

Parameters:

  • id: app instance id

         optional: false

         type: string

  • name: attachmentName

         optional: false

         type: string

Explanation:

This method downloads the attachment specified by attachmentName parameter.

Example:

GET /api/attachment/1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d?attachmentName=companylogo.jpg 

GET /api/attachment?id=1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d&attachmentName=companylogo.jpg

REMARK!: To know the exact name of the attachment it is best to first get using API the list of all attachments stored in the given application instance.

Add an attachments to application instance

POST  /api/attachment/{id}/{address}?action=[ActionName] - this method is deprecated and may not work in newer versions of the site.
POST /api/attachement?id=[ID]&address=[address]&action=[ActionName]

Parameters:

  • id: app instance id

         optional: false

         type: string

  • address: SectionName

         optional: false

         type: string

Explanation:

This method adds the attachments included in the request in the form and executes the action to save the application instance. To add a file in the 'from-data' tab, add the appropriate attachment.

Structure: 

The request has to be of content type: multipart/form-data with loaded files that are to be saved in the application instance.

Example:

POST /api/attachment/1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d/SECTION2?action=Save

POST /api/attachment?id=1-App-EXAMPLEAPP-1-7cc1ea9d268b495eaedf49b9a2a08c3d&address=SECTION2.A1&action=Save

Model: 

The request has to be of content type: multipart/form-data with loaded files that are to be saved in the application instance.

json returned:

{

  "CreatedAttachments":[

      {
          "SectionName": "SECTION4",

          "Address": "SECTION4",

          "Id": "1840ffdd436f4ba8818f41f2ab89e0f6",

          "Name": "NT.xlsx"

        }

    ],

  "ExecutedAction": {

      "CurrentWorkflowState": "Saved",

      "PreviousWorkflowState": "Added",

      "AppInstanceId": "1-App-TEST_BUG-4-c8801d708d3c46d5ac4d1facb1d91756",

      "IsSuccess": true,

      "ErroeMessage": ""

    },

  "IsSuccess": true,

  "ErrorMessage": ""

}

REMARK!: In the multipart/form-data only the name of the file matters, and the file is saved under that name. If the name is a duplicate the consecutive incremented integer is added at the end of the name before the file type to make it unique. (It is best to take a look at what was stored after POST)

 

Add an attachment to data record 

Add an attachment to data record 

POST /api/attachment/{id}/{address} - this method is deprecated and may not work in newer versions of the site.
POST /api/attachment?id=[ID]&address=[address]

Parameters:

  • id - ID table or list 

         optional: false

         type: string

  • address: the name of the file type column, to which we want to add the file

         optional: false

         type: string

Explatation:

This method adds an attachment to a table or list using the column name and record ID.

To add a file it is in the body ->from-data tab in the "key" column choose the type - (FILE or TEXT) and in the "value" column add the file.

Json returned:

{
  "CreatedAttachments":[

      {
          "ColumnName": "FILE",

          "Id": "b5ad89f6e084017acd71841aa050467",

          "Name": "Notes.docx"

        }

  ],

  "IsSuccess": true,

  "ErrorMessage": ""

}

Example:

POST /api/attachment/1-List-LIST_API_KEY-2/FILE

POST/api/attachment?id=1-DataTable-TEST_TAB_API-2&address=FILE

 

Delete an attachment with given id from application instance

Delete an attachment from application instance 

DELETE /api/attachment/{id}/{address}?attachmentId=[id]&action=[action] - this method is deprecated and may not work in newer versions of the site.
DELETE /api/attachment?id=[ID]&address=[address]&attachemntId=[ID]&action=[action]

  • id: app instance ID

         optional: false

         type: string

  • address: SectionName

         optional: false

         type: string

  • action - for app instances only, workflow action to be performed in order to save attachment in app instance

       optional: true

       type: string

Explanation:

This method deletes the attachment specified by attachmentId parameter and executes the action on given instance to save the changes.

Example:

DELETE/api/attachment/1-App-TEST_API_APP-2-2a5eba493b1b48ed87a071c83a5eb7e9/section3?attachmentId=bf9c0e55ab6b4ca0bde8a2f9a5a87cf3&action=delete

json returned:

{
"ExcetedAction":{
   "CurrentWorrkflowState":"deleted",
   "PreviousWorkflowState":"added",
   "AppInstanceId":"1-App-TEST_API_APP-2-2a5eba493b1b48ed87a071c83eb7e9",
   "IsSuccess":true,
   "ErrorMessage":""
   },
 "IsSuccess":true,
 "ErrorMessage":""
}

REMARK!: To know the exact name of the attachment it is best to first get using API the list of all attachments stored in the given application instance.

Delete an attachment with given id from data record

Delete an attachment from data record
DELETE /api/attachment/{id}/{address}?attachmentID=[id] - this method is deprecated and may not work in newer versions of the site.
DELETE /api/attachment?id=[ID]&address=[address]&attachmentId=[id]

Parameters:

  • id - ID table or list 

      optional:false

      type: string

  • address - column name

       optional: false

       type: string

  • attachmentId - id of attachment to remove

       optional: true

       type: string

Explanation:

This method deletes the attachment specified by attachmentId parameter and saves data record or executes the action on given instance to save the changes.

Example:

DELETE /api/attachment/1-DataTable-TEST_TAB_API-2/FILE?attachmentID=4cee0fa555af84e5997be226fefaf3f7b

Delete/api/attachment?id=1-DataTable-TEST_TAB_API-2&address=FILE&attachmentId=543008a09814444ee2b9aee04dafa99e9

json returned when delete attachments from record:

{
"IsSuccess": true,
"ErrorMEssage": null
{

REMARK!: To know the exact name of the attachment it is best to first get using API the list of all attachments stored in the given application instance.

Czy ten artykuł był pomocny?
Liczba użytkowników, którzy uważają ten artykuł za przydatny: 0 z 0
Masz więcej pytań? Wyślij zgłoszenie

0 Komentarze

Komentarze do artykułu są zablokowane.
Oparte na technologii Zendesk