OData services

<< Click to Display Table of Contents >>

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

OData services

Overview

Bizagi provides programmatic access to the underlying business information in your data model, by featuring a powerful API based on RESTful and OData services.

This API allows you to work with your processes data from external applications, especially for the Experience design features for instance to start new relevant processes, execute searches and trigger actions, or to fetch pending cases in other portals or tools of your choice.

 

logo-OData

 

Basic OData concepts

Bizagi complies to OData version 4.0, by featuring a comprehensive set of possibilities to work with the underlying data of the business processes.

OData services are built as RESTful services (featuring resources, accessible throughout URLs and while having every resource use a unique identifier).

 

As RESTful services, these rely on the fixed set of operational HTTP methods as shown in the table below:

 

HTTP METHOD

DESCRIPTION

GET

A read-only operation.

It is used to query the server for specific information.

It is both an idempotent (no matter how many times you apply the operation, the result is always the same), and safe operation (invoking a GET does not change the state of the server).

POST

POST is the only non-idempotent and unsafe operation of HTTP (means that it is allowed to modify the service in a unique way).

You may or may not send information with the request.

You may or may not receive information from the response.

 

For more information about the OData specification, refer to http://www.odata.org/.

 
Security in Bizagi API

The OData services in Bizagi are protected and rely on a standard authentication mechanism which is OAuth version 2.0.

Requests made to these services need to be granted with rights to resources, through previously generated OAuth keys.

Regarding the OAuth version 2.0 specification, Bizagi supports the following two OAuth flows, which the most commonly used ones:

 

1.Authorization code:

This allows the client application to authenticate with inputted credentials on runtime (throughout a login page).

This means that this flow is designed for human interaction, where requests will use impersonation of the end users.

For more information about its specification, refer to https://tools.ietf.org/html/rfc6749#section-1.3.1.

 

2.Client credentials:

This allows server to server integration where there is no need to use further specific credentials of the end users.

For more information about its specification, refer to https://tools.ietf.org/html/rfc6749#section-1.3.4.

 

Bizagi API services

Bizagi offers two different OData services: one to access business data (resources classified as part of the data services), and another to access system configuration regarding Stakeholders definitions (resources classified as part of the metadata services).

Through the data services you may accomplish the following in Bizagi:

Obtain the collections of a Stakeholder's my stuff.

Obtain and execute the actions available for items in a collection of a Stakeholder's my stuff.

Obtain and execute the searches available for a Stakeholder.

Obtain and execute the actions available for items returned by a search for a Stakeholder.

Obtain the list of available processes or relevant processes for a Stakeholder.

Create a new case for a relevant process for a Stakeholder.

Create a new case for a given process for any end user (regardless of being a Stakeholder or not).

Obtain the list of pending cases with their pending activities (regardless of being a Stakeholder or not).

Complete a pending activity or event by submitting information applicable to that activity or event of an end user (regardless of being a Stakeholder or not).

Search for a specific case and obtain its detail, by providing its case identifier.

 

To get started and test for yourself the use of the OData services, refer to Getting started.

 

Through the metadata services you may obtain details focused on how to further invoke data services, such as: Obtaining the list of Stakeholders in the project, or which searches, processes, relevant processes or my stuff collections they have under their Experience design.

 

For a full list on the resources of each service, refer to Services index.

Additionally, it is recommended that you review the information presented under the Basic Concepts of this API.