REST APIs

• 1: Authentication
• 2: Instances

1 - Authentication

Introduction

The framework used for authentication in Kianda is OAuth 2.0. This framework uses industry-standard protocol for authorisation focusing on simplifying client developer practices, and at the same time providing specific authorisation flows for applications. The OAuth 2.0 framework uses Bearer type tokens to authorise access to the platform for individual users. This type of token is required by Kianda to perform any Create, Read, Update and Delete (CRUD) requests to external Application Programming Interfaces (APIs).

When working within Kianda, there is no need for the Bearer token when making API requests during widget, rule or field creation because the Bearer token is already retrieved as part of a user login. If you may want to create an application outside of Kianda however, this Bearer token needs to be provided for any CRUD operations to the API. There are two methods to retrieve the Bearer token:

• Using a POST request
• Using DevTools

Click on the links above to go the the relevant sections.

Retrieving Bearer token using a POST request

You can retrieve a bearer token using a POST request where the content body type is is set to application, x-www-form-urlencoded.

The request will look like https://domain.com/token where the domain is your company, for example https://green-itr.kianda.com/token . For the request to be valid, you need to pass the following form parameters to the body of the request:

The Response Body will be as follows:

{
    "access_token": "<Bearer access_token",
    "token_type": "bearer",
    "expires_in": 299,
    "userName": "<Provided username>",
    "userId": "<Application userId>",
    "subscriptionId": "<SubscriptionID>",
    "securityStamp": "<Token Security token (Guid)>",
    "hostURL": "<Your kianda domain>",
    ".issued": "<Token Issued Date and time>",
    ".expires": "<Token Issued Date and time>"
}

You can obtain the scope value by going to Administration > Subscription > Subscription Details > Subscription Id.

Retrieving Bearer token using DevTools

You can retrieve your Bearer token using Chrome DevTools, making sure you are logged into Kianda. When logged in, open Chrome DevTools by:

1. Right clicking your mouse anywhere on the screen.
2. Click on Inspect in the dialog box.
3. Open the Network tab.
4. Click on the info request.
5. In the Header tab, scroll down to authorisation. You can find your Bearer token here.

What’s next

To learn more about Kianda’s API go to Instance API.

2 - Instances

Introduction

Kianda’s REST Application Programming Interface (API) for instances allows you to flexibly and efficiently perform database operations or methods such as create, update and get/retrieve values on process instances. A process instance is created every time data is either saved or submitted to Kianda’s database for a given process design, see Process instance for more details.

How to get started

Before you get started, there are three things to keep in mind:

1. To use API methods in Kianda you must have an administrator role, go to View and edit user details to see information on how to set roles.

2. Each API method requires a Bearer token, see Authentication for more details.

3. Each of the following methods can be used on process instances or records, where {name} is the name of a process instance, such as ’training-approval-request-1'.

REST API Methods

You can perform Create, Read, and Update operations on Kianda resources using standard HTTP method requests, as summarised below:

Before any of the requests are used, you must have the bearer access token inserted into the request header, see Authentication for details.

Create a process instance - POST

This request creates a process instance/new record. To use POST:

1. Use the following request format:

{{domain}}/api/instances/create

2. Ensure that the bearer token is inserted into the authorisation header

   

3. Pass parameters into the body of the request, for example to create a new instance of a process called ’new-training-process’ where a textbox field called ‘Reason’ will be prepopulated with a value:

   {
    "processName" :"new-training-process",
    "instanceID" : "new-training-process",
    "TriggerField":"",
    "FieldsMappings":[{
      "fieldname":"reason",
      "text":"New employee",
      "value":"New employee"
     }
    ]
   }
   

4. The Response Body will be as follows:

{
	"success":true,
	"instanceID":"new-training-process-70"
}

In the example above a new instance is created with an ID ’new-training-process-70’. The new instance can be see in a List widget in a dashboard as follows.

In this example the Reason text box is populated from the POST request.

Read/Retrieve process instance fields - GET

{{domain}}/api/instances/{name}/fields?names=field1,field2..

where `{name}`is the name of the process instance.

This request retrieves the values of multiple fields by name.

No Request Body is required.

The Response Body will be as follows:

{
	"name":"",
	"text":"",
	"value":"",
}

Update a process instance - PUT

{{domain}}/api/instances/{name}

where `{name}`is the name of the process instance.

This request updates all fields in the instance by performing a comparison based on version number, to ensure there are no duplicate process instances.

The Request Body for the PUT request is:

{
	"ProcessName":"",
	"FieldsMappings":[],
	"TriggerField":"",
	"Status":""
}

The Response Body will be as follows:

{
	"ProcessName":"",
	"FieldsMappings":[],
	"TriggerField":"",
	"Status":""
}