Getting started

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > OData services >

Getting started

Overview

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

 

General recommendations

 

Using Postman.

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

Extensions such as Postman (you can use a similar one such as Advanced REST Client https://advancedrestclient.com/), let you 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 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.

Through Experience design, ensure that you have created Stakeholders and have associated the users in your Work Portal to the relevant Stakeholder, so Bizagi can present 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.

There are a few specific services which are an exception to the above rule; for instance those aimed at returning information about cases, which do not require Stakeholder configuration.

 

What you need to do

Here is a high-level outline of what you do to invoke Bizagi OData services:

 

1.  Register an OAuth application.

This first step is granting access to an external application and creating appropriate access keys.

This is a requirement in order to use OData services.

 

2. Authenticate with OAuth.

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

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

 

3. Invoke OData services.

As a last step, you can make any number of invocations can be through Postman while using the access token.

 

 

Procedure

To easily test drive Bizagi OData services, follow these steps.

 

1. Register an OAuth application.

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

 

Click the OAuth2 Applications option under the Admin menu to grant access to an external application.

 

OData_Workportal1

 

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

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

 

 

OData_Workportal2

 

note_pin

For the default and system settings, you may only choose to edit the token's lifetime, which determines the number of minutes after which a token expires (this enhances the security employed by these tokens, especially against replay attacks).

 

OData_Workportal15

 

 

When defining the new application, provide the following details:

Name: provide 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 at Bizagi API OAuth concepts.

Web Site: Specify an associated web site URL.

Allowed Scope: Possible checkboxes to check are: API or Login.

We recommend you enable API to grant access so you can make full use of the OData services.

Enable Login especially when using Authorization Code as the Grant type.

User name: (applies when using Client credentials). Provide the name of an existing Bizagi user. Make sure 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 general use, consider selecting Web application.

A standard approach is to use Web application so a server capable of processing requests through endpoints invokes the Bizagi API, while mobile apps or other type of clients invoke services from such server.

Redirect URI: (Applies when using Authorization Code). Define the URL to which the user is directed in the callback after providing their credentials.

You always need to define the URL using HTTPS.

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

 

note_pin

We recommend that you use these combinations, usually involving tow 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

 

In this example, the registered application  authenticates on behalf of the agilityCorp\TomH user.

 

Once you are done, click Save.

Your new registered application appears in the list with its access keys.

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

 

OData_Workportal4

 

 

2. Authenticate with OAuth.

Once you have copied the Client Id and Client Secret, establishing authenticated communication through Postman.

Note that Bizagi expects the credentials as a single string encoded in base64.

 

2.1 To encode the credentials as a single string:

Copy the Client id first and append a colon (:), then add the Client secret.

Here is the format, disregarding the [] characters:

[Client Id]:[Client Secret]

Encode this string with base64.

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

 

The result is a string containing 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 Input the URL of this service for your specific Bizagi project.

Use an HTTP POST action with the URL set as:

[your_bizagi_project_url]/oauth2/server/token

 

Make sure that:

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

For an on-premise Bizagi project, the URL would be:

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

For Automation Service projects, the URL would be:

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

 

Specify as well that No Auth is employed as the authorization type.

 

OData_Postman2

 

2.4 On the Headers tab, specify:

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

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

Use the following format, disregarding the [] characters:

Basic [Encoded credentials]

 

OData_Postman2b

 

 

2.5 Finally, on the Body tab, check the raw checkbox to include this line in the body:

grant_type=client_credentials&scope=api

 

OData_Postman3

 

note_pin

The possible values for grant_type are client_credentials and authorization_code.

The possible values for scope are login, api and all.

You need to use authorization_code in a client application that implements this spec adequately (while sending out credentials).

 

At this point you can 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. Invoke OData services.

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

To do a quick test, you can use an HTTP GET action to fetch some basic data.

 

Make sure you use an OData service URL.

For a quick start, use:

[your_bizagi_project_url]/odata/data/stakeholders

 

Configure:

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

Follow this format, disregarding the [] characters:

Bearer [access_token]

Content-type: application/json

 

OData_Postman4

 

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:

 

OData_Postman6

 

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

 

OData_Postman1Workportal

 

The access_token expires after the time you set for its token lifetime setting elapses, so you may need to launch a new invocation and authenticate again with the Encoded credentials.

 

note_pin

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

To learn about filters and other options to restrict which data you will work with, refer to Querying options.

 

At this point that you have made a first invocation to these services. You can now explore the resources and different alternatives to query them.

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

For additional information about properties, querying options and other useful concepts when invoking these services, browse Basic concepts.