Overview
This section describes how to create a case in Bizagi from Joomla!.
With the example presented in this how-to, Joomla! can be extended with a powerful digital platform with BPM capabilities such as Bizagi.
This integration focuses on Joomla! as an entry point of your client's requests (A content manager used as a Portal), and Bizagi hosting processes behind.
The following architecture diagram represents this how-to's considered set-up and integration:
1. Through Joomla!, clients access your Web site and send a contact request.
2. The contact information is sent by an intermediate Web application that uses Bizagi SOA Layer (Web services).
3. A new Process instance (a case in Bizagi) is automatically created and listed in Bizagi Work Portal.
Prerequisites
For this integration, it is required to have installed Joomla! 1.5 or higher.
Joomla! may be downloaded from its official web page.
What you need to do
To accomplish this integration we consider the following steps:
1. Using components in Joomla! for the contact us form.
2. Having the Bizagi Process to manage "contact us" requests.
3. Using a Web application for the Web service invocation.
Example
The example shown will consider and describe:
First, publishing a "Contact us" form in your company's Web site to capture the initial information.
Then, this information is sent via Web services to Bizagi so that it is delegated to your workflow Process (creating one case for the contact us request).
To send this information via Web services, we need to include developing a Web service invocation.
To simplify this integration and example, the invocation of the Web services published by Bizagi will not be done through PHP directly, but through a component in a .NET web application.
1. Using components in Joomla! for the contact us form
In order to carry out this example for Joomla!, creation of the following files and folders is carried out with the structure shown below:
•site/contactus.php - this is the entry point to our component
•site/controller.php - this file contains our base controller
•site/views/contactus/view.html.php - this file retrieves the necessary data and pushes it into the template
•site/views/contactus/tmpl/default.php - this is the template for our output which contains the contact us form HTML
•site/models/contactus.php - this is created in order to follow a proper MVC pattern.
•contactus.xml - this is the XML (manifest) file that tells Joomla! how to install our component.
These files and folders are named according to the defined [conventions] and our component is called contactus (in Joomla! it will be installed as com_contactus).
The Default.php file should be as shown:
Notice that the action set for our form, references the http location in which we will find a .NET component, developed to complete the integration with Bizagi's project.
This will be thoroughly detailed on a next section (Using a web application for the web service invocation).
You may download this Joomla!'s component ready for installation.
2. Having the Bizagi Process to manage "contact us" requests
Since we have the entry point for these contact us requests directly as a Web page in Joomla!, we require having a Bizagi process to receive these requests to then continue with the BPM approach to process the incoming information (for example: reviewing the request, contacting that person, etc,).
For this example, a simple Contact Us process was created in Bizagi, with the following characteristics:
1. The process is named ContactUsRequest, and the data model for this process has as a process entity an entity called ContactUsRequest as well.
2. The entity ContactUsRequest has mainly these attributes:
•ContactName (string)
•EmailAddress (string)
•Message (string)
•TelephoneNumber (string)
Notice you need to specify a length for the string type attributes. Make sure they are long enough to support the incoming information in Joomla!'s form. Suggested values are:
•ContactName Length: 50
•EmailAddress Length: 50
•Message Length: 4000
•TelephoneNumber Length: 20
3. The first activity's form, shows all the 4 attributes previously listed.
The incoming request from the contact us page will create a new case and in this first activity's form we will be able to see the submitted information.
In summary, the attributes: ContactName, EmailAddress, Message and TelephoneNumber are included in this form as non-editable.
3. Using a Web application for the Web service invocation
In order to create cases in Bizagi with externally submitted information, we need that a Web application invokes Bizagi Web services. To do this, in this example we will illustrate the development of a Web application in a .NET solution.
This Web application will be in charge of sending out the information to invoke the createCases web method in Bizagi SOA Layer (to start a Process instance).
Take into account that Bizagi offers through its SOA Layer many more methods available for integration, that can be also used in Joomla! and for this scenario as well (for example to either update or consult the information of an existing case).
For more information about such options, refer to Invoking Bizagi services from external applications.
The following sample Web application was worked with Microsoft Visual Studio 2008 and for a Bizagi .NET project. The created Web application solution will be addressed from now on as the ContactUsApplication:
1. Create a new project in Visual Studio and for its type, select ASP. Net Web Application.
For the ContactUsApplication, a Web reference in the visual studio project is required as:
http://[your_Bizagi_server]/[your_Bizagi_project]/webservices/workflowenginesoa.asmx
2. Create the corresponding Web reference to your Bizagi project's published Web services:
|
This is a simplified example, and therefore take into account that according to secure and best practices, the access to Bizagi Web services should be restricted and controlled at the Server itself (IIS configuration). This should be done according to your own-defined security policies. |
Given that the Joomla!'s contact us form will pass on the information to the ContactUsApplication, we require retrieving these parameters in the Default.aspx.cs in its Page_Load method.
The Default.aspx.cs should be as shown:
The invocation of the web service is carried out in a different class, called WSController.cs.
To create the WSController class, add a new item to your project as shown:
The code for our WSController.cs class is as shown:
You may download the complete Visual Studio example project.
Finally, mount these files in the server's IIS as an application so that access from the link is possible (as http://[your_Bizagi_server]/[your_iis_application]/Default.aspx).
To do this, first copy the solution folder into the server's C:\inetpub\wwwroot\path.
Then, open the IIS manager. You may do so from the run command as shown:
Right-click on the copied folder and select the Convert to application option:
Notice that the resulting URL location of this web application should correspond to that defined in the Default.php's form action.
At this point, you are set so that your clients can access your contact us form in Joomla! and send you contact requests through it and into your Bizagi process! To test this application, run your Joomla! site in a browser of your choice by typing (according to your Apache Server's port installation):
http:[your_server]:[apache_port]/Joomla_1.5.22-Stable-Full_Package/index.php?option=com_contactus
Execution
To see this example working, we first fill out the initial information in the contact us request form directly in Joomla! (and access our Contact us form as referred to previously).
Then we execute our Process in Bizagi Work Portal by clicking the Run option:
We can see the pending activity for a created case with Joomla!'s input:
