How to Create a Case Using SOA
From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS
<keywords content="keywords"> soa, new case, create case </keywords>
Contents |
How to start a Bizagi process from an external application
Overview
A common request is the possibility of starting Bizagi processes from a portal or an external application, for example SharePoint, email or any custom developed program.
In Bizagi, we have this option as the possibility to use Bizagi's SOA layer (its web services) to create one or more cases of any Bizagi process (from an external application).
This may be accomplished by using the createCases or createCasesAsString web method of the WorkflowEngineSOA web service, already included and published in every Bizagi project.
The createCases and createCasesAsString web method have the same functionality; their only difference is that createCases receives an XML document while createCasesAsString receives a String with XML-formatted information.
View further information about the createCases and createCasesAsString web method (input and output).
Example
The following example is carried out using the Vacation Request process from My first Process. (This documentation refers to Bizagi's latest version) The example is no longer available in 9.1.x versions.
The first activity in this process, Register Vacation Request, has the following form:
Through this example, new cases will be created including any initial business information, which will be shown in the first activity.
To be able to do this, is important to be familiarized with the data model. This process has a simple data model and all the data of the first activity is in the process entity (VacationRequest).
Input XML
To create a new case for this process, the XML that needs to be sent to the createCases web method is as follows:
<BizAgiWSParam>
<domain>domain</domain>
<userName>admon</userName>
<Cases>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2010-03-18T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2010-03-26T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>6</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
</Cases>
</BizAgiWSParam>
With this example XML, we will create one case for the VacationRequest process and the creator would be the admon user.
To create more than one case, include a <Case> for each case wanted. The creator may also be changed but keep in mind that it has to be a user that exists for the Bizagi project and that has permission to start a new case of the desired process.
For example:
<BizAgiWSParam>
<domain>mydomain</domain>
<userName>cindyj</userName>
<Cases>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2010-03-18T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2010-03-26T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>6</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2010-07-19T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2010-07-23T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>4</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
<Case>
<Process>VacationRequest</Process>
<Entities>
<VacationRequest>
<VacationStartingDate>2010-12-16T12:00:00-05:00</VacationStartingDate>
<VacationEndingDate>2011-01-07T12:00:00-05:00</VacationEndingDate>
<NumberOfOfficeDaysReques>17</NumberOfOfficeDaysReques>
</VacationRequest>
</Entities>
</Case>
</Cases>
</BizAgiWSParam>
To create cases without any business information, do not include the tag <Entities>:
<BizAgiWSParam>
<domain>domain</domain>
<userName>admon</userName>
<Cases>
<Case>
<Process>VacationRequest</Process>
</Case>
</Cases>
</BizAgiWSParam>
Bizagi's data model
To include business information in the created cases, it is important to use the corresponding name of the elements in the data model XML structure.
For example, the value of the <Process> tag must be the name of the process, not its display name. Likewise the first tag under <Entities> will be the reference attribute in the Application Entity (App) to your Process entity, and from there on, the corresponding attribute's or collection's name must be use. Never use the display name, and ensure you have the element's name information as case-sensitive.
To learn about or review how is the business information expected in Bizagi's data model, you may make use of the Xml schema generation option in Bizagi.
The external application
Using a Windows Application to simulate the external application triggering the new case in Bizagi (as shown in the image below), the necessary information is inputted and a button is clicked to invoke the creation of a new Vacation Request case.
For this example, we use a local Bizagi application with the following URL:
http://biz-cindyj/MyFirstProcess/
Once the button is clicked, the case is created using Bizagi's SOA Layer and within the response information (output), we receive the case number, along with other additional information.
Case created from an external application:
To make this work in a .Net application and using Bizagi Xpress or Bizagi Enterprise .Net in the example, a Web Reference must be created (for this example the Web Reference name is MyFirstProcessWE) using this URL:
http://biz-cindyj/MyFirstProcess/webservices/WorkflowEngineSOA.asmx
and the button-click code will be:
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);
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);
MyFirstProcessWE.WorkflowEngineSOA ws = new MyFirstProcessWE.WorkflowEngineSOA();
XmlNode xn = ws.createCases(xDoc);
if (xn.SelectSingleNode("process/processId").InnerText != "0")
{
textBox2.Text = xn.SelectSingleNode("process/processRadNumber").InnerText;
}
}
To view the considerations for Bizagi Enterprise JEE edition, review the next section.
Additional considerations
Take into account the considerations listed at Bizagi_SOA_layer_URL_and_considerations, to ensure the interoperability between different platform technologies (.Net, JEE).
Related Articles
- View further information about the createCases web method (input and output).
- Learn about Bizagi's SOA Layer.
- View how is any Entity's or process' data model presented through the Xml schema generation option in Bizagi.
<comments />
