Getting started

<< Click to Display Table of Contents >>

Navigation:  Bizagi API >

Getting started

Overview

Bizagi provides an API featuring OData services, as described at Bizagi API.

In order to explore and validate how these Bizagi OData services work, consider getting started by following the steps mentioned below.

 

General recommendations

Consider the following notes:

 

Using Postman.

For a quick start, we strongly recommend using Google Chrome and an extension plug-in called Postman.

Extensions such as Postman (or you may choose to use a similar one such as Advanced REST Client https://advancedrestclient.com/), allow you to invoke OData services while being able to customize the information that gets sent in the header of the request (which is not possible through a browser).

For information about Postman, refer to https://www.getpostman.com/docs/.

 

Configuring the potential of Stakeholders.

For ideal results and in order to fully seize the data considered by the Bizagi OData services, we strongly recommend having modeled processes in your project which make use of the Experience design.

Throughout Experience design, ensure that you have created Stakeholders and that you have them configured in your Work portal to your different users, so that Bizagi is presenting data differently according to the given Stakeholder.

 

OData_Postman1Workportal

 

The image above shows a user named Tom Hall which is set as a Legal Area Worker Stakeholder.

 

What you need to do

To invoke Bizagi OData services, consider the following high-level outline:

 

1.  Registering an OAuth application.

This first step is about granting access to an external application, while creating appropriate access keys.

This is a requirement in order to use OData services.

 

2. Authenticating with OAuth.

This step uses Postman to establish authenticated communication with the OData services.

Once using the access keys, you will get an access token to make further requests.

 

3. Invoking OData services.

As a last step, any number of invocations can be made while using the access token (still considering Postman).

 

 

Procedure

In order to easily test drive the Bizagi OData services, follow these steps.

 

1. Registering an OAuth application.

Once you have users set as Stakeholders and use comprehensively, the Experience design features in Bizagi, go to the Work portal.

 

Click on the OAuth2 Applications option available under the Admin menu in order to grant access to an external application.

 

OData_Workportal1

 

Notice this option lists services being accessed by Bizagi devices, but it allows you to include additional applications that represent granted access to the services by getting appropriate access keys.

Click on the option to add a new record in this table:

 

 

OData_Workportal2

 

note_pin

Note that for the default and system settings, you may only choose to edit the token's lifetime, which determines a number of minutes after which a token expires (in order to enhance the security employed by these tokens, especially regarding replay attacks).

 

OData_Workportal15

 

 

When defining the new application, ensure you consider the following details:

Name: Give a unique and representative name.

Grant type: Possible values are: Authorization Code, Client credentials, or all.

More information about these values and when to use each best, is instructed at Bizagi API OAuth concepts.

Web Site: Specify an associated Web site URL.

Allowed Scope: Possible checkboxes to tick are: API, or Login.

It is recommended to always enable API in order to grant access so that you can make full use of the OData services.

Enable Login specially when choosing to use Authorization Code as the Grant type.

User name: (Applies when using Client credentials). Type the name of an existing Bizagi user, and ensure you select it from the suggested list of matching users (includes the domain information).

Redirect strategy:  (Applies when using Authorization Code). Possible values are: Web Application, Mobile Title Bar Browser, and Mobile Localhost Port.

A redirect strategy defines which clients will be able to make use of this application.

For this initial test and for a general use, you may consider setting Web application.

Nonetheless, an usually recommended approach is indeed to use Web application so that a server (capable of processing requests through endpoints) invokes the Bizagi API, while having in turn, mobile apps or any other type of clients invoke services from such server.

Redirect URI: (Applies when using Authorization Code). Define the URL to which there will be directed in the callback once an user inputs his/her credentials.

Token lifetime: Define the number of minutes for which a same token is valid and can be reused for another invocation (usually to enhanced security while avoiding replay attacks).

 

 

note_pin

Note it is recommended to use these combinations, involving usually 2 different applications:

 

For Data services:

Grant type: Authorization code, Allowed scope: Login and API.

 

For Metadata services:

Grant type: Client credentials, Allowed scope: API.

 

 

OData_Workportal3

 

Notice how in this example, the registered application will authenticate on behalf of the agilityCorp\TomH user.

 

Once you are done, click Save.

You will notice that your new registered application is listed along with its access keys.

Access keys to be used and copied to the clipboard, are: Client Id and Client Secret.

 

OData_Workportal4

 

 

2. Authenticating with OAuth.

Once that you have copied the Client Id and Client Secret, through Postman we establish authenticated communication.

Before doing so, note that Bizagi expects the credentials as a single string encoded in base64.

 

2.1 In order to encode this as a single string, carry out the following:

Copy the Client id first and append a colon (:) to finally add the Client secret.

The following format is employed, disregarding the [] characters:

[Client Id]:[Client Secret]

Encode this string with base64.

For this you may rely on external web sites such as https://www.base64encode.org/, or use your own program.

 

In the end, you will have a resulting string with the credentials contained within, and we will refer to it as the Encoded credentials:

 

OData_Postman0

 

 

2.2 Open the Postman extension plug-in and use this encoded string to authenticate to the OAuth service.

 

OData_Postman0b

 

2.3 First make sure you input the URL of this service for your specific Bizagi project.

Ensure you use an HTTP POST action with such URL set as:

[your_bizagi_project_url]/oauth2/server/token

 

Consider:

[your_bizagi_project_url]: Corresponds to the URL where end users access the Bizagi Work portal.

For instance for an on-premise Bizagi project, such URL would be:

https://[your_server]/[your_project]/oauth2/server/token

While for Bizagi Cloud projects, such URL would be:

https://[project_environment]-[your_project]-[your_company].bizagi.com/oauth2/server/token

 

 

Specify as well that No Auth is employed.

 

OData_Postman2

 

2.4 Switch to the Headers tab and specify:

Content-type: application/x-www-form-urlencoded

Authorization: Input the Basic keyword, add a blank space and then add the Encoded credentials obtained in a previous step.

The following format is employed, disregarding the [] characters:

Basic [Encoded credentials]

 

OData_Postman2b

 

 

2.5 Finally switch to the Body tab tick the raw setting to include this line in the body:

grant_type=client_credentials&scope=api

 

OData_Postman3

 

note_pin

Notice that the possible values for grant_type are: client_credentials or authorization_code.

Similarly, possible values for the scope are: login, api or all.

However, the use of authorization_code needs to be done in a client application where it implements this spec adequately (while sending out credentials).

 

At this point you may click Send, which triggers the request to authenticate.

A successful response returns an access_token along with other data relevant to it:
 

OData_Postman5

 

 

3. Invoking OData services.

Once you get the access_token, you may use it for a new invocation and test drive the OData services.

This time and in order to do a quick test, you may use an HTTP GET action to fetch some basic data.

 

When doing so, make sure you use a OData service URL this time.

For a quick start, you may use:

[your_bizagi_project_url]/odata/data/stakeholders

 

Then configure:

Authorization: Input the Bearer keyword, add a blank space and then add the access_token obtained in the previous step.

The following format is employed, disregarding the [] characters:

Bearer [access_token]

Content-type: application/json

 

OData_Postman4

 

At this point you may click Send, which triggers the request to fetch data in JSON format.

A successful response for this specific example and URL, returns the name of the Stakeholders to which the authenticated user belongs to:

 

OData_Postman6

 

Notice how the set Stakeholder for this user (agilityCorp/TomH having full name as Tom Hall) is Legal Area Worker.

 

OData_Postman1Workportal

 

Consider that the access_token expires as set through its token lifetime settings, and therefore you may need to launch a new invocation by first authenticating again with the Encoded credentials.

 

note_pin

You may of course choose to include filters or navigate data returned by the response.

In order to learn about the filters and options to restrict which data you want to handle, refer to Querying options.

 

At this point that you have made a first invocation to these services, you may further explore the resources and different alternatives to query them.

For more information about all of these services, refer to Data services or Metadata services.