Using OData with Mulesoft

<< Click to Display Table of Contents >>

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

Using OData with Mulesoft

Overview

Bizagi has a RESTful API to integrate external systems using the OData standard. See the OData layer. This API exposes several methods that let an external system create instances of processes, tasks, obtain information about cases, and related to the experience design.

 

Although OData itself is a standard, systems expect the specification of APIs in a single language. One of those languages is RAML. This modeling language provides a format that both the API provider and consumer can use..

 

There are service providers that use RAML to help organizations keep all their APIs centralized and organized. One API manager offering is Mulesoft. Bizagi has created a descriptor of Bizagi OData services that can be used in Mulesoft, so  you can test and invoke OData methods directly from the  API manager.

 

RAML

RAML stands for RESTful API Modeling Language. Using this language, you can define a description of an API to help developers to manage an API lifecycle: Designing, building, testing, documenting, and using.

 

As a modeling language, RAML let you translate an API technical description, into a language applications with a user interface can use, so developers can test, configure and document an entire API without using code.

 

Mulesoft structure

Integration between different systems is a common concern in organizations. The usual way to expose an integration layer is through APIs. Each system and application in core businesses may customize its API, based on technologies, protocols, and systems used. Managing and centralizing information related to APIs can be a demanding task that Mulesoft can make easier.

 

Within the same platform, you can upload systems APIs like Bizagi or Salesforce. Then create your API for specific business scenarios in a particular area, for example, Invoice payment in the Finance area. This business API can contain a whole set of systems APIs needed to execute business tasks like creating the customer invoice. Finally, you can create an experience layer of APIs aimed for devices or technologies, for example, a web application or a mobile device. The following picture shows how APIs can be structured in Mulesoft.

 

raml_1

 

Mulesoft has a web-based platform named Anypoint, where you can manage the integration of all your systems and applications, by reusing their APIs.

 

Each API can be contained in one object called Asset. For each asset, you can define the documentation, policies, endpoints, and other information related to the API.

 

For asset creation, Anypoint has the Exchange module where you can add or create private or public assets. Mulesoft provides a public repository wheren you can expose public assets. You can also create private assets, and define their asset types, depending on how the API is exposed:

 

REST RAML

SOAP API using WSDL

HTTP API

Custom

 

After creating or adding an asset, and configuring it, you can use the API related to the asset in applications that you can build in Anypoint.

 

RAML descriptor of the OData layer

The integration layer of Bizagi is OData. The RAML descriptor translates the OData API in RAML, so you can create an asset in Anypoint, and use all the integration endpoints within Mulesoft.

This descriptor contains the following OData methods. See our Services index:

 

Cases

Cases(Id)

Cases/Workitems

Cases/Workitems(ID)

Cases/Workitem(Id)/Next

Processes

Process(ID)

Processes(ID)/Start

Processes(ID)/Cases

 

note_pin

Before using the RAML Odata descriptor we recommend understanding the OData layer first. See getting started.

 

Download the Odata RAML descriptor

Click here to download the ZIP file containing the Bizagi Odata RAML descriptor.

 

Asset configuration

To configure the asset, you need to access the Anypoint platform.

 

raml_2

 

Click the three-line menu at the top-left corner and select Exchange.

 

raml_3

In your private master module, Click Publish new asset located at the top right corner.

 

raml_4

Enter the asset name and select the REST API – RAML asset type. Then upload the ZIP file containing the Bizagi OData RAML descriptor. Make sure that the Main file is api.raml. Finally, click Publish.

 

raml_5

 

When you access the asset, you see three main design areas:

 

raml_6

 

1.Asset specification: This section contains the following items.

 

Item

Description

Endpoints

Bizagi OData methods contained in the RAML descriptor.

Documentation

Description of the RAML file.

Types

Types of responses that you can find throughout the endpoints. Each response object shows its JSON structure.

Security

Authentication types which are available when you invoke each endpoint.

API instances

This section contains all the URLs from where you can invoke the API (asset).  From here, you can configure the URL of the Bizagi project that you are integrating through the Mulesoft asset.

 

2. The middle section is the design area. When you click a module from the left panel, Anypoint displays the design area of that object. For example, when you click an Endpoint, you find its description in the design area.

 

raml_7

 

Here you find the description of each endpoint (OData method), including examples of inputs and outputs. For example, in POST methods, you can find the structure of the expected body input.

 

raml_33

 

3. Details panel: In this panel, you find detailed information about the module you selected. You can also share the asset with other Mulseoft users, download the RAML descriptor, and add tags.

 

raml_8

 

The tabs displayed in this panel depend on the module you selected in the asset specification section.

 

Learn how to set the asset with a Bizagi project.