Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Activiti Developers Guide</h1><p><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvY30&amp;locale=en_GB&amp;version=2" data-macro-name="toc"></p><h1>Building a distribution from the source</h1><h2>Dependencies</h2><p>JDK 5+ : Make sure that you do not use code constructs that require JDK 6 or higher.<br /> Maven 2.0.9<br /> Ant 1.7.1</p><h2>Source Code</h2><p><a href="https://svn.codehaus.org/activiti">https://svn.codehaus.org/activiti</a> (see <a href="http://xircles.codehaus.org/projects/activiti/repo">http://xircles.codehaus.org/projects/activiti/repo</a> for more links including anonynmous access for non-committers).</p><h2>Building the distribution</h2><ol><li>Check out the latest version from trunk: '<em>svn co</em> <a href="http://svn.codehaus.org/activiti/activiti/trunk/">http://svn.codehaus.org/activiti/activiti/trunk/</a>'</li><li>Go into the <em>distro</em> subfolder and run the following ant command: <em>'ant clean distro'</em></li><li>The distribution can now be found in the <em>target</em> folder.</li></ol><h2>Setup scripts in the distro</h2><p>After an distribution is unzipped (or directly in the <em>distro/target/activiti-version</em> directory), a number of scripts are offered to our users as well. Those scripts can be found in <em>[activiti.home]/setup/build.xml</em> and can optionally use settings from <em>[user.home]/.activiti/build.properties</em></p><p>As an example, here's the content of my <em>[user.home]/.activiti/build.properties</em>:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>activiti.home=/Users/tombaeyens/Documents/workspace/activiti/distro/target/activiti-5.0.alpha1-SNAPSHOT
downloads.dir=/Users/tombaeyens/Downloads
tomcat.enable.debug=true
</pre></td></tr></table><p><strong>activiti.home</strong>, is used in the setup/build.xml. It will work straight from the sources. So you can add the setup from the sources to your ant view in your IDE.</p><p><strong>downloads.dir</strong>, is used in the setup/build.xml. It allows you to configure a custom location for your directory to download/find tomcat. If you don't specify this, the default is relative to the setup directory (../downloads). So if you use the setup/build from the sources, you might end up downloading tomcat into your sources. If that still would happen, don't check it in! <img class="emoticon emoticon-wink" data-emoticon-name="wink" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/wink.png" alt="(wink)" title="(wink)" /></p><p><strong>tomcat.enable.debug</strong> is used in setup/build.xml when Tomcat is installed. If the property is specified (whatever value), the parameter 'jpda' will be added to the start commands in Tomcat's 'startup.sh' and 'startup.bat' scripts. That will cause the remote debugging service to listen on port 8000.</p><p><strong>skip.deploy.activiti.modeler=true</strong> set this property if the Activiti Modeler fetching from net and deployment must be skipped.<br /> Unless before a release or explicitly <a class="confluence-link unresolved" data-content-title="How to build Activiti Modeler from Signavio" data-linked-resource-default-alias="How to build Activiti Modeler from Signavio" href="#">working on the Activiti Modeler</a>, it's advised to set this property since sometimes a version matching the current trunk version isn't uploaded yet, causing the demo setup to fail.<br /> mvn.executable=mvn.bat on windows you have to set this property to make the calls from the ant build scripts (distro/build.xml and qa/build.xml) to maven work.</p><p><strong>activiti.modeler.download.url</strong>: To work with Activiti Modeler or Activiti Cycle on trunk, set the property <em>activiti.modeler.download.url</em> in your <em>[user.home]/.activiti/build.properties</em> to, e.g., <a href="http://activiti.org/downloads/activiti-modeler-5.0.beta1.war">http://activiti.org/downloads/activiti-modeler-5.0.beta1.war</a> if you want to use a previous release or something like <a href="file:///home/falko/svn/activiti-modeler/dist/activiti-modeler.war">file:///home/falko/svn/activiti-modeler/dist/activiti-modeler.war</a> if you want to use an <a class="confluence-link unresolved" data-content-title="How to build Activiti Modeler from Signavio" data-linked-resource-default-alias="How to build Activiti Modeler from Signavio" href="#">own build of the Activiti Modeler</a>.</p><p><strong>linux.browser=echo:</strong> Set this poperty to echo to prevent the browser from being opened. You also use a different browser than Firefox through this property.</p><p><strong>[user.home]/.activiti/tomcat-users.xml</strong> To enable the automatic redeployment targets in <em>qa/build.xml</em>, put a <em>tomcat-users.xml</em> in your <em>[user.home]/.activiti</em> directory with the following content:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>  &lt;?xml version="1.0" encoding="utf-8"?> 
  &lt;tomcat-users> 
    &lt;role rolename="manager"/> 
    &lt;user username="activiti" password="activiti" roles="manager"/> 
  &lt;/tomcat-users>
