Latest version: v2.52
WhatsApp: 0623684723

Business App API

Follow

Introduction

Workspace 365 Business App API allows clients to manage Business App records programmatically. Business App API is over HTTP and uses JSON as the input and output data format.

In the current documentation, values in curly braces e.g. {parameter} indicate placeholders for request parts to be replaced with actual values.

Prerequisites

To be able to use Business App API, the following conditions should be met:

  • Business App API is enabled in the Workspace 365 environment
  • Target Business App is installed
  • Target Business App is enabled.

Environment administrator can enable Business App API on the corresponding settings page, and the authentication token will be generated.

Authentication

Each request to Business App API should be authenticated with the token generated on the Business App API settings page. Each environment requires its own token. For authentication use the standard HTTP Authorization header with ‘Workspace365’ authentication scheme and token as credentials:

Authorization: Workspace365 {token}

E.g. Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098

It is strongly recommended not to use Business App API over non-https channels.

Authentication response codes

The API responds with the following HTTP status codes in case of authentication failure:

401

One of the following applies:

  • authorization header is missing
  • authentication scheme is incorrect
  • token is invalid for the environment

403

Business App API is not enabled for the environment

 

API endpoints description

Create new Business App record

POST /{environment name}/BusinessAppApi/{business app name}

Response status codes

200

A record has been created successfully; check response data format

400

Validation issue; check error response data format

401, 403

Authentication issue, check potential reasons

404

  • Cannot find a business app with supplied name
  • Business app is not installed
  • Business app is not enabled

 

Input data structure

Business App record properties are to be supplied in the JSON format, with property names corresponding to field names configured for the business app in Business App Builder:

{
"{property name 1}": {value 1},
"{property name 2}": {value 2},
...
"{property name N}": {value N},
}

 

Extra properties supplied but not present on the business app will be ignored without any validation errors. It is possible to omit properties, provided the corresponding business app fields are not required. Currently, the default values configured in the business app are NOT applied in that case.

Fields of the following types should not be supplied to the API and will have empty values in the created record:

  • Link to a single business app record (Combobox (parent) in Business App Builder)
  • Link to multiple business app records (Gridview (child) in Business App Builder)
  • E-mail link
  • Folder link
  • User
  • Calculation

Fields of the following types should not be supplied to the API, and will have correctly generated values in the created record:

  • Autonumber

For properties which are not required, null can be used to indicate that a value is not present.

 

String properties

Values for the following fields are passed as a string according to the JSON specification:

  • Single line text
  • Multiline text
  • Rich text
  • Email

For example:

"New Day at Work"
"user@example.com"
"Some <b>bold</b> rich text"

 

Numeric properties

Integer field values are passed as a JSON number without fractional part, and is expected to be in the range of 32-bit signed integer:

42

Decimal field values are passed as JSON number, valid range and precision corresponds to that of a IEEE 754 double-precision floating point:

12.34

Percentage field values format is the same as decimal, e.g. 15.5% should be

15.5

 

Currency

Currency fields are to be passed as a JSON object having “Amount” property (a number), and a “Currency” property indicating an ISO 4217 currency code as a string. Currency should be in the list of currencies supported by Workspace 365.

Amount should be in the range of System.Decimal CLS type.

Example:

{"Amount": 499.99, "Currency": "EUR"}

 

Date and time properties

Date fields having ‘Date and time’ mode set in Business App Builder are expected to be strings in ISO 8601 format. If time zone is not specified, server time zone is assumed.

Examples:

"2017-03-30T08:25:21"
"2017-03-30T08:25:21+04:00"
"2017-03-30T08:25:21Z"

Date fields having ‘Date only’ mode set in Business App Builder are expected to be passed as a string in ISO 8601 format without a time portion. If the passed value has a time part, it will not result in error, but the time part will not be taken into account.

Example:

"2017-03-30"

Date fields having ‘Time only’ mode set in Business App Builder are expected to be strings in ISO 8601 without a date part. It implies 24-hours format.

Example:

"20:13:14"

 

Dropdown

Values for fields of type “Dropdown menu” are supplied as a JSON string corresponding to the text value of a desired item.

If no value needs to be selected, empty string (“”) shall be provided.
Examples (assuming “New”, “Approved”, “Done” dropdown configuration):

"Approved"
""

 

Checkbox

Values for fields of type “Checkbox list” are provided as a JSON array of strings corresponding to the text values of checked items.

If no values are selected, empty array shall be provided.

Examples (assuming “New”, “Approved”, “Done” dropdown configuration):

["New", "Approved"]
[]

 

Successful response

If Business App record has been created successfully, the response will be a JSON object containing a single property “id” which contains a Workspace 365 identifier of the created record. The identifier is a signed 32-bit integer number.

Example:

{“id”: 1034}

 

Error response

If a Business App record has not been created due to an incorrect input data, response will be a JSON object having “globalError” and “fieldErrors” properties.

