URL and important notes

<< Click to Display Table of Contents >>

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

URL and important notes

Overview

Bizagi features an API for external applications to access the processes functionality and the business information underlying in your data model, as described at Bizagi API for external applications.

Refer to the following important notes and further details when using Bizagi API.

 

 

URL of Bizagi web services

Bizagi web services are already generated, built and published in order to speed up the implementation of your integration requirements.

Recall that you may too configure additional aspects for them (e.g, hardened security measures) at the Web application server and even relocate them.

The URL and initial location of these services will vary according to the Web application server being used by your project, having 1 web service for each of the 3 categories representing a major component in Bizagi's product architecture (BPMN engine/Workflow, Data access engine/Entity Manager, or Query engine).

 

 

In Bizagi projects using Microsoft's IIS, Bizagi web services are located as:

http://[Server_name]/[Bizagi_project]/WebServices/[internal_component].asmx?wsdl

Notice that:

 

[Server_name] is the name of your project's server.

[Bizagi_project] is the name of your Bizagi project.

[internal_component] is the name of Bizagi's internal component: EntityManagerSOA, WorkflowEngineSOA, or QuerySOA.

 

Example:

http://localhost/CreditApplication/WebServices/EntityManagerSOA.asmx?wsdl

 

note_pin

Note that you should always reference these web services with the explicit ?wsdl termination.

Though when using .NET technologies (a client, even a browser) you may look up such web services without using this termination, you should follow interoperability best practices to ensure that for instance, a Java-based or php client can interpret them.

 

Important notes and best practices

The following notes consider best practices and specifics for web services interoperability among different platform technologies.

 

1. Data types in web methods

Available web methods offer the same functionality for Bizagi projects.

Web methods of Bizagi API are those named with an "...AsString" termination (such as createCasesAsString, getEntitiesAsString, queryCasesAsString, performActivityAsString, saveEntityAsString, to name a few).

Such web methods use string inputs and outputs.

 

note_pin

Other web services and methods not using the "...AsString" termination but handling XMLDocument data types, are mainly shipped in by Bizagi for backward compatibility purposes.

Such web methods (e.g, createCases, getEntities, queryCases, performActivity, saveEntity) use a XMLDocument class which is native of .NET's framework and will not allow best interoperability practices.

 

2. Root node mandatory

When using Bizagi API (or also when Bizagi receives a response from an external service invocation), note that the resulting XML (after any transformation if applicable) should always include a root node.

The same holds true for best practices , in which well-formed XML files always contain a root node.

 

3. CDATA syntax

When using Bizagi API (or also when Bizagi receives a response from an external service invocation), keep in mind that it is required that XML are well-formed (properly enclosed).

It is strongly recommended to use the CDATA element in the syntax of your XMLs to wrap any string-based information that may interfere with enclosing characters.

The use of CDATA is XML-standard and aligned to best practices in order to ensure that any XML special characters (those proprietary of XML notation, such as: apostrophe, double quotes, ampersand, less-than and greater-than signs), are correctly interpreted.

CDATA syntax will allow for escape characters.

 

The following example shows the CDATA element use in a getActivitiesAsString invocation:

<![CDATA[<BizAgiWSParam><domain>domain</domain><userName>admon</userName></BizAgiWSParam>]]>

 

The following example shows the CDATA element use in a getEntities invocation:

<BizAgiWSParam><EntityData><EntityName>Customer</EntityName><Filters><![CDATA[ Active=1 ]]></Filters>

</EntityData></BizAgiWSParam>

 

note_pin

Keep in mind that there may be some SOAP-client tools which do require CDATA (e.g, SOAP UI) and such special treatments in the information that is sent.

Refer to your SOAP-client specific documentation to learn about any special treatments when sending information.

 

4. Date formatting

When using Bizagi API (or also when Bizagi receives a response from an external service invocation), and while sending dates, it is required to use XML-standard date formatting.

You will need to ensure the following complete format for dates is kept:

YYYY-MM-DDTHH:mm:ss

 

5. Files as attachments

When using Bizagi API (or also when Bizagi receives a response from an external service invocation), and while sending files, it is required to handle them as String encoded in base 64.

 

SOALayerConsiderations_Base64

 

To view more information and an example about how to send attachments into Bizagi processes, refer to Uploading files or images from an external application.