<?xml version="1.0" encoding="UTF-8"?>
<chapter id="ch.designer"
         version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">

  <title>Designer</title>

  <para>Web-based process editing is possible using the jBPM Designer. The designer is fully integrated into Drools Guvnor, the knowledge repository where you can store all your BPM assets such as of course your BPMN2 processes as well as rules, process images, workitem configurations, and process forms. The Designer can be used to create, view or update BPMN2 based processes which are executable in the jBPM runtime environment.</para>
  
  <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/designer-screenshot.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>

  <para>Designer targets the following scenarios:</para>

  <itemizedlist>
    <listitem>View and/or edit existing BPMN2 processes: The designer allows you to open existing BPMN2 processes (for
    example created using the BPMN2 Eclipse editor or any other tooling that exports BPMN2 XML) in a web
    context.</listitem>
    <listitem>Create fully executable BPMN2 processes: A user can create a new BPMN2 process in the Designer and
    use the editing capabilities (drag and drop and filling in properties in the properties panel) to fill
    in the details. This for example allows business users to create complete business processes all inside a
    a browser. The integration with Drools Guvnor allows for your business processes as wells as other business
    assets such as business rules, process forms/images, etc. to be stored and versioned inside a content 
    repository.</listitem>
  </itemizedlist>
  
  <para>Designer supports all BPMN2 elements that are also supported by jBPM as well as all jBPM-specific BPMN2
  extension elements and attributes.</para>
    
  <section>
    <title>Installation</title>
    
    <para>If you are using the jBPM installer, this should automatically download and install the
    latest version of the designer for you. To manually install the designer, simply drop the designer
    war into your application server deploy folder. Currently out-of-the-box designer deployments exist for JBoss 
    5.1.0 and JBoss AS7. Note: If you want to deploy on other (versions of an) application server, you might
    have to adjust the dependencies inside the war based on the default libraries provided by your
    application server. The latest version of the designer can be found 
    <ulink url="http://sourceforge.net/projects/jbpm/files/designer/">here</ulink>.</para>
    
    <para>To start working with the designer, open Guvnor (e.g. <ulink url="http://localhost:8080/drools-guvnor">
    http://localhost:8080/drools-guvnor</ulink>) and either open an existing BPMN2 process or create
    a new one (under the "Knowledge Bases category on the left, select create new BPMN2 process").  This
    will open up the designer for the selected process in the center panel.  You can use the palette on the
    left to drag and drop node types and the properties tab on the right to fill in the details (if either
    of these panels is not visible, click the arrow on the side of the editor to make them move forward).</para>
    
    <para>The designer may also be opened stand-alone by using the following link:
    <ulink url="http://localhost:8080/designer/editor?profile=jbpm&amp;uuid=123456">http://localhost:8080/designer/editor?profile=jbpm&amp;uuid=123456</ulink>
    (where 123456 should be replaced by the uuid of a process stored in Guvnor). Note that running designer in this way allows you to only view existing processes,
    and not save any edits nor create new ones. Information on how to integrate designer into your own applications can be found <ulink url="http://blog.athico.com/2011/04/using-oryx-designer-and-guvnor-in-your.html">here</ulink>.</para>
    
  </section>
  
  <section>
    <title>Source code</title>

    <para>The designer source code is available for each release. You can find it <ulink url="http://sourceforge.net/projects/jbpm/files/designer/">here</ulink>.</para>
    
    <para>You can also browse and clone the project on <ulink url="https://github.com/tsurdilo/process-designer">github</ulink>.</para>
  </section>
  
  <section>
    <title>Designer UI Explained</title>
    
    <para>The Designer UI is composed of a number of sections as shown in the screenshot below:</para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/designer-ui-parts.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  
   <para>
   	<itemizedlist>
      <listitem>(1) Shape Repository Panel - the expandable section on the left shows the jBPM BPMN2 (default) shape repository.
       It includes all shapes of the jBPM BPMN2 stencil set which can be used to assemble your processes. If you expand each section sub-group
       you can see the BPMN2 elements that can be placed onto the Designer Canvas (2) by dragging and dropping the shape onto it.</listitem>
      <listitem>(2) Canvas - this is your process drawing board. After dropping different shapes onto the canvas, you can move them around, connect them, etc. Clicking on a shape
      on the canvas allows you to set its properties in the expandable Properties Window (3)</listitem>
      <listitem>(3) Properties Panel - this expandable section on the right allows you to set both process and shape properties. It is divided in two sections, namely "Often used", and "More Properties" section which 
      is expandable. When clicking on a shape in the Canvas, this panel is reloaded to show properties specific to the shape type. If you click on the canvas itself (not on a shape) the section shows your general 
      process properties.</listitem>
      <listitem>(4) Toolbar - the toolbar contains operations which can be performed on shapes present on the Canvas. Individual operations are disabled or enabled depending on what is selected. For example, if no shapes are selected,
      the Cut/Paste/Delete operations are disabled, and become enabled once you select a shape. Hovering over the icons in the Toolbar displays the description text of the operation.</listitem>
      <listitem>(5) Footer - the footer contains operations that allow users to view the source of the process being editor in the Canvas section in various formats such as BPMN2, PNG, JSON, etc.</listitem>
      <listitem>(6) Process Information - this section contains information about your process, such as its name, creation date, version, etc</listitem>
    </itemizedlist>
   </para>
   
   <para>
   Connecting shapes together in the canvas is realized with the Shape-Menu. The Shape-Menu is displayed by clicking on a shape:
   </para>
   <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/shape-menu.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  <para>
  The Shape-Menu is composed of two sections:
  	<itemizedlist>
	<listitem>(1) Connection section: allows you to easily connect your shape with a new one. The shapes displayed in this section are based on connection rules of the BPMN2 specification.</listitem>
  	<listitem>(2) Morphing section: allows you to easily morphe a base shape into any other that extend this base shape.</listitem>
  	</itemizedlist>
  </para>
  <para>Following sequence of picture shows how easy it is to quickly create and connect multiple shapes in the canvas:</para>
  <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/example-creation.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  <para>
  You can also name your shapes by double-clicking on the shape in the canvas. This sets the name attribute of the particular shape:
  </para>
  <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/naming-shapes.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  </section>  
  
  <section>
    <title>Support for Domain-specific service nodes</title>

    <para>Designer has full support for jBPM domain-specific service nodes. To include your service nodes in the Designer jBPM BPMN2 stencil set,
    you can either upload your existing service node definitions into Guvnor, or use the the new service node configuration editor which we added 
    to Guvnor to create new configurations.
    </para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/wideditor.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
    
    
    <para>Once you have some service node configurations present, you can see them being included in Designer stencil 
    set by re-opening an existing or creating a new process. Your service nodes will be now available under the "Service Task" 
    section of the jBPM BPMN2 stencil set.
    </para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/servicetasks.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
    
    <para>Service nodes are fully usable within your processes. Please note that the service node configurations are 
    package-specific in Guvnor. If you want to re-use your service nodes across multiple Guvnor packages, you have to
    copy their configurations to each indidual package you would like to use them in.
    </para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/widsinprocess.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  
  <para>
    For more information on this feature please view 
    <ulink url="http://vimeo.com/26126678">this</ulink>, and <ulink url="http://vimeo.com/24288229">this</ulink> video.
  </para>
    
  </section>
  
  <section>
    <title>Configuring Designer</title>
    <para>Designer is tightly integrated with Guvnor. By default Designer expects to find a Guvnor instance on
    http://localhost:8080/drools-guvnor/. Guvnor, by default, expects to find the Designer on http://localhost:8080/designer.
    Here we show how to configure both Designer and Guvnor to be able to change these default settings when needed.</para>
	
	<section> 
	<title>Changing the default configuration in Designer</title>
	<para>   
    In cases where Guvnor is configured to use https, or is running on a different
    host/port/domain/subdomain you have to configure Designer to reflect these settings. in order to change Designer 
    configurations you have to deploy it as an exploded war. In $designer.war/profiles/jbpm.xml notice the section 
    on the bottom:
    </para> 
    <programlisting language="xml">
      &lt;externalloadurl protocol="http" host="localhost:8080" subdomain="drools-guvnor/org.drools.guvnor.Guvnor/oryxeditor" usr="admin" pwd="admin"/&gt;
    </programlisting>
    
    <para>
      The configuration attributes include:
      <itemizedlist>
        <listitem>protocol: the protocol to use (http/https)</listitem>
        <listitem>host: includes both the host and the port that Guvnor is running on</listitem>
        <listitem>subdomain: in some situations Guvnor subdomain is not drools-guvnor. You should leave the path to the
        servlet as-is.</listitem>
        <listitem>usr: if you have set up JAAS authentication in Guvnor, provide a Guvnor user name here. Note that 
        this user should have admin privileges in Guvnor</listitem>
        <listitem>pwd: password for the Guvnor user</listitem>
      </itemizedlist>
    </para>
    
    <para>
    Alernative you can specify these configrations via system properties:
    <itemizedlist>
      <listitem>oryx.external.protocol</listitem>
      <listitem>oryx.external.host</listitem>
      <listitem>oryx.external.usr</listitem>
      <listitem>oryx.external.pwd</listitem>
    </itemizedlist>
    </para>
    <para>
    If you choose to use system properties you do not have to deploy the designer war as exploded.
    </para>
    </section>
    <section> 
	<title>Changing the default configuration in Guvnor</title>
	<para>To configure Guvnor to reflect the host/port/domain/subdomain and the default profile settings of the Designer, we need to edit $drools-guvnor.war/WEB-INF/preferences.properties:</para>
	<programlisting language="text">
#Designer configuration
designer.url=http://localhost:8080
#Do not change this unless you know what are you doing
designer.context=designer
designer.profile=jbpm
	</programlisting>
	
	<para>
      The configuration attributes include:
      <itemizedlist>
        <listitem>designer.url: set the protocol, host, and port where Designer is located at</listitem>
        <listitem>designer.context: this sets the configured subdomain of Designer. Should not change unless you deploy it under some other subdomain</listitem>
        <listitem>designer.profile: Designer can have multiple profiles defined. Profiles determine the used stencil set, the saving/loading strategy of processes, etc. The default 
        profile name used is "jbpm" and this should not be changes unless you create a custom profile to be used</listitem>
      </itemizedlist>
    </para>
    
    <para>
    Note that in order to be able to edit $drools-guvnor.war/WEB-INF/preferences.properties, you have to deploy Guvnor as an exploded archive.
    </para>
	</section>
  </section>
  
  <section>
    <title>Generation of process and task forms</title>

    <para>Designer allows users to generate process and task ftl forms. These forms are fully usable in the jBPM console. To start
    using this feature, locate the "Generate Task Form Templates" button in the designer toolbar:</para> 
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/button-create-task-forms.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
   </figure>
    
    <para>Designer will iterate
    through your process BPMN2 and create forms for your process, and each of the human tasks in your process. It uses
    the defined process variables and human task data input/output parameters and associations to create form fields. 
    The generated forms are stored in Guvnor, and user is presented with a page which shows each of the forms created
    as well as a link to their sources in Guvnor:</para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/taskformgeneration.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
    
    <para>As mentioned, all forms are fully usable inside jBPM console. In addition each form includes basic JavaScript
    form validation which is determined based on the type of the process variables, and/or human task data input/output 
    association definitions.
    Here is an example generated human task form.</para>
  
  <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/sampleusertaskform.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  
  <para>In order for process and task forms to be generated you have to make sure that your process has it's id 
  parameter set, as well that each of your human tasks have the TaskName parameter set. Task forms contain pure
  HTML, CSS, and JavaScript, so they are easily editable in any HTML editor. Please note that there is no edit
  feature available currently in Designer, so each time you generate forms, existing ones will be overwritten.</para>
  
  <para>
    For more information on this feature please view 
    <ulink url="http://vimeo.com/26126678">this</ulink> video.
  </para>
  
  </section>
  
  <section>
    <title>View processes as PDF and PNG</title>

    <para>Any process created in Designer can be easily viewed in PDF and PNG formats. In the Designer footer section locate the "Convert to PDF" and "Convert to PNG" buttons.
    Both PDF and PNG formats are also stored in Guvnor, making it easily accessible. 
    </para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/processpdf.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>

  <para>The footer section also includes buttons to view the process sources in ERDF, JSON, SVG, and BPMN2 formats.</para>
	<figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/footer-buttons.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
	    
    </section>

  <section>
    <title>Viewing process BPMN2 source</title>

    <para>At any time you can view your process's BPMN2 source by selecting the Source->View Source link in the 
    Guvnor toolbar above the designer frame. The soure generated by designer is fully BPMN2 compliant and can be 
    used in any BPMN2 compliant editor.  
    </para>
    
    <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/bpmnsource.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
  
  <para>Same can be done by clicking on the BPMN2 button in the footer section of the designer:</para>
  <figure>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/Chapter-Designer/view-source-bpmn2.png" format="PNG" role="" />
      </imageobject>
    </mediaobject>
  </figure>
    
    </section>
    
    <section>
    <title>Embedding designer in your own application</title>

    <para>It is possible to embed the designer in your own application and still be able to utilize Guvnor as the 
    asset repository for all of your process assets. For more information on this feature please view 
    <ulink url="http://vimeo.com/22033817">this video</ulink>.
    </para>
    </section>
    
    <section>
    	<title>Migrating existing jBPM 3.2 based processes to BPMN2</title>
    	<para>To migrate your existing jBPM 3.2 based processes to BPMN2 locate the migration button in the toolbar section of the designer:</para>
    	
    	<figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/button-migrate-from-jpdl.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
 		 
 		 <para>The feature allows users to select the location of their processdefinition file, and the location of it's gpd.xml file. Designer then uses the <ulink url="https://github.com/droolsjbpm/jbpmmigration">jbpmmigration tool</ulink> to 
 		 convert the jBPM 3.2 based processes to BPMN2 and displays it onto the designer canvas:</para>
 		 
 		 <figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/jpdl-to-bpmn2-migrate.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
 		 <para>
    		For more information on this feature please view 
   			 <ulink url="http://vimeo.com/30857949">this</ulink> video.
  		</para>
    </section>
    
    
    <section>
    	<title>Visual Process Validation</title>
    	<para>To run process validation against the process you are developing in the designer, locate the validation button in the designer toolbar section:</para>
    	<figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/button-process-validation.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
 		 <para>In case of validation errors, designer presents a red "X" mark next to process nodes that contain them. Mouse-over this red "X" presents a tooltip with the descriptions of validation errors.
 		 Note that since the process node is not visually displayed, designer will merge all process-node-specific validation errors with those of the very first node of the BPMN2 process. Following
 		 is a screenshot of the visual process validation feature in use:</para>
 		 <figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/visual-validation.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
 		 <para>
    		For more information on this feature please view 
   			 <ulink url="http://vimeo.com/30857949">this</ulink> video.
  		</para>
    </section>
    
    <section>
    	<title>Integration with the jBPM Service Repository</title>
    	<para>Designer integrates with the <ulink url="http://kverlaen.blogspot.com/2011/10/introducing-service-repository.html">jBPM Service Repository and allows users to install and use assets from the repository.</ulink>.
    	To connect to the Service Repository from designer, click on the service repository button in the designer toolbar:</para>
    	<figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/button-query-service-repo.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
 		 <para>Designer will present you with all assets located in the jBPM service repository in table format. Colums of this table show information about the specific asset in the repo.
 		 To install the item to your local Guvnor package, simply double-click on the item row. You will have to save and re-open your process in order to be able to start using the installed items.</para>
 		 
 		 <figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/service-repository-integration.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
 		 <para>
    		For more information on this feature please view 
   			 <ulink url="http://vimeo.com/30857949">this</ulink> video.
  		</para>
    </section>
    
    <section>
    	<title>Generating code to share the process image, PDF, and embedded process editor</title>
    	<para>It is important to be able to share your process with users who do not have access to your running designer instance. For these cases
    	designer allows code generation of "sharable" image, PDF and embedded editor code of your processes. To use this feature locate the following 
    	dropdown in the designer toolbar section:</para>
    	<figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/share-process-info.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
 		 </figure>
    </section>
    
    <section>
    	<title>Importing existing BPMN2 processes</title>
    	<para>You can easily import your existing BPMN2 processes into the designer by locating and clicking on the following
    	dropdown selection list in the toolbar section:</para>
    	<figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/import-from-source.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
    	</figure>
    	<para>You will be able to either select an existing file on your filesystem or paste existing BPMN2 XML. The designer canvas
    	will automatically import and display your process without a page refresh.</para>
    </section>
    
    <section>
    	<title>Viewing Process Information</title>
    	<figure>
    	<mediaobject>
      	<imageobject>
        	<imagedata align="center" fileref="images/Chapter-Designer/process-info-panel.png" format="PNG" role="" />
      	</imageobject>
    	</mediaobject>
    	</figure>
    	<para>The Process Information section displays important information about your process. These include the process:
    	<itemizedlist>
        <listitem>name</listitem>
        <listitem>format</listitem>
        <listitem>Guvnor package name the process belongs to</listitem>
        <listitem>creation date</listitem>
        <listitem>name of user that created the process</listitem>
        <listitem>last modification date</listitem>
        <listitem>last check-in comment</listitem>
        <listitem>version number</listitem>
        </itemizedlist>
    	</para>
    </section>
    
    <section>
    <title>Requirements</title>
    <para>Java:
    	<itemizedlist>
        <listitem>Java 6</listitem>
      </itemizedlist>
    </para>
    <para>Browsers:
      <itemizedlist>
        <listitem>Mozilla Firefox (including 6)</listitem>
        <listitem>Google Chrome</listitem>
      </itemizedlist>
    </para>
    <para>JBoss AS:
      <itemizedlist>
        <listitem>Designer war is currently compatible with JBoss AS 4.x, 5.1, and 7</listitem>
      </itemizedlist>
    </para>
    </section>
</chapter>