</pre></td></tr></table><h2><span style="color: rgb(0,51,102);">Eclipse IDE Setup</span></h2><p><span style="color: rgb(0,0,0);">You'll need to install the Maven and Subversion (SVN) plugins.</span></p><p><span style="color: rgb(0,0,0);">In the &quot;Galileo - </span><span style="color: rgb(0,51,102);">[</span><span style="color: rgb(0,51,102);"><a href="http://download.eclipse.org/releases/galileo">http://download.eclipse.org/releases/galileo</a></span>|http://download.eclipse.org/releases/galileo]&quot; update site, which should be available automatically, install &quot;Collaboration --&gt; Subversibe SVN Team provider&quot;. After rebooting and adding an SVN repository, you'll be asked automatically to install one of the polarion connectors for SVN. Just take the latest version of the polarion connectors. In case that doesn't happen automatically install a polarion connector manually from &quot;Subversive SVN Connectors Site <span style="color: rgb(0,51,102);">[</span><span style="color: rgb(0,51,102);"><a href="http://community.polarion.com/projects/subversive/download/eclipse/2.0/update-site/">http://community.polarion.com/projects/subversive/download/eclipse/2.0/update-site/</a></span>|http://community.polarion.com/projects/subversive/download/eclipse/2.0/update-site/]&quot;</p><p><span style="color: rgb(0,0,0);">Install the Maven plugins from </span><span style="color: rgb(0,51,102);">[</span><span style="color: rgb(0,51,102);"><a href="http://m2eclipse.sonatype.org/sites/m2e">http://m2eclipse.sonatype.org/sites/m2e</a></span>|http://m2eclipse.sonatype.org/sites/m2e]</p><p>First check out the activiti root from SVN as one project. Then import existing projects and navigate to the modules directory. All the module projects should then be found and can be imported in one go.</p><p>In order to have BPMN code completion and validation, import BPMN's XML Schemas from <em>activiti-engine/src/main/resources/org/activiti/impl/bpmn/parser</em> into the Eclipse XML Catalog, which can be found in Preferences --&gt; XML --&gt; XMLCatalog.</p><h2>Coding style</h2><ul><li><span style="color: rgb(0,0,0);">In the eclipse directory of the root activiti source directory are some files that should be imported as eclipse preferences. The filenames indicate the dialog that can be used to import them.  Those eclipse files indicate the general coding style guidelines.</span>** <span style="color: rgb(0,0,0);">indents are 2 spaces (no tabs)</span>** <span style="color: rgb(0,0,0);">sun style braces formatting</span></li><li><span style="color: rgb(0,0,0);">By default, our member field access should be set to</span> <span style="color: rgb(0,0,0);"><strong>protected</strong></span></li></ul><h2>Commits</h2><p>As much as possible try to group all related changes into single commits. </p><p>Before committing, run the following check to see if all is OK.</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>mvn -Pcheck clean install
</pre></td></tr></table><p>In the commit message, start with the jira issue, a space and then the commit text like in this example</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>ACT-826 Fixed all problems in the world
</pre></td></tr></table><h2><span style="color: rgb(0,51,102);"><strong>Running the test suite using Spring configuration</strong></span></h2><p>Use</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>mvn -Pcheckspring clean install
</pre></td></tr></table><p>to run the test suite on spring configuration only or</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>mvn -Pcheck,checkspring clean install
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">to combine running the engine testsuite on an Activiti config as well as on a Spring config</span></p><p><span style="color: rgb(0,0,0);">If you run the checkspring profile, the spring module will copy the engine tests over to the spring module before compiling and running the tests.  Those tests are deleted in the 'package' build phase</span></p><p><span style="color: rgb(0,0,0);">If you need to debug spring configuration test cases, just execute a </span></p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>mvn -Pcheckspring clean test
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">in the activiti-spring module, then refresh your IDE and the classes and spring configuration will be in your activiti-spring project ready to be debugged.</span></p><h2>Checkin when test is failing</h2><p>In some situations, it might be practical to check in while some tests are still failing.  In that situation, make sure that the tests are excluded in the modules pom.xml and that you have created a JIRA issue for it.  Reference the jira issue from the pom next to the excluded test.  And reference to the pom in the jira issue.</p><h1>QA</h1><p>Build file qa/build.xml contains a number of targets for driving the QA. It also contains convenience targets for developers to do integration testing.</p><p>More about the QA and CI infrastructure can be found here: <a class="confluence-link" href="/display/ACT/QA+and+CI+Guide" data-linked-resource-id="179961974" data-linked-resource-type="page" data-linked-resource-default-alias="QA and CI Guide" data-base-url="http://docs.codehaus.org">QA and CI Guide</a></p><h1>Demo setup</h1><p><span style="color: rgb(0,0,0);">To run smoke tests on webapps, the quickest way to get started is using the target test.demo.setup in qa/build.xml</span><br /> <span style="color: rgb(0,0,0);">That will also startup h2 and tomcat. So to rebuild, you can use the target test.demo.setup.refresh That target will first shutdown tomcat and h2 and then do a full new demo test setup.</span><br /> <span style="color: rgb(0,0,0);">Building the javadocs</span></p><p><span style="color: rgb(0,0,0);">Use target build.javadocs in qa/build.xml</span></p><h2>Debugging ant task</h2><p><a href="http://www.vitorrodrigues.com/blog/2009/07/10/debugging-ant-tasks-in-eclipse/">http://www.vitorrodrigues.com/blog/2009/07/10/debugging-ant-tasks-in-eclipse/</a></p><h2><span style="color: rgb(0,51,102);">GIT pointers</span></h2><p><span style="color: rgb(0,0,0);">We decided not to use GIT for now.  These pointers are here for future reference when we would evaluate GIT again.</span></p><p><span style="color: rgb(0,0,0);">Currently there is a GIT repository fork from SVN, for experimental purposes. If you prefer to use GIT let Tom know and we can take that into account when deciding whether to stick with it.</span></p><p><span style="color: rgb(0,0,0);">To use GIT as a committer you will probably want to use ssh to authenticate automatically. Codehaus requires DSA tokens (not RSA) so you may need to create those first:</span></p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>$ ssh-keygen -t dsa
... &lt;accept the defaults>
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">Ensure that your </span><span style="color: rgb(0,0,0);"><code>~/.ssh</code></span><span style="color: rgb(0,0,0);"> directory is only readable by you (</span><span style="color: rgb(0,0,0);"><code>chmod 700 ~/.ssh</code></span><span style="color: rgb(0,0,0);"> should do it). You will also probably need a </span><span style="color: rgb(0,0,0);"><code>~/.ssh/config</code></span><span style="color: rgb(0,0,0);"> that contains these lines:</span></p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>Host git.codehaus.org
	User git
	Hostname git.codehaus.org
	PreferredAuthentications publickey
	IdentityFile ~/.ssh/id_dsa
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">Typical initial setup:</span></p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>$ git config --global user.name "My Name"
$ git config --global user.email my.email@my.address.com
$ git config --global core.autocrlf input
# All the --global above can be set locally if you prefer
$ git clone ssh://git@git.codehaus.org/activiti-git.git activiti
$ cd activiti
$ git branch -a
... (list of branches)
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">There are plenty of online resources for git. A good one is </span><span style="color: rgb(0,51,102);">[</span><span style="color: rgb(0,51,102);">Pro Git</span>|http://progit.org/book]. IntelliJ has good IDE support. Eclipse has some very active development in <span style="color: rgb(0,51,102);">[</span><span style="color: rgb(0,51,102);">EGit</span>|http://www.eclipse.org/egit/], but only basic features currently (things are moving very fast). Most people find <span style="color: rgb(0,0,0);"><code>gitk</code></span><span style="color: rgb(0,0,0);">or </span><span style="color: rgb(0,0,0);"><code>gitx</code></span><span style="color: rgb(0,0,0);"> (Mac only) very useful for visualization (launch with </span><span style="color: rgb(0,0,0);"><code>--all</code></span><span style="color: rgb(0,0,0);"> for best results).</span></p><p><span style="color: rgb(0,0,0);">As a rule with GIT you do not make changes directly to remote branches, but rather you create your own local branch and merge changes from there to the remote branch (via a local mirror).  Typical workflow</span></p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre># create a new local branch to work from
$ git checkout -b feature/my-new-idea

