Requisites and concepts for SOAP web services

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > SOAP web services >

Requisites and concepts for SOAP web services

Overview

Bizagi features a SOAP-based API for external applications to access the processes functionality and the business information underlying in your data model, as described at SOAP web services.

Though Bizagi API provides a comprehensive set of  web services which are already generated, built and published, consider the following concepts before using them.

 

note_pin

It is expected (requisite) that at least one process has been fully modeled in your project (workflow, data model, etc), in order to be able to use Bizagi API.

Though some web methods may not strictly handle or require a process, these will at least use definitions of your data model.

 

It is also important that you have verified and validated that your process works as expected.

This is so because Bizagi manages transactions consistently across its different components, while guaranteeing data integrity. For instance this means that Bizagi will throw an exception and rollback any web service invocation that enables a next workflow activity, if that activity executes a business rule that fails.

 

Requisites

In order to start using these web services, ensure you enable their use in each of your environments through Bizagi Studio.

 

To do so, locate the Environment option in the upper ribbon under the Configuration tab, and ensure you tick either the Enable legacy web services (asmx) or the Enable WS-Security checkbox.

Consider that it is strongly recommended to choose the Enable WS-Security alternative for an enhanced level of security. Through this alternative you would configure the use of certificates (the set of X509 parameters shown below).

Otherwise you will need to configure access restrictions for these web services, as instructed at the Bizagi System administration chapter, according to your web server).

 

EnablingWS

 

Further detail on this procedure is described at Enabling Bizagi API.

 

 

Data model definitions

Bizagi API works with standard XML-structured inputs and outputs (requests and responses).

Therefore, refer to these 2 concepts before getting started with Bizagi API.

 

1. Data model XML schema

When sending business information to Bizagi (either when creating new cases, completing an activity, or updating records in the data model), you will need to ensure this information is sent in an XML structure that complies to Bizagi Xpath concepts and the XML schema of your data model.

 

EntitiesXmlSchemas_Image004

 

For more information about viewing and understanding how your process data model is represented through an XML schema, refer to Bizagi XML schemas.

 

2. Business keys definitions

As in any integration of two applications, it is a best practice to rely on unique codes for records instead of internal system IDs.

A unique code will represent that information which distinguishes each record, and so, relying on unique codes allows you to ensure that both Bizagi and your external application are talking about same specific records, especially when there's the need to update or reference a given one.

 

In Bizagi, you may pre-define unique codes through the business key concept.

For each Entity you may specify which attribute or set of attributes hold the information that represents unique codes (unique constraints).

Furthermore, having well-defined business keys will allow Bizagi to validate and avoid duplicate records.

 

BusinessKeys01

 

For more information about the business keys concept in Bizagi, refer to Using business keys in XMLs.