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.
The URL of these services will vary according to the three categories representing a major component in Bizagi's product architecture (BPMN engine/Workflow, Data access engine/Entity Manager, or Query engine).
WS-Security web services when enabled, are located as:
https://[environment]-[project]-[company].bizagi.com/WebServices/[internal_component].svc?wsdl
Notice that:
•[environment] is the environment where the project is running.
•[project] is the name of your Bizagi project.
•[internal_component] is the name of Bizagi's internal component: EntityManagerSOA, WorkflowEngineSOA, or QuerySOA.
Example:
http://test-CreditApplication-AceCompany.bizagi.com/WebServices/EntityManagerSOA.asmx?wsdl
|
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 make sure 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.
|
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 make sure 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>
|
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 make sure 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.
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.
6. Remove relationships
When using Bizagi API methods to save or update data from Bizagi entities (i.e, Save Entity, Perform Activity or Set Event) You may use the tag <REMOVE> in order to remove records from a collection.
You will need to specify the records to be removed using their businesskeys per each record.
The following example shows how to remove records from the Applicants collection:
<?xml version="1.0" encoding="utf-8"?>
<BizAgiWSParam>
<Entities idCase="7501" idTask="180">
<idRequest>
<Applicants>
<REMOVE>
<Applicant businessKey="BuroScore=6">
</Applicant>
<Applicant businessKey="BuroScore=9"/>
</REMOVE>
<Applicant>
<BuroScore>100</BuroScore>
</Applicant>
</Applicants>
</idRequest>
</Entities>
</BizAgiWSParam>
In this example, the Applicants with BuroScore equals to 6 and to 9 will be removed from the Applicants collection. Furthermore, a new applicant is being added with BuroScore equals to 100.
7. Setting an attribute to null
In methods like Save Entity or Save Activity you are able to set a specific attribute to null. To do so, you must set the "nil" attribute to true within the entity's attribute you want to set to null:
<Entities>
<idRequest>
<Applicants>
<Applicant>
<BuroScore nil="true"></BuroScore>
</Applicant>
</Applicants>
</idRequest>
</Entities>
|
The prior example does not apply for file or image attributes. |
Last Updated 2/8/2022 10:40:37 AM