Property “globalError” will be set to a non-null object in case of a validation error which is not connected to a single specific field. It is a JSON object with a “message” property containing potentially human-readable error description.

Property “fieldErrors” will be set if some field values failed the validation. For every such a field there would be a property named the same as in the input, containing a JSON object with a “message” property containing potentially human-readable error description.

Human readable messages can be given in one of the languages supported by Workspace 365 if the request contains a corresponding Accept-Language header.

Example:

{
  "globalError": null,
  "fieldErrors": {
    "Joining date": {
      "message": "Date format is incorrect"
    },
    "State": {
      "message": "Dropdown value not found"
    },
    "Lastname": {
      "message": "Is required"
    },
    "Email": {
      "message": "The email address is invalid"
    }
  }
}

 

 

Request and response examples

Successful request and response

Request:

POST https://workspace365.url/environment/BusinessAppApi/Employee HTTP/1.1
Host: workspace365.url
Content-Type: application/json; charset=utf-8
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098
{
      "Firstname": "John",
      "Lastname": "Doe",      
      "Email": "johndoe@example.com",      
      "Joining date": "2012-02-13",      
      "Capacity": 60,      
      "Rate": {     
      "Amount": 15.00,
      "Currency": "USD"
      },    
      "State": "Active",
      "Equipment": [ "Monitor", "Desktop" ],
      "Comments": "<p>something</p><b>bold<b>"
}

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
X-Frame-Options: SAMEORIGIN
Date: Thu, 06 Apr 2017 14:39:54 GMT

{"id":5}

 

Successful request and response with some null values

Request:

POST https://workspace365.url/environment/BusinessAppApi/Employeee HTTP/1.1
Host: workspace365.url
Content-Type: application/json; charset=utf-8
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098

{
      "Firstname": "John",
      "Lastname": "Doe",
      "Email": "johndoe@example.com",
      "Joining date": null,
      "Capacity": 60,
      "Rate": null,
      "State": null,
      "Equipment": [ "Monitor", "Desktop" ],
      "Comments": "<p>something</p><b>bold<b>"
}

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
X-Frame-Options: SAMEORIGIN
Date: Tue, 11 Apr 2017 09:31:06 GMT

{"id":8}

 

Failed global validation response

Request:

POST https://workspace365.url/environment/BusinessAppApi/Employee HTTP/1.1
Host: workspace365.url
Content-Type: application/json; charset=utf-8
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098

{
      "Firstname": "John",
      "Lastname": "Doe",
      "Email": "johndoe@example.com",
      "Joining date": "2012-02-13",
      "Capacity": 60,
      "Rate": {
        "Amount": 15.00,
        "Currency": "USD"
      },
      "State": "Active",
      "Equipment": [ "Monitor", "Desktop" ],
      "Comments": "<p>something</p><b>bold<b>"
}

Response:

HTTP/1.1 403 Forbidden
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
X-Frame-Options: SAMEORIGIN
Date: Thu, 06 Apr 2017 14:42:20 GMT

{"globalError":{"message":"Business App isn't enabled"},"fieldErrors":null}

 

Failed fields validation response

Request:

POST https://workspace365.url/environment/BusinessAppApi/Employee HTTP/1.1
Host: workspace365.url
Content-Type: application/json; charset=utf-8
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098

{
      "Firstname": "John",
      "Email": "johndoe at example.com",
      "Joining date": "2012-13-13",
      "Capacity": 60,
      "Rate": {
        "Amount": 15.00,
        "Currency": "USD"
      },
      "State": "Invalid",
      "Equipment": [ "Monitor", "Desktop" ],
      "Comments": "<p>something</p><b>bold<b>"
}

Response:

HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
X-Frame-Options: SAMEORIGIN
Date: Thu, 06 Apr 2017 14:46:19 GMT

{"globalError":null,"fieldErrors":{"Joining date":
{"message":"Error during converting data '2012-13-13' to type 'DateTime'"},
"State":{"message":"_ValueNotFound"},"Lastname":{"message":"Is required"},
"Email":{"message":"The email address is invalid"}}}

 

Failed fields validation response in a requested language

Request:

POST https://workspace365.url/environment/BusinessAppApi/Employee HTTP/1.1
Host: workspace365.url
Content-Type: application/json; charset=utf-8
Accept-Language: nl
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098

{
      "Firstname": "John",
      "Email": "johndoe at example.com",
      "Joining date": "2012-11-13",
      "Capacity": 60,
      "Rate": {
        "Amount": 15.00,
        "Currency": "USD"
      },
      "State": "",
      "Equipment": [],
      "Comments": "<p>something</p><b>bold<b>"
}

Response:

HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
X-Frame-Options: SAMEORIGIN
Date: Thu, 06 Apr 2017 14:52:11 GMT

{"globalError":null,"fieldErrors":{"Lastname":{"message":"Is vereist"},
"Email":{"message":"Dit e-mailadres is ongeldig"}}}
Have more questions? Submit a request

Comments