Overview
A common integration requirement in corporate projects, is to have the possibility of starting Processes from a portal or an external application (e.g SharePoint, an E-mail or custom application, or any other program).
In Bizagi, Processes already present a comprehensive set of Web services and methods so that all their functionality can be invoked from any other application.
Such possibility is available through Bizagi SOA layer.
For further information about this feature, refer to Invoking Bizagi services from external applications.
What you need to do
To start one or more Processes in Bizagi from other applications, all you need to do is to invoke the createCasesAsString Web method already published in your project's Work portal.
This Web method belongs to the WorkflowEngineSOA Web services. For complete information about the access URL to these web services, refer to SOA Layer URL and considerations.
While invoking the createCasesAsString, or the createCases Web methods available for Bizagi .NET, you will send out XML-structured input mainly containing: The user creating the case or cases, the Process or Processes for which these cases will be started, and any initial business information considered relevant (any data, attachments, etc).
To view further detail about the createCasesAsString input and output structure, refer to createCasesAsString.
Example
The following example is carried out using the Vacation Request Process as worked in through the My First Process workshop.
For this Process, we will create cases from an external application.
To send initial business information in this Process, it is important that we become familiar with the data model involved.
We want to send out the data shown by the first Activity in this Process which corresponds to: The vacation starting and ending dates, and the number of office days requested.
This information corresponds to the following attributes of our Process Entity called VacationRequest.
To include both process and business information in the Process instances (created cases), it is important to use the exact name of the elements as expected by Bizagi in the XML structure.
For example, the value contained in the <Process> tag must be the name of the Process, and not its display name.
Likewise, the first tag under the <Entities> tag will correspond to the reference attribute at the Application Entity which relates to your Process Entity. From there on, use also the corresponding attribute or collection name that navigates to the attributes you want to assign values to.
Never use display names, and also make sure that you input this information in a case-sensitive manner.
To review information about how is the business information expected in Bizagi's data model, refer to Data model XML schemas.
Defining the Input XML
To create a new case for the Vacation Request Process, the following XML structure is sent as input:
<BizAgiWSParam>
<domain>domain</domain>
<userName>admon</userName>
<Cases>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2012-03-18T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2012-03-26T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>6</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
</Cases>
</BizAgiWSParam>
Note that this example XML creates only one case for the Vacation Request Process, and is registered as created by the domain\admon user.
To create more than one case, make sure you include additional occurrences of the <Case> tag within the <Cases> tag.
The creator user specified in this XML requires that:
1. He/she has been already created at the Bizagi Work Portal.
2. He/she has permissions to start new cases of the given process.
For instance, we could create multiple cases with the following XML:
<BizAgiWSParam>
<domain>domain</domain>
<userName>admon</userName>
<Cases>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2012-03-18T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2012-03-26T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>6</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2012-07-19T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2012-07-23T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>4</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2011-12-16T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2012-01-07T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>17</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
</Cases>
</BizAgiWSParam>
|
The <Entities> tag is optional. You may choose to create empty cases. Doing so, is accomplished by NOT including this tag and any information in it. |
The external application
We will now use a simple Windows Application to simulate an external application triggering the new cases in Bizagi processes.
In this dummy Application, the initial business information is inputted and then a button is clicked to invoke the web method of Bizagi SOA Layer.
Since this example is worked with Bizagi .NET edition, we can either invoke the createCasesAsString or createCases web method.
For this example worked in a .NET application in Visual Studio, we previously defined a Web Reference that points to our createCases web URL:
https://[project_environment]-[your_project]-[your_company].bizagi.com/webservices/WorkflowEngineSOA.asmx?wsdl
Once the button is clicked, the case is created using Bizagi SOA Layer. Within the response information (output), we receive the case number, along with other additional information.
The code behind the button-click event is:
private void button1_Click(object sender, EventArgs e)
{
//Dates are converted to string using this command to avoid problems with different dates formats
string sStartingDate = XmlConvert.ToString(dateTimePicker1.Value, XmlDateTimeSerializationMode.Unspecified);
string sSEndingDate = XmlConvert.ToString(dateTimePicker2.Value, XmlDateTimeSerializationMode.Unspecified);
//We build the input XML
string sXml = "<BizAgiWSParam>";
sXml += "<domain>domain</domain>";
sXml += "<userName>admon</userName>";
sXml += "<Cases>";
sXml += "<Case>";
sXml += "<Process>VacationRequest</Process>";
sXml += "<Entities>";
sXml += "<VacationRequest>";
sXml += "<VacationStartingDate>" + sStartingDate + "</VacationStartingDate>";
sXml += "<VacationEndingDate>" + sSEndingDate + "</VacationEndingDate>";
sXml += "<NumberOfOfficeDaysReques>" + textBox1.Text + "</NumberOfOfficeDaysReques>";
sXml += "</VacationRequest>";
sXml += "</Entities>";
sXml += "</Case>";
sXml += "</Cases>";
sXml += "</BizAgiWSParam>";
XmlDocument xDoc = new XmlDocument();
xDoc.LoadXml(sXml);
//We use the set web reference and invoke the createCases method
MyFirstProcessWE.WorkflowEngineSOA ws = new MyFirstProcessWE.WorkflowEngineSOA();
XmlNode xn = ws.createCases(xDoc);
//If the response information is successful, we retrieve the new case's Id.
if (xn.SelectSingleNode("process/processId").InnerText != "0")
{
textBox2.Text = xn.SelectSingleNode("process/processRadNumber").InnerText;
}
}
Verifying at the Work Portal
At our project's Work Portal at https://[project_environment]-[your_project]-[your_company].bizagi.com, we verify that the case number 502 was successfully created.
This case will be shown in its pending Activity with the initially sent information.
Note that the Activity right after the Process start is called Register Vacation Request:
Last Updated 1/27/2023 3:41:48 PM