# edit source code...
$ git status
... (list of changes)

# add all your changes to local index (N.B. -A might not always be appropriate)
$ git add -A .

# commit locally
$ git commit -m "My nice changes"
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">Keep doing that until you are happy. If you want to tidy up your commits and send them as a batch instead of individual changes look at </span><span style="color: rgb(0,0,0);"><code>git rebase -i ...</code></span><span style="color: rgb(0,0,0);">. Now you are ready to share your work. If you want to stay on a branch and collaborate with someone, push up your branch</span></p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre># if it is new:
$ git push origin feature/my-new-idea

# if you already shared it
$ git push
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">To checkout someone else's remote branch for collaboration:</span></p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre># Make sure you have all the remote changes
$ git fetch

# Or just make sure the branch is there
$ git branch -a
...

# Checkout the branch
$ git checkout origin/feature/my-new-idea
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">When you are ready to merge with the remote master (dev trunk):</span></p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre># get changes from remote repository
$ git fetch

# merge changes onto master (= dev trunk for everyone else)
$ git checkout master
$ git merge origin/master

# merge master onto your features (assuming you are ready to try and push it
# up to the remote repository)
$ git merge feature/my-new-idea

# push changes up to remote repository and move back to local branch to
# continue work
$ git push
$ git checkout feature/my-new-feature

# optionally rebase to keep history clean
$ git rebase master
</pre></td></tr></table><p><span style="color: rgb(0,0,0);">There are many combinations of commands that achieve the same end result as that last sequence. Your preferred workflow might be different, and of course any time there are conflicts it will have to change (GIT is quite good at telling you what it thinks is wrong in a conflict).</span></p>