1<!DOCTYPE html> 2<html lang="en"> 3<head> 4<meta charset="UTF-8"> 5<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> 6<meta name="viewport" content="width=device-width, initial-scale=1.0"> 7<meta name="generator" content="Asciidoctor 1.5.5"> 8<meta name="author" content="v 6.0.0"> 9<title>Activiti User Guide</title> 10<style> 11/*! normalize.css v2.1.2 | MIT License | git.io/normalize */ 12/* ========================================================================== HTML5 display definitions ========================================================================== */ 13/** Correct `block` display not defined in IE 8/9. */ 14article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; } 15 16/** Correct `inline-block` display not defined in IE 8/9. */ 17audio, canvas, video { display: inline-block; } 18 19/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */ 20audio:not([controls]) { display: none; height: 0; } 21 22/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */ 23[hidden], template { display: none; } 24 25script { display: none !important; } 26 27/* ========================================================================== Base ========================================================================== */ 28/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */ 29html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ } 30 31/** Remove default margin. */ 32body { margin: 0; } 33 34/* ========================================================================== Links ========================================================================== */ 35/** Remove the gray background color from active links in IE 10. */ 36a { background: transparent; } 37 38/** Address `outline` inconsistency between Chrome and other browsers. */ 39a:focus { outline: thin dotted; } 40 41/** Improve readability when focused and also mouse hovered in all browsers. */ 42a:active, a:hover { outline: 0; } 43 44/* ========================================================================== Typography ========================================================================== */ 45/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */ 46h1 { font-size: 2em; margin: 0.67em 0; } 47 48/** Address styling not present in IE 8/9, Safari 5, and Chrome. */ 49abbr[title] { border-bottom: 1px dotted; } 50 51/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */ 52b, strong { font-weight: bold; } 53 54/** Address styling not present in Safari 5 and Chrome. */ 55dfn { font-style: italic; } 56 57/** Address differences between Firefox and other browsers. */ 58hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; } 59 60/** Address styling not present in IE 8/9. */ 61mark { background: #ff0; color: #000; } 62 63/** Correct font family set oddly in Safari 5 and Chrome. */ 64code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; } 65 66/** Improve readability of pre-formatted text in all browsers. */ 67pre { white-space: pre-wrap; } 68 69/** Set consistent quote types. */ 70q { quotes: "\201C" "\201D" "\2018" "\2019"; } 71 72/** Address inconsistent and variable font size in all browsers. */ 73small { font-size: 80%; } 74 75/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */ 76sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; } 77 78sup { top: -0.5em; } 79 80sub { bottom: -0.25em; } 81 82/* ========================================================================== Embedded content ========================================================================== */ 83/** Remove border when inside `a` element in IE 8/9. */ 84img { border: 0; } 85 86/** Correct overflow displayed oddly in IE 9. */ 87svg:not(:root) { overflow: hidden; } 88 89/* ========================================================================== Figures ========================================================================== */ 90/** Address margin not present in IE 8/9 and Safari 5. */ 91figure { margin: 0; } 92 93/* ========================================================================== Forms ========================================================================== */ 94/** Define consistent border, margin, and padding. */ 95fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; } 96 97/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */ 98legend { border: 0; /* 1 */ padding: 0; /* 2 */ } 99 100/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */ 101button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ } 102 103/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */ 104button, input { line-height: normal; } 105 106/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */ 107button, select { text-transform: none; } 108 109/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */ 110button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ } 111 112/** Re-set default cursor for disabled elements. */ 113button[disabled], html input[disabled] { cursor: default; } 114 115/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
116input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ } 117 118/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */ 119input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; } 120 121/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */ 122input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; } 123 124/** Remove inner padding and border in Firefox 4+. */ 125button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; } 126 127/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */ 128textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ } 129 130/* ========================================================================== Tables ========================================================================== */ 131/** Remove most spacing between table cells. */ 132table { border-collapse: collapse; border-spacing: 0; } 133 134meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; } 135 136meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; } 137 138meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; } 139 140*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; } 141 142html, body { font-size: 100%; } 143 144body { background: white; color: #222222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; } 145 146a:hover { cursor: pointer; } 147 148img, object, embed { max-width: 100%; height: auto; } 149 150object, embed { height: 100%; } 151 152img { -ms-interpolation-mode: bicubic; } 153 154#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; } 155 156.left { float: left !important; } 157 158.right { float: right !important; } 159 160.text-left { text-align: left !important; } 161 162.text-right { text-align: right !important; } 163 164.text-center { text-align: center !important; } 165 166.text-justify { text-align: justify !important; } 167 168.hide { display: none; } 169 170.antialiased, body { -webkit-font-smoothing: antialiased; } 171 172img { display: inline-block; vertical-align: middle; } 173 174textarea { height: auto; min-height: 50px; } 175 176select { width: 100%; } 177 178p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; } 179 180.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #003b6b; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; } 181 182/* Typography resets */ 183div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; } 184 185/* Default Link Styles */ 186a { color: #00579e; text-decoration: none; line-height: inherit; } 187a:hover, a:focus { color: #333333; } 188a img { border: none; } 189 190/* Default paragraph styles */ 191p { font-family: Arial, sans-serif; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; text-rendering: optimizeLegibility; } 192p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; } 193 194/* Default header styles */ 195h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Arial, sans-serif; font-weight: normal; font-style: normal; color: #7b2d00; text-rendering: optimizeLegibility; margin-top: 0.5em; margin-bottom: 0.5em; line-height: 1.2125em; } 196h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #ff6b15; line-height: 0; } 197 198h1 { font-size: 2.125em; } 199 200h2 { font-size: 1.6875em; } 201 202h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; } 203 204h4 { font-size: 1.125em; } 205 206h5 { font-size: 1.125em; } 207 208h6 { font-size: 1em; } 209 210hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; } 211 212/* Helpful Typography Defaults */ 213em, i { font-style: italic; line-height: inherit; } 214 215strong, b { font-weight: bold; line-height: inherit; } 216 217small { font-size: 60%; line-height: inherit; } 218 219code { font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: bold; color: #003426; } 220 221/* Lists */ 222ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; list-style-position: outside; font-family: Arial, sans-serif; } 223 224ul, ol { margin-left: 1.5em; } 225ul.no-bullet, ol.no-bullet { margin-left: 1.5em; } 226 227/* Unordered Lists */ 228ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ } 229ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; } 230ul.square { list-style-type: square; } 231ul.circle { list-style-type: circle; } 232ul.disc { list-style-type: disc; }
233ul.no-bullet { list-style: none; } 234 235/* Ordered Lists */ 236ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; } 237 238/* Definition Lists */ 239dl dt { margin-bottom: 0.3em; font-weight: bold; } 240dl dd { margin-bottom: 0.75em; } 241 242/* Abbreviations */ 243abbr, acronym { text-transform: uppercase; font-size: 90%; color: black; border-bottom: 1px dotted #dddddd; cursor: help; } 244 245abbr { text-transform: none; } 246 247/* Blockquotes */ 248blockquote { margin: 0 0 0.75em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; } 249blockquote cite { display: block; font-size: 0.8125em; color: #e15200; } 250blockquote cite:before { content: "\2014 \0020"; } 251blockquote cite a, blockquote cite a:visited { color: #e15200; } 252 253blockquote, blockquote p { line-height: 1.6; color: #333333; } 254 255/* Microformats */ 256.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; } 257.vcard li { margin: 0; display: block; } 258.vcard .fn { font-weight: bold; font-size: 0.9375em; } 259 260.vevent .summary { font-weight: bold; } 261.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; } 262 263@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } 264 h1 { font-size: 2.75em; } 265 h2 { font-size: 2.3125em; } 266 h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } 267 h4 { font-size: 1.4375em; } } 268/* Tables */ 269table { background: white; margin-bottom: 1.25em; border: solid 1px #d8d8ce; } 270table thead, table tfoot { background: -webkit-linear-gradient(top, #add386, #90b66a); font-weight: bold; } 271table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: white; text-align: left; } 272table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #6d6e71; } 273table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #edf2f2; } 274table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.4; } 275 276h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } 277 278a:hover, a:focus { text-decoration: underline; } 279 280.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; } 281.clearfix:after, .float-group:after { clear: both; } 282 283*:not(pre) > code { font-size: inherit; font-style: normal !important; letter-spacing: 0; padding: 3px 2px 1px 2px; background-color: #eeeeee; border: 1px solid #dddddd; -webkit-border-radius: 0; border-radius: 0; line-height: inherit; } 284 285pre, pre > code { line-height: 1.6; color: black; font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; } 286 287.keyseq { color: #333333; } 288 289kbd { display: inline-block; color: black; font-size: 0.75em; line-height: 1.4; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; } 290 291.keyseq kbd:first-child { margin-left: 0; } 292 293.keyseq kbd:last-child { margin-right: 0; } 294 295.menuseq, .menu { color: black; } 296 297b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; } 298 299b.button:before { content: "["; padding: 0 3px 0 2px; } 300 301b.button:after { content: "]"; padding: 0 2px 0 3px; } 302 303#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 1.5em; padding-right: 1.5em; } 304#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; } 305#header:after, #content:after, #footnotes:after, #footer:after { clear: both; } 306 307#content { margin-top: 1.25em; } 308 309#content:before { content: none; } 310 311#header > h1:first-child { color: #7b2d00; margin-top: 2.25rem; margin-bottom: 0; } 312#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #dddddd; } 313#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #dddddd; padding-bottom: 8px; } 314#header .details { border-bottom: 1px solid #dddddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #e15200; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; } 315#header .details span:first-child { margin-left: -0.125em; } 316#header .details span.email a { color: #333333; } 317#header .details br { display: none; } 318#header .details br + span:before { content: "\00a0\2013\00a0"; } 319#header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #333333; } 320#header .details br + span#revremark:before { content: "\00a0|\00a0"; } 321#header #revnumber { text-transform: capitalize; } 322#header #revnumber:after { content: "\00a0"; } 323 324#content > h1:first-child:not([class]) { color: #7b2d00; border-bottom: 1px solid #dddddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; } 325 326#toc { border-bottom: 0 solid #dddddd; padding-bottom: 0.5em; } 327#toc > ul { margin-left: 0.125em; } 328#toc ul.sectlevel0 > li > a { font-style: italic; } 329#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; } 330#toc ul { font-family: Arial, sans-serif; list-style-type: none; } 331#toc a { text-decoration: none; } 332#toc a:active { text-decoration: underline; } 333 334#toctitle { color: #003b6b; font-size: 1.2em; } 335 336@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; } 337 body.toc2 { padding-left: 15em; padding-right: 0; } 338 #toc.toc2 { margin-top: 0 !important; background-color: white; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; } 339 #toc.toc2 #toctitle { margin-top: 0; font-size: 1.2em; } 340 #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; } 341 #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } 342 #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } 343 body.toc2.toc-right { padding-left: 0; padding-right: 15em; } 344 body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } } 345@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } 346 #toc.toc2 { width: 20em; } 347 #toc.toc2 #toctitle { font-size: 1.375em; } 348 #toc.toc2 > ul { font-size: 0.95em; } 349 #toc.toc2 ul ul { padding-left: 1.25em; } 350 body.toc2.toc-right { padding-left: 0; padding-right: 20em; } } 351#content #toc { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; } 352#content #toc > :first-child { margin-top: 0; } 353#content #toc > :last-child { margin-bottom: 0; } 354 355#footer { max-width: 100%; background-color: none; padding: 1.25em; } 356 357#footer-text { color: black; line-height: 1.44; } 358 359.sect1 { padding-bottom: 0.625em; } 360 361@media only screen and (min-width: 768px) { .sect1 { padding-bottom: 1.25em; } } 362.sect1 + .sect1 { border-top: 0 solid #dddddd; } 363 364#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; } 365#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; } 366#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; } 367#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #7b2d00; text-decoration: none; } 368#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #622400; } 369 370.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; } 371 372.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; } 373 374table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; } 375 376.paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { color: #7b2d00; } 377 378table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; } 379 380.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; } 381.admonitionblock > table td.icon { text-align: center; width: 80px; } 382.admonitionblock > table td.icon img { max-width: none; } 383.admonitionblock > table td.icon .title { font-weight: bold; font-family: Arial, sans-serif; text-transform: uppercase; } 384.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #e15200; } 385.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; } 386 387.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; } 388.exampleblock > .content > :first-child { margin-top: 0; } 389.exampleblock > .content > :last-child { margin-bottom: 0; } 390 391.sidebarblock { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; } 392.sidebarblock > :first-child { margin-top: 0; } 393.sidebarblock > :last-child { margin-bottom: 0; } 394.sidebarblock > .content > .title { color: #003b6b; margin-top: 0; } 395 396.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; } 397 398.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { background: #eeeeee; } 399.sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { background: #f2f1f1; } 400 401.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 1px dashed #666666; -webkit-border-radius: 0; border-radius: 0; word-wrap: break-word; padding: 1.25em 1.5625em 1.125em 1.5625em; font-size: 0.8125em; } 402.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; } 403@media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.90625em; } } 404@media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 1em; } } 405 406.literalblock.output pre { color: #eeeeee; background-color: black; } 407 408.listingblock pre.highlightjs { padding: 0; } 409.listingblock pre.highlightjs > code { padding: 1.25em 1.5625em 1.125em 1.5625em; -webkit-border-radius: 0; border-radius: 0; } 410 411.listingblock > .content { position: relative; } 412 413.listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: #999; } 414 415.listingblock:hover code[data-lang]:before { display: block; } 416 417.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; } 418 419.listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; } 420 421table.pyhltable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; } 422 423table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; } 424 425table.pyhltable td.code { padding-left: .75em; padding-right: 0; } 426 427pre.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #dddddd; } 428 429pre.pygments .lineno { display: inline-block; margin-right: .25em; } 430 431table.pyhltable .linenodiv { background: none !important; padding-right: 0 !important; } 432 433.quoteblock { margin: 0 1em 0.75em 1.5em; display: table; } 434.quoteblock > .title { margin-left: -1.5em; margin-bottom: 0.75em; } 435.quoteblock blockquote, .quoteblock blockquote p { color: #333333; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; } 436.quoteblock blockquote { margin: 0; padding: 0; border: 0; } 437.quoteblock blockquote:before { content: "\201c"; float: left;
437 font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #003b6b; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); } 438.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; } 439.quoteblock .attribution { margin-top: 0.5em; margin-right: 0.5ex; text-align: right; } 440.quoteblock .quoteblock { margin-left: 0; margin-right: 0; padding: 0.5em 0; border-left: 3px solid #e15200; } 441.quoteblock .quoteblock blockquote { padding: 0 0 0 0.75em; } 442.quoteblock .quoteblock blockquote:before { display: none; } 443 444.verseblock { margin: 0 1em 0.75em 1em; } 445.verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #333333; font-weight: 300; text-rendering: optimizeLegibility; } 446.verseblock pre strong { font-weight: 400; } 447.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; } 448 449.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; } 450.quoteblock .attribution br, .verseblock .attribution br { display: none; } 451.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.05em; color: #e15200; } 452 453.quoteblock.abstract { margin: 0 0 0.75em 0; display: block; } 454.quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { text-align: left; word-spacing: 0; } 455.quoteblock.abstract blockquote:before, .quoteblock.abstract blockquote p:first-of-type:before { display: none; } 456 457table.tableblock { max-width: 100%; border-collapse: separate; } 458table.tableblock td > .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; } 459 460table.spread { width: 100%; } 461 462table.tableblock, th.tableblock, td.tableblock { border: 0 solid #d8d8ce; } 463 464table.grid-all th.tableblock, table.grid-all td.tableblock { border-width: 0 1px 1px 0; } 465 466table.grid-all tfoot > tr > th.tableblock, table.grid-all tfoot > tr > td.tableblock { border-width: 1px 1px 0 0; } 467 468table.grid-cols th.tableblock, table.grid-cols td.tableblock { border-width: 0 1px 0 0; } 469 470table.grid-all * > tr > .tableblock:last-child, table.grid-cols * > tr > .tableblock:last-child { border-right-width: 0; } 471 472table.grid-rows th.tableblock, table.grid-rows td.tableblock { border-width: 0 0 1px 0; } 473 474table.grid-all tbody > tr:last-child > th.tableblock, table.grid-all tbody > tr:last-child > td.tableblock, table.grid-all thead:last-child > tr > th.tableblock, table.grid-rows tbody > tr:last-child > th.tableblock, table.grid-rows tbody > tr:last-child > td.tableblock, table.grid-rows thead:last-child > tr > th.tableblock { border-bottom-width: 0; } 475 476table.grid-rows tfoot > tr > th.tableblock, table.grid-rows tfoot > tr > td.tableblock { border-width: 1px 0 0 0; } 477 478table.frame-all { border-width: 1px; } 479 480table.frame-sides { border-width: 0 1px; } 481 482table.frame-topbot { border-width: 1px 0; } 483 484th.halign-left, td.halign-left { text-align: left; } 485 486th.halign-right, td.halign-right { text-align: right; } 487 488th.halign-center, td.halign-center { text-align: center; } 489 490th.valign-top, td.valign-top { vertical-align: top; } 491 492th.valign-bottom, td.valign-bottom { vertical-align: bottom; } 493 494th.valign-middle, td.valign-middle { vertical-align: middle; } 495 496table thead th, table tfoot th { font-weight: bold; } 497 498tbody tr th { display: table-cell; line-height: 1.4; background: -webkit-linear-gradient(top, #add386, #90b66a); } 499 500tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: white; font-weight: bold; } 501 502p.tableblock > code:only-child { background: none; padding: 0; } 503 504p.tableblock { font-size: 1em; } 505 506td > div.verse { white-space: pre; } 507 508ol { margin-left: 1.75em; } 509 510ul li ol { margin-left: 1.5em; } 511 512dl dd { margin-left: 1.125em; } 513 514dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; } 515 516ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.375em; } 517 518ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; } 519 520ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; } 521 522ul.checklist li > p:first-child > .fa-check-square-o:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; } 523 524ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; } 525 526ul.inline { margin: 0 auto 0.375em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; } 527ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; } 528ul.inline > li > * { display: block; } 529 530.unstyled dl dt { font-weight: normal; font-style: normal; } 531 532ol.arabic { list-style-type: decimal; } 533 534ol.decimal { list-style-type: decimal-leading-zero; } 535 536ol.loweralpha { list-style-type: lower-alpha; } 537 538ol.upperalpha { list-style-type: upper-alpha; } 539 540ol.lowerroman { list-style-type: lower-roman; } 541 542ol.upperroman { list-style-type: upper-roman; } 543 544ol.lowergreek { list-style-type: lower-greek; } 545 546.hdlist > table, .colist > table { border: 0; background: none; } 547.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; } 548 549td.hdlist1 { padding-right: .75em; font-weight: bold; } 550 551td.hdlist1, td.hdlist2 { vertical-align: top; } 552 553.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; } 554 555.colist > table tr > td:first-of-type { padding: 0 0.75em; line-height: 1; } 556.colist > table tr > td:last-of-type { padding: 0.25em 0; } 557 558.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; } 559 560.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; } 561.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; } 562.imageblock > .title { margin-bottom: 0; } 563.imageblock.thumb, .imageblock.th { border-width: 6px; } 564.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; } 565 566.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; } 567.image.left { margin-right: 0.625em; } 568.image.right { margin-left: 0.625em; } 569 570a.image { text-decoration: none; } 571 572span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; } 573span.footnote a, span.footnoteref a { text-decoration: none; } 574span.footnote a:active, span.footnoteref a:active { text-decoration: underline; } 575 576#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; } 577#footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; } 578#footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; } 579#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; } 580#footnotes .footnote:last-of-type { margin-bottom: 0; } 581 582#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; } 583 584.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; } 585.gist .file-data > table td.line-data { width: 99%; } 586 587div.unbreakable { page-break-inside: avoid; } 588 589.big { font-size: larger; } 590 591.small { font-size: smaller; } 592 593.underline { text-decoration: underline; } 594 595.overline { text-decoration: overline; } 596 597.line-through { text-decoration: line-through; } 598 599.aqua { color: #00bfbf; } 600 601.aqua-background { background-color: #00fafa; } 602 603.black { color: black; } 604 605.black-background { background-color: black; } 606 607.blue { color: #0000bf; } 608 609.blue-background { background-color: #0000fa; } 610 611.fuchsia { color: #bf00bf; } 612 613.fuchsia-background { background-color: #fa00fa; } 614 615.gray { color: #606060; } 616 617.gray-background { background-color: #7d7d7d; } 618 619.green { color: #006000; } 620 621.green-background { background-color: #007d00; } 622 623.lime { color: #00bf00; } 624 625.lime-background { background-color: #00fa00; } 626 627.maroon { color: #600000; } 628 629.maroon-background { background-color: #7d0000; } 630 631.navy { color: #000060; } 632 633.navy-background { background-color: #00007d; } 634 635.olive { color: #606000; } 636 637.olive-background { background-color: #7d7d00; } 638 639.purple { color: #600060; } 640 641.purple-background { background-color: #7d007d; } 642 643.red { color: #bf0000; } 644 645.red-background { background-color: #fa0000; } 646 647.silver { color: #909090; } 648 649.silver-background { background-color: #bcbcbc; } 650 651.teal { color: #006060; } 652 653.teal-background { background-color: #007d7d; } 654 655.white { color: #bfbfbf; } 656 657.white-background { background-color: #fafafa; } 658 659.yellow { color: #bfbf00; } 660 661.yellow-background { background-color: #fafa00; } 662 663span.icon > .fa { cursor: default; } 664 665.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; } 666.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #004176; } 667.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; } 668.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; } 669.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; } 670.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; } 671 672.conum[data-value] { display: inline-block; color: #fff !important; background-color: black; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; } 673.conum[data-value] * { color: #fff !important; } 674.conum[data-value] + b { display: none; } 675.conum[data-value]:after { content: attr(data-value); } 676pre .conum[data-value] { position: relative; top: -0.125em; } 677 678b.conum * { color: inherit !important; } 679 680.conum:not([data-value]):empty { display: none; } 681 682h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { border-bottom: 1px solid #dddddd; } 683 684.sect1 { padding-bottom: 0; } 685 686#toctitle { color: #00406F; font-weight: normal; margin-top: 1.5em; } 687 688.sidebarblock { border-color: #aaa; } 689 690code { -webkit-border-radius: 4px; border-radius: 4px; } 691
692p.tableblock.header { color: #6d6e71; } 693 694.literalblock pre, .listingblock pre { background: #eeeeee; } 695 696</style> 697<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"> 698<style> 699.listingblock .pygments .hll { background-color: #ffffcc } 700.listingblock .pygments, .listingblock .pygments code { background: #f8f8f8; } 701.listingblock .pygments .tok-c { color: #408080; font-style: italic } /* Comment */ 702.listingblock .pygments .tok-err { border: 1px solid #FF0000 } /* Error */ 703.listingblock .pygments .tok-k { color: #008000; font-weight: bold } /* Keyword */ 704.listingblock .pygments .tok-o { color: #666666 } /* Operator */ 705.listingblock .pygments .tok-ch { color: #408080; font-style: italic } /* Comment.Hashbang */ 706.listingblock .pygments .tok-cm { color: #408080; font-style: italic } /* Comment.Multiline */ 707.listingblock .pygments .tok-cp { color: #BC7A00 } /* Comment.Preproc */ 708.listingblock .pygments .tok-cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */ 709.listingblock .pygments .tok-c1 { color: #408080; font-style: italic } /* Comment.Single */ 710.listingblock .pygments .tok-cs { color: #408080; font-style: italic } /* Comment.Special */ 711.listingblock .pygments .tok-gd { color: #A00000 } /* Generic.Deleted */ 712.listingblock .pygments .tok-ge { font-style: italic } /* Generic.Emph */ 713.listingblock .pygments .tok-gr { color: #FF0000 } /* Generic.Error */ 714.listingblock .pygments .tok-gh { color: #000080; font-weight: bold } /* Generic.Heading */ 715.listingblock .pygments .tok-gi { color: #00A000 } /* Generic.Inserted */ 716.listingblock .pygments .tok-go { color: #888888 } /* Generic.Output */ 717.listingblock .pygments .tok-gp { color: #000080; font-weight: bold } /* Generic.Prompt */ 718.listingblock .pygments .tok-gs { font-weight: bold } /* Generic.Strong */ 719.listingblock .pygments .tok-gu { color: #800080; font-weight: bold } /* Generic.Subheading */ 720.listingblock .pygments .tok-gt { color: #0044DD } /* Generic.Traceback */ 721.listingblock .pygments .tok-kc { color: #008000; font-weight: bold } /* Keyword.Constant */ 722.listingblock .pygments .tok-kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ 723.listingblock .pygments .tok-kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ 724.listingblock .pygments .tok-kp { color: #008000 } /* Keyword.Pseudo */ 725.listingblock .pygments .tok-kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ 726.listingblock .pygments .tok-kt { color: #B00040 } /* Keyword.Type */ 727.listingblock .pygments .tok-m { color: #666666 } /* Literal.Number */ 728.listingblock .pygments .tok-s { color: #BA2121 } /* Literal.String */ 729.listingblock .pygments .tok-na { color: #7D9029 } /* Name.Attribute */ 730.listingblock .pygments .tok-nb { color: #008000 } /* Name.Builtin */ 731.listingblock .pygments .tok-nc { color: #0000FF; font-weight: bold } /* Name.Class */ 732.listingblock .pygments .tok-no { color: #880000 } /* Name.Constant */ 733.listingblock .pygments .tok-nd { color: #AA22FF } /* Name.Decorator */ 734.listingblock .pygments .tok-ni { color: #999999; font-weight: bold } /* Name.Entity */ 735.listingblock .pygments .tok-ne { color: #D2413A; font-weight: bold } /* Name.Exception */ 736.listingblock .pygments .tok-nf { color: #0000FF } /* Name.Function */ 737.listingblock .pygments .tok-nl { color: #A0A000 } /* Name.Label */ 738.listingblock .pygments .tok-nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ 739.listingblock .pygments .tok-nt { color: #008000; font-weight: bold } /* Name.Tag */ 740.listingblock .pygments .tok-nv { color: #19177C } /* Name.Variable */ 741.listingblock .pygments .tok-ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ 742.listingblock .pygments .tok-w { color: #bbbbbb } /* Text.Whitespace */ 743.listingblock .pygments .tok-mb { color: #666666 } /* Literal.Number.Bin */ 744.listingblock .pygments .tok-mf { color: #666666 } /* Literal.Number.Float */ 745.listingblock .pygments .tok-mh { color: #666666 } /* Literal.Number.Hex */ 746.listingblock .pygments .tok-mi { color: #666666 } /* Literal.Number.Integer */ 747.listingblock .pygments .tok-mo { color: #666666 } /* Literal.Number.Oct */ 748.listingblock .pygments .tok-sa { color: #BA2121 } /* Literal.String.Affix */ 749.listingblock .pygments .tok-sb { color: #BA2121 } /* Literal.String.Backtick */ 750.listingblock .pygments .tok-sc { color: #BA2121 } /* Literal.String.Char */ 751.listingblock .pygments .tok-dl { color: #BA2121 } /* Literal.String.Delimiter */ 752.listingblock .pygments .tok-sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ 753.listingblock .pygments .tok-s2 { color: #BA2121 } /* Literal.String.Double */ 754.listingblock .pygments .tok-se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ 755.listingblock .pygments .tok-sh { color: #BA2121 } /* Literal.String.Heredoc */ 756.listingblock .pygments .tok-si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ 757.listingblock .pygments .tok-sx { color: #008000 } /* Literal.String.Other */ 758.listingblock .pygments .tok-sr { color: #BB6688 } /* Literal.String.Regex */ 759.listingblock .pygments .tok-s1 { color: #BA2121 } /* Literal.String.Single */ 760.listingblock .pygments .tok-ss { color: #19177C } /* Literal.String.Symbol */ 761.listingblock .pygments .tok-bp { color: #008000 } /* Name.Builtin.Pseudo */ 762.listingblock .pygments .tok-fm { color: #0000FF } /* Name.Function.Magic */ 763.listingblock .pygments .tok-vc { color: #19177C } /* Name.Variable.Class */ 764.listingblock .pygments .tok-vg { color: #19177C } /* Name.Variable.Global */ 765.listingblock .pygments .tok-vi { color: #19177C } /* Name.Variable.Instance */ 766.listingblock .pygments .tok-vm { color: #19177C } /* Name.Variable.Magic */ 767.listingblock .pygments .tok-il { color: #666666 } /* Literal.Number.Integer.Long */ 768</style> 769</head> 770<body class="book toc2 toc-left"> 771<div id="header"> 772<h1>Activiti User Guide</h1> 773<div class="details"> 774<span id="author" class="author">
774v 6.0.0</span><br> 775</div> 776<div id="toc" class="toc2"> 777<div id="toctitle">Table of Contents</div> 778<ul class="sectlevel1"> 779<li><a href="#_introduction">1. Introduction</a> 780<ul class="sectlevel2"> 781<li><a href="#license">1.1. License</a></li> 782<li><a href="#download">1.2. Download</a></li> 783<li><a href="#sources">1.3. Sources</a></li> 784<li><a href="#required.software">1.4. Required software</a> 785<ul class="sectlevel3"> 786<li><a href="#_jdk_7">1.4.1. JDK 7+</a></li> 787<li><a href="#_ide">1.4.2. IDE</a></li> 788</ul> 789</li> 790<li><a href="#reporting.problems">1.5. Reporting problems</a></li> 791<li><a href="#experimental">1.6. Experimental features</a></li> 792<li><a href="#internal">1.7. Internal implementation classes</a></li> 793</ul> 794</li> 795<li><a href="#_getting_started">2. Getting Started</a> 796<ul class="sectlevel2"> 797<li><a href="#demo.setup.one.minute.version">2.1. One minute version</a></li> 798<li><a href="#activiti.setup">2.2. Activiti setup</a></li> 799<li><a href="#activiti.setup.database">2.3. Activiti database setup</a></li> 800<li><a href="#getting.started.including.libs">2.4. Include the Activiti jar and its dependencies</a></li> 801<li><a href="#getting.started.next.steps">2.5. Next steps</a></li> 802</ul> 803</li> 804<li><a href="#_configuration">3. Configuration</a> 805<ul class="sectlevel2"> 806<li><a href="#configuration">3.1. Creating a ProcessEngine</a></li> 807<li><a href="#configurationRoot">3.2. ProcessEngineConfiguration bean</a></li> 808<li><a href="#databaseConfiguration">3.3. Database configuration</a></li> 809<li><a href="#jndiDatasourceConfig">3.4. JNDI Datasource Configuration</a> 810<ul class="sectlevel3"> 811<li><a href="#jndi_configuration">3.4.1. Configuration</a></li> 812<li><a href="#_jndi_properties">3.4.2. JNDI properties</a></li> 813</ul> 814</li> 815<li><a href="#supporteddatabases">3.5. Supported databases</a></li> 816<li><a href="#creatingDatabaseTable">3.6. Creating the database tables</a></li> 817<li><a href="#database.tables.explained">3.7. Database table names explained</a></li> 818<li><a href="#databaseUpgrade">3.8. Database upgrade</a></li> 819<li><a href="#jobExecutorConfiguration">3.9. Job Executor (since version 6.0.0)</a></li> 820<li><a href="#_job_executor_activation">3.10. Job executor activation</a></li> 821<li><a href="#mailServerConfiguration">3.11. Mail server configuration</a></li> 822<li><a href="#historyConfiguration">3.12. History configuration</a></li> 823<li><a href="#exposingConfigurationBeans">3.13. Exposing configuration beans in expressions and scripts</a></li> 824<li><a href="#processDefinitionCacheConfiguration">3.14. Deployment cache configuration</a></li> 825<li><a href="#loggingConfiguration">3.15. Logging</a></li> 826<li><a href="#MDC">3.16. Mapped Diagnostic Contexts</a></li> 827<li><a href="#eventDispatcher">3.17. Event handlers</a> 828<ul class="sectlevel3"> 829<li><a href="#eventDispatcherListener">3.17.1. Event listener implementation</a></li> 830<li><a href="#eventDispatcherConfiguration">3.17.2. Configuration and setup</a></li> 831<li><a href="#eventDispatcherConfigurationRuntime">3.17.3. Adding listeners at runtime</a></li> 832<li><a href="#eventDispatcherConfigurationProcessDefinition">3.17.4. Adding listeners to process definitions</a> 833<ul class="sectlevel4"> 834<li><a href="#_listeners_executing_user_defined_logic">Listeners executing user-defined logic</a></li> 835<li><a href="#_listeners_throwing_bpmn_events">Listeners throwing BPMN events</a></li> 836<li><a href="#_notes_on_listeners_on_a_process_definition">Notes on listeners on a process-definition</a></li> 837</ul> 838</li> 839<li><a href="#eventDispatcherCustomEvents">3.17.5. Dispatching events through API</a></li> 840<li><a href="#eventDispatcherEventTypes">3.17.6. Supported event types</a></li> 841<li><a href="#eventDispatcherRemarks">3.17.7. Additional remarks</a></li> 842</ul> 843</li> 844</ul> 845</li> 846<li><a href="#chapterApi">4. The Activiti API</a> 847<ul class="sectlevel2"> 848<li><a href="#apiEngine">4.1. The Process Engine API and services</a></li> 849<li><a href="#_exception_strategy">4.2. Exception strategy</a></li> 850<li><a href="#api.services">4.3. Working with the Activiti services</a> 851<ul class="sectlevel3"> 852<li><a href="#api.services.deployment">4.3.1. Deploying the process</a></li> 853<li><a href="#api.services.start.processinstance">4.3.2. Starting a process instance</a></li> 854<li><a href="#api.services.tasks">4.3.3. Completing tasks</a></li> 855<li><a href="#api.services.suspend">4.3.4. Suspending and activating a process</a></li> 856<li><a href="#api.services">4.3.5. Further reading</a></li> 857</ul> 858</li> 859<li><a href="#queryAPI">4.4. Query API</a></li> 860<li><a href="#apiVariables">4.5. Variables</a></li> 861<li><a href="#apiTransientVariables">4.6. Transient variables</a></li> 862<li><a href="#apiExpressions">4.7. Expressions</a></li> 863<li><a href="#apiUnitTesting">4.8. Unit testing</a></li> 864<li><a href="#apiDebuggingUnitTest">4.9. Debugging unit tests</a></li> 865<li><a href="#apiProcessEngineInWebApp">4.10. The process engine in a web application</a></li> 866</ul> 867</li> 868<li><a href="#springintegration">5. Spring integration</a> 869<ul class="sectlevel2"> 870<li><a href="#_processenginefactorybean">5.1. ProcessEngineFactoryBean</a></li> 871<li><a href="#_transactions">5.2. Transactions</a></li> 872<li><a href="#springExpressions">5.3. Expressions</a></li> 873<li><a href="#_automatic_resource_deployment">5.4. Automatic resource deployment</a></li> 874<li><a href="#springUnitTest">5.5. Unit testing</a></li> 875<li><a href="#_jpa_with_hibernate_4_2_x">5.6. JPA with Hibernate 4.2.x</a></li> 876<li><a href="#springSpringBoot">5.7. Spring Boot</a> 877<ul class="sectlevel3"> 878<li><a href="#_compatibility">5.7.1. Compatibility</a></li> 879<li><a href="#_getting_started_2">5.7.2. Getting started</a></li> 880<li><a href="#_changing_the_database_and_connection_pool">5.7.3. Changing the database and connection pool</a></li> 881<li><a href="#_rest_support">5.7.4. REST support</a></li> 882<li><a href="#_jpa_support">5.7.5. JPA support</a></li> 883<li><a href="#_further_reading">5.7.6. Further Reading</a></li> 884</ul> 885</li> 886</ul> 887</li> 888<li><a href="#chDeployment">6. Deployment</a> 889<ul class="sectlevel2"> 890<li><a href="#_business_archives">6.1. Business archives</a> 891<ul class="sectlevel3"> 892<li><a href="#_deploying_programmatically">6.1.1. Deploying programmatically</a></li> 893</ul> 894</li> 895<li><a href="#_external_resources">6.2. External resources</a> 896<ul class="sectlevel3"> 897<li><a href="#_java_classes">6.2.1. Java classes</a></li> 898<li><a href="#_using_spring_beans_from_a_process">6.2.2. Using Spring beans from a process</a></li> 899<li><a href="#_creating_a_single_app">6.2.3. Creating a single app</a></li> 900</ul> 901</li> 902<li><a href="#versioningOfProcessDefinitions">6.3. Versioning of process definitions</a></li> 903<li><a href="#providingProcessDiagram">6.4. Providing a process diagram</a></li> 904<li><a href="#generatingProcessDiagram">6.5. Generating a process diagram</a></li> 905<li><a href="#deploymentCategory">6.6. Category</a></li> 906</ul> 907</li> 908<li>
908<a href="#bpmn20">7. BPMN 2.0 Introduction</a> 909<ul class="sectlevel2"> 910<li><a href="#whatIsBpmn">7.1. What is BPMN?</a></li> 911<li><a href="#bpmnDefiningProcess">7.2. Defining a process</a></li> 912<li><a href="#_getting_started_10_minute_tutorial">7.3. Getting started: 10 minute tutorial</a> 913<ul class="sectlevel3"> 914<li><a href="#bpmn10MinuteTutorialPrerequisites">7.3.1. Prerequisites</a></li> 915<li><a href="#bpmn10MinuteTutorialGoal">7.3.2. Goal</a></li> 916<li><a href="#bpmnFirstExampleUseCase">7.3.3. Use case</a></li> 917<li><a href="#bpmnFirstExampleDiagram">7.3.4. Process diagram</a></li> 918<li><a href="#bpmnFirstExampleXml">7.3.5. XML representation</a></li> 919<li><a href="#bpmnFirstExamplStartProcess">7.3.6. Starting a process instance</a></li> 920<li><a href="#bpmnFirstExampleCandidateList">7.3.7. Task lists</a></li> 921<li><a href="#bpmnFirstExampleClaimTask">7.3.8. Claiming the task</a></li> 922<li><a href="#bpmnFirstExampleCompleteTask">7.3.9. Completing the task</a></li> 923<li><a href="#bpmnFirstExampleEndingProcess">7.3.10. Ending the process</a></li> 924<li><a href="#bpmnFirstExampleCode">7.3.11. Code overview</a></li> 925<li><a href="#bpmnFirstExampleFutureEnhancements">7.3.12. Future enhancements</a></li> 926</ul> 927</li> 928</ul> 929</li> 930<li><a href="#bpmnConstructs">8. BPMN 2.0 Constructs</a> 931<ul class="sectlevel2"> 932<li><a href="#bpmnCustomExtensions">8.1. Custom extensions</a></li> 933<li><a href="#bpmnEvents">8.2. Events</a> 934<ul class="sectlevel3"> 935<li><a href="#eventDefinitions">8.2.1. Event Definitions</a></li> 936<li><a href="#timerEventDefinitions">8.2.2. Timer Event Definitions</a></li> 937<li><a href="#bpmnErrorEventDefinition">8.2.3. Error Event Definitions</a></li> 938<li><a href="#bpmnSignalEventDefinition">8.2.4. Signal Event Definitions</a> 939<ul class="sectlevel4"> 940<li><a href="#bpmnSignalEventDefinitionThrow">Throwing a Signal Event</a></li> 941<li><a href="#bpmnSignalEventDefinitionCatch">Catching a Signal Event</a></li> 942<li><a href="#bpmnSignalEventDefinitionQuery">Querying for Signal Event subscriptions</a></li> 943<li><a href="#bpmnSignalEventDefinitionScope">Signal event scope</a></li> 944<li><a href="#bpmnSignalEventDefinitionExample">Signal Event example(s)</a></li> 945</ul> 946</li> 947<li><a href="#bpmnMessageEventDefinition">8.2.5. Message Event Definitions</a> 948<ul class="sectlevel4"> 949<li><a href="#bpmnMessageEventDefinitionThrow">Throwing a Message Event</a></li> 950<li><a href="#bpmnMessageEventDefinitionQuery">Querying for Message Event subscriptions</a></li> 951<li><a href="#bpmnMessageEventDefinitionExample">Message Event example(s)</a></li> 952</ul> 953</li> 954<li><a href="#bpmnStartEvents">8.2.6. Start Events</a></li> 955<li><a href="#bpmnNoneStartEvent">8.2.7. None Start Event</a> 956<ul class="sectlevel4"> 957<li><a href="#noneStartEventDescription">Description</a></li> 958<li><a href="#noneStartEventGraphicalNotation">Graphical notation</a></li> 959<li><a href="#noneStartEventXml">XML representation</a></li> 960<li><a href="#noneStartEventCustomExtension">Custom extensions for the none start event</a></li> 961</ul> 962</li> 963<li><a href="#bpmnTimerStartEvent">8.2.8. Timer Start Event</a> 964<ul class="sectlevel4"> 965<li><a href="#timerStartEventDescription">Description</a></li> 966<li><a href="#timerStartEventGraphicalNotation">Graphical notation</a></li> 967<li><a href="#timerStartEventXml">XML representation</a></li> 968</ul> 969</li> 970<li><a href="#bpmnMessageStartEvent">8.2.9. Message Start Event</a> 971<ul class="sectlevel4"> 972<li><a href="#messageStartEventDescription">Description</a></li> 973<li><a href="#messageStartEventGraphicalNotation">Graphical notation</a></li> 974<li><a href="#messageStartEventXml">XML representation</a></li> 975</ul> 976</li> 977<li><a href="#bpmnSignalStartEvent">8.2.10. Signal Start Event</a> 978<ul class="sectlevel4"> 979<li><a href="#bpmnSignalStartEventDescription">Description</a></li> 980<li><a href="#signalStartEventGraphicalNotation">Graphical notation</a></li> 981<li><a href="#signalStartEventXml">XML representation</a></li> 982</ul> 983</li> 984<li><a href="#bpmnErrorStartEvent">8.2.11. Error Start Event</a> 985<ul class="sectlevel4"> 986<li><a href="#errorStartEventDescription">Description</a></li> 987<li><a href="#errorStartEventGraphicalNotation">Graphical notation</a></li> 988<li><a href="#errorStartEventXml">XML representation</a></li> 989</ul> 990</li> 991<li><a href="#bpmnEndEvent">8.2.12. End Events</a></li> 992<li><a href="#bpmnNoneEndEvent">8.2.13. None End Event</a> 993<ul class="sectlevel4"> 994<li><a href="#noneEndEventDescription">Description</a></li> 995<li><a href="#bpmnNoneEndEventDescription">Graphical notation</a></li> 996<li><a href="#bpmnNoneStartEventXml">XML representation</a></li> 997</ul> 998</li> 999<li><a href="#bpmnErrorEndEvent">8.2.14. Error End Event</a> 1000<ul class="sectlevel4"> 1001<li><a href="#bpmnErrorEndEventDescription">Description</a></li> 1002<li><a href="#bpmnErrorEndEventGraphicalNotation">Graphical notation</a></li> 1003<li><a href="#bpmnErrorEndEventXml">XML representation</a></li> 1004</ul> 1005</li> 1006<li><a href="#bpmnCancelEndEvent">8.2.15. Terminate End Event</a> 1007<ul class="sectlevel4"> 1008<li><a href="#_description">Description</a></li> 1009<li><a href="#_graphical_notation">Graphical notation</a></li> 1010<li><a href="#_xml_representation">XML representation</a></li> 1011</ul> 1012</li> 1013<li><a href="#_cancel_end_event">8.2.16. Cancel End Event</a> 1014<ul class="sectlevel4"> 1015<li><a href="#_description_2">Description</a></li> 1016<li><a href="#bpmnCancelEndEventGraphicalNotation">Graphical notation</a></li> 1017<li><a href="#bpmnCancelEndEventXml">XML representation</a></li> 1018</ul> 1019</li> 1020<li><a href="#bpmnBoundaryEvent">8.2.17. Boundary Events</a></li> 1021<li><a href="#bpmnTimerBoundaryEvent">8.2.18. Timer Boundary Event</a> 1022<ul class="sectlevel4"> 1023<li><a href="#timerBoundaryEventDescription">Description</a></li> 1024<li><a href="#bpmnTimerBoundaryEventGraphicalNotation">Graphical Notation</a></li> 1025<li><a href="#bpmnTimerBoundaryEventXml">XML Representation</a></li> 1026<li><a href="#bpmnKnownIssueBoundaryEvent">Known issue with boundary events</a></li> 1027</ul> 1028</li> 1029<li><a href="#bpmnBoundaryErrorEvent">8.2.19. Error Boundary Event</a> 1030<ul class="sectlevel4"> 1031<li><a href="#bpmnBoundaryErrorEventDescription">Description</a></li> 1032<li><a href="#bpmnBoundaryErrorEventgraphicalNotation">Graphical notation</a></li> 1033<li><a href="#bpmnBoundaryErrorEventXml">Xml representation</a></li> 1034<li><a href="#bpmnBoundaryErrorEventExample">Example</a></li> 1035</ul> 1036</li> 1037<li><a href="#bpmnBoundarySignalEvent">8.2.20. Signal Boundary Event</a> 1038<ul class="sectlevel4"> 1039<li><a href="#bpmnBoundarySignalEventDescription">Description</a></li> 1040<li><a href="#bpmnBoundarySignalEventGraphicalNotation">Graphical notation</a></li> 1041<li><a href="#bpmnBoundarySignalEventXml">XML representation</a></li> 1042<li><a href="#bpmnBoundarySignalEventExample">Example</a></li> 1043</ul> 1044</li> 1045<li><a href="#bpmnBoundaryMessageEvent">8.2.21. Message Boundary Event</a> 1046<ul class="sectlevel4"> 1047<li><a href="#bpmnBoundaryMessageEventDescription">Description</a></li> 1048<li><a href="#bpmnBoundaryMessageEventGraphicalNotation">Graphical notation</a></li> 1049<li><a href="#bpmnBoundaryMessageEventXml">XML representation</a></li> 1050<li><a href="#bpmnBoundaryMessageEventExample">Example</a></li> 1051</ul> 1052</li> 1053<li><a href="#bpmnBoundaryCancelEvent">8.2.22. Cancel Boundary Event</a> 1054<ul class="sectlevel4"> 1055<li><a href="#_description_3">Description</a></li> 1056<li><a href="#bpmnBoundaryCancelEventGraphicalNotation">Graphical notation</a></li> 1057<li><a href="#bpmnBoundarySignalEventXml">XML representation</a></li> 1058</ul> 1059</li> 1060<li><a href="#bpmnBoundaryCompensationEvent">8.2.23. Compensation Boundary Event</a> 1061<ul class="sectlevel4"> 1062<li><a href="#_description_4">Description</a></li> 1063<li><a href="#bpmnBoundaryCompensationEventGraphicalNotation">Graphical notation</a></li> 1064<li><a href="#bpmnBoundaryCompensationEventXml">XML representation</a></li> 1065</ul> 1066</li> 1067<li><a href="#bpmnIntermediateCatchingEvent">8.2.24. Intermediate Catching Events</a></li> 1068<li><a href="#bpmnTimerIntermediateEvent">8.2.25. Timer Intermediate Catching Event</a> 1069<ul class="sectlevel4"> 1070<li><a href="#bpmnTimerIntermediateEventDescription">Description</a></li> 1071<li><a href="#bpmnTimerIntermediateEventGraphicalNotation">Graphical Notation</a></li> 1072<li><a href="#bpmnTimerIntermediateEventXml">XML Representation</a></li> 1073</ul> 1074</li> 1075<li><a href="#bpmnIntermediateSignalEvent">8.2.26. Signal Intermediate Catching Event</a> 1076<ul class="sectlevel4"> 1077<li><a href="#bpmnIntermediateSignalEventDescription">Description</a></li> 1078<li><a href="#bpmnIntermediateSignalEventGraphicalNotation">Graphical notation</a></li> 1079<li><a href="#bpmnIntermediateSignalEventXml">XML representation</a></li> 1080<li><a href="#bpmnIntermediateSignalEventExample">Example</a></li> 1081</ul> 1082</li> 1083<li><a href="#bpmnIntermediateMessageEvent">8.2.27. Message Intermediate Catching Event</a> 1084<ul class="sectlevel4"> 1085<li><a href="#bpmnIntermediateMessageEventDescription">Description</a></li> 1086<li><a href="#bpmnIntermediateMessageEventGraphicalNotation">Graphical notation</a></li> 1087<li><a href="#bpmnIntermediateSignalEventXml">XML representation</a></li> 1088<li><a href="#bpmnIntermediateMessageEventExample">Example</a></li> 1089</ul> 1090</li> 1091<li><a href="#bpmnIntermediateThrowEvent">8.2.28. Intermediate Throwing Event</a></li> 1092<li><a href="#bpmnIntermediateThrowNoneEvent">8.2.29. Intermediate Throwing None Event</a></li> 1093<li><a href="#bpmnIntermediateThrowSignalEvent">8.2.30. Signal Intermediate Throwing Event</a> 1094<ul class="sectlevel4"> 1095<li><a href="#bpmnIntermediateThrowSignalEventDescription">Description</a></li> 1096<li><a href="#bpmnIntermediateThrowSignalEventGraphicalNotation">Graphical notation</a></li> 1097<li><a href="#bpmnIntermediateThrowSignalEventXml">XML representation</a></li> 1098<li><a href="#bpmnIntermediateSignalEventExample">Example</a></li> 1099</ul> 1100</li> 1101<li><a href="#bpmnIntermediateThrowCompensationEvent">8.2.31. Compensation Intermediate Throwing Event</a> 1102<ul class="sectlevel4"> 1103<li><a href="#_description_5">Description</a></li> 1104<li><a href="#bpmnIntermediateThrowCompensationEventGraphicalNotation">Graphical notation</a></li> 1105<li><a href="#bpmnIntermediateThrowSignalEventXml">Xml representation</a></li> 1106</ul> 1107</li> 1108</ul> 1109</li> 1110<li><a href="#bpmnSequenceFlow">8.3. Sequence Flow</a> 1111<ul class="sectlevel3"> 1112<li><a href="#sequenceFlowDescription">8.3.1. Description</a></li> 1113<li><a href="#sequenceFlowGraphicalNotation">8.3.2. Graphical notation</a></li> 1114<li><a href="#sequenceFlowXml">8.3.3. XML representation</a></li> 1115<li><a href="#bpmnConditionalSequenceFlow">8.3.4. Conditional sequence flow</a> 1116<ul class="sectlevel4"> 1117<li><a href="#condSeqFlowDescription">Description</a></li> 1118<li><a href="#conditionalSequenceFlowGraphicalNotation">Graphical notation</a></li> 1119<li><a href="#conditionalSequenceFlowXml">XML representation</a></li> 1120</ul> 1121</li> 1122<li><a href="#bpmnDefaultSequenceFlow">8.3.5. Default sequence flow</a> 1123<ul class="sectlevel4"> 1124<li><a href="#bpmnDefaultSequenceFlowDescription">Description</a></li> 1125<li><a href="#bpmnDefaultSequenceFlowGraphicalNotation">Graphical notation</a></li> 1126<li><a href="#bpmnDefaultSequenceFlowXmlRepresentation">XML representation</a></li> 1127</ul> 1128</li> 1129</ul> 1130</li> 1131<li><a href="#bpmnGateways">8.4. Gateways</a> 1132<ul class="sectlevel3"> 1133<li><a href="#bpmnExclusiveGateway">8.4.1. Exclusive Gateway</a> 1134<ul class="sectlevel4"> 1135<li><a href="#exclusiveGatewayDescription">Description</a></li> 1136<li><a href="#exclusiveGatewayGraphNotation">Graphical notation</a></li> 1137<li><a href="#exclusiveGatewayXML">XML representation</a></li> 1138</ul> 1139</li> 1140<li><a href="#bpmnParallelGateway">8.4.2. Parallel Gateway</a> 1141<ul class="sectlevel4"> 1142<li><a href="#bpmnParallelGatewayDescription">Description</a></li> 1143<li><a href="#bpmnParallelGatewayGraphicalNotation">Graphical Notation</a></li> 1144<li><a href="#bpmnParallelGatewayXML">XML representation</a></li> 1145</ul> 1146</li> 1147<li><a href="#bpmnInclusiveGateway">8.4.3. Inclusive Gateway</a> 1148<ul class="sectlevel4"> 1149<li><a href="#bpmnInclusiveGatewayDescription">Description</a></li> 1150<li><a href="#bpmnInclusiveGatewayGraphicalNotation">Graphical Notation</a></li> 1151<li><a href="#bpmnInclusiveGatewayXML">XML representation</a></li> 1152</ul> 1153</li> 1154<li><a href="#bpmnEventbasedGateway">8.4.4. Event-based Gateway</a> 1155<ul class="sectlevel4"> 1156<li><a href="#eventBasedGatewayDescription">Description</a></li> 1157<li><a href="#eventBasedGatewayGraphNotation">Graphical notation</a></li> 1158<li><a href="#eventBasedGatewayXML">XML representation</a></li> 1159<li><a href="#eventBasedGatewayExample">Example(s)</a></li> 1160</ul> 1161</li> 1162</ul> 1163</li> 1164<li><a href="#bpmnTask">8.5. Tasks</a> 1165<ul class="sectlevel3"> 1166<li><a href="#bpmnUserTask">8.5.1. User Task</a> 1167<ul class="sectlevel4"> 1168<li><a href="#bpmnUserTaskDescription">Description</a></li> 1169<li><a href="#bpmnUserTaskGraphicalNotation">Graphical notation</a></li> 1170<li><a href="#bpmnUserTaskXml">XML representation</a></li> 1171<li><a href="#bpmnUserTaskDueDate">Due Date</a></li> 1172<li><a href="#bpmnUserTaskAssignment">User assignment</a></li> 1173<li><a href="#bpmnUserTaskUserAssignmentExtension">Activiti extensions for task assignment</a></li> 1174<li><a href="#bpmnUserTaskUserCustomIdentityLinkAssignmentExtension">Custom identity link types (Experimental)</a></li> 1175<li><a href="#bpmnUserTaskUserCustomAssignmentTaskListeners">Custom Assignment via task listeners</a></li> 1176</ul> 1177</li> 1178<li><a href="#bpmnScriptTask">8.5.2. Script Task</a> 1179<ul class="sectlevel4"> 1180<li><a href="#bpmnScriptTaskDescription">Description</a></li> 1181<li><a href="#bpmnScriptTaskGraphicalNotation">Graphical Notation</a></li> 1182<li><a href="#bpmnScriptTaskXml">XML representation</a></li> 1183<li><a href="#bpmnScriptTaskVariables">Variables in scripts</a></li> 1184<li><a href="#bpmnScriptTaskResultValue">Script results</a></li> 1185<li><a href="#_security">Security</a></li> 1186</ul> 1187</li> 1188<li><a href="#bpmnJavaServiceTask">8.5.3. Java Service Task</a> 1189<ul class="sectlevel4"> 1190<li><a href="#bpmnJavaServiceTaskDescription">Description</a></li> 1191<li><a href="#bpmnJavaServiceTaskGraphicalNotation">Graphical Notation</a></li> 1192<li><a href="#bpmnJavaServiceTaskXML">XML representation</a></li> 1193<li><a href="#bpmnJavaServiceTaskImplementation">Implementation</a></li> 1194<li><a href="#serviceTaskFieldInjection">Field Injection</a></li> 1195<li><a href="#serviceTaskFieldInjectionThreadSafety">Field injection and thread safety</a></li> 1196<li><a href="#serviceTaskResultValue">Service task results</a></li> 1197<li><a href="#serviceTaskExceptionHandling">Handling exceptions</a> 1198<ul class="sectlevel5"> 1199<li><a href="#serviceTaskBpmnErrors">Throwing BPMN Errors</a></li> 1200<li><a href="#exceptionMapping">Exception mapping</a></li> 1201<li><a href="#serviceTaskExceptionSequenceFlow">Exception Sequence Flow</a></li> 1202</ul> 1203</li> 1204<li><a href="#serviceTaskCallActivitiService">Using an Activiti service from within a JavaDelegate</a></li> 1205</ul> 1206</li> 1207<li><a href="#bpmnWebserviceTask">8.5.4. Web Service Task</a> 1208<ul class="sectlevel4"> 1209<li><a href="#_description_6">Description</a></li> 1210<li><a href="#bpmnWebserviceTaskGraphicalNotation">Graphical Notation</a></li> 1211<li><a href="#bpmnWebserviceTaskXML">XML representation</a></li> 1212<li><a href="#bpmnWebserviceTaskIOSpecification">Web Service Task IO Specification</a></li> 1213<li><a href="#bpmnWebserviceTaskDataInputAssociation">Web Service Task data input associations</a></li> 1214<li><a href="#bpmnWebserviceTaskDataOutputAssociation">Web Service Task data output associations</a></li> 1215</ul> 1216</li> 1217<li><a href="#bpmnBusinessRuleTask">8.5.5. Business Rule Task</a> 1218<ul class="sectlevel4"> 1219<li><a href="#_description_7">Description</a></li> 1220<li><a href="#bpmnBusinessRuleTaskGraphicalNotation">Graphical Notation</a></li> 1221<li><a href="#bpmnBusinessRuleTaskXML">XML representation</a></li> 1222</ul> 1223</li> 1224<li><a href="#bpmnEmailTask">8.5.6. Email Task</a> 1225<ul class="sectlevel4"> 1226<li><a href="#bpmnEmailTaskServerConfiguration">Mail server configuration</a></li> 1227<li><a href="#bpmnEmailTaskUsage">Defining an Email Task</a></li> 1228<li><a href="#bpmnEmailTaskExampleUsage">Example usage</a></li> 1229</ul> 1230</li> 1231<li><a href="#bpmnMuleTask">8.5.7. Mule Task</a> 1232<ul class="sectlevel4"> 1233<li><a href="#bpmnMuleTaskUsage">Defining an Mule Task</a></li> 1234<li><a href="#bpmnMuleTaskExampleUsage">Example usage</a></li> 1235</ul> 1236</li> 1237<li><a href="#bpmnCamelTask">8.5.8. Camel Task</a> 1238<ul class="sectlevel4"> 1239<li><a href="#bpmnCamelTaskUsage">Defining a Camel Task</a></li> 1240<li>
1240<a href="#bpmnCamelTaskSimpleCamelCall">Simple Camel Call example</a></li> 1241<li><a href="#bpmnCamelTaskPingPong">Ping Pong example</a></li> 1242<li><a href="#_returning_back_the_variables">Returning back the variables</a></li> 1243<li><a href="#bpmnCamelTaskAsyncPingPong">Asynchronous Ping Pong example</a></li> 1244<li><a href="#bpmnCamelTaskAsyncPingPong">Instantiate workflow from Camel route</a></li> 1245</ul> 1246</li> 1247<li><a href="#bpmnManualTask">8.5.9. Manual Task</a> 1248<ul class="sectlevel4"> 1249<li><a href="#bpmnManualTaskDescription">Description</a></li> 1250<li><a href="#bpmnManualTaskGraphicalNotation">Graphical Notation</a></li> 1251<li><a href="#bpmnManualTaskXml">XML representation</a></li> 1252</ul> 1253</li> 1254<li><a href="#bpmnReceiveTask">8.5.10. Java Receive Task</a> 1255<ul class="sectlevel4"> 1256<li><a href="#bpmnReceiveTaskDescription">Description</a></li> 1257<li><a href="#_graphical_notation_2">Graphical notation</a></li> 1258<li><a href="#_xml_representation_2">XML representation</a></li> 1259</ul> 1260</li> 1261<li><a href="#bpmnShellTask">8.5.11. Shell Task</a> 1262<ul class="sectlevel4"> 1263<li><a href="#bpmnShellTaskDescription">Description</a></li> 1264<li><a href="#bpmnShellTaskUsage">Defining a shell task</a></li> 1265<li><a href="#bpmnShellTaskExampleUsage">Example usage</a></li> 1266</ul> 1267</li> 1268<li><a href="#executionListeners">8.5.12. Execution listener</a> 1269<ul class="sectlevel4"> 1270<li><a href="#executionListenerFieldInjection">Field injection on execution listeners</a></li> 1271</ul> 1272</li> 1273<li><a href="#taskListeners">8.5.13. Task listener</a></li> 1274<li><a href="#bpmnMultiInstance">8.5.14. Multi-instance (for each)</a> 1275<ul class="sectlevel4"> 1276<li><a href="#bpmnMultiInstanceDescription">Description</a></li> 1277<li><a href="#bpmnMultiInstanceGraphicalNotation">Graphical notation</a></li> 1278<li><a href="#bpmnMultiInstanceXml">Xml representation</a></li> 1279<li><a href="#bpmnMultiInstanceBoundaryEvent">Boundary events and multi-instance</a></li> 1280<li><a href="#bpmnCompensationHandlers">Multi instance and execution listeners</a></li> 1281</ul> 1282</li> 1283<li><a href="#_compensation_handlers">8.5.15. Compensation Handlers</a> 1284<ul class="sectlevel4"> 1285<li><a href="#bpmnCompensationHandlerDescription">Description</a></li> 1286<li><a href="#bpmnCompensationHandlerGraphicalNotation">Graphical notation</a></li> 1287<li><a href="#bpmnCompensationHandlerXml">XML representation</a></li> 1288</ul> 1289</li> 1290</ul> 1291</li> 1292<li><a href="#bpmnSubprocessAndCallActivity">8.6. Sub-Processes and Call Activities</a> 1293<ul class="sectlevel3"> 1294<li><a href="#bpmnSubProcess">8.6.1. Sub-Process</a> 1295<ul class="sectlevel4"> 1296<li><a href="#bpmnSubProcessDescription">Description</a></li> 1297<li><a href="#bpmnSubProcessGraphicalNotation">Graphical Notation</a></li> 1298<li><a href="#bpmnSubProcessXML">XML representation</a></li> 1299</ul> 1300</li> 1301<li><a href="#bpmnEventSubprocess">8.6.2. Event Sub-Process</a> 1302<ul class="sectlevel4"> 1303<li><a href="#bpmnEventSubprocessDescription">Description</a></li> 1304<li><a href="#bpmnEventSubprocessGraphicalNotation">Graphical Notation</a></li> 1305<li><a href="#bpmnEventSubprocessXMLRepresentation">XML representation</a></li> 1306<li><a href="#bpmnEventSubprocessExample">Example</a></li> 1307</ul> 1308</li> 1309<li><a href="#bpmnTransactionSubprocess">8.6.3. Transaction subprocess</a> 1310<ul class="sectlevel4"> 1311<li><a href="#_description_8">Description</a></li> 1312<li><a href="#bpmnEventSubprocessGraphicalNotation">Graphical Notation</a></li> 1313<li><a href="#bpmnEventSubprocessXMLRepresentation">XML representation</a></li> 1314<li><a href="#bpmnEventSubprocessExample">Example</a></li> 1315</ul> 1316</li> 1317<li><a href="#bpmnCallActivity">8.6.4. Call activity (subprocess)</a> 1318<ul class="sectlevel4"> 1319<li><a href="#bpmnCallActivityDescription">Description</a></li> 1320<li><a href="#bpmnCallActivityGraphicalNotation">Graphical Notation</a></li> 1321<li><a href="#bpmnCallActivityXMLRepresentation">XML representation</a></li> 1322<li><a href="#bpmnCallActivityPassVariables">Passing variables</a></li> 1323<li><a href="#bpmnCallActivityExample">Example</a></li> 1324</ul> 1325</li> 1326</ul> 1327</li> 1328<li><a href="#bpmnConcurrencyAndTransactions">8.7. Transactions and Concurrency</a> 1329<ul class="sectlevel3"> 1330<li><a href="#asyncContinuations">8.7.1. Asynchronous Continuations</a></li> 1331<li><a href="#failRetry">8.7.2. Fail Retry</a></li> 1332<li><a href="#exclusiveJobs">8.7.3. Exclusive Jobs</a> 1333<ul class="sectlevel4"> 1334<li><a href="#_why_exclusive_jobs">Why exclusive Jobs?</a></li> 1335<li><a href="#_what_are_exclusive_jobs">What are exclusive jobs?</a></li> 1336</ul> 1337</li> 1338</ul> 1339</li> 1340<li><a href="#security">8.8. Process Initiation Authorization</a></li> 1341<li><a href="#dataobjects">8.9. Data objects</a></li> 1342</ul> 1343</li> 1344<li><a href="#forms">9. Forms</a> 1345<ul class="sectlevel2"> 1346<li><a href="#formProperties">9.1. Form properties</a></li> 1347<li><a href="#externalFormRendering">9.2. External form rendering</a></li> 1348</ul> 1349</li> 1350<li><a href="#_jpa">10. JPA</a> 1351<ul class="sectlevel2"> 1352<li><a href="#_requirements">10.1. Requirements</a></li> 1353<li><a href="#jpaconfiguration">10.2. Configuration</a></li> 1354<li><a href="#_usage">10.3. Usage</a> 1355<ul class="sectlevel3"> 1356<li><a href="#_simple_example">
135610.3.1. Simple Example</a></li> 1357<li><a href="#_query_jpa_process_variables">10.3.2. Query JPA process variables</a></li> 1358<li><a href="#_advanced_example_using_spring_beans_and_jpa">10.3.3. Advanced example using Spring beans and JPA</a></li> 1359</ul> 1360</li> 1361</ul> 1362</li> 1363<li><a href="#history">11. History</a> 1364<ul class="sectlevel2"> 1365<li><a href="#historyQuery">11.1. Querying history</a> 1366<ul class="sectlevel3"> 1367<li><a href="#historyQueryProcessInstance">11.1.1. HistoricProcessInstanceQuery</a></li> 1368<li><a href="#historyQueryVariableInstance">11.1.2. HistoricVariableInstanceQuery</a></li> 1369<li><a href="#historyQueryActivityInstance">11.1.3. HistoricActivityInstanceQuery</a></li> 1370<li><a href="#historyQueryDetail">11.1.4. HistoricDetailQuery</a></li> 1371<li><a href="#historyQueryTaskInstance">11.1.5. HistoricTaskInstanceQuery</a></li> 1372</ul> 1373</li> 1374<li><a href="#historyConfig">11.2. History configuration</a></li> 1375<li><a href="#historyFormAuditPurposes">11.3. History for audit purposes</a></li> 1376</ul> 1377</li> 1378<li><a href="#activitiDesigner">12. Eclipse Designer</a> 1379<ul class="sectlevel2"> 1380<li><a href="#eclipseDesignerInstallation">12.1. Installation</a></li> 1381<li><a href="#eclipseDesignerEditorFeatures">12.2. Activiti Designer editor features</a></li> 1382<li><a href="#eclipseDesignerBPMNFeatures">12.3. Activiti Designer BPMN features</a></li> 1383<li><a href="#eclipseDesignerDeployment">12.4. Activiti Designer deployment features</a></li> 1384<li><a href="#eclipseDesignerExtending">12.5. Extending Activiti Designer</a> 1385<ul class="sectlevel3"> 1386<li><a href="#eclipseDesignerCustomizingPalette">12.5.1. Customizing the palette</a> 1387<ul class="sectlevel4"> 1388<li><a href="#_extension_setup_eclipse_maven">Extension setup (Eclipse/Maven)</a></li> 1389<li><a href="#eclipseDesignerApplyingExtension">Applying your extension to Activiti Designer</a></li> 1390<li><a href="#_adding_shapes_to_the_palette">Adding shapes to the palette</a> 1391<ul class="sectlevel5"> 1392<li><a href="#eclipseDesignerConfiguringRuntime">Configuring runtime execution of Custom Service Tasks</a></li> 1393</ul> 1394</li> 1395<li><a href="#eclipseDesignerPropertyTypes">Property types</a> 1396<ul class="sectlevel5"> 1397<li><a href="#_propertytype_text">PropertyType.TEXT</a></li> 1398<li><a href="#_propertytype_multiline_text">PropertyType.MULTILINE_TEXT</a></li> 1399<li><a href="#_propertytype_period">PropertyType.PERIOD</a></li> 1400<li><a href="#_propertytype_boolean_choice">PropertyType.BOOLEAN_CHOICE</a></li> 1401<li><a href="#_propertytype_radio_choice">PropertyType.RADIO_CHOICE</a></li> 1402<li><a href="#_propertytype_combobox_choice">PropertyType.COMBOBOX_CHOICE</a></li> 1403<li><a href="#_propertytype_date_picker">PropertyType.DATE_PICKER</a></li> 1404<li><a href="#_propertytype_data_grid">PropertyType.DATA_GRID</a></li> 1405</ul> 1406</li> 1407<li><a href="#_disabling_default_shapes_in_the_palette">Disabling default shapes in the palette</a></li> 1408</ul> 1409</li> 1410<li><a href="#_validating_diagrams_and_exporting_to_custom_output_formats">12.5.2. Validating diagrams and exporting to custom output formats</a> 1411<ul class="sectlevel4"> 1412<li><a href="#_creating_a_processvalidator_extension">Creating a ProcessValidator extension</a></li> 1413<li><a href="#_creating_an_exportmarshaller_extension">Creating an ExportMarshaller extension</a></li> 1414</ul> 1415</li> 1416</ul> 1417</li> 1418</ul> 1419</li> 1420<li><a href="#_rest_api">13. REST API</a> 1421<ul class="sectlevel2"> 1422<li><a href="#_general_activiti_rest_principles">13.1. General Activiti REST principles</a> 1423<ul class="sectlevel3"> 1424<li><a href="#_installation_and_authentication">13.1.1. Installation and Authentication</a></li> 1425<li><a href="#_configuration_2">13.1.2. Configuration</a></li> 1426<li><a href="#restUsageInTomcat">13.1.3. Usage in Tomcat</a></li> 1427<li><a href="#_methods_and_return_codes">13.1.4. Methods and return-codes</a></li> 1428<li><a href="#_error_response_body">13.1.5. Error response body</a></li> 1429<li><a href="#_request_parameters">13.1.6. Request parameters</a> 1430<ul class="sectlevel4"> 1431<li><a href="#_url_fragments">URL fragments</a></li> 1432<li><a href="#_rest_url_query_parameters">Rest URL query parameters</a></li> 1433<li><a href="#restJsonBody">JSON body parameters</a></li> 1434<li><a href="#restPagingAndSort">Paging and sorting</a></li> 1435<li><a href="#restQueryVariable">JSON query variable format</a></li> 1436<li><a href="#restVariables">Variable representation</a></li> 1437</ul> 1438</li> 1439</ul> 1440</li> 1441<li><a href="#_deployment">13.2. Deployment</a> 1442<ul class="sectlevel3"> 1443<li><a href="#_list_of_deployments">13.2.1. List of Deployments</a></li> 1444<li><a href="#_get_a_deployment">13.2.2. Get a deployment</a></li> 1445<li><a href="#_create_a_new_deployment">13.2.3. Create a new deployment</a></li> 1446<li><a href="#_delete_a_deployment">13.2.4. Delete a deployment</a></li> 1447<li><a href="#_list_resources_in_a_deployment">13.2.5. List resources in a deployment</a></li> 1448<li><a href="#_get_a_deployment_resource">13.2.6. Get a deployment resource</a></li> 1449<li><a href="#_get_a_deployment_resource_content">13.2.7. Get a deployment resource content</a></li> 1450</ul> 1451</li> 1452<li><a href="#_process_definitions">13.3. Process Definitions</a> 1453<ul class="sectlevel3"> 1454<li><a href="#_list_of_process_definitions">13.3.1. List of process definitions</a></li> 1455<li><a href="#_get_a_process_definition">13.3.2. Get a process definition</a></li> 1456<li><a href="#_update_category_for_a_process_definition">13.3.3. Update category for a process definition</a></li> 1457<li><a href="#_get_a_process_definition_resource_content">13.3.4. Get a process definition resource content</a></li> 1458<li><a href="#_get_a_process_definition_bpmn_model">13.3.5. Get a process definition BPMN model</a></li> 1459<li><a href="#_suspend_a_process_definition">13.3.6. Suspend a process definition</a></li> 1460<li><a href="#_activate_a_process_definition">13.3.7. Activate a process definition</a></li> 1461<li><a href="#_get_all_candidate_starters_for_a_process_definition">13.3.8. Get all candidate starters for a process-definition</a></li> 1462<li><a href="#_add_a_candidate_starter_to_a_process_definition">13.3.9. Add a candidate starter to a process definition</a></li> 1463<li><a href="#_delete_a_candidate_starter_from_a_process_definition">13.3.10. Delete a candidate starter from a process definition</a></li> 1464<li><a href="#_get_a_candidate_starter_from_a_process_definition">13.3.11. Get a candidate starter from a process definition</a></li> 1465</ul> 1466</li> 1467<li><a href="#_models">13.4. Models</a> 1468<ul class="sectlevel3"> 1469<li><a href="#_get_a_list_of_models">13.4.1. Get a list of models</a></li> 1470<li><a href="#_get_a_model">13.4.2. Get a model</a></li> 1471<li><a href="#_update_a_model">13.4.3. Update a model</a></li> 1472<li><a href="#_create_a_model">13.4.4. Create a model</a></li> 1473<li><a href="#_delete_a_model">13.4.5. Delete a model</a></li> 1474<li><a href="#_get_the_editor_source_for_a_model">13.4.6. Get the editor source for a model</a></li> 1475<li><a href="#_set_the_editor_source_for_a_model">13.4.7. Set the editor source for a model</a></li> 1476<li><a href="#_get_the_extra_editor_source_for_a_model">13.4.8. Get the extra editor source for a model</a></li> 1477<li><a href="#_set_the_extra_editor_source_for_a_model">13.4.9. Set the extra editor source for a model</a></li> 1478</ul> 1479</li> 1480<li><a href="#_process_instances">13.5. Process Instances</a> 1481<ul class="sectlevel3"> 1482<li><a href="#_get_a_process_instance">13.5.1. Get a process instance</a></li> 1483<li><a href="#_delete_a_process_instance">13.5.2. Delete a process instance</a></li> 1484<li><a href="#_activate_or_suspend_a_process_instance">13.5.3. Activate or suspend a process instance</a></li> 1485<li><a href="#_start_a_process_instance">13.5.4. Start a process instance</a></li> 1486<li><a href="#restProcessInstancesGet">13.5.5. List of process instances</a></li> 1487<li><a href="#_query_process_instances">13.5.6. Query process instances</a></li> 1488<li><a href="#_get_diagram_for_a_process_instance">13.5.7. Get diagram for a process instance</a></li> 1489<li><a href="#_get_involved_people_for_process_instance">13.5.8. Get involved people for process instance</a></li> 1490<li><a href="#_add_an_involved_user_to_a_process_instance">13.5.9. Add an involved user to a process instance</a></li> 1491<li><a href="#_remove_an_involved_user_to_from_process_instance">13.5.10. Remove an involved user to from process instance</a></li> 1492<li><a href="#_list_of_variables_for_a_process_instance">13.5.11. List of variables for a process instance</a></li> 1493<li><a href="#_get_a_variable_for_a_process_instance">13.5.12. Get a variable for a process instance</a></li> 1494<li><a href="#_create_or_update_variables_on_a_process_instance">13.5.13. Create (or update) variables on a process instance</a></li> 1495<li><a href="#_update_a_single_variable_on_a_process_instance">13.5.14. Update a single variable on a process instance</a></li> 1496<li><a href="#_create_a_new_binary_variable_on_a_process_instance">13.5.15. Create a new binary variable on a process-instance</a></li> 1497<li><a href="#_update_an_existing_binary_variable_on_a_process_instance">13.5.16. Update an existing binary variable on a process-instance</a></li> 1498</ul> 1499</li> 1500<li><a href="#_executions">13.6. Executions</a> 1501<ul class="sectlevel3"> 1502<li><a href="#_get_an_execution">13.6.1. Get an execution</a></li> 1503<li><a href="#_execute_an_action_on_an_execution">13.6.2. Execute an action on an execution</a></li> 1504<li><a href="#_get_active_activities_in_an_execution">13.6.3. Get active activities in an execution</a></li> 1505<li><a href="#restExecutionsGet">13.6.4. List of executions</a></li> 1506<li><a href="#_query_executions">13.6.5. Query executions</a></li> 1507<li><a href="#_list_of_variables_for_an_execution">13.6.6. List of variables for an execution</a></li> 1508<li><a href="#_get_a_variable_for_an_execution">13.6.7. Get a variable for an execution</a></li> 1509<li><a href="#_create_or_update_variables_on_an_execution">13.6.8. Create (or update) variables on an execution</a></li> 1510<li><a href="#_update_a_variable_on_an_execution">13.6.9. Update a variable on an execution</a></li> 1511<li><a href="#_create_a_new_binary_variable_on_an_execution">13.6.10. Create a new binary variable on an execution</a></li> 1512<li><a href="#_update_an_existing_binary_variable_on_a_process_instance_2">13.6.11. Update an existing binary variable on a process-instance</a></li> 1513</ul> 1514</li> 1515<li><a href="#_tasks">13.7. Tasks</a> 1516<ul class="sectlevel3"> 1517<li><a href="#_get_a_task">13.7.1. Get a task</a></li> 1518<li><a href="#restTasksGet">13.7.2. List of tasks</a></li> 1519<li><a href="#_query_for_tasks">13.7.3. Query for tasks</a></li> 1520<li><a href="#_update_a_task">13.7.4. Update a task</a></li> 1521<li><a href="#_task_actions">13.7.5. Task actions</a></li> 1522<li><a href="#_delete_a_task">
152213.7.6. Delete a task</a></li> 1523<li><a href="#_get_all_variables_for_a_task">13.7.7. Get all variables for a task</a></li> 1524<li><a href="#_get_a_variable_from_a_task">13.7.8. Get a variable from a task</a></li> 1525<li><a href="#_get_the_binary_data_for_a_variable">13.7.9. Get the binary data for a variable</a></li> 1526<li><a href="#_create_new_variables_on_a_task">13.7.10. Create new variables on a task</a></li> 1527<li><a href="#_create_a_new_binary_variable_on_a_task">13.7.11. Create a new binary variable on a task</a></li> 1528<li><a href="#_update_an_existing_variable_on_a_task">13.7.12. Update an existing variable on a task</a></li> 1529<li><a href="#_updating_a_binary_variable_on_a_task">13.7.13. Updating a binary variable on a task</a></li> 1530<li><a href="#_delete_a_variable_on_a_task">13.7.14. Delete a variable on a task</a></li> 1531<li><a href="#_delete_all_local_variables_on_a_task">13.7.15. Delete all local variables on a task</a></li> 1532<li><a href="#_get_all_identity_links_for_a_task">13.7.16. Get all identity links for a task</a></li> 1533<li><a href="#_get_all_identitylinks_for_a_task_for_either_groups_or_users">13.7.17. Get all identitylinks for a task for either groups or users</a></li> 1534<li><a href="#_get_a_single_identity_link_on_a_task">13.7.18. Get a single identity link on a task</a></li> 1535<li><a href="#_create_an_identity_link_on_a_task">13.7.19. Create an identity link on a task</a></li> 1536<li><a href="#_delete_an_identity_link_on_a_task">13.7.20. Delete an identity link on a task</a></li> 1537<li><a href="#_create_a_new_comment_on_a_task">13.7.21. Create a new comment on a task</a></li> 1538<li><a href="#_get_all_comments_on_a_task">13.7.22. Get all comments on a task</a></li> 1539<li><a href="#_get_a_comment_on_a_task">13.7.23. Get a comment on a task</a></li> 1540<li><a href="#_delete_a_comment_on_a_task">13.7.24. Delete a comment on a task</a></li> 1541<li><a href="#_get_all_events_for_a_task">13.7.25. Get all events for a task</a></li> 1542<li><a href="#_get_an_event_on_a_task">13.7.26. Get an event on a task</a></li> 1543<li><a href="#_create_a_new_attachment_on_a_task_containing_a_link_to_an_external_resource">13.7.27. Create a new attachment on a task, containing a link to an external resource</a></li> 1544<li><a href="#_create_a_new_attachment_on_a_task_with_an_attached_file">13.7.28. Create a new attachment on a task, with an attached file</a></li> 1545<li><a href="#_get_all_attachments_on_a_task">13.7.29. Get all attachments on a task</a></li> 1546<li><a href="#_get_an_attachment_on_a_task">13.7.30. Get an attachment on a task</a></li> 1547<li><a href="#_get_the_content_for_an_attachment">13.7.31. Get the content for an attachment</a></li> 1548<li><a href="#_delete_an_attachment_on_a_task">13.7.32. Delete an attachment on a task</a></li> 1549</ul> 1550</li> 1551<li><a href="#_history">13.8. History</a> 1552<ul class="sectlevel3"> 1553<li><a href="#_get_a_historic_process_instance">13.8.1. Get a historic process instance</a></li> 1554<li><a href="#restHistoricProcessInstancesGet">13.8.2. List of historic process instances</a></li> 1555<li><a href="#_query_for_historic_process_instances">13.8.3. Query for historic process instances</a></li> 1556<li><a href="#_delete_a_historic_process_instance">13.8.4. Delete a historic process instance</a></li> 1557<li><a href="#_get_the_identity_links_of_a_historic_process_instance">13.8.5. Get the identity links of a historic process instance</a></li> 1558<li><a href="#_get_the_binary_data_for_a_historic_process_instance_variable">13.8.6. Get the binary data for a historic process instance variable</a></li> 1559<li><a href="#_create_a_new_comment_on_a_historic_process_instance">13.8.7. Create a new comment on a historic process instance</a></li> 1560<li><a href="#_get_all_comments_on_a_historic_process_instance">13.8.8. Get all comments on a historic process instance</a></li> 1561<li><a href="#_get_a_comment_on_a_historic_process_instance">13.8.9. Get a comment on a historic process instance</a></li> 1562<li><a href="#_delete_a_comment_on_a_historic_process_instance">13.8.10. Delete a comment on a historic process instance</a></li> 1563<li><a href="#_get_a_single_historic_task_instance">13.8.11. Get a single historic task instance</a></li> 1564<li><a href="#restHistoricTaskInstancesGet">13.8.12. Get historic task instances</a></li> 1565<li><a href="#_query_for_historic_task_instances">13.8.13. Query for historic task instances</a></li> 1566<li><a href="#_delete_a_historic_task_instance">13.8.14. Delete a historic task instance</a></li> 1567<li><a href="#_get_the_identity_links_of_a_historic_task_instance">13.8.15. Get the identity links of a historic task instance</a></li> 1568<li><a href="#_get_the_binary_data_for_a_historic_task_instance_variable">13.8.16. Get the binary data for a historic task instance variable</a></li> 1569<li><a href="#restHistoricActivityInstancesGet">13.8.17. Get historic activity instances</a></li> 1570<li><a href="#_query_for_historic_activity_instances">13.8.18. Query for historic activity instances</a></li> 1571<li><a href="#restHistoricVariableInstancesGet">13.8.19. List of historic variable instances</a></li> 1572<li><a href="#_query_for_historic_variable_instances">13.8.20. Query for historic variable instances</a></li> 1573<li><a href="#restHistoricDetailGet">13.8.21. Get historic detail</a></li> 1574<li><a href="#_query_for_historic_details">13.8.22. Query for historic details</a></li> 1575<li><a href="#_get_the_binary_data_for_a_historic_detail_variable">13.8.23. Get the binary data for a historic detail variable</a></li> 1576</ul> 1577</li> 1578<li><a href="#_forms">13.9. Forms</a> 1579<ul class="sectlevel3"> 1580<li><a href="#_get_form_data">13.9.1. Get form data</a></li> 1581<li><a href="#_submit_task_form_data">13.9.2. Submit task form data</a></li> 1582</ul> 1583</li> 1584<li><a href="#_database_tables">13.10. Database tables</a> 1585<ul class="sectlevel3"> 1586<li><a href="#_list_of_tables">13.10.1. List of tables</a></li> 1587<li><a href="#_get_a_single_table">13.10.2. Get a single table</a></li> 1588<li><a href="#_get_column_info_for_a_single_table">13.10.3. Get column info for a single table</a></li> 1589<li><a href="#_get_row_data_for_a_single_table">13.10.4. Get row data for a single table</a></li> 1590</ul> 1591</li> 1592<li><a href="#_engine">13.11. Engine</a> 1593<ul class="sectlevel3"> 1594<li><a href="#_get_engine_properties">13.11.1. Get engine properties</a></li> 1595<li><a href="#_get_engine_info">13.11.2. Get engine info</a></li> 1596</ul> 1597</li> 1598<li><a href="#_runtime">
159813.12. Runtime</a> 1599<ul class="sectlevel3"> 1600<li><a href="#_signal_event_received">13.12.1. Signal event received</a></li> 1601</ul> 1602</li> 1603<li><a href="#_jobs">13.13. Jobs</a> 1604<ul class="sectlevel3"> 1605<li><a href="#_get_a_single_job">13.13.1. Get a single job</a></li> 1606<li><a href="#_delete_a_job">13.13.2. Delete a job</a></li> 1607<li><a href="#_execute_a_single_job">13.13.3. Execute a single job</a></li> 1608<li><a href="#_get_the_exception_stacktrace_for_a_job">13.13.4. Get the exception stacktrace for a job</a></li> 1609<li><a href="#_get_a_list_of_jobs">13.13.5. Get a list of jobs</a></li> 1610</ul> 1611</li> 1612<li><a href="#_users">13.14. Users</a> 1613<ul class="sectlevel3"> 1614<li><a href="#_get_a_single_user">13.14.1. Get a single user</a></li> 1615<li><a href="#_get_a_list_of_users">13.14.2. Get a list of users</a></li> 1616<li><a href="#_update_a_user">13.14.3. Update a user</a></li> 1617<li><a href="#_create_a_user">13.14.4. Create a user</a></li> 1618<li><a href="#_delete_a_user">13.14.5. Delete a user</a></li> 1619<li><a href="#_get_a_user_s_picture">13.14.6. Get a user’s picture</a></li> 1620<li><a href="#_updating_a_user_s_picture">13.14.7. Updating a user’s picture</a></li> 1621<li><a href="#_list_a_user_s_info">13.14.8. List a user’s info</a></li> 1622<li><a href="#_get_a_user_s_info">13.14.9. Get a user’s info</a></li> 1623<li><a href="#_update_a_user_s_info">13.14.10. Update a user’s info</a></li> 1624<li><a href="#_create_a_new_user_s_info_entry">13.14.11. Create a new user’s info entry</a></li> 1625<li><a href="#_delete_a_user_s_info">13.14.12. Delete a user’s info</a></li> 1626</ul> 1627</li> 1628<li><a href="#_groups">13.15. Groups</a> 1629<ul class="sectlevel3"> 1630<li><a href="#_get_a_single_group">13.15.1. Get a single group</a></li> 1631<li><a href="#_get_a_list_of_groups">13.15.2. Get a list of groups</a></li> 1632<li><a href="#_update_a_group">13.15.3. Update a group</a></li> 1633<li><a href="#_create_a_group">13.15.4. Create a group</a></li> 1634<li><a href="#_delete_a_group">13.15.5. Delete a group</a></li> 1635<li><a href="#_get_members_in_a_group">13.15.6. Get members in a group</a></li> 1636<li><a href="#_add_a_member_to_a_group">13.15.7. Add a member to a group</a></li> 1637<li><a href="#_delete_a_member_from_a_group">13.15.8. Delete a member from a group</a></li> 1638</ul> 1639</li> 1640</ul> 1641</li> 1642<li><a href="#cdiintegration">14. CDI integration</a> 1643<ul class="sectlevel2"> 1644<li><a href="#_setting_up_activiti_cdi">14.1. Setting up activiti-cdi</a> 1645<ul class="sectlevel3"> 1646<li><a href="#_looking_up_a_process_engine">14.1.1. Looking up a Process Engine</a></li> 1647<li><a href="#_configuring_the_process_engine">14.1.2. Configuring the Process Engine</a></li> 1648<li><a href="#_deploying_processes">14.1.3. Deploying Processes</a></li> 1649<li><a href="#_associating_a_conversation_with_a_process_instance">14.1.4. Associating a Conversation with a Process Instance</a></li> 1650<li><a href="#_declaratively_controlling_the_process">14.1.5. Declaratively controlling the Process</a></li> 1651<li><a href="#_referencing_beans_from_the_process">14.1.6. Referencing Beans from the Process</a></li> 1652<li><a href="#_working_with_businessprocessscoped_beans">14.1.7. Working with @BusinessProcessScoped beans</a></li> 1653<li><a href="#_injecting_process_variables">14.1.8. Injecting Process Variables</a></li> 1654<li><a href="#_receiving_process_events">14.1.9. Receiving Process Events</a></li> 1655<li><a href="#_additional_features">14.1.10. Additional Features</a></li> 1656</ul> 1657</li> 1658<li><a href="#_known_limitations">14.2. Known Limitations</a></li> 1659</ul> 1660</li> 1661<li><a href="#chapter_ldap">15. LDAP integration</a> 1662<ul class="sectlevel2"> 1663<li><a href="#ldap_usage">15.1. Usage</a></li> 1664<li><a href="#ldap_usecases">15.2. Use cases</a></li> 1665<li><a href="#ldap_configuration">15.3. Configuration</a></li> 1666<li><a href="#ldap_properties">15.4. Properties</a></li> 1667</ul> 1668</li> 1669<li><a href="#_advanced">16. Advanced</a> 1670<ul class="sectlevel2"> 1671<li><a href="#_async_executor">16.1. Async Executor</a> 1672<ul class="sectlevel3"> 1673<li><a href="#async_executor_design">16.1.1. Async Executor design</a></li> 1674<li><a href="#_async_executor_configuration">16.1.2. Async executor configuration</a></li> 1675<li><a href="#_message_queue_based_async_executor">16.1.3. Message Queue based Async Executor</a></li> 1676</ul> 1677</li> 1678<li><a href="#advanced_parseHandlers">16.2. Hooking into process parsing</a></li> 1679<li><a href="#advanced.uuid.generator">16.3. UUID id generator for high concurrency</a></li> 1680<li><a href="#advanced.tenancy">16.4. Multitenancy</a></li> 1681<li><a href="#advanced.custom.sql.queries">16.5. Execute custom SQL</a> 1682<ul class="sectlevel3"> 1683<li><a href="#_annotation_based_mapped_statements">16.5.1. Annotation based Mapped Statements</a></li> 1684<li><a href="#_xml_based_mapped_statements">16.5.2. XML based Mapped Statements</a></li> 1685</ul> 1686</li> 1687<li><a href="#advanced.process.engine.configurators">16.6. Advanced Process Engine configuration with a ProcessEngineConfigurator
1687</a></li> 1688<li><a href="#advanced.task.query.switching">16.7. Advanced query API: seamless switching between runtime and historic task querying</a></li> 1689<li><a href="#advanced.custom.session.manager">16.8. Custom identity management by overriding standard SessionFactory</a></li> 1690<li><a href="#advanced.safe.bpmn.xml">16.9. Enable safe BPMN 2.0 xml</a></li> 1691<li><a href="#advanced.event.logging">16.10. Event logging (Experimental)</a></li> 1692<li><a href="#_disabling_bulk_inserts">16.11. Disabling bulk inserts</a></li> 1693<li><a href="#advancedSecureScripting">16.12. Secure Scripting</a></li> 1694</ul> 1695</li> 1696<li><a href="#Tooling">17. Tooling</a> 1697<ul class="sectlevel2"> 1698<li><a href="#JMX">17.1. JMX</a> 1699<ul class="sectlevel3"> 1700<li><a href="#jmxIntroduction">17.1.1. Introduction</a></li> 1701<li><a href="#jmxQuickStart">17.1.2. Quick Start</a></li> 1702<li><a href="#_attributes_and_operations">17.1.3. Attributes and operations</a></li> 1703<li><a href="#_configuration_3">17.1.4. Configuration</a></li> 1704<li><a href="#_jmx_service_url">17.1.5. JMX Service URL</a></li> 1705</ul> 1706</li> 1707<li><a href="#mavenArchetypes">17.2. Maven archetypes</a> 1708<ul class="sectlevel3"> 1709<li><a href="#_create_test_case">17.2.1. Create Test Case</a></li> 1710</ul> 1711</li> 1712</ul> 1713</li> 1714</ul> 1715</div> 1716</div> 1717<div id="content"> 1718<div class="sect1"> 1719<h2 id="_introduction">1. Introduction</h2> 1720<div class="sectionbody"> 1721<div class="sect2"> 1722<h3 id="license">1.1. License</h3> 1723<div class="paragraph"> 1724<p>Activiti is distributed under <a href="http://www.apache.org/licenses/LICENSE-2.0.html">the Apache V2 license</a>.</p> 1725</div> 1726</div> 1727<div class="sect2"> 1728<h3 id="download">1.2. Download</h3> 1729<div class="paragraph"> 1730<p><a href="http://activiti.org/download.html"><a href="http://activiti.org/download.html" class="bare">http://activiti.org/download.html</a></a></p> 1731</div> 1732</div> 1733<div class="sect2"> 1734<h3 id="sources">1.3. Sources</h3> 1735<div class="paragraph"> 1736<p>The distribution contains most of the sources as jar files. The source code of Activiti can be found on 1737 <a href="https://github.com/Activiti/Activiti"><a href="https://github.com/Activiti/Activiti" class="bare">https://github.com/Activiti/Activiti</a></a></p> 1738</div> 1739</div> 1740<div class="sect2"> 1741<h3 id="required.software">1.4. Required software</h3> 1742<div class="sect3"> 1743<h4 id="_jdk_7">1.4.1. JDK 7+</h4> 1744<div class="paragraph"> 1745<p>Activiti runs on a JDK higher than or equal to version 7. Go to <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle Java SE downloads</a> and click on button "Download JDK". There are installation instructions on that page as well. To verify that your installation was successful, run <code>java -version</code> on the command line. That should print the installed version of your JDK.</p> 1746</div> 1747</div> 1748<div class="sect3"> 1749<h4 id="_ide">1.4.2. IDE</h4> 1750<div class="paragraph"> 1751<p>Activiti development can be done with the IDE of your choice. If you would like to use the Activiti Designer then you need Eclipse Kepler or Luna. 1752Download the eclipse distribution of your choice from <a href="http://www.eclipse.org/downloads/">the Eclipse download page</a>. Unzip the downloaded file and then you should be able to start it with the eclipse file in the directory <code>eclipse</code>. 1753Further in this user guide, there is a section on <a href="#eclipseDesignerInstallation">installing our eclipse designer plugin</a>.</p> 1754</div> 1755</div> 1756</div> 1757<div class="sect2"> 1758<h3 id="reporting.problems">1.5. Reporting problems</h3> 1759<div class="paragraph"> 1760<p>Every self-respecting developer should have read <a href="http://www.catb.org/~esr/faqs/smart-questions.html">How to ask questions the smart way</a>.</p> 1761</div> 1762<div class="paragraph"> 1763<p>After you’ve done that you can post questions and comments on <a href="http://forums.activiti.org/en/viewforum.php?f=3">the Users forum</a> and create issues in <a href="https://activiti.atlassian.net">our JIRA issue tracker</a>.</p> 1764</div> 1765<div class="admonitionblock note"> 1766<table> 1767<tr> 1768<td class="icon"> 1769<i class="fa icon-note" title="Note"></i> 1770</td> 1771<td class="content"> 1772<div class="paragraph"> 1773<p>Even though Activiti is hosted on GitHub, issues should not be reported using GitHub’s issue system. If you wish to report an issue, do not create a GitHub issue, but use <a href="https://activiti.atlassian.net">our JIRA</a>.</p> 1774</div> 1775</td> 1776</tr> 1777</table> 1778</div> 1779</div> 1780<div class="sect2"> 1781<h3 id="experimental">1.6. Experimental features</h3> 1782<div class="paragraph"> 1783<p>Sections marked with <strong>[EXPERIMENTAL]</strong> should 1784 not be considered stable.</p> 1785</div> 1786<div class="paragraph"> 1787<p>All classes that have <code>.impl.</code> in the package name are internal implementation classes and cannot be considered stable. However, if the user guide mentions those classes as configuration values, they are supported and can be considered stable.</p> 1788</div> 1789</div> 1790<div class="sect2"> 1791<h3 id="internal">1.7. Internal implementation classes</h3> 1792<div class="paragraph"> 1793<p>In the jar file, all classes in packages that have <code>.impl.</code> (e.g. <code>org.activiti.engine.impl.db</code>) in them are implementation classes and should be considered internal. No stability guarantees are given on classes or interfaces that are in implementation classes.</p> 1794</div> 1795</div> 1796</div> 1797</div> 1798<div class="sect1"> 1799<h2 id="_getting_started">2. Getting Started</h2> 1800<div class="sectionbody"> 1801<div class="sect2"> 1802<h3 id="demo.setup.one.minute.version">2.1. One minute version</h3> 1803<div class="paragraph"> 1804<p>After downloading the Activiti UI WAR file from the <a href="http://www.activiti.org">Activiti website</a>, follow these steps to get the demo setup running with default settings. You’ll need a working <a href="http://java.sun.com/javase/downloads/index.jsp">Java runtime</a> and <a href="http://tomcat.apache.org/download-80.cgi">Apache Tomcat</a> installation (actually, any web container would work since we only rely on the servlet capability. But we test on Tomcat primarily).</p> 1805</div> 1806<div class="ulist"> 1807<ul> 1808<li> 1809<p>Copy the downloaded activiti-app.war to the webapps directory of Tomcat.</p> 1810</li> 1811<li> 1812<p>Start Tomcat by running the startup.bat or startup.sh scripts in the bin folder of Tomcat</p> 1813</li> 1814<li> 1815<p>When Tomcat is started open your browser and go to <a href="http://localhost:8080/activiti-app"><a href="http://localhost:8080/activiti-app" class="bare">http://localhost:8080/activiti-app</a></a>. 1816Login with admin and password test.</p> 1817</li> 1818</ul> 1819</div> 1820<div class="paragraph"> 1821<p>That’s it! The Activiti UI application uses an in-memory H2 database by default, if you want to use another database configuration please read <a href="#activiti.setup">the longer version</a>.</p> 1822</div> 1823</div> 1824<div class="sect2"> 1825<h3 id="activiti.setup">2.2. Activiti setup</h3> 1826<div class="paragraph"> 1827<p>To install Activiti you’ll need a working <a href="http://java.sun.com/javase/downloads/index.jsp">Java runtime</a> and <a href="http://tomcat.apache.org/download-70.cgi">Apache Tomcat</a> installation. Also make sure that the <em>JAVA_HOME</em> system variable is correctly set. The way to do this depends on your operating system.</p> 1828</div> 1829<div class="paragraph"> 1830<p>To get the Activiti UI and REST web applications running just copy the WARs downloaded from the Activiti download page to the <code>webapps</code> folder in your Tomcat installation directory. By default the UI application runs with an in-memory database.</p> 1831</div> 1832<div class="paragraph"> 1833<p>Demo user:</p> 1834</div> 1835<table class="tableblock frame-all grid-all spread"> 1836<colgroup> 1837<col style="width: 33.3333%;"> 1838<col style="width: 33.3333%;"> 1839<col style="width: 33.3334%;"> 1840</colgroup> 1841<thead> 1842<tr> 1843<th class="tableblock halign-left valign-top">UserId</th> 1844<th class="tableblock halign-left valign-top">Password</th> 1845<th class="tableblock halign-left valign-top">Security roles</th> 1846</tr> 1847</thead> 1848<tbody> 1849<tr> 1850<td class="tableblock halign-left valign-top"><p class="tableblock">admin</p></td> 1851<td class="tableblock halign-left valign-top"><p class="tableblock">test</p></td> 1852<td class="tableblock halign-left valign-top"><p class="tableblock">admin</p></td> 1853</tr> 1854</tbody> 1855</table> 1856<div class="paragraph"> 1857<p>Now you can access following web application:</p> 1858</div> 1859<table class="tableblock frame-all grid-all spread"> 1860<colgroup> 1861<col style="width: 33.3333%;"> 1862<col style="width: 33.3333%;"> 1863<col style="width: 33.3334%;"> 1864</colgroup> 1865<thead> 1866<tr> 1867<th class="tableblock halign-left valign-top">Webapp Name</th> 1868<th class="tableblock halign-left valign-top">URL</th> 1869<th class="tableblock halign-left valign-top">Description</th> 1870</tr> 1871</thead> 1872<tbody> 1873<tr> 1874<td class="tableblock halign-left valign-top"><p class="tableblock">Activiti UI</p></td> 1875<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://localhost:8080/activiti-app"><a href="http://localhost:8080/activiti-app" class="bare">http://localhost:8080/activiti-app</a></a></p></td> 1876<td class="tableblock halign-left valign-top"><p class="tableblock">The process engine user console. Use this tool to start new processes, assign tasks, view and claim tasks, etc.</p></td> 1877</tr> 1878</tbody> 1879</table> 1880<div class="paragraph"> 1881<p>Note that the Activiti UI app demo setup is a way of showing the capabilities and functionality of Activiti as easily and as fast as possible. This does however, <strong>not</strong> mean 1882that it is the only way of using Activiti. As Activiti is <em>just a jar</em>, it can be embedded in any Java environment: with swing or on a Tomcat, JBoss, WebSphere, etc. Or you could very well cho
1882ose to run Activiti as a typical, standalone BPM server. If it is possible in Java, it is possible with Activiti!</p> 1883</div> 1884</div> 1885<div class="sect2"> 1886<h3 id="activiti.setup.database">2.3. Activiti database setup</h3> 1887<div class="paragraph"> 1888<p>As said in the one minute demo setup, the Activiti UI app runs an in-memory H2 database by default. To run the Activiti UI app with a standalone H2 or another database the activiti-app.properties in the WEB-INF/classes/META-INF/activiti-app of the Activiti UI web application should be changed.</p> 1889</div> 1890</div> 1891<div class="sect2"> 1892<h3 id="getting.started.including.libs">2.4. Include the Activiti jar and its dependencies</h3> 1893<div class="paragraph"> 1894<p>To include the Activiti jar and its dependent libraries, we advise using <a href="http://maven.apache.org/">Maven</a> (or <a href="http://ant.apache.org/ivy/">Ivy</a>), as it 1895 simplifies dependency management on both our and your side a lot. Follow the instructions at <a href="http://www.activiti.org/community.html#maven.repository" class="bare">http://www.activiti.org/community.html#maven.repository</a> to include the necessary jars in your environment.</p> 1896</div> 1897<div class="paragraph"> 1898<p>Alternatively, if you don’t want to use Maven you can include the jars in your project yourself. The Activiti download zip contains a folder <code>libs</code> which contain all the Activiti jars (and the source jars). The dependencies are not shipped this way. The required dependencies of the Activiti engine are (generated using <code>mvn dependency:tree</code>):</p> 1899</div> 1900<div class="listingblock"> 1901<div class="content"> 1902<pre>org.activiti:activiti-engine:jar:6.x 1903+- org.activiti:activiti-bpmn-converter:jar:6.x:compile 1904| \- org.activiti:activiti-bpmn-model:jar:6.x:compile 1905| +- com.fasterxml.jackson.core:jackson-core:jar:2.2.3:compile 1906| \- com.fasterxml.jackson.core:jackson-databind:jar:2.2.3:compile 1907| \- com.fasterxml.jackson.core:jackson-annotations:jar:2.2.3:compile 1908+- org.activiti:activiti-process-validation:jar:6.x:compile 1909+- org.activiti:activiti-image-generator:jar:6.x:compile 1910+- org.apache.commons:commons-email:jar:1.2:compile 1911| +- javax.mail:mail:jar:1.4.1:compile 1912| \- javax.activation:activation:jar:1.1:compile 1913+- org.apache.commons:commons-lang3:jar:3.3.2:compile 1914+- org.mybatis:mybatis:jar:3.3.0:compile 1915+- org.springframework:spring-beans:jar:4.1.6.RELEASE:compile 1916| \- org.springframework:spring-core:jar:4.1.6.RELEASE:compile 1917+- joda-time:joda-time:jar:2.6:compile 1918+- org.slf4j:slf4j-api:jar:1.7.6:compile 1919+- org.slf4j:jcl-over-slf4j:jar:1.7.6:compile</pre> 1920</div> 1921</div> 1922<div class="paragraph"> 1923<p>Note: the mail jars are only needed if you are using the <a href="#bpmnEmailTask">mail service task</a>.</p> 1924</div> 1925<div class="paragraph"> 1926<p>All the dependencies can easily be downloaded using <code>mvn dependency:copy-dependencies</code> on a module of the <a href="https://github.com/Activiti/Activiti">Activiti source code</a>.</p> 1927</div> 1928</div> 1929<div class="sect2"> 1930<h3 id="getting.started.next.steps">2.5. Next steps</h3> 1931<div class="paragraph"> 1932<p>Playing around with the <a href="#activitiUI">Activiti UI</a> web application is a good way to get familiar with the Activiti concepts and functionality. However, the main purpose of Activiti is of course to enable powerful BPM and workflow capabilities in your own application. The following chapters will help you to get familiar with how to use Activiti programmatically in your environment:</p> 1933</div> 1934<div class="ulist"> 1935<ul> 1936<li> 1937<p><a href="#configuration">The chapter on configuration</a> will teach you how to set up Activiti and how to obtain an instance of the <code>ProcessEngine</code> class which is your central access point to all the engine functionality of Activiti. 1938*<a href="#chapterApi">The API chapter</a> will guide you through the services which form Activiti’s API. These services offer the Activiti engine functionality in a convenient yet powerful way and can be used in any Java environment. 1939*Interested in getting insight on BPMN 2.0, the format in which processes for the Activiti engine are written? Then continue on to the <a href="#bpmn2
19390">BPMN 2.0 section</a>.</p> 1940</li> 1941</ul> 1942</div> 1943</div> 1944</div> 1945</div> 1946<div class="sect1"> 1947<h2 id="_configuration">3. Configuration</h2> 1948<div class="sectionbody"> 1949<div class="sect2"> 1950<h3 id="configuration">3.1. Creating a ProcessEngine</h3> 1951<div class="paragraph"> 1952<p>The Activiti process engine is configured through an XML file called <code>activiti.cfg.xml</code>. Note that this is <strong>not</strong> applicable if you’re using <a href="#springintegration">the Spring style of building a process engine</a>.</p> 1953</div> 1954<div class="paragraph"> 1955<p>The easiest way to obtain a <code>ProcessEngine</code>, is to use the <code>org.activiti.engine.ProcessEngines</code> class:</p> 1956</div> 1957<div class="listingblock"> 1958<div class="content"> 1959<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">getDefaultProcessEngine</span><span class="tok-o">()</span> 1960</td></tr></table></code></pre> 1961</div> 1962</div> 1963<div class="paragraph"> 1964<p>This will look for an <code>activiti.cfg.xml</code> file on the classpath and construct an engine based on the configuration in that file. The following snippet shows an example configuration. The following sections will give a detailed overview of the configuration properties.</p> 1965</div> 1966<div class="listingblock"> 1967<div class="content"> 1968<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 1969 2 1970 3 1971 4 1972 5 1973 6 1974 7 1975 8 1976 9 197710 197811 197912 198013 198114 198215 198316 198417 198518 198619 198720</div></td><td class="code"><span></span><span class="tok-nt"><beans</span> <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.springframework.org/schema/beans"</span> 1988 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 1989 <span class="tok-na">xsi:schemaLocation=</span><span class="tok-s">"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"</span><span class="tok-nt">></span> 1990 1991 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"</span><span class="tok-nt">></span> 1992 1993 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcUrl"</span> <span class="tok-na">value=</span><span class="tok-s">"jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000"</span> <span class="tok-nt">/></span> 1994 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcDriver"</span> <span class="tok-na">value=</span><span class="tok-s">"org.h2.Driver"</span> <span class="tok-nt">/></span> 1995 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcUsername"</span> <span class="tok-na">value=</span><span class="tok-s">"sa"</span> <span class="tok-nt">/></span> 1996 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcPassword"</span> <span class="tok-na">value=</span><span class="tok-s">""</span> <span class="tok-nt">/></span> 1997 1998 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 1999 2000 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"asyncExecutorActivate"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 2001 2002 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"mailServerHost"</span> <span class="tok-na">value=</span><span class="tok-s">"mail.my-corp.com"</span> <span class="tok-nt">/></span> 2003 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"mailServerPort"</span> <span class="tok-na">value=</span><span class="tok-s">"5025"</span> <span class="tok-nt">/></span> 2004 <span class="tok-nt"></bean></span> 2005 2006<span class="tok-nt"></beans></span> 2007</td></tr></table></code></pre> 2008</div> 2009</div> 2010<div class="paragraph"> 2011<p>Note that the configuration XML is in fact a Spring configuration. <strong>This does not mean that Activiti can only be used in a Spring environment!</strong> We are simply leveraging the parsing and dependency injection capabilities of Spring internally for building up the engine.</p> 2012</div> 2013<div class="paragraph"> 2014<p>The ProcessEngineConfiguration object can also be created programmatically using the configuration file. It is also possible to use a different bean id (e.g. see line 3).</p> 2015</div> 2016<div class="listingblock"> 2017<div class="content"> 2018<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 20192 20203 20214 20225</div></td><td class="code"><span></span><span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">
2022createProcessEngineConfigurationFromResourceDefault</span><span class="tok-o">();</span> 2023<span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createProcessEngineConfigurationFromResource</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">resource</span><span class="tok-o">);</span> 2024<span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createProcessEngineConfigurationFromResource</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">resource</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">beanName</span><span class="tok-o">);</span> 2025<span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createProcessEngineConfigurationFromInputStream</span><span class="tok-o">(</span><span class="tok-n">InputStream</span> <span class="tok-n">inputStream</span><span class="tok-o">);</span> 2026<span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createProcessEngineConfigurationFromInputStream</span><span class="tok-o">(</span><span class="tok-n">InputStream</span> <span class="tok-n">inputStream</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">beanName</span><span class="tok-o">);</span> 2027</td></tr></table></code></pre> 2028</div> 2029</div> 2030<div class="paragraph"> 2031<p>It is also possible not to use a configuration file, and create a configuration based on 2032defaults (see <a href="#configurationClasses">the different supported classes</a> for more information).</p> 2033</div> 2034<div class="listingblock"> 2035<div class="content"> 2036<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 20372</div></td><td class="code"><span></span><span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createStandaloneProcessEngineConfiguration</span><span class="tok-o">();</span> 2038<span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createStandaloneInMemProcessEngineConfiguration</span><span class="tok-o">();</span> 2039</td></tr></table></code></pre> 2040</div> 2041</div> 2042<div class="paragraph"> 2043<p>All these <code>ProcessEngineConfiguration.createXXX()</code> methods return a <code>ProcessEngineConfiguration</code> that can further be tweaked if needed. After calling the <code>buildProcessEngine()</code> operation, a <code>ProcessEngine</code> is created:</p> 2044</div> 2045<div class="listingblock"> 2046<div class="content"> 2047<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 20482 20493 20504 20515</div></td><td class="code"><span></span><span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">createStandaloneInMemProcessEngineConfiguration</span><span class="tok-o">()</span> 2052 <span class="tok-o">.</span><span class="tok-na">setDatabaseSchemaUpdate</span><span class="tok-o">(</span><span class="tok-n">ProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">DB_SCHEMA_UPDATE_FALSE</span><span class="tok-o">)</span> 2053 <span class="tok-o">.</span><span class="tok-na">setJdbcUrl</span><span class="tok-o">(</span><span class="tok-s">"jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000"</span><span class="tok-o">)</span> 2054 <span class="tok-o">.</span><span class="tok-na">setAsyncExecutorActivate</span><span class="tok-o">(</span><span class="tok-kc">false</span><span class="tok-o">)</span> 2055 <span class="tok-o">.</span><span class="tok-na">buildProcessEngine</span><span class="tok-o">();</span> 2056</td></tr></table></code></pre> 2057</div> 2058</div> 2059</div> 2060<div class="sect2"> 2061<h3 id="configurationRoot">3.2. ProcessEngineConfiguration bean</h3> 2062<div class="paragraph"> 2063<p>The <code>activiti.cfg.xml</code> must contain a bean that has the id <code>'processEngineConfiguration'</code>.</p> 2064</div> 2065<div class="listingblock"> 2066<div class="content"> 2067<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span> <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"</span><span class="tok-nt">></span> 2068</td></tr></table></code></pre> 2069</div> 2070</div> 2071<div class="paragraph"> 2072<p>This bean is then used to construct the <code>ProcessEngine</code>. There are multiple classes available that can be used to define the <code>processEngineConfiguration</code>. These classes represent different environments, and set defaults accordingly. It’
2072s a best practice to select the class the matches (the most) your environment, to minimalise the number of properties needed to configure the engine. The following classes are currently available (more will follow in future releases): <a id="configurationClasses"></a></p> 2073</div> 2074<div class="ulist"> 2075<ul> 2076<li> 2077<p><strong>org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration</strong>: the process engine is used in a standalone way. Activiti will take care of the transactions. By default, the database will only be checked when the engine boots (and an exception is thrown if there is no Activiti schema or the schema version is incorrect).</p> 2078</li> 2079<li> 2080<p><strong>org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration</strong>: this is a convenience class for unit testing purposes. Activiti will take care of the transactions. An H2 in-memory database is used by default. The database will be created and dropped when the engine boots and shuts down. When using this, probably no additional configuration is needed (except when using for example the job executor or mail capabilities).</p> 2081</li> 2082<li> 2083<p><strong>org.activiti.spring.SpringProcessEngineConfiguration</strong>: To be used when the process engine is used in a Spring environment. See <a href="#springintegration">the Spring integration section</a> for more information.</p> 2084</li> 2085<li> 2086<p><strong>org.activiti.engine.impl.cfg.JtaProcessEngineConfiguration</strong>: To be used when the engine runs in standalone mode, with JTA transactions.</p> 2087</li> 2088</ul> 2089</div> 2090</div> 2091<div class="sect2"> 2092<h3 id="databaseConfiguration">3.3. Database configuration</h3> 2093<div class="paragraph"> 2094<p>There are two ways to configure the database that the Activiti engine will use. The first option is to define the JDBC properties of the database:</p> 2095</div> 2096<div class="ulist"> 2097<ul> 2098<li> 2099<p><strong>jdbcUrl</strong>: JDBC URL of the database.</p> 2100</li> 2101<li> 2102<p><strong>jdbcDriver</strong>: implementation of the driver for the specific database type.</p> 2103</li> 2104<li> 2105<p><strong>jdbcUsername</strong>: username to connect to the database.</p> 2106</li> 2107<li> 2108<p><strong>jdbcPassword</strong>: password to connect to the database.</p> 2109</li> 2110</ul> 2111</div> 2112<div class="paragraph"> 2113<p>The data source that is constructed based on the provided JDBC properties will have the default <a href="http://www.mybatis.org/">MyBatis</a> connection pool settings. The following attributes can optionally be set to tweak that connection pool (taken from the MyBatis documentation):</p> 2114</div> 2115<div class="ulist"> 2116<ul> 2117<li> 2118<p><strong>jdbcMaxActiveConnections</strong>: The number of active connections that the connection pool at maximum at any time can contain. Default is 10.</p> 2119</li> 2120<li> 2121<p><strong>jdbcMaxIdleConnections</strong>: The number of idle connections that the connection pool at maximum at any time can contain.</p> 2122</li> 2123<li> 2124<p><strong>jdbcMaxCheckoutTime</strong>: The amount of time in milliseconds a connection can be <em>checked out</em> from the connection pool before it is forcefully returned. Default is 20000 (20 seconds).</p> 2125</li> 2126<li> 2127<p><strong>jdbcMaxWaitTime</strong>: This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it is taking unusually long (to avoid failing silently forever if the pool is misconfigured) Default is 20000 (20 seconds).</p> 2128</li> 2129</ul> 2130</div> 2131<div class="paragraph"> 2132<p>Example database configuration:</p> 2133</div> 2134<div class="listingblock"> 2135<div class="content"> 2136<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 21372 21383 21394</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcUrl"</span> <span class="tok-na">value=</span><span class="tok-s">"jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000"</span> <span class="tok-nt">/></span> 2140<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcDriver"</span> <span class="tok-na">value=</span><span class="tok-s">"org.h2.Driver"</span> <span class="tok-nt">/></span> 2141<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcUsername"</span> <span class="tok-na">value=</span><span class="tok-s">"sa"</span> <span class="tok-nt">/></span> 2142<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcPassword"</span> <span class="tok-na">value=</span><span class="tok-s">""</span> <span class="tok-nt">/></span> 2143</td></tr></table></code></pre> 2144</div> 2145</div> 2146<div class="paragraph"> 2147<p>Our benchmarks have shown that the MyBatis connection pool is not the most efficient or resilient when dealing with a lot of concurrent requests. As such, it is advised to us a <code>javax.sql.DataSource</code> implementation and inject it into the process engine configuration (For example DBCP, C3P0, Hikari, Tomcat Connection Pool, etc.):</p> 2148</div> 2149<div class="listingblock"> 2150<div class="content"> 2151<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 2152 2 2153 3 2154 4 2155 5 2156 6 2157 7 2158 8 2159 9 216010 216111
216212</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"dataSource"</span> <span class="tok-na">class=</span><span class="tok-s">"org.apache.commons.dbcp.BasicDataSource"</span> <span class="tok-nt">></span> 2163 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"driverClassName"</span> <span class="tok-na">value=</span><span class="tok-s">"com.mysql.jdbc.Driver"</span> <span class="tok-nt">/></span> 2164 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"url"</span> <span class="tok-na">value=</span><span class="tok-s">"jdbc:mysql://localhost:3306/activiti"</span> <span class="tok-nt">/></span> 2165 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"username"</span> <span class="tok-na">value=</span><span class="tok-s">"activiti"</span> <span class="tok-nt">/></span> 2166 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"password"</span> <span class="tok-na">value=</span><span class="tok-s">"activiti"</span> <span class="tok-nt">/></span> 2167 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"defaultAutoCommit"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 2168<span class="tok-nt"></bean></span> 2169 2170<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"</span><span class="tok-nt">></span> 2171 2172 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"dataSource"</span> <span class="tok-na">ref=</span><span class="tok-s">"dataSource"</span> <span class="tok-nt">/></span> 2173 ... 2174</td></tr></table></code></pre> 2175</div> 2176</div> 2177<div class="paragraph"> 2178<p>Note that Activiti does not ship with a library that allows to define such a data source. So you have to make sure that the libraries are on your classpath.</p> 2179</div> 2180<div class="paragraph"> 2181<p>The following properties can be set, regardless of whether you are using the JDBC or data source approach:</p> 2182</div> 2183<div class="ulist"> 2184<ul> 2185<li> 2186<p><strong>databaseType</strong>: it’s normally not necessary to specify this property as it is automatically analyzed from the database connection metadata. Should only be specified in case automatic detection fails. Possible values: {h2, mysql, oracle, postgres, mssql, db2}. This setting will determine which create/drop scripts and queries will be used. See <a href="#supporteddatabases">the <em>supported databases</em> section</a> for an overview of which types are supported.</p> 2187</li> 2188<li> 2189<p><strong>databaseSchemaUpdate</strong>: allows to set the strategy to handle the database schema on process engine boot and shutdown.</p> 2190<div class="ulist"> 2191<ul> 2192<li> 2193<p><code>false</code> (default): Checks the version of the DB schema against the library when the process engine is being created and throws an exception if the versions don’t match.</p> 2194</li> 2195<li> 2196<p><code>true</code>: Upon building the process engine, a check is performed and an update of the schema is performed if it is necessary. If the schema doesn’t exist, it is created.</p> 2197</li> 2198<li> 2199<p><code>create-drop</code>: Creates the schema when the process engine is being created and drops the schema when the process engine is being closed.</p> 2200</li> 2201</ul> 2202</div> 2203</li> 2204</ul> 2205</div> 2206</div> 2207<div class="sect2"> 2208<h3 id="jndiDatasourceConfig">3.4. JNDI Datasource Configuration</h3> 2209<div class="paragraph"> 2210<p>By default, the database configuration for Activiti is contained within the db.properties files in the WEB-INF/classes of each web application. This isn’t always ideal because it 2211requires users to either modify the db.properties in the Activiti source and recompile the war file, or explode the war and modify the db.properties on every deployment.</p> 2212</div> 2213<div class="paragraph"> 2214<p>By using JNDI (Java Naming and Directory Interface) to obtain the database connection, the connection is fully managed by the Servlet Container and the configuration can be managed outside the war deployment. This also allows more control over the connection parameters than what is provided by the db.properties file.</p> 2215</div> 2216<div class="sect3"> 2217<h4 id="jndi_configuration">3.4.1. Configuration</h4> 2218<div class="paragraph"> 2219<p>Configuration of the JNDI datasource will differ depending on what servlet container application you are using. The instructions below will work for Tomcat, but for other container applications, please refer to the documentation for your container app.</p> 2220</div> 2221<div class="paragraph"> 2222<p>If using Tomcat, the JNDI resource is configured within $CATALINA_BASE/conf/[enginename]/[hostname]/[warname].xml (for the Activiti UI this will usually be $CATALINA_BASE/conf/Catalina/localhost/activiti-app.xml). The default context is copied from the Activiti w
2222ar file when the application is first deployed, so if it already exists, you will need to replace it. To change the JNDI resource so that the application connects to MySQL instead of H2, for example, change the file to the following:</p> 2223</div> 2224<div class="listingblock"> 2225<div class="content"> 2226<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 2227 2 2228 3 2229 4 2230 5 2231 6 2232 7 2233 8 2234 9 223510 223611 223712 223813 223914 224015 224116</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="UTF-8"?></span> 2242 <span class="tok-nt"><Context</span> <span class="tok-na">antiJARLocking=</span><span class="tok-s">"true"</span> <span class="tok-na">path=</span><span class="tok-s">"/activiti-app"</span><span class="tok-nt">></span> 2243 <span class="tok-nt"><Resource</span> <span class="tok-na">auth=</span><span class="tok-s">"Container"</span> 2244 <span class="tok-na">name=</span><span class="tok-s">"jdbc/activitiDB"</span> 2245 <span class="tok-na">type=</span><span class="tok-s">"javax.sql.DataSource"</span> 2246 <span class="tok-na">description=</span><span class="tok-s">"JDBC DataSource"</span> 2247 <span class="tok-na">url=</span><span class="tok-s">"jdbc:mysql://localhost:3306/activiti"</span> 2248 <span class="tok-na">driverClassName=</span><span class="tok-s">"com.mysql.jdbc.Driver"</span> 2249 <span class="tok-na">username=</span><span class="tok-s">"sa"</span> 2250 <span class="tok-na">password=</span><span class="tok-s">""</span> 2251 <span class="tok-na">defaultAutoCommit=</span><span class="tok-s">"false"</span> 2252 <span class="tok-na">initialSize=</span><span class="tok-s">"5"</span> 2253 <span class="tok-na">maxWait=</span><span class="tok-s">"5000"</span> 2254 <span class="tok-na">maxActive=</span><span class="tok-s">"120"</span> 2255 <span class="tok-na">maxIdle=</span><span class="tok-s">"5"</span><span class="tok-nt">/></span> 2256 <span class="tok-nt"></Context></span> 2257</td></tr></table></code></pre> 2258</div> 2259</div> 2260</div> 2261<div class="sect3"> 2262<h4 id="_jndi_properties">3.4.2. JNDI properties</h4> 2263<div class="paragraph"> 2264<p>To configure a JNDI Datasource, use following properties in the properties file for the Activiti UI:</p> 2265</div> 2266<div class="ulist"> 2267<ul> 2268<li> 2269<p>datasource.jndi.name: the JNDI name of the Datasource.</p> 2270</li> 2271<li> 2272<p>datasource.jndi.resourceRef: Set whether the lookup occurs in a J2EE container, i.e. if the prefix "java:comp/env/" needs to be added if the JNDI name doesn’t already contain it. Default is "true".</p> 2273</li> 2274</ul> 2275</div> 2276</div> 2277</div> 2278<div class="sect2"> 2279<h3 id="supporteddatabases">3.5. Supported databases</h3> 2280<div class="paragraph"> 2281<p>Listed below are the types (case sensitive!) that Activiti uses to refer to databases.</p> 2282</div> 2283<table id="databaseTypes" class="tableblock frame-all grid-all spread"> 2284<colgroup> 2285<col style="width: 33.3333%;"> 2286<col style="width: 33.3333%;"> 2287<col style="width: 33.3334%;"> 2288</colgroup> 2289<thead> 2290<tr> 2291<th class="tableblock halign-left valign-top">Activiti database type</th> 2292<th class="tableblock halign-left valign-top">Example JDBC URL</th> 2293<th class="tableblock halign-left valign-top">Notes</th> 2294</tr> 2295</thead> 2296<tbody> 2297<tr> 2298<td class="tableblock halign-left valign-top"><p class="tableblock">h2</p></td> 2299<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc:h2:tcp://localhost/activiti</p></td> 2300<td class="tableblock halign-left valign-top"><p class="tableblock">Default configured database</p></td> 2301</tr> 2302<tr> 2303<td class="tableblock halign-left valign-top"><p class="tableblock">mysql</p></td> 2304<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc:mysql://localhost:3306/activiti?autoReconnect=true</p></td> 2305<td class="tableblock halign-left valign-top"><p class="tableblock">Tested using mysql-connector-java database driver</p></td> 2306</tr> 2307<tr> 2308<td class="tableblock halign-left valign-top"><p class="tableblock">oracle</p></td> 2309<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc:oracle:thin:@localhost:1521:xe</p></td> 2310<td class="tableblock halign-left valign-top"></td> 2311</tr> 2312<tr> 2313<td class="tableblock halign-left valign-top"><p class="tableblock">postgres</p></td> 2314<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc:postgresql://localhost:5432/activiti</p></td> 2315<td class="tableblock halign-left valign-top"></td> 2316</tr> 2317<tr> 2318<td class="tableblock halign-left valign-top"><p class="tableblock">db2</p></td> 2319<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc:db2://localhost:50000/activiti</p></td> 2320<td class="tableblock halign-left valign-top"></td> 2321</tr> 2322<tr> 2323<td class="tableblock halign-left valign-top"><p class="tableblock">mssql</p></td> 2324<td class="tableblock halign-left valign-top"><p class="tableblock">
2324jdbc:sqlserver://localhost:1433;databaseName=activiti (jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver) <em>OR</em> jdbc:jtds:sqlserver://localhost:1433/activiti (jdbc.driver=net.sourceforge.jtds.jdbc.Driver)</p></td> 2325<td class="tableblock halign-left valign-top"><p class="tableblock">Tested using Microsoft JDBC Driver 4.0 (sqljdbc4.jar) and JTDS Driver</p></td> 2326</tr> 2327</tbody> 2328</table> 2329</div> 2330<div class="sect2"> 2331<h3 id="creatingDatabaseTable">3.6. Creating the database tables</h3> 2332<div class="paragraph"> 2333<p>The easiest way to create the database tables for your database is to:</p> 2334</div> 2335<div class="ulist"> 2336<ul> 2337<li> 2338<p>Add the activiti-engine jars to your classpath</p> 2339</li> 2340<li> 2341<p>Add a suitable database driver</p> 2342</li> 2343<li> 2344<p>Add an Activiti configuration file (<em>activiti.cfg.xml</em>) to your classpath, pointing to your database (see <a href="#databaseConfiguration">database configuration section</a>)</p> 2345</li> 2346<li> 2347<p>Execute the main method of the <em>DbSchemaCreate</em> class</p> 2348</li> 2349</ul> 2350</div> 2351<div class="paragraph"> 2352<p>However, often only database administrators can execute DDL statements on a database. On a production system, this is also the wisest of choices. The SQL DDL statements can be found on the Activiti downloads page or inside the Activiti distribution folder, in the <code>database</code> subdirectory. The scripts are also in the engine jar (<em>activiti-engine-x.jar</em>), in the package <em>org/activiti/db/create</em> (the <em>drop</em> folder contains the drop statements). The SQL files are of the form</p> 2353</div> 2354<div class="listingblock"> 2355<div class="content"> 2356<pre>activiti.{db}.{create|drop}.{type}.sql</pre> 2357</div> 2358</div> 2359<div class="paragraph"> 2360<p>Where <em>db</em> is any of the <a href="#supporteddatabases">supported databases</a> and <em>type</em> is</p> 2361</div> 2362<div class="ulist"> 2363<ul> 2364<li> 2365<p><strong>engine:</strong> the tables needed for engine execution. Required.</p> 2366</li> 2367<li> 2368<p><strong>identity:</strong> the tables containing users, groups and memberships of users to groups. These tables are optional and should be used when using the default identity management as shipped with the engine.</p> 2369</li> 2370<li> 2371<p><strong>history:</strong> the tables that contain the history and audit information. Optional: not needed when history level is set to <em>none</em>. Note that this will also disable some features (such as commenting on tasks) which store the data in the history database.</p> 2372</li> 2373</ul> 2374</div> 2375<div class="paragraph"> 2376<p><strong>Note for MySQL users:</strong> MySQL version lower than 5.6.4 has no support for timestamps or dates with millisecond precision. To make things even worse, some version will throw an exception when trying to create such a column but other versions don’t. When doing auto-creation/upgrade, the engine will change the DDL when executing it. When using the DDL file approach, both a regular version and a special file with <em>mysql55</em> in it are available (this applies on anything lower than 5.6.4). This latter file will have column types with no millisecond precision in it.</p> 2377</div> 2378<div class="paragraph"> 2379<p>Concretely, the following applies for MySQL version</p> 2380</div> 2381<div class="ulist"> 2382<ul> 2383<li> 2384<p><strong><5.6:</strong> No millisecond precision available. DDL files available (look for files containing <em>mysql55</em>). Auto creation/update will work out of the box.</p> 2385</li> 2386<li> 2387<p><strong>5.6.0 - 5.6.3:</strong> No millisecond precision available. Auto creation/update will NOT work. It is advised to upgrade to a newer database version anyway. DDL files for <em>mysql 5.5</em> could be used if really needed.</p> 2388</li> 2389<li> 2390<p><strong>5.6.4+:</strong> Millisecond precision available. DDL files available (default file containing <em>mysql</em>). Auto creation/update works out of the box.</p> 2391</li> 2392</ul> 2393</div> 2394<div class="paragraph"> 2395<p>Do note that in the case of upgrading the MySQL database later on and the Activiti tables are already created/upgraded, the column type change will have to be done manually!</p> 2396</div> 2397</div> 2398<div class="sect2"> 2399<h3 id="database.tables.explained">3.7. Database table names explained</h3> 2400<div class="paragraph"> 2401<p>The database names of Activiti all start with <strong>ACT_</strong>. The second part is a two-character identification of the use case of the table. This use case will also roughly match the service API.</p> 2402</div> 2403<div class="ulist"> 2404<ul> 2405<li> 2406<p><strong>ACT_RE_</strong>*: <em>RE</em> stands for <code>repository</code>. Tables with this prefix contain <em>static</em> information such as process definitions and process resources (images, rules, etc.).</p> 2407</li> 2408<li> 2409<p><strong>ACT_RU_</strong>*: <em>RU</em> stands for <code>runtime</code>. These are the runtime tables that contain the runtime data of process instances, user tasks, variables, jobs, etc. Activiti only stores the runtime data during process instance execution, and removes the records when a process instance ends. This keeps the runtime tables small and fast.</p> 2410</li> 2411<li> 2412<p><strong>ACT_ID_</strong>*: <em>ID</em> stands for <code>identity</code>. These tables contain identity information, such as users, groups, etc.</p> 2413</li> 2414<li> 2415<p><strong>ACT_HI_</strong>*: <em>HI</em> stands for <code>history</code>. These are the tables that contain historic data, such as past process instances, variables, tasks, etc.</p> 2416</li> 2417<li> 2418<p><strong>ACT_GE_</strong>*: <code>general</code> data, which is used in various use cases.</p> 2419</li> 2420</ul> 2421</div> 2422</div> 2423<div class="sect2"> 2424<h3 id="databaseUpgrade">3.8. Database upgrade</h3> 2425<div class="paragraph"> 2426<p>Make sure you make a backup of your database (using your database backup capabilities) before you run an upgrade.</p> 2427</div> 2428<div class="paragraph"> 2429<p>By default, a version check will be performed each time a process engine is created. This typically happens once at boot time of your application or of the Activiti webapps. If the Activiti library n
2429otices a difference between the library version and the version of the Activiti database tables, then an exception is thrown.</p> 2430</div> 2431<div class="paragraph"> 2432<p>To upgrade, you have to start with putting the following configuration property in your activiti.cfg.xml configuration file:</p> 2433</div> 2434<div class="listingblock"> 2435<div class="content"> 2436<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 24372 24383 24394 24405 24416 24427 24438 24449</div></td><td class="code"><span></span><span class="tok-nt"><beans</span> <span class="tok-nt">></span> 2445 2446 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"</span><span class="tok-nt">></span> 2447 <span class="tok-c"><!-- ... --></span> 2448 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 2449 <span class="tok-c"><!-- ... --></span> 2450 <span class="tok-nt"></bean></span> 2451 2452<span class="tok-nt"></beans></span> 2453</td></tr></table></code></pre> 2454</div> 2455</div> 2456<div class="paragraph"> 2457<p><strong>Also, include a suitable database driver for your database to the classpath.</strong> Upgrade the Activiti libraries in your application. Or start up a new version of Activiti and point it to a database that contains an older version. With <code>databaseSchemaUpdate</code> set to <code>true</code>, Activiti will automatically upgrade the DB schema to the newer version the first time when it notices that libraries and DB schema are out of sync.</p> 2458</div> 2459<div class="paragraph"> 2460<p><strong>As an alternative you can also run the upgrade DDL statements.</strong> It’s also possible to run the upgrade database scripts, available on the Activiti downloads page.</p> 2461</div> 2462</div> 2463<div class="sect2"> 2464<h3 id="jobExecutorConfiguration">3.9. Job Executor (since version 6.0.0)</h3> 2465<div class="paragraph"> 2466<p>The async executor of Activiti 5 is the only available job executor in Activiti 6 as it is a more performant and more database friendly way of executing asynchronous jobs in the Activiti Engine. 2467The old job executor of Activiti 5 is removed. More information can be found in the advanced section of the user guide.</p> 2468</div> 2469<div class="paragraph"> 2470<p>Moreover, if running under Java EE 7, JSR-236 compliant <code>ManagedAsyncJobExecutor</code> can be used for letting the container manage the threads. In order to enable them, the thread factory should be passed in the configuration as follows:</p> 2471</div> 2472<div class="listingblock"> 2473<div class="content"> 2474<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 24752 24763 24774 24785 24796 24807 24818 24829</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"threadFactory"</span> <span class="tok-na">class=</span><span class="tok-s">"org.springframework.jndi.JndiObjectFactoryBean"</span><span class="tok-nt">></span> 2483 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jndiName"</span> <span class="tok-na">value=</span><span class="tok-s">"java:jboss/ee/concurrency/factory/default"</span> <span class="tok-nt">/></span> 2484<span class="tok-nt"></bean></span> 2485 2486<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"customJobExecutor"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.jobexecutor.ManagedAsyncJobExecutor"</span><span class="tok-nt">></span> 2487 <span class="tok-c"><!-- ... --></span> 2488 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"threadFactory"</span> <span class="tok-na">ref=</span><span class="tok-s">"threadFactory"</span> <span class="tok-nt">/></span> 2489 <span class="tok-c"><!-- ... --></span> 2490<span class="tok-nt"></bean></span> 2491</td></tr></table></code></pre> 2492</div> 2493</div> 2494<div class="paragraph"> 2495<p>The managed implementation fall back to their default counterparts if the thread factory is not specified.</p> 2496</div> 2497</div> 2498<div class="sect2"> 2499<h3 id="_job_executor_activation">3.10. Job executor activation</h3> 2500<div class="paragraph"> 2501<p>The <code>
2501AsyncExecutor</code> is a component that manages a thread pool to fire timers and other asynchronous tasks. Other implementations are possible (for example using a message queue, see the advanced section of the user guide).</p> 2502</div> 2503<div class="paragraph"> 2504<p>By default, the <code>AsyncExecutor</code> is not activated and not started. With the following configuration the async executor can be started together with the Activiti Engine.</p> 2505</div> 2506<div class="listingblock"> 2507<div class="content"> 2508<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"asyncExecutorActivate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 2509</td></tr></table></code></pre> 2510</div> 2511</div> 2512<div class="paragraph"> 2513<p>The property asyncExecutorActivate instructs the Activiti Engine to startup the Async executor at startup.</p> 2514</div> 2515</div> 2516<div class="sect2"> 2517<h3 id="mailServerConfiguration">3.11. Mail server configuration</h3> 2518<div class="paragraph"> 2519<p>Configuring a mail server is optional. Activiti supports sending e-mails in business processes. To actually send an e-mail, a valid SMTP mail server configuration is required. See the <a href="#bpmnEmailTaskServerConfiguration">e-mail task</a> for the configuration options.</p> 2520</div> 2521</div> 2522<div class="sect2"> 2523<h3 id="historyConfiguration">3.12. History configuration</h3> 2524<div class="paragraph"> 2525<p>Customizing the configuration of history storage is optional. This allows you to tweak settings that influence the <a href="#history">history capabilities</a> of the engine. See <a href="#historyConfig">history configuration</a> for more details.</p> 2526</div> 2527<div class="listingblock"> 2528<div class="content"> 2529<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"history"</span> <span class="tok-na">value=</span><span class="tok-s">"audit"</span> <span class="tok-nt">/></span> 2530</td></tr></table></code></pre> 2531</div> 2532</div> 2533</div> 2534<div class="sect2"> 2535<h3 id="exposingConfigurationBeans">3.13. Exposing configuration beans in expressions and scripts</h3> 2536<div class="paragraph"> 2537<p>By default, all beans that you specify in the <code>activiti.cfg.xml</code> configuration or in your own Spring configuration file are available to expressions and in the scripts. If you want to limit the visibility of beans in your configuration file, you can configure a property called <code>beans</code> in your process engine configuration. The beans property in <code>ProcessEngineConfiguration</code> is a map. When you specify that property, only beans specified in that map will be visible to expressions and scripts. The exposed beans will be exposed with the names as you specify in that map.</p> 2538</div> 2539</div> 2540<div class="sect2"> 2541<h3 id="processDefinitionCacheConfiguration">3.14. Deployment cache configuration</h3> 2542<div class="paragraph"> 2543<p>All process definition are cached (after they’re parsed) to avoid hitting the database every time a process definition is needed and because process definition data doesn’t change. By default, there is no limit on this cache. To limit the process definition cache, add following property</p> 2544</div> 2545<div class="listingblock"> 2546<div class="content"> 2547<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"processDefinitionCacheLimit"</span> <span class="tok-na">value=</span><span class="tok-s">"10"</span> <span class="tok-nt">/></span> 2548</td></tr></table></code></pre> 2549</div> 2550</div> 2551<div class="paragraph"> 2552<p>
2552Setting this property will swap the default hashmap cache with a LRU cache that has the provided hard limit. Of course, the <em>best</em> value of this property depends on the total amount of process definitions stored and the number of process definitions actually used at runtime by all the runtime process instances.</p> 2553</div> 2554<div class="paragraph"> 2555<p>You can also inject your own cache implementation. This must be a bean that implements the org.activiti.engine.impl.persistence.deploy.DeploymentCache interface:</p> 2556</div> 2557<div class="listingblock"> 2558<div class="content"> 2559<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 25602 25613</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"processDefinitionCache"</span><span class="tok-nt">></span> 2562 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyCache"</span> <span class="tok-nt">/></span> 2563<span class="tok-nt"></property></span> 2564</td></tr></table></code></pre> 2565</div> 2566</div> 2567<div class="paragraph"> 2568<p>There is a similar property called <code>knowledgeBaseCacheLimit</code> and <code>knowledgeBaseCache</code> for configuring the rules cache. This is only needed when you use the rules task in your processes.</p> 2569</div> 2570</div> 2571<div class="sect2"> 2572<h3 id="loggingConfiguration">3.15. Logging</h3> 2573<div class="paragraph"> 2574<p>All logging (activiti, spring, mybatis, …​) is routed through SLF4J and allows for selecting the logging-implementation of your choice.</p> 2575</div> 2576<div class="paragraph"> 2577<p><strong>By default no SFL4J-binding jar is present in the activiti-engine dependencies, this should be added in your project in order to use the logging framework of your choice.</strong> If no implementation jar is added, SLF4J will use a NOP-logger, not logging anything at all, other than a warning that nothing will be logged. For more info on these bindings <a href="http://www.slf4j.org/codes.html#StaticLoggerBinder"><a href="http://www.slf4j.org/codes.html#StaticLoggerBinder" class="bare">http://www.slf4j.org/codes.html#StaticLoggerBinder</a></a>.</p> 2578</div> 2579<div class="paragraph"> 2580<p>With Maven, add for example a dependency like this (here using log4j), note that you still need to add a version:</p> 2581</div> 2582<div class="listingblock"> 2583<div class="content"> 2584<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 25852 25863 25874</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 2588 <span class="tok-nt"><groupId></span>org.slf4j<span class="tok-nt"></groupId></span> 2589 <span class="tok-nt"><artifactId></span>slf4j-log4j12<span class="tok-nt"></artifactId></span> 2590<span class="tok-nt"></dependency></span> 2591</td></tr></table></code></pre> 2592</div> 2593</div> 2594<div class="paragraph"> 2595<p>The activiti-ui and activiti-rest webapps are configured to use Log4j-binding. Log4j is also used when running the tests for all the activiti-* modules.</p> 2596</div> 2597<div class="paragraph"> 2598<p><strong>Important note when using a container with commons-logging in the classpath:</strong> In order to route the spring-logging through SLF4J, a bridge is used (see <a href="http://www.slf4j.org/legacy.html#jclOverSLF4J"><a href="http://www.slf4j.org/legacy.html#jclOverSLF4J" class="bare">http://www.slf4j.org/legacy.html#jclOverSLF4J</a></a>). If your container provides a commons-logging implementation, please follow directions on this page: <a href="http://www.slf4j.org/codes.html#release"><a href="http://www.slf4j.org/codes.html#release" class="bare">http://www.slf4j.org/codes.html#release</a></a> to ensure stability.</p> 2599</div> 2600<div class="paragraph"> 2601<p>Example when using Maven (version omitted):</p> 2602</div> 2603<div class="listingblock"> 2604<div class="content"> 2605<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 26062 26073 26084</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 2609 <span class="tok-nt"><groupId></span>org.slf4j<span class="tok-nt"></groupId></span> 2610 <span class="tok-nt"><artifactId></span>jcl-over-slf4j<span class="tok-nt"></artifactId></span> 2611<span class="tok-nt"></dependency></span> 2612</td></tr></table></code></pre> 2613</div> 2614</div> 2615</div> 2616<div class="sect2"> 2617<h3 id="MDC">3.16. Mapped Diagnostic Contexts</h3> 2618<div class="paragraph"> 2619<p>Activiti supports Mapped Diagnostic Contexts feature of SLF4j. These basic
2619information are passed to the underlying logger along with what is going to be logged:</p> 2620</div> 2621<div class="ulist"> 2622<ul> 2623<li> 2624<p>processDefinition Id as mdcProcessDefinitionID</p> 2625</li> 2626<li> 2627<p>processInstance Id as mdcProcessInstanceID</p> 2628</li> 2629<li> 2630<p>execution Id as mdcExecutionId</p> 2631</li> 2632</ul> 2633</div> 2634<div class="paragraph"> 2635<p>None of these information are logged by default. The logger can be configured to show them in desired format, extra to the usual logged messages. For example in Log4j the following sample layout definition causes the logger to show the above mentioned information:</p> 2636</div> 2637<div class="listingblock"> 2638<div class="content"> 2639<pre class="pygments highlight"><code data-lang="properties"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 26402</div></td><td class="code"><span></span><span class="tok-na">log4j.appender.consoleAppender.layout.ConversionPattern</span><span class="tok-o">=</span><span class="tok-s">ProcessDefinitionId=%X{mdcProcessDefinitionID}</span> 2641<span class="tok-na">executionId</span><span class="tok-o">=</span><span class="tok-s">%X{mdcExecutionId} mdcProcessInstanceID=%X{mdcProcessInstanceID} mdcBusinessKey=%X{mdcBusinessKey} %m%n</span> 2642</td></tr></table></code></pre> 2643</div> 2644</div> 2645<div class="paragraph"> 2646<p>This is useful when the logs contain information that needs to checked in real time, by means of a log analyzer for example.</p> 2647</div> 2648</div> 2649<div class="sect2"> 2650<h3 id="eventDispatcher">3.17. Event handlers</h3> 2651<div class="paragraph"> 2652<p>The event mechanism in the Activiti engine allows you to get notified when various events occur within the engine. Take a look at <a href="#eventDispatcherEventTypes">all supported event types</a> for an overview of the events available.</p> 2653</div> 2654<div class="paragraph"> 2655<p>It’s possible to register a listener for certain types of events as opposed to getting notified when any type of event is dispatched. You can either add engine-wide event listeners <a href="#eventDispatcherConfiguration">through the configuration</a>, add engine-wide event listeners <a href="#eventDispatcherConfigurationRuntime">at runtime using the API</a> or add event-listeners to <a href="#eventDispatcherConfigurationProcessDefinition">specific process definitions in the BPMN XML</a>.</p> 2656</div> 2657<div class="paragraph"> 2658<p>All events dispatched are a subtype of <code>org.activiti.engine.delegate.event.ActivitiEvent</code>. The event exposes (if available) the <code>type</code>, <code>executionId</code>, <code>processInstanceId</code> and <code>processDefinitionId</code>. Certain events contain additional context related to the event that occurred, additional information about additional payload can be found in the list of <a href="#eventDispatcherEventTypes">all supported event types</a>.</p> 2659</div> 2660<div class="sect3"> 2661<h4 id="eventDispatcherListener">3.17.1. Event listener implementation</h4> 2662<div class="paragraph"> 2663<p>The only requirement an event-listener has, is to implement <code>org.activiti.engine.delegate.event.ActivitiEventListener</code>. Below is an example implementation of a listener, which outputs all events received to the standard-out, with exception of events related to job-execution:</p> 2664</div> 2665<div class="listingblock"> 2666<div class="content"> 2667<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 2668 2 2669 3 2670 4 2671 5 2672 6 2673 7 2674 8 2675 9 267610 267711 267812 267913 268014 268115 268216 268317 268418 268519 268620 268721 268822 268923 269024 269125 269226</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyEventListener</span> <span class="tok-kd">implements</span> <span class="tok-n">ActivitiEventListener</span> <span class="tok-o">{</span> 2693 2694 <span class="tok-nd">@Override</span> 2695 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">onEvent</span><span class="tok-o">(</span><span class="tok-n">ActivitiEvent</span> <span class="tok-n">event</span><span class="tok-o">)</span> <span class="tok-o">{</span> 2696 <span class="tok-k">switch</span> <span class="tok-o">(</span><span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-na">getType</span><span class="tok-o">())</span> <span class="tok-o">{</span> 2697
2698 <span class="tok-k">case</span> <span class="tok-n">JOB_EXECUTION_SUCCESS</span><span class="tok-o">:</span> 2699 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"A job well done!"</span><span class="tok-o">);</span> 2700 <span class="tok-k">break</span><span class="tok-o">;</span> 2701 2702 <span class="tok-k">case</span> <span class="tok-n">JOB_EXECUTION_FAILURE</span><span class="tok-o">:</span> 2703 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"A job has failed..."</span><span class="tok-o">);</span> 2704 <span class="tok-k">break</span><span class="tok-o">;</span> 2705 2706<span class="tok-nl"> default:</span> 2707 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Event received: "</span> <span class="tok-o">+</span> <span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-na">getType</span><span class="tok-o">());</span> 2708 <span class="tok-o">}</span> 2709 <span class="tok-o">}</span> 2710 2711 <span class="tok-nd">@Override</span> 2712 <span class="tok-kd">public</span> <span class="tok-kt">boolean</span> <span class="tok-nf">isFailOnException</span><span class="tok-o">()</span> <span class="tok-o">{</span> 2713 <span class="tok-c1">// The logic in the onEvent method of this listener is not critical, exceptions</span> 2714 <span class="tok-c1">// can be ignored if logging fails...</span> 2715 <span class="tok-k">return</span> <span class="tok-kc">false</span><span class="tok-o">;</span> 2716 <span class="tok-o">}</span> 2717<span class="tok-o">}</span> 2718</td></tr></table></code></pre> 2719</div> 2720</div> 2721<div class="paragraph"> 2722<p>The <code>isFailOnException()</code> method determines the behaviour in case the <code>onEvent(..)</code> method throws an exception when an event is dispatched. In case <code>false</code> is returned, the exception is ignored. When <code>true</code> is returned, the exception is not ignored and bubbles up, effectively failing the current ongoing command. In case the event was part of an API-call (or any other transactional operation, e.g. job-execution), the transaction will be rolled back. In case the behaviour in the event-listener is not business-critical, it’s recommended to return <code>false</code>.</p> 2723</div> 2724<div class="paragraph"> 2725<p>There are a few base implementations provided by Activiti to facilitate common use cases of event-listeners. These can be used as base-class or as an example listener implementation:</p> 2726</div> 2727<div class="ulist"> 2728<ul> 2729<li> 2730<p><strong>org.activiti.engine.delegate.event.BaseEntityEventListener</strong>: An event-listener base-class that can be used to listen for entity-related events for a specific type of entity or for all entities. It hides away the type-checking and offers 4 methods that should be overridden: <code>onCreate(..)</code>, <code>onUpdate(..)</code> and <code>onDelete(..)</code> when an entity is created, updated or deleted. For all other entity-related events, the <code>onEntityEvent(..) </code>is called.</p> 2731</li> 2732</ul> 2733</div> 2734</div> 2735<div class="sect3"> 2736<h4 id="eventDispatcherConfiguration">3.17.2. Configuration and setup</h4> 2737<div class="paragraph"> 2738<p>If an event-listener is configured in the process engine configuration, it will be active when the process engine starts and will remain active after subsequent reboots of the engine.</p> 2739</div> 2740<div class="paragraph"> 2741<p>The property <code>eventListeners</code> expects a list of <code>org.activiti.engine.delegate.event.ActivitiEventListener</code> instances. As usual, you can either declare an inline bean definition or use a <code>ref</code> to an existing bean instead. The snippet below adds an event-listener to the configuration that is notified when any event is dispatched, regardless of its type:</p> 2742</div> 2743<div class="listingblock"> 2744<div class="content"> 2745<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 27462 27473 27484 27495 27506 27517 27528</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"</span><span class="tok-nt">></span> 2753 ... 2754 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"eventListeners"</span><span class="tok-nt">></span>
2755 <span class="tok-nt"><list></span> 2756 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.example.MyEventListener"</span> <span class="tok-nt">/></span> 2757 <span class="tok-nt"></list></span> 2758 <span class="tok-nt"></property></span> 2759<span class="tok-nt"></bean></span> 2760</td></tr></table></code></pre> 2761</div> 2762</div> 2763<div class="paragraph"> 2764<p>To get notified when certain types of events get dispatched, use the <code>typedEventListeners</code> property, which expects a map. The key of a map-entry is a comma-separated list of event-names (or a single event-name). The value of a map-entry is a list of <code>org.activiti.engine.delegate.event.ActivitiEventListener</code> instances. The snippet below adds an event-listener to the configuration, that is notified when a job execution was successful or failed:</p> 2765</div> 2766<div class="listingblock"> 2767<div class="content"> 2768<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 2769 2 2770 3 2771 4 2772 5 2773 6 2774 7 2775 8 2776 9 277710 277811 277912</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"</span><span class="tok-nt">></span> 2780 ... 2781 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"typedEventListeners"</span><span class="tok-nt">></span> 2782 <span class="tok-nt"><map></span> 2783 <span class="tok-nt"><entry</span> <span class="tok-na">key=</span><span class="tok-s">"JOB_EXECUTION_SUCCESS,JOB_EXECUTION_FAILURE"</span> <span class="tok-nt">></span> 2784 <span class="tok-nt"><list></span> 2785 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.example.MyJobEventListener"</span> <span class="tok-nt">/></span> 2786 <span class="tok-nt"></list></span> 2787 <span class="tok-nt"></entry></span> 2788 <span class="tok-nt"></map></span> 2789 <span class="tok-nt"></property></span> 2790<span class="tok-nt"></bean></span> 2791</td></tr></table></code></pre> 2792</div> 2793</div> 2794<div class="paragraph"> 2795<p>The order of dispatching events is determined on the order the listeners were added. First, all normal event-listeners are called (<code>eventListeners</code> property) in the order they are defined in the <code>list</code>. After that, all typed event listeners (<code>typedEventListeners</code> properties) are called, if an event of the right type is dispatched.</p> 2796</div> 2797</div> 2798<div class="sect3"> 2799<h4 id="eventDispatcherConfigurationRuntime">3.17.3. Adding listeners at runtime</h4> 2800<div class="paragraph"> 2801<p>It’s possible to add and remove additional event-listeners to the engine by using the API (<code>RuntimeService</code>):</p> 2802</div> 2803<div class="listingblock"> 2804<div class="content"> 2805<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 2806 2 2807 3 2808 4 2809 5 2810 6 2811 7 2812 8 2813 9 281410 281511 281612 281713 281814 281915 282016 282117 282218 282319</div></td><td class="code"><span></span><span class="tok-cm">/**</span> 2824<span class="tok-cm"> * Adds an event-listener which will be notified of ALL events by the dispatcher.</span> 2825<span class="tok-cm"> * @param listenerToAdd the listener to add</span> 2826<span class="tok-cm"> */</span> 2827<span class="tok-kt">void</span> <span class="tok-nf">addEventListener</span><span class="tok-o">(</span><span class="tok-n">ActivitiEventListener</span> <span class="tok-n">listenerToAdd</span><span class="tok-o">);</span> 2828 2829<span class="tok-cm">/**</span> 2830<span class="tok-cm"> * Adds an event-listener which will only be notified when an event occurs, which type is in the given types.</span> 2831<span class="tok-cm"> * @param listenerToAdd the listener to add</span> 2832<span class="tok-cm"> * @param types types of events the listener should be notified for</span> 2833<span class="tok-cm"> */</span> 2834<span class="tok-kt">void</span> <span class="tok-nf">addEventListener</span><span class="tok-o">(</span><span class="tok-n">ActivitiEventListener</span> <span class="tok-n">listenerToAdd</span><span class="tok-o">,</span> <span class="tok-n">ActivitiEventType</span><span class="tok-o">...</span> <span class="tok-n">types</span><span class="tok-o">);</span> 2835 2836<span class="tok-cm">/**</span> 2837<span class="tok-cm"> * Removes the given listener from this dispatcher. The listener will no longer be notified,</span> 2838<span class="tok-cm"> * regardless of the type(s) it was registered for in the first place.</span> 2839<span class="tok-cm"> * @param listenerToRemove listener to remove</span> 2840<span class="tok-cm"> */</span> 2841 <span class="tok-kt">void</span> <span class="tok-nf">removeEventListener</span><span class="tok-o">(</span><span class="tok-n">ActivitiEventListener</span> <span class="tok-n">listenerToRemove</span><span class="tok-o">);</span> 2842</td></tr></table></code></pre> 2843</div> 2844</div> 2845<div class="paragraph"> 2846<p>Please note that the listeners added at runtime <strong>are not retained when the engine is rebooted.</strong></p> 2847</div> 2848</div> 2849<div class="sect3"> 2850<h4 id="eventDispatcherConfigurationProcessDefinition">3.17.4. Adding listeners to process definitions</h4> 2851<div class="paragraph"> 2852<p>It’
2852s possible to add listeners to a specific process-definition. The listeners will only be called for events related to the process definition and to all events related to process instances that are started with that specific process definition. The listener implementations can be defined using a fully qualified classname, an expression that resolves to a bean that implements the listener interface or can be configured to throw a message/signal/error BPMN event.</p> 2853</div> 2854<div class="sect4"> 2855<h5 id="_listeners_executing_user_defined_logic">Listeners executing user-defined logic</h5> 2856<div class="paragraph"> 2857<p>The snippet below adds 2 listeners to a process-definition. The first listener will receive events of any type, with a listener implementation based on a fully-qualified class name. The second listener is only notified when a job is successfully executed or when it failed, using a listener that has been defined in the <code>beans</code> property of the process engine configuration.</p> 2858</div> 2859<div class="listingblock"> 2860<div class="content"> 2861<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 28622 28633 28644 28655 28666 28677 28688 28699</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"testEventListeners"</span><span class="tok-nt">></span> 2870 <span class="tok-nt"><extensionElements></span> 2871 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.test.MyEventListener"</span> <span class="tok-nt">/></span> 2872 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">delegateExpression=</span><span class="tok-s">"${testEventListener}"</span> <span class="tok-na">events=</span><span class="tok-s">"JOB_EXECUTION_SUCCESS,JOB_EXECUTION_FAILURE"</span> <span class="tok-nt">/></span> 2873 <span class="tok-nt"></extensionElements></span> 2874 2875 ... 2876 2877<span class="tok-nt"></process></span> 2878</td></tr></table></code></pre> 2879</div> 2880</div> 2881<div class="paragraph"> 2882<p>For events related to entities, it’s also possible to add listeners to a process-definition that get only notified when entity-events occur for a certain entity type. The snippet below shows how this can be achieved. It can be used along for ALL entity-events (first example) or for specific event types only (second example).</p> 2883</div> 2884<div class="listingblock"> 2885<div class="content"> 2886<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 28872 28883 28894 28905 28916 28927 28938 28949</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"testEventListeners"</span><span class="tok-nt">></span> 2895 <span class="tok-nt"><extensionElements></span> 2896 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.test.MyEventListener"</span> <span class="tok-na">entityType=</span><span class="tok-s">"task"</span> <span class="tok-nt">/></span> 2897 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">delegateExpression=</span><span class="tok-s">"${testEventListener}"</span> <span class="tok-na">events=</span><span class="tok-s">"ENTITY_CREATED"</span> <span class="tok-na">entityType=</span><span class="tok-s">"task"</span> <span class="tok-nt">/></span> 2898 <span class="tok-nt"></extensionElements></span> 2899 2900 ... 2901 2902<span class="tok-nt"></process></span> 2903</td></tr></table></code></pre> 2904</div> 2905</div> 2906<div class="paragraph"> 2907<p>Supported values for the <code>entityType</code> are: <code>attachment</code>, <code>comment</code>, <code>execution</code>, <code>identity-link</code>, <code>job</code>, <code>process-instance</code>, <code>process-definition</code>, <code>task</code>.</p> 2908</div> 2909</div> 2910<div class="sect4"> 2911<h5 id="_listeners_throwing_bpmn_events">Listeners throwing BPMN events</h5> 2912<div class="paragraph"> 2913<p><a href="#experimental">[EXPERIMENTAL]</a></p> 2914</div> 2915<div class="paragraph"> 2916<p>Another way of handling events being dispatched is to throw a BPMN event. Please bear in mind that it only makes sense to throw BPMN-events with certain kinds of Activiti event types. For example, throwing a BPMN event when the process-instance is deleted will result in an error. The snippet below shows how to throw a signal inside process-instance, throw a signal to an external process (global), throw a message-event inside the process-instance and throw an error-event inside the process-instance. Instead of using the <code>class</code> or <code>delegateExpression</code>, the attribute <code>throwEvent</code> is used, along with an additional attribute, specific to the type of event being thrown.</p> 2917</div> 2918<div class="listingblock"> 2919<div class="content"> 2920<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 29212 29223 29234 29245</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"testEventListeners"</span><span class="tok-nt">></span> 2925 <span class="tok-nt"><extensionElements></span> 2926 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">throwEvent=</span><span class="tok-s">"signal"</span> <span class="tok-na">signalName=</span><span class="tok-s">"My signal"</span> <span class="tok-na">events=</span><span class="tok-s">"TASK_ASSIGNED"</span> <span class="tok-nt">/></span> 2927 <span class="tok-nt"></extensionElements></span> 2928<span class="tok-nt"></process></span> 2929</td></tr></table></code></pre> 2930</div> 2931</div> 2932<div class="listingblock"> 2933<div class="content"> 2934<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 29352 29363 29374 29385</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"testEventListeners"</span><span class="tok-nt">></span> 2939 <span class="tok-nt"><extensionElements></span> 2940 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">throwEvent=</span><span class="tok-s">"globalSignal"</span> <span class="tok-na">signalName=</span><span class="tok-s">"My signal"</span> <span class="tok-na">events=</span><span class="tok-s">"TASK_ASSIGNED"</span> <span class="tok-nt">/></span> 2941 <span class="tok-nt"></extensionElements></span> 2942<span class="tok-nt"></process></span> 2943</td></tr></table></code></pre> 2944</div> 2945</div> 2946<div class="listingblock"> 2947<div class="content"> 2948<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 29492 29503 29514 29525</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"testEventListeners"</span><span class="tok-nt">></span> 2953 <span class="tok-nt"><extensionElements></span> 2954 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">throwEvent=</span><span class="tok-s">"message"</span> <span class="tok-na">messageName=</span><span class="tok-s">"My message"</span> <span class="tok-na">events=</span><span class="tok-s">"TASK_ASSIGNED"</span> <span class="tok-nt">/></span> 2955 <span class="tok-nt"></extensionElements></span> 2956<span class="tok-nt"></process></span> 2957</td></tr></table></code></pre> 2958</div> 2959</div> 2960<div class="listingblock"> 2961<div class="content"> 2962<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 29632 29643 29654 29665</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"testEventListeners"</span><span class="tok-nt">></span> 2967 <span class="tok-nt"><extensionElements></span> 2968 <span class="tok-nt"><activiti:eventListener</span> <span class="tok-na">throwEvent=</span><span class="tok-s">"error"</span> <span class="tok-na">errorCode=</span><span class="tok-s">"123"</span> <span class="tok-na">events=</span><span class="tok-s">"TASK_ASSIGNED"</span> <span class="tok-nt">/></span> 2969 <span class="tok-nt"></extensionElements></span> 2970<span class="tok-nt"></process></span> 2971</td></tr></table></code></pre> 2972</div> 2973</div> 2974<div class="paragraph"> 2975<p>If additional logic is needed to decide whether or not to throw the BPMN-event, it’s possible to extend the listener-classes provided by Activiti. By overriding the <code>isValidEvent(ActivitiEvent event) in your subclass, the BPMN-event throwing can be prevented. The classes involved are +org.activiti.engine.test.api.event.SignalThrowingEventListenerTest</code>, <code>org.activiti.engine.impl.bpmn.helper.MessageThrowingEventListener</code> and <code>org.activiti.engine.impl.bpmn.helper.ErrorThrowingEventListener</code>.</p> 2976</div> 2977</div> 2978<div class="sect4"> 2979<h5 id="_notes_on_listeners_on_a_process_definition">Notes on listeners on a process-definition</h5> 2980<div class="ulist"> 2981<ul> 2982<li> 2983<p>Event-listeners can only be declared on the <code>process</code> element, as a child-element of the <code>extensionElements</code>. Listeners cannot be defined on individual activities in the process.</p> 2984</li> 2985<li> 2986<p>Expressions used in the <code>delegateExpression</code> do not have access to the execution-context, as other expressions (e.g. in gateways) have. They can only reference beans defined in the <code>beans</code> property of the process engine configuration or when using spring (and the beans property is absent) to any spring-bean that implements the listener interface.</p> 2987</li> 2988<li> 2989<p>When using the <code>class</code> attribute of a listener, there will only be a single instance of that class created. Make sure the listener implementations do not rely on member-fields or ensure safe usage from multiple threads/contexts.</p> 2990</li> 2991<li> 2992<p>When an illegal event-type is used in the <code>events</code> attribute or illegal <code>throwEvent</code> value is used, an exception will be thrown when the process-definition is deployed (effectively failing the deployment). When an illegal value for <code>class</code> or <code>delegateExecution</code> is supplied (either a nonexistent class, a nonexistent bean reference or a delegate not implementing listener interface), an exception will be thrown when the process is started (or when the first valid event for that process-definition is dispatched to the listener). Make sure the referenced classes are on the classpath and that the expressions resolve to a valid instance.</p> 2993</li> 2994</ul> 2995</div> 2996</div> 2997</div> 2998<div class="sect3"> 2999<h4 id="eventDispatcherCustomEvents">3.17.5. Dispatching events through API</h4> 3000<div class="paragraph"> 3001<p>We opened up the event-dispatching mechanism through the API, to allow you to dispatch custom events to any listeners that are registered in the engine. It’s recommended (although not enforced) to only dispatch <code>ActivitiEvents</code> with type <code>CUSTOM</code>. Dispatching the event can be done using the <code>RuntimeService</code>:</p> 3002</div> 3003<div class="listingblock"> 3004<div class="content"> 3005<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 30062 30073 30084 30095 30106 30117 30128 30139</div></td><td class="code"><span></span><span class="tok-cm">/**</span> 3014<span class="tok-cm"> * Dispatches the given event to any listeners that are registered.</span> 3015<span class="tok-cm"> * @param event event to dispatch.</span> 3016<span class="tok-cm"> *</span> 3017<span class="tok-cm">
3017 * @throws ActivitiException if an exception occurs when dispatching the event or when the {@link ActivitiEventDispatcher}</span> 3018<span class="tok-cm"> * is disabled.</span> 3019<span class="tok-cm"> * @throws ActivitiIllegalArgumentException when the given event is not suitable for dispatching.</span> 3020<span class="tok-cm"> */</span> 3021 <span class="tok-kt">void</span> <span class="tok-nf">dispatchEvent</span><span class="tok-o">(</span><span class="tok-n">ActivitiEvent</span> <span class="tok-n">event</span><span class="tok-o">);</span> 3022</td></tr></table></code></pre> 3023</div> 3024</div> 3025</div> 3026<div class="sect3"> 3027<h4 id="eventDispatcherEventTypes">3.17.6. Supported event types</h4> 3028<div class="paragraph"> 3029<p>Listed below are all event types that can occur in the engine. Each type corresponds to an enum value in the <code>org.activiti.engine.delegate.event.ActivitiEventType</code>.</p> 3030</div> 3031<table id="eventTypes" class="tableblock frame-all grid-all spread"> 3032<caption class="title">Table 1. Supported events</caption> 3033<colgroup> 3034<col style="width: 33.3333%;"> 3035<col style="width: 33.3333%;"> 3036<col style="width: 33.3334%;"> 3037</colgroup> 3038<thead> 3039<tr> 3040<th class="tableblock halign-left valign-top">Event name</th> 3041<th class="tableblock halign-left valign-top">Description</th> 3042<th class="tableblock halign-left valign-top">Event classes</th> 3043</tr> 3044</thead> 3045<tbody> 3046<tr> 3047<td class="tableblock halign-left valign-top"><p class="tableblock">ENGINE_CREATED</p></td> 3048<td class="tableblock halign-left valign-top"><p class="tableblock">The process-engine this listener is attached to, has been created and is ready for API-calls.</p></td> 3049<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEvent</code></p></td> 3050</tr> 3051<tr> 3052<td class="tableblock halign-left valign-top"><p class="tableblock">ENGINE_CLOSED</p></td> 3053<td class="tableblock halign-left valign-top"><p class="tableblock">The process-engine this listener is attached to, has been closed. API-calls to the engine are no longer possible.</p></td> 3054<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEvent</code></p></td> 3055</tr> 3056<tr> 3057<td class="tableblock halign-left valign-top"><p class="tableblock">ENTITY_CREATED</p></td> 3058<td class="tableblock halign-left valign-top"><p class="tableblock">A new entity is created. The new entity is contained in the event.</p></td> 3059<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3060</tr> 3061<tr> 3062<td class="tableblock halign-left valign-top"><p class="tableblock">ENTITY_INITIALIZED</p></td> 3063<td class="tableblock halign-left valign-top"><p class="tableblock">A new entity has been created and is fully initialized. If any children are created as part of the creation of an entity, this event will be fired AFTER the create/initialisation of the child entities as opposed to the <code>ENTITY_CREATE</code> event.</p></td> 3064<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3065</tr> 3066<tr> 3067<td class="tableblock halign-left valign-top"><p class="tableblock">ENTITY_UPDATED</p></td> 3068<td class="tableblock halign-left valign-top"><p class="tableblock">An existing is updated. The updated entity is contained in the event.</p></td> 3069<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3070</tr> 3071<tr> 3072<td class="tableblock halign-left valign-top"><p class="tableblock">ENTITY_DELETED</p></td> 3073<td class="tableblock halign-left valign-top"><p class="tableblock">An existing entity is deleted. The deleted entity is contained in the event.</p></td> 3074<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3075</tr> 3076<tr> 3077<td class="tableblock halign-left valign-top"><p class="tableblock">ENTITY_SUSPENDED</p></td> 3078<td class="tableblock halign-left valign-top"><p class="tableblock">An existing entity is suspended. The suspended entity is contained in the event. Will be dispatched for ProcessDefinitions, ProcessInstances and Tasks.</p></td> 3079<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3080</tr> 3081<tr> 3082<td class="tableblock halign-left valign-top"><p class="tableblock">ENTITY_ACTIVATED</p></td> 3083<td class="tableblock halign-left valign-top"><p class="tableblock">An existing entity is activated. The activated entity is contained in the event. Will be dispatched for ProcessDefinitions, ProcessInstances and Tasks.</p></td> 3084<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3085</tr> 3086<tr> 3087<td class="tableblock halign-left valign-top"><p class="tableblock">JOB_EXECUTION_SUCCESS</p></td> 3088<td class="tableblock halign-left valign-top"><p class="tableblock">A job has been executed successfully. The event contains the job that was executed.</p></td> 3089<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3090</tr> 3091<tr> 3092<td class="tableblock halign-left valign-top"><p class="tableblock">JOB_EXECUTION_FAILURE</p></td> 3093<td class="tableblock halign-left valign-top"><p class="tableblock">The execution of a job has failed. The event contains the job that was executed and the exception.</p></td> 3094<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code> and <code>org.activiti…​ActivitiExceptionEvent</code></p></td> 3095</tr> 3096<tr> 3097<td class="tableblock halign-left valign-top"><p class="tableblock">
3097JOB_RETRIES_DECREMENTED</p></td> 3098<td class="tableblock halign-left valign-top"><p class="tableblock">The number of job retries have been decremented due to a failed job. The event contains the job that was updated.</p></td> 3099<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3100</tr> 3101<tr> 3102<td class="tableblock halign-left valign-top"><p class="tableblock">TIMER_FIRED</p></td> 3103<td class="tableblock halign-left valign-top"><p class="tableblock">A timer has been fired. The event contains the job that was executed?</p></td> 3104<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3105</tr> 3106<tr> 3107<td class="tableblock halign-left valign-top"><p class="tableblock">JOB_CANCELED</p></td> 3108<td class="tableblock halign-left valign-top"><p class="tableblock">A job has been canceled. The event contains the job that was canceled. Job can be canceled by 3109 API call, task was completed and associated boundary timer was canceled, on the new process definition 3110 deployment.</p></td> 3111<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3112</tr> 3113<tr> 3114<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_STARTED</p></td> 3115<td class="tableblock halign-left valign-top"><p class="tableblock">An activity is starting to execute</p></td> 3116<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiActivityEvent</code></p></td> 3117</tr> 3118<tr> 3119<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_COMPLETED</p></td> 3120<td class="tableblock halign-left valign-top"><p class="tableblock">An activity is completed successfully</p></td> 3121<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiActivityEvent</code></p></td> 3122</tr> 3123<tr> 3124<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_CANCELLED</p></td> 3125<td class="tableblock halign-left valign-top"><p class="tableblock">An activity is going to be cancelled. There can be three reasons for activity cancellation (MessageEventSubscriptionEntity, SignalEventSubscriptionEntity, TimerEntity).</p></td> 3126<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiActivityCancelledEvent</code></p></td> 3127</tr> 3128<tr> 3129<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_SIGNALED</p></td> 3130<td class="tableblock halign-left valign-top"><p class="tableblock">An activity received a signal</p></td> 3131<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiSignalEvent</code></p></td> 3132</tr> 3133<tr> 3134<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_MESSAGE_RECEIVED</p></td> 3135<td class="tableblock halign-left valign-top"><p class="tableblock">An activity received a message. Dispatched before the activity receives the message. When received, a <code>ACTIVITY_SIGNAL</code> or <code>ACTIVITY_STARTED</code> will 3136 be dispatched for this activity, depending on the type (boundary-event or event-subprocess start-event)</p></td> 3137<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiMessageEvent</code></p></td> 3138</tr> 3139<tr> 3140<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_ERROR_RECEIVED</p></td> 3141<td class="tableblock halign-left valign-top"><p class="tableblock">An activity has received an error event. Dispatched before the actual error has been handled by 3142 the activity. The event’s <code>activityId</code> contains a reference to the error-handling activity. 3143 This event will be either followed by a <code>ACTIVITY_SIGNALLED</code> event or <code>ACTIVITY_COMPLETE</code> 3144 for the involved activity, if the error was delivered successfully.</p></td> 3145<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiErrorEvent</code></p></td> 3146</tr> 3147<tr> 3148<td class="tableblock halign-left valign-top"><p class="tableblock">UNCAUGHT_BPMN_ERROR</p></td> 3149<td class="tableblock halign-left valign-top"><p class="tableblock">An uncaught BPMN error has been thrown. The process did not have any handlers for that specific error. The event’s <code>activityId</code> will be empty.</p></td> 3150<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiErrorEvent</code></p></td> 3151</tr> 3152<tr> 3153<td class="tableblock halign-left valign-top"><p class="tableblock">ACTIVITY_COMPENSATE</p></td> 3154<td class="tableblock halign-left valign-top"><p class="tableblock">An activity is about to be compensated. The event contains the id of the activity that is will be executed for compensation.</p></td> 3155<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiActivityEvent</code></p></td> 3156</tr> 3157<tr> 3158<td class="tableblock halign-left valign-top"><p class="tableblock">VARIABLE_CREATED</p></td> 3159<td class="tableblock halign-left valign-top"><p class="tableblock">A variable has been created. The event contains the variable name, value and related execution and task (if any).</p></td> 3160<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiVariableEvent</code></p></td> 3161</tr> 3162<tr> 3163<td class="tableblock halign-left valign-top"><p class="tableblock">VARIABLE_UPDATED</p></td> 3164<td class="tableblock halign-left valign-top"><p class="tableblock">An existing variable has been updated. The event contains the variable name, updated value and related execution and task (if any).</p></td> 3165<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiVariableEvent</code></p></td> 3166</tr> 3167<tr> 3168<td class="tableblock halign-left valign-top"><p class="tableblock">VARIABLE_DELETED</p></td> 3169<td class="tableblock halign-left valign-top"><p class="tableblock">An existing variable has been deleted. The event contains the variable name, last known value and related execution and task (if any).</p></td> 3170<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiVariableEvent</code></p></td> 3171</tr> 3172<tr> 3173<td class="tableblock halign-left valign-top"><p class="tableblock">TASK_ASSIGNED</p></td> 3174<td class="tableblock halign-left valign-top"><p class="tableblock">A task has been assigned to a user. The event contains the task</p></td> 3175<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3176</tr> 3177<tr> 3178<td class="tableblock halign-left valign-top"><p class="tableblock">TASK_CREATED</p></td> 3179<td class="tableblock halign-left valign-top"><p class="tableblock">A task has been created. This is dispatched after the <code>ENTITY_CREATE</code> event. In case the task is part of a process, this event will be 3180 fired before the task listeners are executed.</p></td> 3181<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3182</tr> 3183<tr> 3184<td class="tableblock halign-left valign-top"><p class="tableblock">TASK_COMPLETED</p></td> 3185<td class="tableblock halign-left valign-top"><p class="tableblock">A task has been completed. This is dispatched before the <code>ENTITY_DELETE</code> event. In case the task is part of a process, this event will be 3186 fired before the process has moved on and will be followed by a <code>ACTIVITY_COMPLETE</code> event, targeting the activity that represents the completed task.</p></td> 3187<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3188</tr> 3189<tr> 3190<td class="tableblock halign-left valign-top"><p class="tableblock">PROCESS_COMPLETED</p></td> 3191<td class="tableblock halign-left valign-top"><p class="tableblock">A process has been completed. Dispatched after the last activity <code>ACTIVITY_COMPLETED </code> event. Process is completed when it reaches state in which process instance does not have 3192 any transition to take.</p></td> 3193<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiEntityEvent</code></p></td> 3194</tr> 3195<tr> 3196<td class="tableblock halign-left valign-top"><p class="tableblock">PROCESS_CANCELLED</p></td> 3197<td class="tableblock halign-left valign-top"><p class="tableblock">A process has been cancelled. Dispatched before the process instance is deleted from runtime. Process instance is cancelled by API call <code>RuntimeService.deleteProcessInstance</code></p></td> 3198<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiCancelledEvent</code></p></td> 3199</tr> 3200<tr> 3201<td class="tableblock halign-left valign-top"><p class="tableblock">MEMBERSHIP_CREATED</p></td> 3202<td class="tableblock halign-left valign-top"><p class="tableblock">A user has been added to a group. The event contains the ids of the user and group involved.</p></td> 3203<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiMembershipEvent</code></p></td> 3204</tr> 3205<tr> 3206<td class="tableblock halign-left valign-top"><p class="tableblock">MEMBERSHIP_DELETED</p></td> 3207<td class="tableblock halign-left valign-top"><p class="tableblock">A user has been removed from a group. The event contains the ids of the user and group involved.</p></td> 3208<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiMembershipEvent</code></p></td> 3209</tr> 3210<tr> 3211<td class="tableblock halign-left valign-top"><p class="tableblock">
3211MEMBERSHIPS_DELETED</p></td> 3212<td class="tableblock halign-left valign-top"><p class="tableblock">All members will be removed from a group. The event is thrown before the members are removed, so they are still accessible. No individual 3213 <code>MEMBERSHIP_DELETED</code> events will be thrown if all members are deleted at once, for performance reasons.</p></td> 3214<td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.activiti…​ActivitiMembershipEvent</code></p></td> 3215</tr> 3216</tbody> 3217</table> 3218<div class="paragraph"> 3219<p>All <code>ENTITY_\*</code> events are related to entities inside the engine. The list below show an overview of what entity-events are dispatched for which entities:</p> 3220</div> 3221<div class="ulist"> 3222<ul> 3223<li> 3224<p><strong><code>ENTITY_CREATED, ENTITY_INITIALIZED, ENTITY_DELETED</code></strong>: Attachment, Comment, Deployment, Execution, Group, IdentityLink, Job, Model, ProcessDefinition, ProcessInstance, Task, User.</p> 3225</li> 3226<li> 3227<p><strong><code>ENTITY_UPDATED</code></strong>: Attachment, Deployment, Execution, Group, IdentityLink, Job, Model, ProcessDefinition, ProcessInstance, Task, User.</p> 3228</li> 3229<li> 3230<p><strong><code>ENTITY_SUSPENDED, ENTITY_ACTIVATED</code></strong>: ProcessDefinition, ProcessInstance/Execution, Task.</p> 3231</li> 3232</ul> 3233</div> 3234</div> 3235<div class="sect3"> 3236<h4 id="eventDispatcherRemarks">3.17.7. Additional remarks</h4> 3237<div class="paragraph"> 3238<p><strong>Only listeners are notified in the engine the events are dispatched from.</strong> So in case you have different engines - running against the same database - only events that originated in the engine the listener is registered for, are dispatched to that listener. The events that occur in the other engine are not dispatched to the listeners, regardless of the fact they are running in the same JVM or not.</p> 3239</div> 3240<div class="paragraph"> 3241<p>Certain event-types (related to entities) expose the targeted entity. Depending on the type or event, these entities cannot be updated anymore (e.g. when the entity is deleted). If possible, use the <code>EngineServices</code> exposed by the event to interact in a safe way with the engine. Even then, you need to be cautious with updates/operations on entities that are involved in the dispatched event.</p> 3242</div> 3243<div class="paragraph"> 3244<p>No entity-events are dispatched related to history, as they all have a runtime-counterpart which have their events dispatched.</p> 3245</div> 3246</div> 3247</div> 3248</div> 3249</div> 3250<div class="sect1"> 3251<h2 id="chapterApi">4. The Activiti API</h2> 3252<div class="sectionbody"> 3253<div class="sect2"> 3254<h3 id="apiEngine">4.1. The Process Engine API and services</h3> 3255<div class="paragraph"> 3256<p>The engine API is the most common way of interacting with Activiti. The central starting point is the <code>ProcessEngine</code>, which can be created in several ways as described in the <a href="#configuration">configuration section</a>. From the ProcessEngine, you can obtain the various services that contain the workflow/BPM methods. ProcessEngine and the services objects are thread safe. So you can keep a reference to 1 of those for a whole server.</p> 3257</div> 3258<div class="imageblock" style="text-align: center"> 3259<div class="content"> 3260<img src="images/api.services.png" alt="api.services"> 3261</div> 3262</div> 3263<div class="listingblock"> 3264<div class="content"> 3265<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 3266 2 3267 3 3268 4 3269 5 3270 6 3271 7 3272 8 3273 9 327410</div></td><td class="code"><span></span><span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">getDefaultProcessEngine</span><span class="tok-o">();</span> 3275 3276<span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRuntimeService</span><span class="tok-o">();</span> 3277<span class="tok-n">RepositoryService</span> <span class="tok-n">repositoryService</span> <span class="tok-o">=</span> <span class="tok-n">
3277processEngine</span><span class="tok-o">.</span><span class="tok-na">getRepositoryService</span><span class="tok-o">();</span> 3278<span class="tok-n">TaskService</span> <span class="tok-n">taskService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getTaskService</span><span class="tok-o">();</span> 3279<span class="tok-n">ManagementService</span> <span class="tok-n">managementService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getManagementService</span><span class="tok-o">();</span> 3280<span class="tok-n">IdentityService</span> <span class="tok-n">identityService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getIdentityService</span><span class="tok-o">();</span> 3281<span class="tok-n">HistoryService</span> <span class="tok-n">historyService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getHistoryService</span><span class="tok-o">();</span> 3282<span class="tok-n">FormService</span> <span class="tok-n">formService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getFormService</span><span class="tok-o">();</span> 3283<span class="tok-n">DynamicBpmnService</span> <span class="tok-n">dynamicBpmnService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getDynamicBpmnService</span><span class="tok-o">();</span> 3284</td></tr></table></code></pre> 3285</div> 3286</div> 3287<div class="paragraph"> 3288<p><code>ProcessEngines.getDefaultProcessEngine()</code> will initialize and build a process engine the first time it is called and afterwards always return the same process engine. Proper creation and closing of all process engines can be done with <code>ProcessEngines.init()</code> and <code>ProcessEngines.destroy()</code>.</p> 3289</div> 3290<div class="paragraph"> 3291<p>The ProcessEngines class will scan for all <code>activiti.cfg.xml</code> and <code>activiti-context.xml</code> files. For all <code>activiti.cfg.xml</code> files, the process engine will be built in the typical Activiti way: <code>ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(inputStream).buildProcessEngine()</code>. For all <code>activiti-context.xml</code> files, the process engine will be built in the Spring way: First the Spring application context is created and then the process engine is obtained from that application context.</p> 3292</div> 3293<div class="paragraph"> 3294<p>All services are stateless. This means that you can easily run Activiti on multiple nodes in a cluster, each going to the same database, without having to worry about which machine actually executed previous calls. Any call to any service is idempotent regardless of where it is executed.</p> 3295</div> 3296<div class="paragraph"> 3297<p>The <strong>RepositoryService</strong> is probably the first service needed when working with the Activiti engine. This service offers operations for managing and manipulating <code>deployments</code> and <code>process definitions</code>. Without going into much detail here, a process definition is a Java counterpart of BPMN 2.0 process. It is a representation of the structure and behaviour of each of the steps of a process. A <code>deployment</code> is the unit of packaging within the Activiti engine. A deployment can contain multiple BPMN 2.0 xml files and any other resource. The choice of what is included in one deployment is up to the developer. It can range from a single process BPMN 2.0 xml file to a whole package of processes and relevant resources (for example the deployment <em>hr-processes</em> could contain everything related to hr processes). The <code>RepositoryService</code> allows to <code>deploy</code> such packages. Deploying a deployment means it is uploaded to the engine, where all processes are inspected and parsed before being stored in the database. From that point on, the deployment is known to the system and any process included in the deployment can now be started.</p> 3298</div> 3299<div class="paragraph"> 3300<p>Furthermore, this service allows to</p> 3301</div> 3302<div class="ulist"> 3303<ul> 3304<li> 3305<p>Query on deployments and process definitions known to the engine.</p> 3306</li> 3307<li> 3308<p>Suspend and activate deployments as a whole or specific process definitions. Suspending means no further operations can be done on them, while activation is the opposite operation.</p> 3309</li> 3310<li> 3311<p>Retrieve various resources such as files contained within the deployment or process diagrams that were auto generated by the engine.</p> 3312</li> 3313<li> 3314<p>Retrieve a POJO version of the process definition which can be used to introspect the process using Java rather than xml.</p> 3315</li> 3316</ul> 3317</div> 3318<div class="paragraph"> 3319<p>While the <code>RepositoryService</code> is rather about static information (i.e. data that doesn’t change, or at least not a lot), the <strong>RuntimeService</strong> is quite the opposite. It deals with starting new process instances of process definitions. As said above, a <code>process definition</code> defines the structure and behaviour of the different steps in a process. A process instance is one execution of such a process definition. For each process definition there typically are many instances running at the same time. The <code>RuntimeService</code> also is the service which is used to retrieve and store <code>process variables</code>. This is data which is specific to the given process instance and can be used by various constructs in the process (e.g. an exclusive gateway often uses process variables to determine which path is chosen to continue the process). The <code>Runtimeservice</code> also allows to query on process instances and executions. Executions are a representation of the <code>'token'</code> concept of BPMN 2.0. Basically an execution is a pointer pointing to where the process instance currently is. Lastly, the <code>RuntimeService</code> is used whenever a process instance is waiting for an external trigger and the process needs to be continued. A process instance can have various <code>wait states</code> and this service contains various operations to <em>signal</em> the instance that the external trigger is received and the process instance can be continued.</p> 3320</div> 3321<div class="paragraph"> 3322<p>Tasks that need to be performed by actual human users of the system are core to a BPM engine such as Activiti. Everything around tasks is grouped in the <strong>TaskService</strong>, such as</p> 3323</div> 3324<div class="ulist"> 3325<ul> 3326<li> 3327<p>Querying tasks assigned to users or groups</p> 3328</li> 3329<li> 3330<p>Creating new <em>standalone</em> tasks. These are tasks that are not related to a process instances.</p> 3331</li> 3332<li> 3333<p>Manipulating to which user a task is assigned or which users are in some way involved with the task.</p> 3334</li> 3335<li> 3336<p>Claiming and completing a task. Claiming means that someone decided to be the assignee for the task, meaning that this user will c
3336omplete the task. Completing means <em>doing the work of the tasks</em>. Typically this is filling in a form of sorts.</p> 3337</li> 3338</ul> 3339</div> 3340<div class="paragraph"> 3341<p>The <strong>IdentityService</strong> is pretty simple. It allows the management (creation, update, deletion, querying, …​) of groups and users. It is important to understand that Activiti actually doesn’t do any checking on users at runtime. For example, a task could be assigned to any user, but the engine does not verify if that user is known to the system. This is because the Activiti engine can also be used in conjunction with services such as LDAP, Active Directory, etc.</p> 3342</div> 3343<div class="paragraph"> 3344<p>The <strong>FormService</strong> is an optional service. Meaning that Activiti can perfectly be used without it, without sacrificing any functionality. This service introduces the concept of a <em>start form</em> and a <em>task form</em>. A <em>start form</em> is a form that is shown to the user before the process instance is started, while a <em>task form</em> is the form that is displayed when a user wants to complete a form. Activiti allows to define these forms in the BPMN 2.0 process definition. This service exposes this data in an easy way to work with. But again, this is optional as forms don’t need to be embedded in the process definition.</p> 3345</div> 3346<div class="paragraph"> 3347<p>The <strong>HistoryService</strong> exposes all historical data gathered by the Activiti engine. When executing processes, a lot of data can be kept by the engine (this is configurable) such as process instance start times, who did which tasks, how long it took to complete the tasks, which path was followed in each process instance, etc. This service exposes mainly query capabilities to access this data.</p> 3348</div> 3349<div class="paragraph"> 3350<p>The <strong>ManagementService</strong> is typically not needed when coding custom application using Activiti. It allows to retrieve information about the database tables and table metadata. Furthermore, it exposes query capabilities and management operations for jobs. Jobs are used in Activiti for various things such as timers, asynchronous continuations, delayed suspension/activation, etc. Later on, these topics will be discussed in more detail.</p> 3351</div> 3352<div class="paragraph"> 3353<p>The <strong>DynamicBpmnService</strong> can be used to change part of the process definition without needing to redeploy it. You can for example change the assignee definition for a user task in a process definition, or change the class name of a service task.</p> 3354</div> 3355<div class="paragraph"> 3356<p>For more detailed information on the service operations and the engine API, see <a href="http://activiti.org/javadocs/index.html">the javadocs</a>.</p> 3357</div> 3358</div> 3359<div class="sect2"> 3360<h3 id="_exception_strategy">4.2. Exception strategy</h3> 3361<div class="paragraph"> 3362<p>The base exception in Activiti is the <code>org.activiti.engine.ActivitiException</code>, an unchecked exception. This exception can be thrown at all times by the API, but <em>expected</em> exceptions that happen in specific methods are documented in the <a href="http://activiti.org/javadocs/index.html"> the javadocs</a>. For example, an extract from <code>TaskService</code>:</p> 3363</div> 3364<div class="listingblock"> 3365<div class="content"> 3366<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 33672 33683 33694 33705 33716</div></td><td class="code"><span></span><span class="tok-cm">/**</span> 3372<span class="tok-cm"> * Called when the task is successfully executed.</span> 3373<span class="tok-cm"> * @param taskId the id of the task to complete, cannot be null.</span> 3374<span class="tok-cm"> * @throws ActivitiObjectNotFoundException when no task exists with the given id.</span> 3375<span class="tok-cm"> */</span> 3376 <span class="tok-kt">void</span> <span class="tok-nf">complete</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">taskId</span><span class="tok-o">);</span> 3377</td></tr></table></code></pre> 3378</div> 3379</div> 3380<div class="paragraph"> 3381<p>In the example above, when an id is passed for which no task exists, an exception will be thrown. Also, since the javadoc <strong>explicitly states that taskId cannot be null, an <code>ActivitiIllegalArgumentException</code> will be thrown when <code>null</code> is passed</strong>.</p> 3382</div> 3383<div class="paragraph"> 3384<p>Even though we want to avoid a big exception hierarchy, the following subclasses were added which are thrown in specific cases. All other errors that occur during process-execution or API-invocation that don’t fit into the possible exceptions below, are thrown as regular <code>ActivitiExceptions</code>s.</p> 3385</div> 3386<div class="ulist"> 3387<ul> 3388<li> 3389<p><code>ActivitiWrongDbException</code>: Thrown when the Activiti engine discovers a mismatch between the database schema version and the engine version.</p> 3390</li> 3391<li> 3392<p><code>ActivitiOptimisticLockingException</code>: Thrown when an optimistic locking occurs in the data store caused by concurrent access of the same data entry.</p> 3393</li> 3394<li> 3395<p><code>ActivitiClassLoadingException</code>: Thrown when a class requested to load was not found or when an error occurred while loading it (e.g. JavaDelegates, TaskListeners, …​).</p> 3396</li> 3397<li> 3398<p><code>ActivitiObjectNotFoundException</code>: Thrown when an object that is requested or action on does not exist.</p> 3399</li> 3400<li> 3401<p><code>ActivitiIllegalArgumentException</code>: An exception indicating that an illegal argument has been supplied in an Activiti API-call, an illegal value was configured in the engine’s configuration or an illegal value has been supplied or an illegal value is used in a process-definition.</p> 3402</li> 3403<li> 3404<p><code>ActivitiTaskAlreadyClaimedException</code>: Thrown when a task is already claimed, when the <code>taskService.claim(…​)</code> is called.</p> 3405</li> 3406</ul> 3407</div> 3408</div> 3409<div class="sect2"> 3410<h3 id="api.services">4.3. Working with the Activiti services</h3> 3411<div class="paragraph"> 3412<p>As described above, the way to interact with the Activiti engine is through the services exposed by an instance of the <code>org.activiti.engine.ProcessEngine</code> class. The following code snippets assume you have a working Activiti environment, i.e. you have access to a valid <code>org.activiti.engine.ProcessEngine</code>. If you simply want to try out the code below, you can download or clone the <a href="https://github.com/Activiti/activiti-unit-test-template">Activiti unit test template</a>, import it in your IDE and add a <code>testUserguideCode()</code> method to the <code>org.activiti.MyUnitTest</code> unit test.</p> 3413</div> 3414<div class="paragraph"> 3415<p>The end goal of this little tutorial will be to have a working business process which mimics a simplistic vacation request process at a company:</p> 3416</div> 3417<div class="imageblock" style="text-align: center"> 3418<div class="content"> 3419<img src="images/api.vacationRequest.png" alt="api.vacationRequest"> 3420</div> 3421</div> 3422<div class="sect3"> 3423<h4 id="api.services.deployment">4.3.1. Deploying the process</h4> 3424<div class="paragraph"> 3425<p>Everything that is related to <em>static</em> data (such as process definitions) are accessed through the <strong>RepositoryService</strong>. Conceptually, every such static piece of data is content of the <em>repository</em> of the Activiti engine.</p> 3426</div> 3427<div class="paragraph"> 3428<p>Create a new xml file <code>VacationRequest.bpmn20.xml</code> in the <code>src/test/resources/org/activiti/test</code> resource folder (or anywhere else if you’re not using the unit test template) with the following content. Note that this section won’t explain the xml constructs being used in the example above. Please read <a href="#bpmn2
34280">the BPMN 2.0 chapter</a> to become familiar with these constructs first if needed.</p> 3429</div> 3430<div class="listingblock"> 3431<div class="content"> 3432<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 3433 2 3434 3 3435 4 3436 5 3437 6 3438 7 3439 8 3440 9 344110 344211 344312 344413 344514 344615 344716 344817 344918 345019 345120 345221 345322 345423 345524 345625 345726 345827 345928 346029 346130 346231 346332 346433 346534 346635 346736 346837 346938 347039 347140 347241 347342 347443 347544 347645 347746 347847 347948 348049 348150 348251 348352 348453 348554 348655 348756 348857 348958 349059 349160 349261 349362 349463 349564 349665 349766 349867 349968 350069 350170 350271 350372 350473 350574 350675 350776 350877 350978 351079 351180 351281 351382 351483 351584 351685</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="UTF-8" ?></span> 3517<span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"definitions"</span> 3518 <span class="tok-na">targetNamespace=</span><span class="tok-s">"http://activiti.org/bpmn20"</span> 3519 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 3520 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 3521 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span><span class="tok-nt">></span> 3522 3523 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"vacationRequest"</span> <span class="tok-na">name=</span><span class="tok-s">"Vacation request"</span><span class="tok-nt">></span> 3524 3525 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"request"</span> <span class="tok-na">activiti:initiator=</span><span class="tok-s">"employeeName"</span><span class="tok-nt">></span> 3526 <span class="tok-nt"><extensionElements></span> 3527 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"numberOfDays"</span> <span class="tok-na">name=</span><span class="tok-s">"Number of days"</span> <span class="tok-na">type=</span><span class="tok-s">"long"</span> <span class="tok-na">value=</span><span class="tok-s">"1"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span><span class="tok-nt">/></span> 3528 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"startDate"</span> <span class="tok-na">name=</span><span class="tok-s">"First day of holiday (dd-MM-yyy)"</span> <span class="tok-na">datePattern=</span><span class="tok-s">"dd-MM-yyyy hh:mm"</span> <span class="tok-na">type=</span><span class="tok-s">"date"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 3529 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"vacationMotivation"</span> <span class="tok-na">name=</span><span class="tok-s">"Motivation"</span> <span class="tok-na">type=</span><span class="tok-s">"
3529string"</span> <span class="tok-nt">/></span> 3530 <span class="tok-nt"></extensionElements></span> 3531 <span class="tok-nt"></startEvent></span> 3532 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"request"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"handleRequest"</span> <span class="tok-nt">/></span> 3533 3534 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"handleRequest"</span> <span class="tok-na">name=</span><span class="tok-s">"Handle vacation request"</span> <span class="tok-nt">></span> 3535 <span class="tok-nt"><documentation></span> 3536 ${employeeName} would like to take ${numberOfDays} day(s) of vacation (Motivation: ${vacationMotivation}). 3537 <span class="tok-nt"></documentation></span> 3538 <span class="tok-nt"><extensionElements></span> 3539 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"vacationApproved"</span> <span class="tok-na">name=</span><span class="tok-s">"Do you approve this vacation"</span> <span class="tok-na">type=</span><span class="tok-s">"enum"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 3540 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"true"</span> <span class="tok-na">name=</span><span class="tok-s">"Approve"</span> <span class="tok-nt">/></span> 3541 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"false"</span> <span class="tok-na">name=</span><span class="tok-s">"Reject"</span> <span class="tok-nt">/></span> 3542 <span class="tok-nt"></activiti:formProperty></span> 3543 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"managerMotivation"</span> <span class="tok-na">name=</span><span class="tok-s">"Motivation"</span> <span class="tok-na">type=</span><span class="tok-s">"
3543string"</span> <span class="tok-nt">/></span> 3544 <span class="tok-nt"></extensionElements></span> 3545 <span class="tok-nt"><potentialOwner></span> 3546 <span class="tok-nt"><resourceAssignmentExpression></span> 3547 <span class="tok-nt"><formalExpression></span>management<span class="tok-nt"></formalExpression></span> 3548 <span class="tok-nt"></resourceAssignmentExpression></span> 3549 <span class="tok-nt"></potentialOwner></span> 3550 <span class="tok-nt"></userTask></span> 3551 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"handleRequest"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"requestApprovedDecision"</span> <span class="tok-nt">/></span> 3552 3553 <span class="tok-nt"><exclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"requestApprovedDecision"</span> <span class="tok-na">name=</span><span class="tok-s">"Request approved?"</span> <span class="tok-nt">/></span> 3554 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"requestApprovedDecision"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"sendApprovalMail"</span><span class="tok-nt">></span> 3555 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${vacationApproved == 'true'}<span class="tok-nt"></conditionExpression></span> 3556 <span class="tok-nt"></sequenceFlow></span> 3557 3558 <span class="tok-nt"><task</span> <span class="tok-na">id=</span><span class="tok-s">"sendApprovalMail"</span> <span class="tok-na">name=</span><span class="tok-s">"Send confirmation e-mail"</span> <span class="tok-nt">/></span> 3559 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow4"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"sendApprovalMail"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd1"</span> <span class="tok-nt">/></span> 3560 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd1"</span> <span class="tok-nt">/></span> 3561 3562 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow5"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"requestApprovedDecision"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"adjustVacationRequestTask"</span><span class="tok-nt">></span> 3563 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${vacationApproved == 'false'}<span class="tok-nt"></conditionExpression></span> 3564 <span class="tok-nt"></sequenceFlow></span> 3565 3566 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"adjustVacationRequestTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Adjust vacation request"</span><span class="tok-nt">></span> 3567 <span class="tok-nt"><documentation></span> 3568 Your manager has disapproved your vacation request for ${numberOfDays} days. 3569 Reason: ${managerMotivation} 3570 <span class="tok-nt"></documentation></span> 3571 <span class="tok-nt"><extensionElements></span> 3572 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"numberOfDays"</span> <span class="tok-na">name=</span><span class="tok-s">"Number of days"</span> <span class="tok-na">value=</span><span class="tok-s">"${numberOfDays}"</span> <span class="tok-na">type=</span><span class="tok-s">"long"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span><span class="tok-nt">/></span>
3573 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"startDate"</span> <span class="tok-na">name=</span><span class="tok-s">"First day of holiday (dd-MM-yyy)"</span> <span class="tok-na">value=</span><span class="tok-s">"${startDate}"</span> <span class="tok-na">datePattern=</span><span class="tok-s">"dd-MM-yyyy hh:mm"</span> <span class="tok-na">type=</span><span class="tok-s">"date"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 3574 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"vacationMotivation"</span> <span class="tok-na">name=</span><span class="tok-s">"Motivation"</span> <span class="tok-na">value=</span><span class="tok-s">"${vacationMotivation}"</span> <span class="tok-na">type=</span><span class="tok-s">"string"</span> <span class="tok-nt">/></span> 3575 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"resendRequest"</span> <span class="tok-na">name=</span><span class="tok-s">"Resend vacation request to manager?"</span> <span class="tok-na">type=</span><span class="tok-s">"enum"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 3576 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"true"</span> <span class="tok-na">name=</span><span class="tok-s">"Yes"</span> <span class="tok-nt">/></span> 3577 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"false"</span> <span class="tok-na">name=</span><span class="tok-s">"No"</span> <span class="tok-nt">/></span> 3578 <span class="tok-nt"></activiti:formProperty></span> 3579 <span class="tok-nt"></extensionElements></span> 3580 <span class="tok-nt"><humanPerformer></span> 3581 <span class="tok-nt"><resourceAssignmentExpression></span> 3582 <span class="tok-nt"><formalExpression></span>${employeeName}<span class="tok-nt"></formalExpression></span> 3583 <span class="tok-nt"></resourceAssignmentExpression></span> 3584 <span class="tok-nt"></humanPerformer></span> 3585 <span class="tok-nt"></userTask></span> 3586 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow6"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"adjustVacationRequestTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"resendRequestDecision"</span> <span class="tok-nt">/></span> 3587 3588 <span class="tok-nt"><exclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"resendRequestDecision"</span> <span class="tok-na">name=</span><span class="tok-s">"Resend request?"</span> <span class="tok-nt">/></span> 3589 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow7"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"resendRequestDecision"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"handleRequest"</span><span class="tok-nt">></span> 3590 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${resendRequest == 'true'}<span class="tok-nt"></conditionExpression></span> 3591 <span class="tok-nt"></sequenceFlow></span> 3592 3593 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow8"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"resendRequestDecision"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd2"</span><span class="tok-nt">></span>
3594 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${resendRequest == 'false'}<span class="tok-nt"></conditionExpression></span> 3595 <span class="tok-nt"></sequenceFlow></span> 3596 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd2"</span> <span class="tok-nt">/></span> 3597 3598 <span class="tok-nt"></process></span> 3599 3600<span class="tok-nt"></definitions></span> 3601</td></tr></table></code></pre> 3602</div> 3603</div> 3604<div class="paragraph"> 3605<p>To make this process known to the Activiti engine, we must <em>deploy</em> it first. Deploying means that the engine will parse the BPMN 2.0 xml to something executable and a new database record will be added for each process definition included in the <em>deployment</em>. This way, when the engine reboots, it will still know all of the <em>deployed</em> processes:</p> 3606</div> 3607<div class="listingblock"> 3608<div class="content"> 3609<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 36102 36113 36124 36135 36146 36157</div></td><td class="code"><span></span><span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">getDefaultProcessEngine</span><span class="tok-o">();</span> 3616<span class="tok-n">RepositoryService</span> <span class="tok-n">repositoryService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRepositoryService</span><span class="tok-o">();</span> 3617<span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 3618 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"org/activiti/test/VacationRequest.bpmn20.xml"</span><span class="tok-o">)</span> 3619 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 3620 3621<span class="tok-n">Log</span><span class="tok-o">.</span><span class="tok-na">info</span><span class="tok-o">(</span><span class="tok-s">"Number of process definitions: "</span> <span class="tok-o">+</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">
3621createProcessDefinitionQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 3622</td></tr></table></code></pre> 3623</div> 3624</div> 3625<div class="paragraph"> 3626<p>Read more about deployment in the <a href="#chDeployment">deployment chapter</a>.</p> 3627</div> 3628</div> 3629<div class="sect3"> 3630<h4 id="api.services.start.processinstance">4.3.2. Starting a process instance</h4> 3631<div class="paragraph"> 3632<p>After deploying the process definition to the Activiti engine, we can start new process instances from it. For each process definition, there are typically many process instances. The process definition is the <em>blueprint</em>, while a process instance is a runtime execution of it.</p> 3633</div> 3634<div class="paragraph"> 3635<p>Everything related to the runtime state of processes can be found in the <strong>RuntimeService</strong>. There are various way to start a new process instance. In the following snippet, we use the key we defined in the process definition xml to start the process instance. We’re also providing some process variables at process instance start, because the description of the first user task will use these in its expressions. Process variables are commonly used because they give meaning to the process instances for a certain process definition. Typically, the process variables are what make process instances differ from one another.</p> 3636</div> 3637<div class="listingblock"> 3638<div class="content"> 3639<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 3640 2 3641 3 3642 4 3643 5 3644 6 3645 7 3646 8 3647 9 364810</div></td><td class="code"><span></span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();</span> 3649<span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"employeeName"</span><span class="tok-o">,</span> <span class="tok-s">"Kermit"</span><span class="tok-o">);</span> 3650<span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"numberOfDays"</span><span class="tok-o">,</span> <span class="tok-k">new</span> <span class="tok-n">Integer</span><span class="tok-o">(</span><span class="tok-mi">4</span><span class="tok-o">));</span> 3651<span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"vacationMotivation"</span><span class="tok-o">,</span> <span class="tok-s">"I'm really tired!"</span><span class="tok-o">);</span> 3652 3653<span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRuntimeService</span><span class="tok-o">();</span> 3654<span class="tok-n">ProcessInstance</span> <span class="tok-n">processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"vacationRequest"</span><span class="tok-o">,</span> <span class="tok-n">variables</span><span class="tok-o">);</span> 3655 3656<span class="tok-c1">// Verify that we started a new process instance</span> 3657<span class="tok-n">Log</span><span class="tok-o">.</span><span class="tok-na">info</span><span class="tok-o">(</span><span class="tok-s">"Number of process instances: "</span> <span class="tok-o">+</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 3658</td></tr></table></code></pre> 3659</div> 3660</div> 3661</div> 3662<div class="sect3"> 3663<h4 id="api.services.tasks">4.3.3. Completing tasks</h4> 3664<div class="paragraph"> 3665<p>When the process starts, the first step will be a user task. This is a step that must be performed by a user of the system. Typically, such a user will have an <em>inbox of tasks</em> which lists all the tasks that need to be done by this user. Following code snippet shows how such a query might be performed:</p> 3666</div> 3667<div class="listingblock"> 3668<div class="content"> 3669<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 36702 36713 36724 36735 36746</div></td><td class="code"><span></span><span class="tok-c1">// Fetch all tasks for the management group</span> 3675<span class="tok-n">TaskService</span> <span class="tok-n">taskService</span> <span class="tok-o">=</span> <span class="tok-n">
3675processEngine</span><span class="tok-o">.</span><span class="tok-na">getTaskService</span><span class="tok-o">();</span> 3676<span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskCandidateGroup</span><span class="tok-o">(</span><span class="tok-s">"management"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 3677<span class="tok-k">for</span> <span class="tok-o">(</span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">:</span> <span class="tok-n">tasks</span><span class="tok-o">)</span> <span class="tok-o">{</span> 3678 <span class="tok-n">Log</span><span class="tok-o">.</span><span class="tok-na">info</span><span class="tok-o">(</span><span class="tok-s">"Task available: "</span> <span class="tok-o">+</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 3679<span class="tok-o">}</span> 3680</td></tr></table></code></pre> 3681</div> 3682</div> 3683<div class="paragraph"> 3684<p>To continue the process instance, we need to finish this task. For the Activiti engine, this means you need to <code>complete</code> the task. Following snippet shows how this is done:</p> 3685</div> 3686<div class="listingblock"> 3687<div class="content"> 3688<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 36892 36903 36914 36925 36936</div></td><td class="code"><span></span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">=</span> <span class="tok-n">tasks</span><span class="tok-o">.</span><span class="tok-na">get</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">);</span> 3694 3695<span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">taskVariables</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();</span> 3696<span class="tok-n">taskVariables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"vacationApproved"</span><span class="tok-o">,</span> <span class="tok-s">"false"</span><span class="tok-o">);</span> 3697<span class="tok-n">taskVariables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"managerMotivation"</span><span class="tok-o">,</span> <span class="tok-s">"We have a tight deadline!"</span><span class="tok-o">);</span> 3698<span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-n">taskVariables</span><span class="tok-o">);</span> 3699</td></tr></table></code></pre> 3700</div> 3701</div> 3702<div class="paragraph"> 3703<p>The process instance will now continue to the next step. In this example, the next step allows the employee to complete a form that adjusts their original vacation request. The employee can resubmit the vacation request which will cause the process to loop back to the start task.</p> 3704</div> 3705</div> 3706<div class="sect3"> 3707<h4 id="api.services.suspend">4.3.4. Suspending and activating a process</h4> 3708<div class="paragraph"> 3709<p>It’s possible to suspend a process definition. When a process definition is suspended, new process instance can’t be created (an exception will be thrown). Suspending the process definition is done through the <code>RepositoryService</code>:</p> 3710</div> 3711<div class="listingblock"> 3712<div class="content"> 3713<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 37142 37153 37164 37175 37186</div></td><td class="code"><span></span><span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">suspendProcessDefinitionByKey</span><span class="tok-o">(</span><span class="tok-s">"vacationRequest"</span><span class="tok-o">);</span> 3719<span class="tok-k">try</span> <span class="tok-o">{</span> 3720 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"vacationRequest"</span><span class="tok-o">);</span> 3721<span class="tok-o">}</span> <span class="tok-k">catch</span> <span class="tok-o">(</span><span class="tok-n">ActivitiException</span> <span class="tok-n">e</span><span class="tok-o">)</span> <span class="tok-o">{</span> 3722 <span class="tok-n">e</span><span class="tok-o">.</span><span class="tok-na">printStackTrace</span><span class="tok-o">();</span> 3723<span class="tok-o">}</span> 3724</td></tr></table></code></pre> 3725</div> 3726</div> 3727<div class="paragraph"> 3728<p>To reactivate a process definition, simply call one of the <code>repositoryService.activateProcessDefinitionXXX</code> methods.</p> 3729</div> 3730<div class="paragraph"> 3731<p>It’s also possible to suspend a process instance. When suspended, the process cannot
3732 be continued (e.g. completing a task throws an exception) and no jobs (such as timers) will executed. Suspending a process instance can be done by calling the <code>runtimeService.suspendProcessInstance</code> method. Activating the process instance again is done by calling the <code>runtimeService.activateProcessInstanceXXX</code> methods.</p> 3733</div> 3734</div> 3735<div class="sect3"> 3736<h4 id="api.services">4.3.5. Further reading</h4> 3737<div class="paragraph"> 3738<p>We’ve barely scratched the surface in the previous sections regarding Activiti functionality. We will expand these sections further in the future with additional coverage of the Activiti API. Of course, as with any open source project, the best way to learn is to inspect the code and read the Javadocs!</p> 3739</div> 3740</div> 3741</div> 3742<div class="sect2"> 3743<h3 id="queryAPI">4.4. Query API</h3> 3744<div class="paragraph"> 3745<p>There are two ways of querying data from the engine: The query API and native queries. The Query API allows to program completely typesafe queries with a fluent API. You can add various conditions to your queries (all of which are applied together as a logical AND) and precisely one ordering. The following code shows an example:</p> 3746</div> 3747<div class="listingblock"> 3748<div class="content"> 3749<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 37502 37513 37524 37535</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">()</span> 3754 <span class="tok-o">.</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">)</span> 3755 <span class="tok-o">.</span><span class="tok-na">processVariableValueEquals</span><span class="tok-o">(</span><span class="tok-s">"orderId"</span><span class="tok-o">,</span> <span class="tok-s">"0815"</span><span class="tok-o">)</span> 3756 <span class="tok-o">.</span><span class="tok-na">orderByDueDate</span><span class="tok-o">().</span><span class="tok-na">asc</span><span class="tok-o">()</span> 3757 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 3758</td></tr></table></code></pre> 3759</div> 3760</div> 3761<div class="paragraph"> 3762<p>Sometimes you need more powerful queries, e.g. queries using an OR operator or restrictions you cannot express using the Query API. For these cases, we introduced native queries, which allow you to write your own SQL queries. The return type is defined by the Query object you use and the data is mapped into the correct objects, e.g. Task, ProcessInstance, Execution, etc…​. Since the query will be fired at the database you have to use table and column names as they are defined in the database; this requires some knowledge about the internal data structure and it is recommended to use native queries with care. The table names can be retrieved via the API to keep the dependency as small as possible.</p> 3763</div> 3764<div class="listingblock"> 3765<div class="content"> 3766<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 37672 37683 37694 37705 37716 37727 37738 37749</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createNativeTaskQuery</span><span class="tok-o">()</span> 3775 <span class="tok-o">.</span><span class="tok-na">sql</span><span class="tok-o">(</span><span class="tok-s">"SELECT count(*) FROM "</span> <span class="tok-o">+</span> <span class="tok-n">managementService</span><span class="tok-o">.</span><span class="tok-na">getTableName</span><span class="tok-o">(</span><span class="tok-n">Task</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">)</span> <span class="tok-o">+</span> <span class="tok-s">" T WHERE T.NAME_ = #{taskName}"</span><span class="tok-o">)</span> 3776 <span class="tok-o">.</span><span class="tok-na">parameter</span><span class="tok-o">(</span><span class="tok-s">"taskName"</span><span class="tok-o">,</span> <span class="tok-s">"gonzoTask"</span><span class="tok-o">)</span> 3777 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 3778 3779<span class="tok-kt">long</span> <span class="tok-n">count</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createNativeTaskQuery</span><span class="tok-o">()</span> 3780 <span class="tok-o">.</span><span class="tok-na">sql</span><span class="tok-o">(</span><span class="tok-s">"SELECT count(*) FROM "</span> <span class="tok-o">+</span> <span class="tok-n">managementService</span><span class="tok-o">.</span><span class="tok-na">getTableName</span><span class="tok-o">(</span><span class="tok-n">Task</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">)</span> <span class="tok-o">+</span> <span class="tok-s">" T1, "</span> 3781 <span class="tok-o">+</span> <span class="tok-n">managementService</span><span class="tok-o">.</span><span class="tok-na">getTableName</span><span class="tok-o">(</span><span class="tok-n">VariableInstanceEntity</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">)</span> <span class="tok-o">+</span> <span class="tok-s">" V1 WHERE V1.TASK_ID_ = T1.ID_"</span><span class="tok-o">)</span> 3782 <span class="tok-o">.</span><span class="tok-na">count</span><span class="tok-o">();</span> 3783</td></tr></table></code></pre> 3784</div> 3785</div> 3786</div> 3787<div class="sect2"> 3788<h3 id="apiVariables">4.5. Variables</h3> 3789<div class="paragraph"> 3790<p>Every process instance needs and uses data to execute the steps it exists of. In Activiti, this data is called <em>variables</em>, which are stored in the database. Variables can be used in expressions (for example to select the correct outgoing sequence flow in an exclusive gateway), in java service tasks when calling external services (for example to provide the input or store the result of the service call), etc.</p> 3791</div> 3792<div class="paragraph"> 3793<p>A process instance can have variables (called <em>process variables</em>), but also <em>executions</em> (which are specific pointers to where the process is active) and user tasks can have variables. A process instance can have any number of variables. Each variable is stored in a row in the <em>ACT_RU_VARIABLE</em> database table.</p> 3794</div> 3795<div class="paragraph"> 3796<p>Any of the <em>startProcessInstanceXXX</em> methods have an optional parameters to provide the variables when the process instance is created and started. For example, from the <em>RuntimeService</em>:</p> 3797</div> 3798<div class="listingblock"> 3799<div class="content"> 3800<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">
3800processDefinitionKey</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span><span class="tok-o">);</span> 3801</td></tr></table></code></pre> 3802</div> 3803</div> 3804<div class="paragraph"> 3805<p>Variables can be added during process execution. For example (<em>RuntimeService</em>):</p> 3806</div> 3807<div class="listingblock"> 3808<div class="content"> 3809<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 38102 38113 38124</div></td><td class="code"><span></span><span class="tok-kt">void</span> <span class="tok-nf">setVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Object</span> <span class="tok-n">value</span><span class="tok-o">);</span> 3813<span class="tok-kt">void</span> <span class="tok-nf">setVariableLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Object</span> <span class="tok-n">value</span><span class="tok-o">);</span> 3814<span class="tok-kt">void</span> <span class="tok-nf">setVariables</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-o">?</span> <span class="tok-kd">extends</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span><span class="tok-o">);</span> 3815<span class="tok-kt">void</span> <span class="tok-nf">setVariablesLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-o">?</span> <span class="tok-kd">extends</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span><span class="tok-o">);</span> 3816</td></tr></table></code></pre> 3817</div> 3818</div> 3819<div class="paragraph"> 3820<p>Note that variables can be set <em>local</em> for a given execution (remember a process instance consists of a tree of executions). The variable will only be visible on that execution, and not higher in the tree of executions. This can be useful if data shouldn’t be propagated to the process instance level, or the variable has a new value for a certain path in the process instance (for example when using parallel paths).</p> 3821</div> 3822<div class="paragraph"> 3823<p>Variables can also be fetched again, as shown below. Note that similar methods exist on the <em>TaskService</em>. This means that tasks, like executions, can have local variables that are <em>alive</em> just for the duration of the task.</p> 3824</div> 3825<div class="listingblock"> 3826<div class="content"> 3827<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 38282 38293 38304 38315 38326</div></td><td class="code"><span></span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getVariables</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">);</span> 3833<span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getVariablesLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">);</span> 3834<span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getVariables</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">Collection</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">></span> <span class="tok-n">variableNames</span><span class="tok-o">);</span> 3835<span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getVariablesLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">Collection</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">></span> <span class="tok-n">variableNames</span><span class="tok-o">);</span> 3836<span class="tok-n">Object</span> <span class="tok-nf">getVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 3837<span class="tok-o"><</span><span class="tok-n">T</span><span class="tok-o">></span> <span class="tok-n">T</span> <span class="tok-nf">getVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Class</span><span class="tok-o"><</span><span class="tok-n">T</span><span class="tok-o">></span> <span class="tok-n">variableClass</span><span class="tok-o">);</span> 3838</td></tr></table></code></pre> 3839</div> 3840</div> 3841<div class="paragraph"> 3842<p>Variables are often used in <a href="#bpmnJavaServiceTask">Java delegates</a>, <a href="#apiExpressions">expressions</a>, execution- or tasklisteners, scripts, etc. In those constructs, the current <em>execution</em> or <em>task</em> object is available and it can be used for variable setting and/or retrieval. The simplest methods are these:</p> 3843</div> 3844<div class="listingblock"> 3845<div class="content"> 3846<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 38472 38483 38494 38505 38516</div></td><td class="code"><span></span><span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getVariables</span><span class="tok-o">();</span> 3852<span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getVariables</span><span class="tok-o">(</span><span class="tok-n">Collection</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">></span> <span class="tok-n">variableNames</span><span class="tok-o">);</span> 3853<span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 3854 3855<span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariables</span><span class="tok-o">(</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">object</span><span class="tok-o">></span> <span class="tok-n">variables</span><span class="tok-o">);</span> 3856<span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Object</span> <span class="tok-n">value</span><span class="tok-o">);</span> 3857</td></tr></table></code></pre> 3858</div> 3859</div> 3860<div class="paragraph"> 3861<p>Note that a variant with <em>local</em> is also available for all of the above.</p> 3862</div> 3863<div class="paragraph"> 3864<p>For historical (and backwards compatible reasons), when doing any of the calls above, behind the scenes actually <strong>all</strong> variables will be fetched from the database. This means that if you have 10 variables, and only get one through <em>getVariable("myVariable")</em>, behind the scenes the other 9 will be fetched and cached. This is not bad, as subsequent calls will not hit the database again. For example, when your process definition has three sequential service tasks (and thus one database transaction), using one call to fetch all variables in the first service task might be better then fetching the variables needed in each service task separately. Note that this applies <strong>both</strong> for getting and setting variables.</p> 3865</div> 3866<div class="paragraph"> 3867<p>Of course, when using a lot of variables or simply when you want tight control on the database query and traffic, this is not appropriate. Since Activiti 5.17, new methods have been introduced to give a t
3867ighter control on this, by adding in new methods that have an optional parameter that tells the engine whether or not behind the scenes all variables need to be fetched and cached:</p> 3868</div> 3869<div class="listingblock"> 3870<div class="content"> 3871<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 38722 38733</div></td><td class="code"><span></span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getVariables</span><span class="tok-o">(</span><span class="tok-n">Collection</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">></span> <span class="tok-n">variableNames</span><span class="tok-o">,</span> <span class="tok-kt">boolean</span> <span class="tok-n">fetchAllVariables</span><span class="tok-o">);</span> 3874<span class="tok-n">Object</span> <span class="tok-nf">getVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-kt">boolean</span> <span class="tok-n">fetchAllVariables</span><span class="tok-o">);</span> 3875<span class="tok-kt">void</span> <span class="tok-nf">setVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Object</span> <span class="tok-n">value</span><span class="tok-o">,</span> <span class="tok-kt">boolean</span> <span class="tok-n">fetchAllVariables</span><span class="tok-o">);</span> 3876</td></tr></table></code></pre> 3877</div> 3878</div> 3879<div class="paragraph"> 3880<p>When using <em>true</em> for the parameter <em>fetchAllVariables</em>, the behaviour will be exactly as described above: when getting or setting a variable, all other variables will be fetched and cached.</p> 3881</div> 3882<div class="paragraph"> 3883<p>However, when using <em>false</em> as value, a specific query will be used and no other variables will be fetched nor cached. Only the value of the variable in question here will be cached for subsequent use.</p> 3884</div> 3885</div> 3886<div class="sect2"> 3887<h3 id="apiTransientVariables">4.6. Transient variables</h3> 3888<div class="paragraph"> 3889<p>Transient variables are variables that behave like regular variables, but are not persisted. Typically, transient variables are used for advanced use cases (i.e. when in doubt, use a regular process variable).</p> 3890</div> 3891<div class="paragraph"> 3892<p>The following applies for transient variables:</p> 3893</div> 3894<div class="ulist"> 3895<ul> 3896<li> 3897<p>There is no history stored at all for transient variables.</p> 3898</li> 3899<li> 3900<p>Like <em>regular</em> variables, transient variables are put on the <em>highest parent</em> when set. This means that when setting a variable on an execution, the transient variable is actually stored on the process instance execution. Like regular variables, a <em>local</em> variant of the method exists if the variable should be set on the specific execution or task.</p> 3901</li> 3902<li> 3903<p>A transient variable can only be accessed until the next <em>wait state</em> in the process definition. After that, they are gone. The wait state means here the point in the process instance where it is persisted to the data store. Note that an <em>async</em> activity also is a <em>wait state</em> in this definition!</p> 3904</li> 3905<li> 3906<p>Transient variables can only be set by the <em>setTransientVariable(name, value)</em>, but transient variables are also returned when calling <em>getVariable(name)</em> (a <em>getTransientVariable(name)</em> also exists, that only checks the transient variables). The reason for this is to make the writing of expressions easy and existing logic using variables works for both types.</p> 3907</li> 3908<li> 3909<p>A transient variable <em>shadows</em> a persistent variable with the same name. This means that when both a persistent and transient variable is set on a process instance and the <em>getVariable("someVariable")</em> is used, the transient variable value will be returned.</p> 3910</li> 3911</ul> 3912</div> 3913<div class="paragraph"> 3914<p>Transient variables can be got and/or set in most places where regular variables are exposed:</p> 3915</div> 3916<div class="ulist"> 3917<ul> 3918<li> 3919<p>On <em>DelegateExecution</em> in <em>JavaDelegate</em> implementations</p> 3920</li> 3921<li> 3922<p>On <em>DelegateExecution</em> in <em>ExecutionListener</em> implementations and on <em>DelegateTask</em> on <em>TaskListener</em> implementations</p> 3923</li> 3924<li> 3925<p>In script task via the <em>execution</em> object</p> 3926</li> 3927<li> 3928<p>When starting a process instance via the runtime service</p> 3929</li> 3930<li> 3931<p>When completing a task</p> 3932</li> 3933<li> 3934<p>When calling the <em>runtimeService.trigger</em> method</p> 3935</li> 3936</ul> 3937</div> 3938<div class="paragraph"> 3939<p>The methods follow the naming convention of the regular process variables:</p> 3940</div> 3941<div class="listingblock"> 3942<div class="content"> 3943<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 3944 2 3945 3 3946 4 3947 5 3948 6 3949 7 3950 8 3951 9 395210 395311 395412 395513</div></td><td class="code"><span></span><span class="tok-kt">void</span> <span class="tok-nf">setTransientVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Object</span> <span class="tok-n">variableValue</span><span class="tok-o">);</span> 3956<span class="tok-kt">void</span> <span class="tok-nf">setTransientVariableLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">,</span> <span class="tok-n">Object</span> <span class="tok-n">variableValue</span><span class="tok-o">);</span> 3957<span class="tok-kt">void</span> <span class="tok-nf">setTransientVariables</span><span class="tok-o">(</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">transientVariables</span><span class="tok-o">);</span> 3958<span class="tok-kt">void</span> <span class="tok-nf">setTransientVariablesLocal</span><span class="tok-o">(</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">transientVariables</span><span class="tok-o">);</span> 3959 3960<span class="tok-n">Object</span> <span class="tok-nf">getTransientVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 3961<span class="tok-n">Object</span> <span class="tok-nf">getTransientVariableLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 3962 3963<span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getTransientVariables</span><span class="tok-o">();</span> 3964<span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-nf">getTransientVariablesLocal</span><span class="tok-o">();</span> 3965 3966<span class="tok-kt">void</span> <span class="tok-nf">removeTransientVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 3967<span class="tok-kt">void</span> <span class="tok-nf">removeTransientVariableLocal</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 3968</td></tr></table></code></pre> 3969</div> 3970</div> 3971<div class="paragraph"> 3972<p>Following BPMN diagram shows a typical example:</p> 3973</div> 3974<div class="imageblock" style="text-align: center"> 3975<div class="content"> 3976<img src="images/api.transient.variable.example.png" alt="api.transient.variable.example"> 3977</div> 3978</div> 3979<div class="paragraph"> 3980<p>Let’s assume the <em>Fetch Data</em> service task calls some remote service (for example using REST). Let’s also assume some config parameters are needed and need to be provided when starting the process instance. Also, these config parameters are not important for historical audit purposes, so we pass them as transient variables:</p> 3981</div> 3982<div class="listingblock"> 3983<div class="content"> 3984<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 39852 39863 39874 39885 39896</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-n">
3989processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceBuilder</span><span class="tok-o">()</span> 3990 <span class="tok-o">.</span><span class="tok-na">processDefinitionKey</span><span class="tok-o">(</span><span class="tok-s">"someKey"</span><span class="tok-o">)</span> 3991 <span class="tok-o">.</span><span class="tok-na">transientVariable</span><span class="tok-o">(</span><span class="tok-s">"configParam01"</span><span class="tok-o">,</span> <span class="tok-s">"A"</span><span class="tok-o">)</span> 3992 <span class="tok-o">.</span><span class="tok-na">transientVariable</span><span class="tok-o">(</span><span class="tok-s">"configParam02"</span><span class="tok-o">,</span> <span class="tok-s">"B"</span><span class="tok-o">)</span> 3993 <span class="tok-o">.</span><span class="tok-na">transientVariable</span><span class="tok-o">(</span><span class="tok-s">"configParam03"</span><span class="tok-o">,</span> <span class="tok-s">"C"</span><span class="tok-o">)</span> 3994 <span class="tok-o">.</span><span class="tok-na">start</span><span class="tok-o">();</span> 3995</td></tr></table></code></pre> 3996</div> 3997</div> 3998<div class="paragraph"> 3999<p>Note that the variables will be available until the user task is reached and persisted to the database. For example, in the <em>Additional Work</em> user task they are not available anymore. Also note that if <em>Fetch Data</em> would have been asynchronous, they won’t be available after that step too.</p> 4000</div> 4001<div class="paragraph"> 4002<p>The <em>Fetch Data</em> (simplified) could be something like</p> 4003</div> 4004<div class="listingblock"> 4005<div class="content"> 4006<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4007 2 4008 3 4009 4 4010 5 4011 6 4012 7 4013 8 4014 9 401510</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">class</span> <span class="tok-nc">FetchDataServiceTask</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 4016 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-o">{</span> 4017 <span class="tok-n">String</span> <span class="tok-n">configParam01</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">)</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getVariable</span><span class="tok-o">(</span><span class="tok-n">configParam01</span><span class="tok-o">);</span> 4018 <span class="tok-c1">// ...</span> 4019 4020 <span class="tok-n">RestReponse</span> <span class="tok-n">restResponse</span> <span class="tok-o">=</span> <span class="tok-n">
4020executeRestCall</span><span class="tok-o">();</span> 4021 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setTransientVariable</span><span class="tok-o">(</span><span class="tok-s">"response"</span><span class="tok-o">,</span> <span class="tok-n">restResponse</span><span class="tok-o">.</span><span class="tok-na">getBody</span><span class="tok-o">());</span> 4022 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setTransientVariable</span><span class="tok-o">(</span><span class="tok-s">"status"</span><span class="tok-o">,</span> <span class="tok-n">restResponse</span><span class="tok-o">.</span><span class="tok-na">getStatus</span><span class="tok-o">());</span> 4023 <span class="tok-o">}</span> 4024<span class="tok-o">}</span> 4025</td></tr></table></code></pre> 4026</div> 4027</div> 4028<div class="paragraph"> 4029<p>The <em>Process Data</em> would get the response transient variable, parse it and store the relevant data in real process variables as we need them later.</p> 4030</div> 4031<div class="paragraph"> 4032<p>The condition on the sequence flow leaving the exclusive gateway are oblivious to whether persistent or transient variables are used (in this case the <em>status</em> transient variable):</p> 4033</div> 4034<div class="listingblock"> 4035<div class="content"> 4036<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${status == 200}<span class="tok-nt"></conditionExpression></span> 4037</td></tr></table></code></pre> 4038</div> 4039</div> 4040</div> 4041<div class="sect2"> 4042<h3 id="apiExpressions">4.7. Expressions</h3> 4043<div class="paragraph"> 4044<p>Activiti uses UEL for expression-resolving. UEL stands for <em>Unified Expression Language</em> and is part of the EE6 specification (see <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html"> the EE6 specification</a> for detailed information). To support all features of latest UEL spec on ALL environments, we use a modified version of JUEL.</p> 4045</div> 4046<div class="paragraph"> 4047<p>Expressions can be used in for example <a href="#bpmnJavaServiceTaskXML">Java Service tasks</a>, <a href="#executionListeners">Execution Listeners</a>, <a href="#taskListeners">Task Listeners</a> and <a href="#conditionalSequenceFlowXml">Conditional sequence flows</a>. Although there are 2 types of expressions, value-expression and method-expression, Activiti abstracts this so they can both be used where an <code>expression</code> is needed.</p> 4048</div> 4049<div class="ulist"> 4050<ul> 4051<li> 4052<p><strong>Value expression</strong>: resolves to a value. By default, all process variables are available to use. Also all spring-beans (if using Spring) are available to use in expressions. Some examples:</p> 4053</li> 4054</ul> 4055</div> 4056<div class="listingblock"> 4057<div class="content"> 4058<pre>${myVar} 4059${myBean.myProperty}</pre> 4060</div> 4061</div> 4062<div class="ulist"> 4063<ul> 4064<li> 4065<p><strong>Method expression</strong>: invokes a method, with or without parameters. <strong>When invoking a method without parameters, be sure to add empty parentheses after the method-name (as this distinguishes the expression from a value expression).</strong> The passed parameters can be literal values or expressions that are resolved themselves. Examples:</p> 4066</li> 4067</ul> 4068</div> 4069<div class="listingblock"> 4070<div class="content"> 4071<pre>${printer.print()} 4072${myBean.addNewOrder('orderName')} 4073${myBean.doSomething(myVar, execution)}</pre> 4074</div> 4075</div> 4076<div class="paragraph"> 4077<p>
4077Note that these expressions support resolving primitives (incl. comparing them), beans, lists, arrays and maps.</p> 4078</div> 4079<div class="paragraph"> 4080<p>On top of all process variables, there are a few default objects available to be used in expressions:</p> 4081</div> 4082<div class="ulist"> 4083<ul> 4084<li> 4085<p><code>execution</code>: The <code>DelegateExecution</code> that holds additional information about the ongoing execution.</p> 4086</li> 4087<li> 4088<p><code>task</code>: The <code>DelegateTask</code> that holds additional information about the current Task. <strong>Note: Only works in expressions evaluated from task listeners.</strong></p> 4089</li> 4090<li> 4091<p><code>authenticatedUserId</code>: The id of the user that is currently authenticated. If no user is authenticated, the variable is not available.</p> 4092</li> 4093</ul> 4094</div> 4095<div class="paragraph"> 4096<p>For more concrete usage and examples, check out <a href="#springExpressions">Expressions in Spring</a>, <a href="#bpmnJavaServiceTaskXML">Java Service tasks</a>, <a href="#executionListeners">Execution Listeners</a>, <a href="#taskListeners">Task Listeners</a> or <a href="#conditionalSequenceFlowXml">Conditional sequence flows</a>.</p> 4097</div> 4098</div> 4099<div class="sect2"> 4100<h3 id="apiUnitTesting">4.8. Unit testing</h3> 4101<div class="paragraph"> 4102<p>Business processes are an integral part of software projects and they should be tested in the same way normal application logic is tested: with unit tests. Since Activiti is an embeddable Java engine, writing unit tests for business processes is as simple as writing regular unit tests.</p> 4103</div> 4104<div class="paragraph"> 4105<p>Activiti supports both JUnit versions 3 and 4 styles of unit testing. In the JUnit 3 style, the <code>org.activiti.engine.test.ActivitiTestCase</code> must be extended. This will make the ProcessEngine and the services available through protected member fields. In the <code>setup()</code> of the test, the processEngine will be initialized by default with the <code>activiti.cfg.xml</code> resource on the classpath. To specify a different configuration file, override the <em>getConfigurationResource()</em> method. Process engines are cached statically over multiple unit tests when the configuration resource is the same.</p> 4106</div> 4107<div class="paragraph"> 4108<p>By extending <code>ActivitiTestCase</code>, you can annotate test methods with <code>org.activiti.engine.test.Deployment</code>. Before the test is run, a resource file of the form <code>testClassName.testMethod.bpmn20.xml</code> in the same package as the test class, will be deployed. At the end of the test, the deployment will be deleted, including all related process instances, tasks, etc. The <code>Deployment</code> annotation also supports setting the resource location explicitly. See the class itself for more information.</p> 4109</div> 4110<div class="paragraph"> 4111<p>Taking all that in account, a JUnit 3 style test looks as follows.</p> 4112</div> 4113<div class="listingblock"> 4114<div class="content"> 4115<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4116 2 4117 3 4118 4 4119 5 4120 6 4121 7 4122 8 4123 9 412410 412511 412612 412713</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyBusinessProcessTest</span> <span class="tok-kd">extends</span> <span class="tok-n">ActivitiTestCase</span> <span class="tok-o">{</span> 4128 4129 <span class="tok-nd">@Deployment</span> 4130 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">testSimpleProcess</span><span class="tok-o">()</span> <span class="tok-o">{</span> 4131 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"simpleProcess"</span><span class="tok-o">);</span> 4132 4133 <span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 4134 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"My Task"</span><span class="tok-o">,</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 4135 4136 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 4137 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 4138 <span class="tok-o">}</span> 4139<span class="tok-o">}</span> 4140</td></tr></table></code></pre> 4141</div> 4142</div> 4143<div class="paragraph"> 4144<p>To get the same functionality when using the JUnit 4 style of writing unit tests, the <code>org.activiti.engine.test.ActivitiRule</code> Rule must be used. Through this rule, the process engine and services are available through getters. As with the <code>ActivitiTestCase</code> (see above), including this <code>Rule</code> will enable the use of the <code>org.activiti.engine.test.Deployment</code> annotation (see above for an explanation of its use and configuration) and it will look for the default configuration file on the classpath. Process engines are statically cached over multiple unit tests when using the same configuration resource.</p> 4145</div> 4146<div class="paragraph"> 4147<p>The following code snippet shows an example of using the JUnit 4 style of testing and the usage of the <code>ActivitiRule</code>.</p> 4148</div> 4149<div class="listingblock"> 4150<div class="content"> 4151<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4152 2 4153 3 4154 4 4155 5 4156 6 4157 7 4158 8 4159 9 416010 416111 416212 416313 416414 416515 416616 416717 416818 416919</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyBusinessProcessTest</span> <span class="tok-o">{</span> 4170 4171 <span class="tok-nd">@Rule</span> 4172 <span class="tok-kd">public</span> <span class="tok-n">ActivitiRule</span> <span class="tok-n">activitiRule</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ActivitiRule</span><span class="tok-o">();</span> 4173 4174 <span class="tok-nd">@Test</span> 4175 <span class="tok-nd">@Deployment</span> 4176 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">ruleUsageExample</span><span class="tok-o">()</span> <span class="tok-o">{</span> 4177 <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">activitiRule</span><span class="tok-o">.</span><span class="tok-na">getRuntimeService</span><span class="tok-o">();</span> 4178 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"ruleUsage"</span><span class="tok-o">);</span> 4179 4180 <span class="tok-n">TaskService</span> <span class="tok-n">taskService</span> <span class="tok-o">=</span> <span class="tok-n">activitiRule</span><span class="tok-o">.</span><span class="tok-na">getTaskService</span><span class="tok-o">();</span> 4181 <span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 4182 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"My Task"</span><span class="tok-o">,</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 4183 4184 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 4185 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 4186 <span class="tok-o">}</span> 4187<span class="tok-o">}</span> 4188</td></tr></table></code></pre> 4189</div> 4190</div> 4191</div> 4192<div class="sect2"> 4193<h3 id="apiDebuggingUnitTest">4.9. Debugging unit tests</h3> 4194<div class="paragraph"> 4195<p>When using the in-memory H2 database for unit tests, the following instructions allow to easily inspect the data in the Activiti database during a debugging session. The screenshots here are taken in Eclipse, but the mechanism should be similar for other IDEs.<
4195/p> 4196</div> 4197<div class="paragraph"> 4198<p>Suppose we have put a <em>breakpoint</em> somewhere in our unit test. In Eclipse this is done by double-clicking in the left border next to the code:</p> 4199</div> 4200<div class="imageblock" style="text-align: center"> 4201<div class="content"> 4202<img src="images/api.test.debug.breakpoint.png" alt="api.test.debug.breakpoint"> 4203</div> 4204</div> 4205<div class="paragraph"> 4206<p>If we now run the unit test in <em>debug</em> mode (right-click in test class, select <em>Run as</em> and then <em>JUnit test</em>), the test execution halts at our breakpoint, where we can now inspect the variables of our test as shown in the right upper panel.</p> 4207</div> 4208<div class="imageblock" style="text-align: center"> 4209<div class="content"> 4210<img src="images/api.test.debug.view.png" alt="api.test.debug.view"> 4211</div> 4212</div> 4213<div class="paragraph"> 4214<p>To inspect the Activiti data, open up the <em>'Display'</em> window (if this window isn’t there, open Window→Show View→Other and select <em>Display</em>.) and type (code completion is available) <code>org.h2.tools.Server.createWebServer("-web").start()</code></p> 4215</div> 4216<div class="imageblock" style="text-align: center"> 4217<div class="content"> 4218<img src="images/api.test.debug.start.h2.server.png" alt="api.test.debug.start.h2.server"> 4219</div> 4220</div> 4221<div class="paragraph"> 4222<p>Select the line you’ve just typed and right-click on it. Now select <em>Display</em> (or execute the shortcut instead of right-clicking)</p> 4223</div> 4224<div class="imageblock" style="text-align: center"> 4225<div class="content"> 4226<img src="images/api.test.debug.start.h2.server.2.png" alt="api.test.debug.start.h2.server.2"> 4227</div> 4228</div> 4229<div class="paragraph"> 4230<p>Now open up a browser and go to <a href="http://localhost:8082"><a href="http://localhost:8082" class="bare">http://localhost:8082</a></a>, and fill in the JDBC URL to the in-memory database (by default this is <code>jdbc:h2:mem:activiti</code>), and hit the connect button.</p> 4231</div> 4232<div class="imageblock" style="text-align: center"> 4233<div class="content"> 4234<img src="images/api.test.debug.h2.login.png" alt="api.test.debug.h2.login"> 4235</div> 4236</div> 4237<div class="paragraph"> 4238<p>You can now see the Activiti data and use it to understand how and why your unit test is executing your process in a certain way.</p> 4239</div> 4240<div class="imageblock" style="text-align: center"> 4241<div class="content"> 4242<img src="images/api.test.debug.h2.tables.png" alt="api.test.debug.h2.tables"> 4243</div> 4244</div> 4245</div> 4246<div class="sect2"> 4247<h3 id="apiProcessEngineInWebApp">4.10. The process engine in a web application</h3> 4248<div class="paragraph"> 4249<p>The <code>ProcessEngine</code> is a thread-safe class and can easily be shared among multiple threads. In a web application, this means it is possible to create the process engine once when the container boots and shut down the engine when the container goes down.</p> 4250</div> 4251<div class="paragraph"> 4252<p>The following code snippet shows how you can write a simple <code>ServletContextListener</code> to initialize and destroy process engines in a plain Servlet environment:</p> 4253</div> 4254<div class="listingblock"> 4255<div class="content"> 4256<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4257 2 4258 3 4259 4 4260 5 4261 6 4262 7 4263 8 4264 9 426510 426611</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ProcessEnginesServletContextListener</span> <span class="tok-kd">implements</span> <span class="tok-n">ServletContextListener</span> <span class="tok-o">{</span> 4267 4268 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">contextInitialized</span><span class="tok-o">(</span><span class="tok-n">ServletContextEvent</span> <span class="tok-n">servletContextEvent</span><span class="tok-o">)</span> <span class="tok-o">{</span> 4269 <span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">init</span><span class="tok-o">();</span> 4270 <span class="tok-o">}</span> 4271 4272 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">contextDestroyed</span><span class="tok-o">(</span><span class="tok-n">ServletContextEvent</span> <span class="tok-n">servletContextEvent</span><span class="tok-o">)</span> <span class="tok-o">{</span> 4273 <span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">destroy</span><span class="tok-o">();</span> 4274 <span class="tok-o">}</span> 4275 4276<span class="tok-o">}</span> 4277</td></tr></table></code></pre> 4278</div> 4279</div> 4280<div class="paragraph"> 4281<p>The <code>contextInitialized</code> method will delegate to <code>ProcessEngines.init()</code>. That will look for <code>activiti.cfg.xml</code> resource files on the classpath, and create a <code>ProcessEngine</code> for the given configurations (e.g. multiple jars with a configuration file). If you have multiple such resource files on the classpath, make sure they all have different names. When the process engine is needed, it can be fetched using</p> 4282</div> 4283<div class="listingblock"> 4284<div class="content"> 4285<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">getDefaultProcessEngine</span><span class="tok-o">()</span> 4286</td></tr></table></code></pre> 4287</div> 4288</div> 4289<div class="paragraph"> 4290<p>or</p> 4291</div> 4292<div class="listingblock"> 4293<div class="content"> 4294<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessEngines</span><span class="tok-o">.</span><span class="tok-na">getProcessEngine</span><span class="tok-o">(</span><span class="tok-s">"myName"</span><span class="tok-o">);</span> 4295</td></tr></table></code></pre> 4296</div> 4297</div> 4298<div class="paragraph"> 4299<p>Of course, it is also possible to use any of the variants of creating a process engine,
4300as described in the <a href="#configuration">configuration section</a>.</p> 4301</div> 4302<div class="paragraph"> 4303<p>The <code>contextDestroyed</code> method of the context-listener delegates to <code>ProcessEngines.destroy()</code>. That will properly close all initialized process engines.</p> 4304</div> 4305</div> 4306</div> 4307</div> 4308<div class="sect1"> 4309<h2 id="springintegration">5. Spring integration</h2> 4310<div class="sectionbody"> 4311<div class="paragraph"> 4312<p>While you can definitely use Activiti without Spring, we’ve provided some very nice integration features that are explained in this chapter.</p> 4313</div> 4314<div class="sect2"> 4315<h3 id="_processenginefactorybean">5.1. ProcessEngineFactoryBean</h3> 4316<div class="paragraph"> 4317<p>The <code>ProcessEngine</code> can be configured as a regular Spring bean. The starting point of the integration is the class <code>org.activiti.spring.ProcessEngineFactoryBean</code>. That bean takes a process engine configuration and creates the process engine. This means that the creation and configuration of properties for Spring is the same as documented in the <a href="#configuration">configuration section</a>. For Spring integration the configuration and engine beans will look like this:</p> 4318</div> 4319<div class="listingblock"> 4320<div class="content"> 4321<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 43222 43233 43244 43255 43266 43277</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.SpringProcessEngineConfiguration"</span><span class="tok-nt">></span> 4328 ... 4329<span class="tok-nt"></bean></span> 4330 4331<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.ProcessEngineFactoryBean"</span><span class="tok-nt">></span> 4332 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">ref=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-nt">/></span> 4333<span class="tok-nt"></bean></span> 4334</td></tr></table></code></pre> 4335</div> 4336</div> 4337<div class="paragraph"> 4338<p>Note that the <code>processEngineConfiguration</code> bean now uses the <code>org.activiti.spring.SpringProcessEngineConfiguration</code> class.</p> 4339</div> 4340</div> 4341<div class="sect2"> 4342<h3 id="_transactions">5.2. Transactions</h3> 4343<div class="paragraph"> 4344<p>We’ll explain the <code>SpringTransactionIntegrationTest</code> found in the Spring examples of the distribution step by step. Below is the Spring configuration file that we use in this example (you can find it in SpringTransactionIntegrationTest-context.xml). The section shown below contains the dataSource, transactionManager, processEngine and the Activiti Engine services.</p> 4345</div> 4346<div class="paragraph"> 4347<p>When passing the DataSource to the <code>SpringProcessEngineConfiguration</code> (using property "dataSource"), Activiti uses a <code>org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy</code> internally, which wraps the passed DataSource. This is done to make sure the SQL connections retrieved from the DataSource and the Spring transactions play well together. This implies that it’s no longer needed to proxy the dataSource yourself in Spring configuration, although it’s still allowed to pass a <code>TransactionAwareDataSourceProxy</code> into the <code>SpringProcessEngineConfiguration</code>. In this case no additional wrapping will occur.</p> 4348</div> 4349<div class="paragraph"> 4350<p><strong>Make sure when declaring a <code>TransactionAwareDataSourceProxy</code> in Spring configuration yourself, that you don’t use it for resources that are already aware of Spring-transactions (e.g. DataSourceTransactionManager and JPATransactionManager need the un-proxied dataSource).</strong></p> 4351</div> 4352<div class="listingblock"> 4353<div class="content"> 4354<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4355 2 4356 3 4357 4 4358 5 4359 6 4360 7 4361 8 4362 9 436310 436411 436512 436613 436714 436815 436916 437017 437118 437219 437320 437421 437522 437623 437724 437825 437926 438027 438128 438229 438330 438431 438532 438633 438734 438835 438936 439037</div></td><td class="code"><span></span><span class="tok-nt"><beans</span> <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.springframework.org/schema/beans"</span>
4391 <span class="tok-na">xmlns:context=</span><span class="tok-s">"http://www.springframework.org/schema/context"</span> 4392 <span class="tok-na">xmlns:tx=</span><span class="tok-s">"http://www.springframework.org/schema/tx"</span> 4393 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 4394 <span class="tok-na">xsi:schemaLocation=</span><span class="tok-s">"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd</span> 4395<span class="tok-s"> http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd</span> 4396<span class="tok-s"> http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd"</span><span class="tok-nt">></span> 4397 4398 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"dataSource"</span> <span class="tok-na">class=</span><span class="tok-s">"org.springframework.jdbc.datasource.SimpleDriverDataSource"</span><span class="tok-nt">></span> 4399 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"driverClass"</span> <span class="tok-na">value=</span><span class="tok-s">"org.h2.Driver"</span> <span class="tok-nt">/></span> 4400 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"url"</span> <span class="tok-na">value=</span><span class="tok-s">"jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000"</span> <span class="tok-nt">/></span> 4401 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"username"</span> <span class="tok-na">value=</span><span class="tok-s">"sa"</span> <span class="tok-nt">/></span> 4402 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"password"</span> <span class="tok-na">value=</span><span class="tok-s">""</span> <span class="tok-nt">/></span> 4403 <span class="tok-nt"></bean></span> 4404 4405 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">class=</span><span class="tok-s">"org.springframework.jdbc.datasource.DataSourceTransactionManager"</span><span class="tok-nt">></span> 4406 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"dataSource"</span> <span class="tok-na">ref=</span><span class="tok-s">"dataSource"</span> <span class="tok-nt">/></span> 4407 <span class="tok-nt"></bean></span> 4408 4409 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.SpringProcessEngineConfiguration"</span><span class="tok-nt">></span> 4410 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"dataSource"</span> <span class="tok-na">ref=</span><span class="tok-s">"dataSource"</span> <span class="tok-nt">/></span> 4411 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">ref=</span><span class="tok-s">"transactionManager"</span> <span class="tok-nt">/></span> 4412 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 4413 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"asyncExecutorActivate"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 4414 <span class="tok-nt"></bean></span> 4415 4416 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.ProcessEngineFactoryBean"</span><span class="tok-nt">></span> 4417 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">ref=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-nt">/></span> 4418 <span class="tok-nt"></bean></span> 4419 4420 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"repositoryService"</span> <span class="tok-na">factory-bean=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">factory-method=</span><span class="tok-s">"getRepositoryService"</span> <span class="tok-nt">/></span> 4421 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"runtimeService"</span> <span class="tok-na">factory-bean=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">factory-method=</span><span class="tok-s">"getRuntimeService"</span> <span class="tok-nt">/></span> 4422 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"taskService"</span> <span class="tok-na">factory-bean=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">factory-method=</span><span class="tok-s">"getTaskService"</span> <span class="tok-nt">/></span> 4423 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"historyService"</span> <span class="tok-na">factory-bean=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">factory-method=</span><span class="tok-s">"getHistoryService"</span> <span class="tok-nt">/></span> 4424 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"managementService"</span> <span class="tok-na">factory-bean=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">factory-method=</span><span class="tok-s">"getManagementService"</span> <span class="tok-nt">/></span> 4425 4426... 4427</td></tr></table></code></pre> 4428</div> 4429</div> 4430<div class="paragraph"> 4431<p>The remainder of that Spring configuration file contains the beans and configuration that we’ll use in this particular example:</p> 4432</div> 4433<div class="listingblock"> 4434<div class="content"> 4435<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4436 2 4437 3 4438 4 4439 5 4440 6 4441 7 4442 8 4443 9 444410 444511</div></td><td class="code"><span></span><span class="tok-nt"><beans></span> 4446 ... 4447 <span class="tok-nt"><tx:annotation-driven</span> <span class="tok-na">transaction-manager=</span><span class="tok-s">"transactionManager"</span><span class="tok-nt">/></span> 4448 4449 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"userBean"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.test.UserBean"</span><span class="tok-nt">></span> 4450 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"runtimeService"</span> <span class="tok-na">ref=</span><span class="tok-s">"runtimeService"</span> <span class="tok-nt">/></span> 4451 <span class="tok-nt"></bean></span> 4452 4453 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"printer"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.test.Printer"</span> <span class="tok-nt">/></span> 4454 4455<span class="tok-nt"></beans></span> 4456</td></tr></table></code></pre> 4457</div> 4458</div> 4459<div class="paragraph"> 4460<p>First the application context is created with any of the Spring ways to do that. In this example you could use a classpath XML resource to configure our Spring application context:</p> 4461</div> 4462<div class="listingblock"> 4463<div class="content"> 4464<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1
44652</div></td><td class="code"><span></span><span class="tok-n">ClassPathXmlApplicationContext</span> <span class="tok-n">applicationContext</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ClassPathXmlApplicationContext</span><span class="tok-o">(</span> 4466 <span class="tok-s">"org/activiti/examples/spring/SpringTransactionIntegrationTest-context.xml"</span><span class="tok-o">);</span> 4467</td></tr></table></code></pre> 4468</div> 4469</div> 4470<div class="paragraph"> 4471<p>or since it is a test:</p> 4472</div> 4473<div class="listingblock"> 4474<div class="content"> 4475<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nd">@ContextConfiguration</span><span class="tok-o">(</span><span class="tok-s">"classpath:org/activiti/spring/test/transaction/SpringTransactionIntegrationTest-context.xml"</span><span class="tok-o">)</span> 4476</td></tr></table></code></pre> 4477</div> 4478</div> 4479<div class="paragraph"> 4480<p>Then we can get the service beans and invoke methods on them. The ProcessEngineFactoryBean will have added an extra interceptor to the services that applies Propagation.REQUIRED transaction semantics on the Activiti service methods. So, for example, we can use the repositoryService to deploy a process like this:</p> 4481</div> 4482<div class="listingblock"> 4483<div class="content"> 4484<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 44852 44863 44874 44885 44896 44907</div></td><td class="code"><span></span><span class="tok-n">RepositoryService</span> <span class="tok-n">repositoryService</span> <span class="tok-o">=</span> 4491 <span class="tok-o">(</span><span class="tok-n">RepositoryService</span><span class="tok-o">)</span> <span class="tok-n">applicationContext</span><span class="tok-o">.</span><span class="tok-na">getBean</span><span class="tok-o">(</span><span class="tok-s">"repositoryService"</span><span class="tok-o">);</span> 4492<span class="tok-n">String</span> <span class="tok-n">deploymentId</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span> 4493 <span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 4494 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"org/activiti/spring/test/hello.bpmn20.xml"</span><span class="tok-o">)</span> 4495 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">()</span> 4496 <span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">();</span> 4497</td></tr></table></code></pre> 4498</div> 4499</div> 4500<div class="paragraph"> 4501<p>The other way around also works. In this case, the Spring transaction will be around the userBean.hello() method and the Activiti service method invocation will join that same transaction.</p> 4502</div> 4503<div class="listingblock"> 4504<div class="content"> 4505<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 45062</div></td><td class="code"><span></span><span class="tok-n">UserBean</span> <span class="tok-n">userBean</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">UserBean</span><span class="tok-o">)</span> <span class="tok-n">applicationContext</span><span class="tok-o">.</span><span class="tok-na">getBean</span><span class="tok-o">(</span><span class="tok-s">"userBean"</span><span class="tok-o">);</span> 4507<span class="tok-n">userBean</span><span class="tok-o">.</span><span class="tok-na">hello</span><span class="tok-o">();</span> 4508</td></tr></table></code></pre> 4509</div> 4510</div> 4511<div class="paragraph"> 4512<p>The UserBean looks like this. Remember from above in the Spring bean configuration we injected the repositoryService into the userBean.</p> 4513</div> 4514<div class="listingblock"> 4515<div class="content"> 4516<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4517 2 4518 3 4519 4 4520 5 4521 6 4522 7 4523 8 4524 9 452510 452611 452712 452813 452914 453015 453116 453217</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">UserBean</span> <span class="tok-o">{</span> 4533 4534 <span class="tok-cm">/** injected by Spring */</span> 4535 <span class="tok-kd">private</span> <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">;</span> 4536 4537 <span class="tok-nd">@Transactional</span> 4538 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">hello</span><span class="tok-o">()</span> <span class="tok-o">{</span> 4539 <span class="tok-c1">// here you can do transactional stuff in your domain model</span> 4540 <span class="tok-c1">// and it will be combined in the same transaction as</span> 4541 <span class="tok-c1">// the startProcessInstanceByKey to the Activiti RuntimeService</span> 4542 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"helloProcess"</span><span class="tok-o">);</span> 4543 <span class="tok-o">}</span> 4544 4545 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setRuntimeService</span><span class="tok-o">(</span><span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">)</span> <span class="tok-o">{</span> 4546 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">;</span> 4547 <span class="tok-o">}</span> 4548<span class="tok-o">}</span> 4549</td></tr></table></code></pre> 4550</div> 4551</div> 4552</div> 4553<div class="sect2"> 4554<h3 id="springExpressions">5.3. Expressions</h3> 4555<div class="paragraph"> 4556<p>When using the ProcessEngineFactoryBean, by default, all <a href="#apiExpressions">expressions</a> in the BPMN processes will also <em>see</em> all the Spring beans. It’s possible to limit the beans you want to expose in expressions or even exposing no beans at all using a map that you can configure. The example below exposes a single bean (printer), available to use under the key "printer". <strong>To have NO beans exposed at all, just pass an empty list as <em>beans</em> property on the SpringProcessEngineConfiguration. When no <em>beans</em> property is set, all Spring beans in the context will be available.</strong></p> 4557</div> 4558<div class="listingblock"> 4559<div class="content"> 4560<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4561 2 4562 3 4563 4 4564 5 4565 6 4566 7 4567 8 4568 9 456910</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.SpringProcessEngineConfiguration"</span><span class="tok-nt">></span> 4570 ... 4571 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"beans"</span><span class="tok-nt">></span> 4572 <span class="tok-nt"><map></span>
4573 <span class="tok-nt"><entry</span> <span class="tok-na">key=</span><span class="tok-s">"printer"</span> <span class="tok-na">value-ref=</span><span class="tok-s">"printer"</span> <span class="tok-nt">/></span> 4574 <span class="tok-nt"></map></span> 4575 <span class="tok-nt"></property></span> 4576<span class="tok-nt"></bean></span> 4577 4578<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"printer"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.examples.spring.Printer"</span> <span class="tok-nt">/></span> 4579</td></tr></table></code></pre> 4580</div> 4581</div> 4582<div class="paragraph"> 4583<p>Now the exposed beans can be used in expressions: for example, the SpringTransactionIntegrationTest <code>hello.bpmn20.xml</code> shows how a method on a Spring bean can be invoked using a UEL method expression:</p> 4584</div> 4585<div class="listingblock"> 4586<div class="content"> 4587<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4588 2 4589 3 4590 4 4591 5 4592 6 4593 7 4594 8 4595 9 459610 459711 459812 459913 460014 460115</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"definitions"</span><span class="tok-nt">></span> 4602 4603 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"helloProcess"</span><span class="tok-nt">></span> 4604 4605 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span> <span class="tok-nt">/></span> 4606 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"start"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"print"</span> <span class="tok-nt">/></span> 4607 4608 <span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"print"</span> <span class="tok-na">activiti:expression=</span><span class="tok-s">"#{printer.printMessage()}"</span> <span class="tok-nt">/></span> 4609 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"print"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 4610 4611 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 4612 4613 <span class="tok-nt"></process></span> 4614 4615<span class="tok-nt"></definitions></span> 4616</td></tr></table></code></pre> 4617</div> 4618</div> 4619<div class="paragraph"> 4620<p>Where <code>Printer</code> looks like this:</p> 4621</div> 4622<div class="listingblock"> 4623<div class="content"> 4624<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 46252 46263 46274 46285 46296</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">Printer</span> <span class="tok-o">{</span> 4630 4631 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">printMessage</span><span class="tok-o">()</span> <span class="tok-o">{</span> 4632 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"hello world"</span><span class="tok-o">);</span> 4633 <span class="tok-o">}</span> 4634<span class="tok-o">}</span> 4635</td></tr></table></code></pre> 4636</div> 4637</div> 4638<div class="paragraph"> 4639<p>And the Spring bean configuration (also shown above) looks like this:</p> 4640</div> 4641<div class="listingblock"> 4642<div class="content"> 4643<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 46442 46453 46464 46475 46486</div></td><td class="code"><span></span><span class="tok-nt"><beans></span> 4649 ... 4650 4651 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"printer"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.examples.spring.Printer"</span> <span class="tok-nt">/></span> 4652 4653<span class="tok-nt"></beans></span> 4654</td></tr></table></code></pre> 4655</div> 4656</div> 4657</div> 4658<div class="sect2"> 4659<h3 id="_automatic_resource_deployment">5.4. Automatic resource deployment</h3> 4660<div class="paragraph"> 4661<p>Spring integration also has a special feature for deploying resources. In the process engine configuration, you can specify a set of resources. When the process engine is created, all those resources will be scanned and deployed. There is filtering in place that prevents duplicate deployments. Only when the resources actually have changed, will new deployments be deployed to the Activiti DB. This makes sense in a lot of use case, where the Spring container is rebooted often (e.g. testing).</p> 4662</div> 4663<div class="paragraph"> 4664<p>Here’s an example:</p> 4665</div> 4666<div class="listingblock"> 4667<div class="content"> 4668<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 46692 46703 46714 46725 46736 46747 46758 46769</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.SpringProcessEngineConfiguration"</span><span class="tok-nt">></span> 4677 ... 4678 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"deploymentResources"</span> 4679 <span class="tok-na">value=</span><span class="tok-s">"classpath*:/org/activiti/spring/test/autodeployment/autodeploy.*.bpmn20.xml"</span> <span class="tok-nt">/></span> 4680<span class="tok-nt"></bean></span> 4681 4682<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.ProcessEngineFactoryBean"</span><span class="tok-nt">></span> 4683 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">ref=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-nt">/></span> 4684<span class="tok-nt"></bean></span> 4685</td></tr></table></code></pre> 4686</div> 4687</div> 4688<div class="paragraph"> 4689<p>By default, the configuration above will group all of the resources matching the filtering into a single deployment to the Activiti engine. The duplicate filtering to prevent re-deployment of unchanged resources applies to the whole deployment. In some cases, this may not be what you want. For instance, if you deploy a set of process resources this way and only a single 4690 process definition in those resources has changed, the deployment as a whole will be considered new and all of the process definitions in that deployment will be re-deployed, resulting in new versions of each of the process definitions, even though only one was actually changed.</p> 4691</div> 4692<div class="paragraph"> 4693<p>To be able to customize the way deployments are determined, you can specify an additional property in the <code>SpringProcessEngineConfiguration</code>, <code>deploymentMode</code>. This property defines the way deployments will be determined from the set of resources that match the filter. There are 3 values that are supported by default for this property:</p> 4694</div> 4695<div class="ulist"> 4696<ul> 4697<li> 4698<p><code>default</code>: Group all resources into a single deployment and apply duplicate filtering to that deployment. This is the default value and it will be used if you don’t specify a value.</p> 4699</li> 4700<li> 4701<p><code>single-resource</code>: Create a separate deployment for each individual resource and apply duplicate filtering to that deployment. This is the value you would use to have each process definition be deployed separately and only create a new process definition version if it has changed.</p> 4702</li> 4703<li> 4704<p><code>resource-parent-folder</code>: Create a separate deployment for resources that share the same parent folder and apply duplicate filtering to that deployment. This value can be used to create separate deployments for most resources, but still be able to group some by placing them in a shared folder. Here’s an example of how to specify the <code>single-resource</code> configuration for <code>deploymentMode</code>:</p> 4705</li> 4706</ul> 4707</div> 4708<div class="listingblock"> 4709<div class="content"> 4710<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 47112 47123 47134 47145 47156</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> 4716 <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.SpringProcessEngineConfiguration"</span><span class="tok-nt">></span> 4717 ... 4718 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"deploymentResources"</span> <span class="tok-na">value=</span><span class="tok-s">"classpath*:/activiti/*.bpmn"</span> <span class="tok-nt">/></span> 4719 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"deploymentMode"</span> <span class="tok-na">value=</span><span class="tok-s">"single-resource"</span> <span class="tok-nt">/></span> 4720<span class="tok-nt"></bean></span> 4721</td></tr></table></code></pre> 4722</div> 4723</div> 4724<div class="paragraph"> 4725<p>In addition to using the values listed above for <code>deploymentMode</code>, you may require customized behavior towards determining deployments. If so, you can create a subclass of <code>SpringProcessEngineConfiguration</code> and override the <code>getAutoDeploymentStrategy(String deploymentMode)</code> method. This method determines which deployment strategy is used for a certain value of the <code>deploymentMode</code> configuration.</p> 4726</div> 4727</div> 4728<div class="sect2"> 4729<h3 id="springUnitTest">5.5. Unit testing</h3> 4730<div class="paragraph"> 4731<p>When integrating with Spring, business processes can be tested very easily using the standard <a href="#apiUnitTesting">Activiti testing facilities</a>. The following example shows how a business process is tested in a typical Spring-based unit test:</p> 4732</div> 4733<div class="listingblock"> 4734<div class="content"> 4735<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4736 2 4737 3 4738 4 4739 5 4740 6 4741 7 4742 8 4743 9 474410 474511 474612 474713 474814 474915 475016 475117 475218 475319 475420 475521 475622 475723 475824 475925 476026</div></td><td class="code"><span></span><span class="tok-nd">@RunWith</span><span class="tok-o">(</span><span class="tok-n">
4760SpringJUnit4ClassRunner</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">)</span> 4761<span class="tok-nd">@ContextConfiguration</span><span class="tok-o">(</span><span class="tok-s">"classpath:org/activiti/spring/test/junit4/springTypicalUsageTest-context.xml"</span><span class="tok-o">)</span> 4762<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyBusinessProcessTest</span> <span class="tok-o">{</span> 4763 4764 <span class="tok-nd">@Autowired</span> 4765 <span class="tok-kd">private</span> <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">;</span> 4766 4767 <span class="tok-nd">@Autowired</span> 4768 <span class="tok-kd">private</span> <span class="tok-n">TaskService</span> <span class="tok-n">taskService</span><span class="tok-o">;</span> 4769 4770 <span class="tok-nd">@Autowired</span> 4771 <span class="tok-nd">@Rule</span> 4772 <span class="tok-kd">public</span> <span class="tok-n">ActivitiRule</span> <span class="tok-n">activitiSpringRule</span><span class="tok-o">;</span> 4773 4774 <span class="tok-nd">@Test</span> 4775 <span class="tok-nd">@Deployment</span> 4776 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">simpleProcessTest</span><span class="tok-o">()</span> <span class="tok-o">{</span> 4777 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"simpleProcess"</span><span class="tok-o">);</span> 4778 <span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 4779 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"My Task"</span><span class="tok-o">,</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 4780 4781 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 4782 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 4783 4784 <span class="tok-o">}</span> 4785<span class="tok-o">}</span> 4786</td></tr></table></code></pre> 4787</div> 4788</div> 4789<div class="paragraph"> 4790<p>Note that for this to work, you need to define a <em>org.activiti.engine.test.ActivitiRule</em> bean in the Spring configuration (which is injected by auto-wiring in the example above).</p> 4791</div> 4792<div class="listingblock"> 4793<div class="content"> 4794<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 47952 47963</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"activitiRule"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.test.ActivitiRule"</span><span class="tok-nt">></span> 4797 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"processEngine"</span> <span class="tok-na">ref=</span><span class="tok-s">"processEngine"</span> <span class="tok-nt">/></span> 4798<span class="tok-nt"></bean></span> 4799</td></tr></table></code></pre> 4800</div> 4801</div> 4802</div> 4803<div class="sect2"> 4804<h3 id="_jpa_with_hibernate_4_2_x">5.6. JPA with Hibernate 4.2.x</h3> 4805<div class="paragraph"> 4806<p>When using Hibernate 4.2.x JPA in service task or listener logic in the Activiti Engine an additional dependency to Spring ORM is needed. This is not needed for Hibernate 4.1.x or lower. The following dependency should be added:</p> 4807</div> 4808<div class="listingblock"> 4809<div class="content"> 4810<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 48112 48123 48134 48145</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 4815 <span class="tok-nt"><groupId></span>org.springframework<span class="tok-nt"></groupId></span> 4816 <span class="tok-nt"><artifactId></span>spring-orm<span class="tok-nt"></artifactId></span> 4817 <span class="tok-nt"><version></span>${org.springframework.version}<span class="tok-nt"></version></span> 4818<span class="tok-nt"></dependency></span> 4819</td></tr></table></code></pre> 4820</div> 4821</div> 4822</div> 4823<div class="sect2"> 4824<h3 id="springSpringBoot">5.7. Spring Boot</h3> 4825<div class="paragraph"> 4826<p>Spring Boot is an application framework which, according to <a href="http://projects.spring.io/spring-boot/">its website</a>, <em>makes it easy to create stand-alone, production-grade Spring based Applications that can you can "just run". It takes an opinionated view of the Spring platform and third-party libraries so you can get started with minimum fuss. Most Spring Boot applications need very little Spring configuration</em>.</p> 4827</div> 4828<div class="paragraph"> 4829<p>For more information on Spring Boot, see <a href="http://projects.spring.io/spring-boot/"><a href="http://projects.spring.io/spring-boot/" class="bare">http://projects.spring.io/spring-boot/</a></a></p> 4830</div> 4831<div class="paragraph"> 4832<p>The Spring Boot - Activiti integration is currently experimental. It has been developer together with Spring committers, but it is still early days. We welcome all to try it out and provide feedback.</p> 4833</div> 4834<div class="sect3"> 4835<h4 id="_compatibility">5.7.1. Compatibility</h4> 4836<div class="paragraph"> 4837<p>Spring Boot requires a JDK 7 runtime. Please check the Spring Boot documentation.</p> 4838</div> 4839</div> 4840<div class="sect3"> 4841<h4 id="_getting_started_2">5.7.2. Getting started</h4> 4842<div class="paragraph"> 4843<p>Spring Boot is all about convention over configuration. To get started, simply add the <em>spring-boot-starters-basic</em> dependency to your project. For example for Maven:</p> 4844</div> 4845<div class="listingblock"> 4846<div class="content"> 4847<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 48482 48493 48504 48515</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 4852 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 4853 <span class="tok-nt"><artifactId></span>activiti-spring-boot-starter-basic<span class="tok-nt"></artifactId></span> 4854 <span class="tok-nt"><version></span>${activiti.version}<span class="tok-nt"></version></span> 4855<span class="tok-nt"></dependency></span> 4856</td></tr></table></code></pre> 4857</div> 4858</div> 4859<div class="paragraph"> 4860<p>That’s all that’s needed. This dependency will transitively add the correct Activiti and Spring dependencies to the classpath. You can now write the Spring Boot application:</p> 4861</div> 4862<div class="listingblock"> 4863<div class="content"> 4864<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4865 2 4866 3 4867 4 4868 5 4869 6 4870 7 4871 8 4872 9 487310 487411 487512 487613 487714 487815</div></td><td class="code"><span></span><span class="tok-kn">
4878import</span> <span class="tok-nn">org.springframework.boot.SpringApplication</span><span class="tok-o">;</span> 4879<span class="tok-kn">import</span> <span class="tok-nn">org.springframework.boot.autoconfigure.EnableAutoConfiguration</span><span class="tok-o">;</span> 4880<span class="tok-kn">import</span> <span class="tok-nn">org.springframework.context.annotation.ComponentScan</span><span class="tok-o">;</span> 4881<span class="tok-kn">import</span> <span class="tok-nn">org.springframework.context.annotation.Configuration</span><span class="tok-o">;</span> 4882 4883<span class="tok-nd">@Configuration</span> 4884<span class="tok-nd">@ComponentScan</span> 4885<span class="tok-nd">@EnableAutoConfiguration</span> 4886<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyApplication</span> <span class="tok-o">{</span> 4887 4888 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kt">void</span> <span class="tok-nf">main</span><span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">[]</span> <span class="tok-n">args</span><span class="tok-o">)</span> <span class="tok-o">{</span> 4889 <span class="tok-n">SpringApplication</span><span class="tok-o">.</span><span class="tok-na">run</span><span class="tok-o">(</span><span class="tok-n">MyApplication</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">,</span> <span class="tok-n">args</span><span class="tok-o">);</span> 4890 <span class="tok-o">}</span> 4891 4892<span class="tok-o">}</span> 4893</td></tr></table></code></pre> 4894</div> 4895</div> 4896<div class="paragraph"> 4897<p>Activiti needs a database to store its data. If you would run the code above, it would give you an informative exception message that you need to add a database driver dependency to the classpath. For now, add the H2 database dependency:</p> 4898</div> 4899<div class="listingblock"> 4900<div class="content"> 4901<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 49022 49033 49044 49055</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 4906 <span class="tok-nt"><groupId></span>com.h2database<span class="tok-nt"></groupId></span> 4907 <span class="tok-nt"><artifactId></span>h2<span class="tok-nt"></artifactId></span> 4908 <span class="tok-nt"><version></span>1.4.183<span class="tok-nt"></version></span> 4909<span class="tok-nt"></dependency></span> 4910</td></tr></table></code></pre> 4911</div> 4912</div> 4913<div class="paragraph"> 4914<p>The application can now be started. You will see output like this:</p> 4915</div> 4916<div class="listingblock"> 4917<div class="content"> 4918<pre> . ____ _ __ _ _ 4919 /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ 4920( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ 4921 \\/ ___)| |_)| | | | | || (_| | ) ) ) ) 4922 ' |____| .__|_| |_|_| |_\__, | / / / / 4923 =========|_|==============|___/=/_/_/_/ 4924 :: Spring Boot :: (v1.1.6.RELEASE) 4925 4926MyApplication : Starting MyApplication on ... 4927s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@33cb5951: startup date [Wed Dec 17 15:24:34 CET 2014]; root of context hierarchy 4928a.s.b.AbstractProcessEngineConfiguration : No process definitions were found using the specified path (classpath:/processes/**.bpmn20.xml). 4929o.activiti.engine.impl.db.DbSqlSession : performing create on engine with resource org/activiti/db/create/activiti.h2.create.engine.sql 4930o.activiti.engine.impl.db.DbSqlSession : performing create on history with resource org/activiti/db/create/activiti.h2.create.history.sql 4931o.activiti.engine.impl.db.DbSqlSession : performing create on identity with resource org/activiti/db/create/activiti.h2.create.identity.sql 4932o.a.engine.impl.ProcessEngineImpl : ProcessEngine default created 4933o.a.e.i.a.DefaultAsyncJobExecutor : Starting up the default async job executor [org.activiti.spring.SpringAsyncExecutor]. 4934o.a.e.i.a.AcquireTimerJobsRunnable : {} starting to acquire async jobs due 4935o.a.e.i.a.AcquireAsyncJobsDueRunnable : {} starting to acquire async jobs due 4936o.s.j.e.a.AnnotationMBeanExporter : Registering beans for JMX exposure on startup 4937MyApplication : Started MyApplication in 2.019 seconds (JVM running for 2.294)</pre> 4938</div> 4939</div> 4940<div class="paragraph"> 4941<p>So by just adding the dependency to the classpath and using the <em>@EnableAutoConfiguration</em> annotation a lot has happened behind the scenes:</p> 4942</div> 4943<div class="ulist"> 4944<ul> 4945<li> 4946<p>An in-memory datasource is created automatically (since the H2 driver is on the classpath) and passed to the Activiti process engine configuration</p> 4947</li> 4948<li> 4949<p>An Activiti ProcessEngine bean is created and exposed</p> 4950</li> 4951<li> 4952<p>All the Activiti services are exposed as Spring beans</p> 4953</li> 4954<li> 4955<p>The Spring Job Executor is created</p> 4956</li> 4957</ul> 4958</div> 4959<div class="paragraph"> 4960<p>Also, any BPMN 2.0 process definition in the <em>processes</em> folder would be automatically deployed. Create a folder <em>processes</em> and add a dummy process definition (named <em>one-task-process.bpmn20.xml</em>) to this folder.</p> 4961</div> 4962<div class="listingblock"> 4963<div class="content"> 4964<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 4965 2 4966 3 4967 4 4968 5 4969 6 4970 7 4971 8 4972 9 497310 497411 497512 497613 497714 497815</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="UTF-8"?></span> 4979<span class="tok-nt"><definitions</span>
4980 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 4981 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 4982 <span class="tok-na">targetNamespace=</span><span class="tok-s">"Examples"</span><span class="tok-nt">></span> 4983 4984 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"oneTaskProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"The One Task Process"</span><span class="tok-nt">></span> 4985 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 4986 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask"</span> <span class="tok-nt">/></span> 4987 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"my task"</span> <span class="tok-nt">/></span> 4988 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 4989 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 4990 <span class="tok-nt"></process></span> 4991 4992<span class="tok-nt"></definitions></span> 4993</td></tr></table></code></pre> 4994</div> 4995</div> 4996<div class="paragraph"> 4997<p>Also add following code lines to test if the deployment actually worked. The <em>CommandLineRunner</em> is a special kind of Spring bean that is executed when the application boots:</p> 4998</div> 4999<div class="listingblock"> 5000<div class="content"> 5001<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5002 2 5003 3 5004 4 5005 5 5006 6 5007 7 5008 8 5009 9 501010 501111 501212 501313 501414 501515 501616 501717 501818 501919 502020 502121 502222 502323 502424 502525 502626 502727 502828</div></td><td class="code"><span></span><span class="tok-nd">@Configuration</span> 5029<span class="tok-nd">@ComponentScan</span> 5030<span class="tok-nd">@EnableAutoConfiguration</span> 5031<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyApplication</span> <span class="tok-o">{</span> 5032 5033 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kt">void</span> <span class="tok-nf">main</span><span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">[]</span> <span class="tok-n">args</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5034 <span class="tok-n">SpringApplication</span><span class="tok-o">.</span><span class="tok-na">run</span><span class="tok-o">(</span><span class="tok-n">MyApplication</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">,</span> <span class="tok-n">args</span><span class="tok-o">);</span> 5035 <span class="tok-o">}</span> 5036 5037 <span class="tok-nd">@Bean</span> 5038 <span class="tok-kd">public</span> <span class="tok-n">CommandLineRunner</span> <span class="tok-nf">init</span><span class="tok-o">(</span><span class="tok-kd">final</span> <span class="tok-n">RepositoryService</span> <span class="tok-n">repositoryService</span><span class="tok-o">,</span> 5039 <span class="tok-kd">final</span> <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">,</span> 5040 <span class="tok-kd">final</span> <span class="tok-n">TaskService</span> <span class="tok-n">taskService</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5041
5042 <span class="tok-k">return</span> <span class="tok-k">new</span> <span class="tok-n">CommandLineRunner</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5043 <span class="tok-nd">@Override</span> 5044 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">run</span><span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">...</span> <span class="tok-n">strings</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 5045 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Number of process definitions : "</span> 5046 <span class="tok-o">+</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createProcessDefinitionQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 5047 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Number of tasks : "</span> <span class="tok-o">+</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 5048 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"oneTaskProcess"</span><span class="tok-o">);</span> 5049 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Number of tasks after process start: "</span> <span class="tok-o">+</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">count</span><span class="tok-o">());</span> 5050 <span class="tok-o">}</span> 5051 <span class="tok-o">};</span> 5052 5053 <span class="tok-o">}</span> 5054 5055<span class="tok-o">}</span> 5056</td></tr></table></code></pre> 5057</div> 5058</div> 5059<div class="paragraph"> 5060<p>The output will be as expected:</p> 5061</div> 5062<div class="listingblock"> 5063<div class="content"> 5064<pre>Number of process definitions : 1 5065Number of tasks : 0 5066Number of tasks after process start : 1</pre> 5067</div> 5068</div> 5069</div> 5070<div class="sect3"> 5071<h4 id="_changing_the_database_and_connection_pool">5.7.3. Changing the database and connection pool</h4> 5072<div class="paragraph"> 5073<p>As stated above, Spring Boot is about convention over configuration. By default, by having only H2 on the classpath, it created an in memory datasource and passed that to the Activiti process engine configuration.</p> 5074</div> 5075<div class="paragraph"> 5076<p>To change the datasource, simply override the default by providing a Datasource bean. We’re using the <em>DataSourceBuilder</em> class here, which is a helper class from Spring Boot. If Tomcat, HikariCP or Commons DBCP are on the classpath one of them will be selected (in that order with Tomcat first). For example, to switch to a MySQL database:</p> 5077</div> 5078<div class="listingblock"> 5079<div class="content"> 5080<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 50812 50823 50834 50845 50856 50867 50878 50889</div></td><td class="code"><span></span><span class="tok-nd">@Bean</span> 5089<span class="tok-kd">public</span> <span class="tok-n">DataSource</span> <span class="tok-nf">database</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5090 <span class="tok-k">return</span> <span class="tok-n">DataSourceBuilder</span><span class="tok-o">.</span><span class="tok-na">create</span><span class="tok-o">()</span>
5091 <span class="tok-o">.</span><span class="tok-na">url</span><span class="tok-o">(</span><span class="tok-s">"jdbc:mysql://127.0.0.1:3306/activiti-spring-boot?characterEncoding=UTF-8"</span><span class="tok-o">)</span> 5092 <span class="tok-o">.</span><span class="tok-na">username</span><span class="tok-o">(</span><span class="tok-s">"alfresco"</span><span class="tok-o">)</span> 5093 <span class="tok-o">.</span><span class="tok-na">password</span><span class="tok-o">(</span><span class="tok-s">"alfresco"</span><span class="tok-o">)</span> 5094 <span class="tok-o">.</span><span class="tok-na">driverClassName</span><span class="tok-o">(</span><span class="tok-s">"com.mysql.jdbc.Driver"</span><span class="tok-o">)</span> 5095 <span class="tok-o">.</span><span class="tok-na">build</span><span class="tok-o">();</span> 5096<span class="tok-o">}</span> 5097</td></tr></table></code></pre> 5098</div> 5099</div> 5100<div class="paragraph"> 5101<p>Remove H2 from the Maven dependencies and add the MySQL driver and the Tomcat connection pooling to the classpath:</p> 5102</div> 5103<div class="listingblock"> 5104<div class="content"> 5105<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5106 2 5107 3 5108 4 5109 5 5110 6 5111 7 5112 8 5113 9 511410</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 5115 <span class="tok-nt"><groupId></span>mysql<span class="tok-nt"></groupId></span> 5116 <span class="tok-nt"><artifactId></span>mysql-connector-java<span class="tok-nt"></artifactId></span> 5117 <span class="tok-nt"><version></span>5.1.34<span class="tok-nt"></version></span> 5118<span class="tok-nt"></dependency></span> 5119<span class="tok-nt"><dependency></span> 5120 <span class="tok-nt"><groupId></span>org.apache.tomcat<span class="tok-nt"></groupId></span> 5121 <span class="tok-nt"><artifactId></span>tomcat-jdbc<span class="tok-nt"></artifactId></span> 5122 <span class="tok-nt"><version></span>8.0.15<span class="tok-nt"></version></span> 5123<span class="tok-nt"></dependency></span> 5124</td></tr></table></code></pre> 5125</div> 5126</div> 5127<div class="paragraph"> 5128<p>When the app is now booted up, you’ll see it uses MySQL as database (and the Tomcat connection pooling framework):</p> 5129</div> 5130<div class="listingblock"> 5131<div class="content"> 5132<pre>org.activiti.engine.impl.db.DbSqlSession : performing create on engine with resource org/activiti/db/create/activiti.mysql.create.engine.sql 5133org.activiti.engine.impl.db.DbSqlSession : performing create on history with resource org/activiti/db/create/activiti.mysql.create.history.sql 5134org.activiti.engine.impl.db.DbSqlSession : performing create on identity with resource org/activiti/db/create/activiti.mysql.create.identity.sql</pre> 5135</div> 5136</div> 5137<div class="paragraph"> 5138<p>When you reboot the application multiple times, you’ll see the number of tasks go up (the H2 in-memory database does not survive a shutdown, the MySQL does).</p> 5139</div> 5140</div> 5141<div class="sect3"> 5142<h4 id="_rest_support">5.7.4. REST support</h4> 5143<div class="paragraph"> 5144<p>Often, a REST API is needed on top of the embedded Activiti engine (interacting with the different services in a company). Spring Boot makes this really easy. Add following dependency to the classpath:</p> 5145</div> 5146<div class="listingblock"> 5147<div class="content"> 5148<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 51492 51503 51514 51525</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 5153 <span class="tok-nt"><groupId></span>org.springframework.boot<span class="tok-nt"></groupId></span> 5154 <span class="tok-nt"><artifactId></span>spring-boot-starter-web<span class="tok-nt"></artifactId></span> 5155 <span class="tok-nt"><version></span>${spring.boot.version}<span class="tok-nt"></version></span> 5156<span class="tok-nt"></dependency></span> 5157</td></tr></table></code></pre> 5158</div> 5159</div> 5160<div class="paragraph"> 5161<p>Create a new class, a Spring service, and create two methods: one to start our process and one to get a task list for a given assignee. We simply wrap Activiti calls here, but in real-life scenario’s this obviously will be more complex obviously.</p> 5162</div> 5163<div class="listingblock"> 5164<div class="content"> 5165<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5166 2 5167 3 5168 4 5169 5 5170 6 5171 7 5172 8 5173 9 517410 517511 517612 517713 517814 517915 518016 518117 518218 518319 518420</div></td><td class="code"><span></span><span class="tok-nd">@Service</span> 5185<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyService</span> <span class="tok-o">{</span> 5186 5187 <span class="tok-nd">@Autowired</span> 5188 <span class="tok-kd">private</span> <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">;</span> 5189 5190 <span class="tok-nd">@Autowired</span> 5191 <span class="tok-kd">private</span> <span class="tok-n">TaskService</span> <span class="tok-n">taskService</span><span class="tok-o">;</span> 5192 5193 <span class="tok-nd">@Transactional</span> 5194 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">startProcess</span><span class="tok-o">()</span> <span class="tok-o">{</span>
5195 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"oneTaskProcess"</span><span class="tok-o">);</span> 5196 <span class="tok-o">}</span> 5197 5198 <span class="tok-nd">@Transactional</span> 5199 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-nf">getTasks</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">assignee</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5200 <span class="tok-k">return</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-n">assignee</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 5201 <span class="tok-o">}</span> 5202 5203<span class="tok-o">}</span> 5204</td></tr></table></code></pre> 5205</div> 5206</div> 5207<div class="paragraph"> 5208<p>We can now create a REST endpoint by annotating a class with <em>@RestController</em>. Here, we simply delegate to the service defined above.</p> 5209</div> 5210<div class="listingblock"> 5211<div class="content"> 5212<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5213 2 5214 3 5215 4 5216 5 5217 6 5218 7 5219 8 5220 9 522110 522211 522312 522413 522514 522615 522716 522817 522918 523019 523120 523221 523322 523423 523524 523625 523726 523827 523928 524029 524130 524231 524332 524433 524534 524635 524736 524837 524938 525039 525140 525241 525342 525443 525544 525645 525746 525847</div></td><td class="code"><span></span><span class="tok-nd">@RestController</span> 5259<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyRestController</span> <span class="tok-o">{</span> 5260 5261 <span class="tok-nd">@Autowired</span> 5262 <span class="tok-kd">private</span> <span class="tok-n">MyService</span> <span class="tok-n">myService</span><span class="tok-o">;</span> 5263 5264 <span class="tok-nd">@RequestMapping</span><span class="tok-o">(</span><span class="tok-n">value</span><span class="tok-o">=</span><span class="tok-s">"/process"</span><span class="tok-o">,</span> <span class="tok-n">method</span><span class="tok-o">=</span> <span class="tok-n">RequestMethod</span><span class="tok-o">.</span><span class="tok-na">POST</span><span class="tok-o">)</span> 5265 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">startProcessInstance</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5266 <span class="tok-n">myService</span><span class="tok-o">.</span><span class="tok-na">startProcess</span><span class="tok-o">();</span> 5267 <span class="tok-o">}</span> 5268 5269 <span class="tok-nd">@RequestMapping</span><span class="tok-o">(</span><span class="tok-n">value</span><span class="tok-o">=</span><span class="tok-s">"/tasks"</span><span class="tok-o">,</span> <span class="tok-n">method</span><span class="tok-o">=</span> <span class="tok-n">RequestMethod</span><span class="tok-o">.</span><span class="tok-na">GET</span><span class="tok-o">,</span> <span class="tok-n">produces</span><span class="tok-o">=</span><span class="tok-n">MediaType</span><span class="tok-o">.</span><span class="tok-na">APPLICATION_JSON_VALUE</span><span class="tok-o">)</span> 5270 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">TaskRepresentation</span><span class="tok-o">></span> <span class="tok-nf">getTasks</span><span class="tok-o">(</span><span class="tok-nd">@RequestParam</span> <span class="tok-n">String</span> <span class="tok-n">assignee</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5271 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">myService</span><span class="tok-o">.</span><span class="tok-na">getTasks</span><span class="tok-o">(</span><span class="tok-n">assignee</span><span class="tok-o">);</span>
5272 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">TaskRepresentation</span><span class="tok-o">></span> <span class="tok-n">dtos</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ArrayList</span><span class="tok-o"><</span><span class="tok-n">TaskRepresentation</span><span class="tok-o">>();</span> 5273 <span class="tok-k">for</span> <span class="tok-o">(</span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">:</span> <span class="tok-n">tasks</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5274 <span class="tok-n">dtos</span><span class="tok-o">.</span><span class="tok-na">add</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">TaskRepresentation</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">()));</span> 5275 <span class="tok-o">}</span> 5276 <span class="tok-k">return</span> <span class="tok-n">dtos</span><span class="tok-o">;</span> 5277 <span class="tok-o">}</span> 5278 5279 <span class="tok-kd">static</span> <span class="tok-kd">class</span> <span class="tok-nc">TaskRepresentation</span> <span class="tok-o">{</span> 5280 5281 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5282 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">name</span><span class="tok-o">;</span> 5283 5284 <span class="tok-kd">public</span> <span class="tok-nf">TaskRepresentation</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">id</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">name</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5285 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">id</span> <span class="tok-o">=</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5286 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">name</span> <span class="tok-o">=</span> <span class="tok-n">name</span><span class="tok-o">;</span> 5287 <span class="tok-o">}</span> 5288 5289 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getId</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5290 <span class="tok-k">return</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5291 <span class="tok-o">}</span> 5292 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setId</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">id</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5293 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">id</span> <span class="tok-o">=</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5294 <span class="tok-o">}</span> 5295 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getName</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5296 <span class="tok-k">return</span> <span class="tok-n">name</span><span class="tok-o">;</span> 5297 <span class="tok-o">}</span> 5298 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setName</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">name</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5299 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">name</span> <span class="tok-o">=</span> <span class="tok-n">name</span><span class="tok-o">;</span> 5300 <span class="tok-o">}</span> 5301 5302 <span class="tok-o">}</span> 5303 5304<span class="tok-o">}</span> 5305</td></tr></table></code></pre> 5306</div> 5307</div> 5308<div class="paragraph"> 5309<p>Both the <em>@Service</em> and the <em>@RestController</em> will be found by the automatic component scan (<em>@ComponentScan</em>) we added to our application class. Run the application class again. We can now interact with the REST API by using for example cURL:</p> 5310</div> 5311<div class="listingblock"> 5312<div class="content"> 5313<pre>curl http://localhost:8080/tasks?assignee=kermit 5314[] 5315 5316curl -X POST http://localhost:8080/process 5317curl http://localhost:8080/tasks?assignee=kermit
5318[{"id":"10004","name":"my task"}]</pre> 5319</div> 5320</div> 5321</div> 5322<div class="sect3"> 5323<h4 id="_jpa_support">5.7.5. JPA support</h4> 5324<div class="paragraph"> 5325<p>To add in JPA support for Activiti in Spring Boot, add following dependency:</p> 5326</div> 5327<div class="listingblock"> 5328<div class="content"> 5329<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 53302 53313 53324 53335</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 5334 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 5335 <span class="tok-nt"><artifactId></span>activiti-spring-boot-starter-jpa<span class="tok-nt"></artifactId></span> 5336 <span class="tok-nt"><version></span>${activiti.version}<span class="tok-nt"></version></span> 5337<span class="tok-nt"></dependency></span> 5338</td></tr></table></code></pre> 5339</div> 5340</div> 5341<div class="paragraph"> 5342<p>This will add in the Spring configuration and beans for using JPA. By default the JPA provider will be Hibernate.</p> 5343</div> 5344<div class="paragraph"> 5345<p>Let’s create a simple Entity class:</p> 5346</div> 5347<div class="listingblock"> 5348<div class="content"> 5349<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5350 2 5351 3 5352 4 5353 5 5354 6 5355 7 5356 8 5357 9 535810 535911 536012 536113 536214 536315 536416 536517 536618 536719 536820 536921 537022 537123 537224 537325 537426 537527 537628 537729 537830 537931 538032 538133 538234 538335 538436 538537 538638 538739 538840 538941 539042 539143 539244 539345 539446 539547 539648 539749 539850 539951 540052 540153 540254 540355 540456 540557 540658 540759 540860 540961 541062 541163 541264 541365</div></td><td class="code"><span></span><span class="tok-nd">@Entity</span> 5414<span class="tok-kd">class</span> <span class="tok-nc">Person</span> <span class="tok-o">{</span> 5415 5416 <span class="tok-nd">@Id</span> 5417 <span class="tok-nd">@GeneratedValue</span> 5418 <span class="tok-kd">private</span> <span class="tok-n">Long</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5419 5420 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">username</span><span class="tok-o">;</span> 5421 5422 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">firstName</span><span class="tok-o">;</span> 5423 5424 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">lastName</span><span class="tok-o">;</span> 5425 5426 <span class="tok-kd">private</span> <span class="tok-n">Date</span> <span class="tok-n">birthDate</span><span class="tok-o">;</span> 5427 5428 <span class="tok-kd">public</span> <span class="tok-nf">Person</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5429 <span class="tok-o">}</span> 5430 5431 <span class="tok-kd">public</span> <span class="tok-nf">Person</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">username</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">firstName</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">lastName</span><span class="tok-o">,</span> <span class="tok-n">Date</span> <span class="tok-n">birthDate</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5432 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">username</span> <span class="tok-o">=</span> <span class="tok-n">username</span><span class="tok-o">;</span> 5433 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">firstName</span> <span class="tok-o">=</span> <span class="tok-n">firstName</span><span class="tok-o">;</span> 5434 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">lastName</span> <span class="tok-o">=</span> <span class="tok-n">lastName</span><span class="tok-o">;</span> 5435 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">birthDate</span> <span class="tok-o">=</span> <span class="tok-n">birthDate</span><span class="tok-o">;</span> 5436 <span class="tok-o">}</span> 5437 5438 <span class="tok-kd">public</span> <span class="tok-n">Long</span> <span class="tok-nf">getId</span><span class="tok-o">()</span> <span class="tok-o">{</span>
5439 <span class="tok-k">return</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5440 <span class="tok-o">}</span> 5441 5442 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setId</span><span class="tok-o">(</span><span class="tok-n">Long</span> <span class="tok-n">id</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5443 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">id</span> <span class="tok-o">=</span> <span class="tok-n">id</span><span class="tok-o">;</span> 5444 <span class="tok-o">}</span> 5445 5446 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getUsername</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5447 <span class="tok-k">return</span> <span class="tok-n">username</span><span class="tok-o">;</span> 5448 <span class="tok-o">}</span> 5449 5450 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setUsername</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">username</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5451 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">username</span> <span class="tok-o">=</span> <span class="tok-n">username</span><span class="tok-o">;</span> 5452 <span class="tok-o">}</span> 5453 5454 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getFirstName</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5455 <span class="tok-k">return</span> <span class="tok-n">firstName</span><span class="tok-o">;</span> 5456 <span class="tok-o">}</span> 5457 5458 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setFirstName</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">firstName</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5459 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">firstName</span> <span class="tok-o">=</span> <span class="tok-n">firstName</span><span class="tok-o">;</span> 5460 <span class="tok-o">}</span> 5461 5462 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getLastName</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5463 <span class="tok-k">return</span> <span class="tok-n">lastName</span><span class="tok-o">;</span> 5464 <span class="tok-o">}</span> 5465 5466 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setLastName</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">lastName</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5467 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">lastName</span> <span class="tok-o">=</span> <span class="tok-n">lastName</span><span class="tok-o">;</span> 5468 <span class="tok-o">}</span> 5469 5470 <span class="tok-kd">public</span> <span class="tok-n">Date</span> <span class="tok-nf">getBirthDate</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5471 <span class="tok-k">return</span> <span class="tok-n">birthDate</span><span class="tok-o">;</span> 5472 <span class="tok-o">}</span> 5473 5474 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setBirthDate</span><span class="tok-o">(</span><span class="tok-n">Date</span> <span class="tok-n">birthDate</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5475 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">birthDate</span> <span class="tok-o">=</span> <span class="tok-n">birthDate</span><span class="tok-o">;</span> 5476 <span class="tok-o">}</span> 5477<span class="tok-o">}</span> 5478</td></tr></table></code></pre> 5479</div> 5480</div> 5481<div class="paragraph"> 5482<p>By default, when not using an in-memory database, the tables won’t be created automatically. Create a file <em>application.properties</em> on the classpath and add following property:</p> 5483</div> 5484<div class="listingblock"> 5485<div class="content"> 5486<pre>spring.jpa.hibernate.ddl-auto=update</pre> 5487</div> 5488</div> 5489<div class="paragraph"> 5490<p>Add following class:</p> 5491</div> 5492<div class="listingblock"> 5493<div class="content"> 5494<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 54952 54963 54974 54985</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">interface</span> <span class="tok-nc">PersonRepository</span> <span class="tok-kd">extends</span> <span class="tok-n">JpaRepository</span><span class="tok-o"><</span><span class="tok-n">Person</span><span class="tok-o">,</span> <span class="tok-n">Long</span><span class="tok-o">></span> <span class="tok-o">{</span> 5499 5500 <span class="tok-n">Person</span> <span class="tok-nf">findByUsername</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">username</span><span class="tok-o">);</span> 5501 5502<span class="tok-o">}</span> 5503</td></tr></table></code></pre> 5504</div> 5505</div> 5506<div class="paragraph"> 5507<p>This is a Spring repository, which offers CRUD out of the box. We add the method to find a Person by username. Spring will automagically implement this based on conventions (i.e. the property names used).</p> 5508</div> 5509<div class="paragraph"> 5510<p>We now enhance our service further:</p> 5511</div> 5512<div class="ulist"> 5513<ul> 5514<li> 5515<p>by adding <em>@Transactional</em> to the class. Note that by adding the JPA dependency above, the DataSourceTransactionManager which we were using before is now automatically swapped out by a JpaTransactionManager.</p> 5516</li> 5517<li> 5518<p>The <em>startProcess</em> now gets an assignee username in, which is used to look up the Person, and put the Person JPA object as a process variable in the process instance.</p> 5519</li> 5520<li> 5521<p>A method to create Dummy users is added. This is used in the CommandLineRunner to populate the database.</p> 5522</li> 5523</ul> 5524</div> 5525<div class="listingblock"> 5526<div class="content"> 5527<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5528 2 5529 3 5530 4 5531 5 5532 6 5533 7 5534 8 5535 9 553610 553711 553812 553913 554014 554115 554216 554317 554418 554519 554620 554721 554822 554923 555024 555125 555226 555327 555428 555529 555630 555731 555832 555933 556034</div></td><td class="code"><span></span><span class="tok-nd">@Service</span> 5561<span class="tok-nd">@Transactional</span> 5562<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyService</span> <span class="tok-o">{</span> 5563 5564 <span class="tok-nd">@Autowired</span> 5565 <span class="tok-kd">private</span> <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">;</span> 5566 5567 <span class="tok-nd">@Autowired</span> 5568 <span class="tok-kd">private</span> <span class="tok-n">TaskService</span> <span class="tok-n">taskService</span><span class="tok-o">;</span> 5569 5570 <span class="tok-nd">@Autowired</span> 5571 <span class="tok-kd">private</span> <span class="tok-n">PersonRepository</span> <span class="tok-n">
5571personRepository</span><span class="tok-o">;</span> 5572 5573 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">startProcess</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">assignee</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5574 5575 <span class="tok-n">Person</span> <span class="tok-n">person</span> <span class="tok-o">=</span> <span class="tok-n">personRepository</span><span class="tok-o">.</span><span class="tok-na">findByUsername</span><span class="tok-o">(</span><span class="tok-n">assignee</span><span class="tok-o">);</span> 5576 5577 <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();</span> 5578 <span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"person"</span><span class="tok-o">,</span> <span class="tok-n">person</span><span class="tok-o">);</span> 5579 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"oneTaskProcess"</span><span class="tok-o">,</span> <span class="tok-n">variables</span><span class="tok-o">);</span> 5580 <span class="tok-o">}</span> 5581 5582 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-nf">getTasks</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">assignee</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5583 <span class="tok-k">return</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-n">assignee</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 5584 <span class="tok-o">}</span> 5585 5586 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">createDemoUsers</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5587 <span class="tok-k">if</span> <span class="tok-o">(</span><span class="tok-n">personRepository</span><span class="tok-o">.</span><span class="tok-na">findAll</span><span class="tok-o">().</span><span class="tok-na">size</span><span class="tok-o">()</span> <span class="tok-o">==</span> <span class="tok-mi">0</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5588 <span class="tok-n">personRepository</span><span class="tok-o">.</span><span class="tok-na">save</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">Person</span><span class="tok-o">(</span><span class="tok-s">"jbarrez"</span><span class="tok-o">,</span> <span class="tok-s">"Joram"</span><span class="tok-o">,</span> <span class="tok-s">"Barrez"</span><span class="tok-o">,</span> <span class="tok-k">new</span> <span class="tok-n">Date</span><span class="tok-o">()));</span> 5589 <span class="tok-n">personRepository</span><span class="tok-o">.</span><span class="tok-na">save</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">Person</span><span class="tok-o">(</span><span class="tok-s">"trademakers"</span><span class="tok-o">,</span> <span class="tok-s">"Tijs"</span><span class="tok-o">,</span> <span class="tok-s">"Rademakers"</span><span class="tok-o">,</span> <span class="tok-k">new</span> <span class="tok-n">Date</span><span class="tok-o">()));
5589</span> 5590 <span class="tok-o">}</span> 5591 <span class="tok-o">}</span> 5592 5593<span class="tok-o">}</span> 5594</td></tr></table></code></pre> 5595</div> 5596</div> 5597<div class="paragraph"> 5598<p>The CommandLineRunner now looks like:</p> 5599</div> 5600<div class="listingblock"> 5601<div class="content"> 5602<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 5603 2 5604 3 5605 4 5606 5 5607 6 5608 7 5609 8 5610 9 561110</div></td><td class="code"><span></span><span class="tok-nd">@Bean</span> 5612<span class="tok-kd">public</span> <span class="tok-n">CommandLineRunner</span> <span class="tok-nf">init</span><span class="tok-o">(</span><span class="tok-kd">final</span> <span class="tok-n">MyService</span> <span class="tok-n">myService</span><span class="tok-o">)</span> <span class="tok-o">{</span> 5613 5614 <span class="tok-k">return</span> <span class="tok-k">new</span> <span class="tok-n">CommandLineRunner</span><span class="tok-o">()</span> <span class="tok-o">{</span> 5615 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">run</span><span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">...</span> <span class="tok-n">strings</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 5616 <span class="tok-n">myService</span><span class="tok-o">.</span><span class="tok-na">createDemoUsers</span><span class="tok-o">();</span> 5617 <span class="tok-o">}</span> 5618 <span class="tok-o">};</span> 5619 5620<span class="tok-o">}</span> 5621</td></tr></table></code></pre> 5622</div> 5623</div> 5624<div class="paragraph"> 5625<p>The RestController is also slightly changed to incorporate the changes above (only showing new methods) and the HTTP POST now has a body that contains the assignee username:</p> 5626</div> 5627<div class="listingblock"> 5628<div class="content"> 5629<pre>@RestController 5630public class MyRestController { 5631 5632 @Autowired 5633 private MyService myService; 5634 5635 @RequestMapping(value="/process", method= RequestMethod.POST) 5636 public void startProcessInstance(@RequestBody StartProcessRepresentation startProcessRepresentation) { 5637 myService.startProcess(startProcessRepresentation.getAssignee()); 5638 } 5639 5640 ... 5641 5642 static class StartProcessRepresentation { 5643 5644 private String assignee; 5645 5646 public String getAssignee() { 5647 return assignee; 5648 } 5649 5650 public void setAssignee(String assignee) { 5651 this.assignee = assignee; 5652 } 5653 }</pre> 5654</div> 5655</div> 5656<div class="paragraph"> 5657<p>And lastly, to try out the Spring-JPA-Activiti integration, we assign the task using the id of the Person JPA object in the process definition:</p> 5658</div> 5659<div class="listingblock"> 5660<div class="content"> 5661<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"my task"</span> <span class="tok-na">activiti:assignee=</span><span class="tok-s">"${person.id}"</span><span class="tok-nt">/></span> 5662</td></tr></table></code></pre> 5663</div> 5664</div> 5665<div class="paragraph"> 5666<p>We can now start a new process instance, providing the user name in the POST body:</p> 5667</div> 5668<div class="listingblock"> 5669<div class="content"> 5670<pre>curl -H "Content-Type: application/json" -d '{"assignee" : "jbarrez"}' http://localhost:8080/process</pre> 5671</div> 5672</div> 5673<div class="paragraph"> 5674<p>And the task list is now fetched using the person id:</p> 5675</div> 5676<div class="listingblock"> 5677<div class="content"> 5678<pre>curl http://localhost:8080/tasks?assignee=1 5679 5680[{"id":"12505","name":"my task"}]</pre> 5681</div> 5682</div> 5683</div> 5684<div class="sect3"> 5685<h4 id="_further_reading">5.7.6. Further Reading</h4> 5686<div class="paragraph"> 5687<p>Obviously there is a lot about Spring Boot that hasn’t been touched yet, like very easy JTA integration or building a war file that can be run on major application servers. And there is a lot more to the Spring Boot integration:</p> 5688</div> 5689<div class="ulist"> 5690<ul> 5691<li> 5692<p>Actuator support</p> 5693</li> 5694<li> 5695<p>Spring Integration support</p> 5696</li> 5697<li> 5698<p>Rest API integration: boot up the Activiti Rest API embedded within the Spring application</p> 5699</li> 5700<li> 5701<p>Spring Security support</p> 5702</li> 5703</ul> 5704</div> 5705<div class="paragraph"> 5706<p>All these areas are a first version at the moment, but they will evolved in the future further.</p> 5707</div> 5708</div> 5709</div> 5710</div> 5711</div> 5712<div class="sect1"> 5713<h2 id="chDeployment">6. Deployment</h2> 5714<div class="sectionbody"> 5715<div class="sect2"> 5716<h3 id="_business_archives">6.1. Business archives</h3> 5717<div class="paragraph"> 5718<p>To deploy processes, they have to be wrapped in a business archive. A business archive is the unit of deployment to an Activiti Engine. A business archive is equivalent to a zip f
5718ile. It can contain BPMN 2.0 processes, task forms, rules and any other type of file. In general, a business archive contains a collection of named resources.</p> 5719</div> 5720<div class="paragraph"> 5721<p>When a business archive is deployed, it is scanned for BPMN files with a <code>.bpmn20.xml</code> or <code>.bpmn</code> extension. Each of those will be parsed and may contain multiple process definitions.</p> 5722</div> 5723<div class="admonitionblock note"> 5724<table> 5725<tr> 5726<td class="icon"> 5727<i class="fa icon-note" title="Note"></i> 5728</td> 5729<td class="content"> 5730<div class="paragraph"> 5731<p>Java classes present in the business archive <strong>will not be added to the classpath</strong>. All custom classes used in process definitions in the business archive (for example Java service tasks or event listener implementations) should be present on the Activiti Engine classpath in order to run the processes.</p> 5732</div> 5733</td> 5734</tr> 5735</table> 5736</div> 5737<div class="sect3"> 5738<h4 id="_deploying_programmatically">6.1.1. Deploying programmatically</h4> 5739<div class="paragraph"> 5740<p>Deploying a business archive from a zip file can be done like this:</p> 5741</div> 5742<div class="listingblock"> 5743<div class="content"> 5744<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 57452 57463 57474 57485 57496 57507</div></td><td class="code"><span></span><span class="tok-n">String</span> <span class="tok-n">barFileName</span> <span class="tok-o">=</span> <span class="tok-s">"path/to/process-one.bar"</span><span class="tok-o">;</span> 5751<span class="tok-n">ZipInputStream</span> <span class="tok-n">inputStream</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ZipInputStream</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">FileInputStream</span><span class="tok-o">(</span><span class="tok-n">barFileName</span><span class="tok-o">));</span> 5752 5753<span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 5754 <span class="tok-o">.</span><span class="tok-na">name</span><span class="tok-o">(</span><span class="tok-s">"process-one.bar"</span><span class="tok-o">)</span> 5755 <span class="tok-o">.</span><span class="tok-na">addZipInputStream</span><span class="tok-o">(</span><span class="tok-n">inputStream</span><span class="tok-o">)</span> 5756 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 5757</td></tr></table></code></pre> 5758</div> 5759</div> 5760<div class="paragraph"> 5761<p>It’s also possible to build a deployment from individual resources. See the javadocs for more details.</p> 5762</div> 5763</div> 5764</div> 5765<div class="sect2"> 5766<h3 id="_external_resources">6.2. External resources</h3> 5767<div class="paragraph"> 5768<p>Process definitions live in the Activiti database. These process definitions can reference delegation classes when using Service Tasks or execution listeners or Spring beans from the Activiti configuration file. These
5768classes and the Spring configuration file have to be available to all process engines that may execute the process definitions.</p> 5769</div> 5770<div class="sect3"> 5771<h4 id="_java_classes">6.2.1. Java classes</h4> 5772<div class="paragraph"> 5773<p>All custom classes that are used in your process (e.g. JavaDelegates used in Service Tasks or event-listeners, TaskListeners, …​) should be present on the engine’s classpath when an instance of the process is started.</p> 5774</div> 5775<div class="paragraph"> 5776<p>During deployment of a business archive however, those classes don’t have to be present on the classpath. This means that your delegation classes don’t have to be on the classpath when deploying a new business archive with Ant.</p> 5777</div> 5778<div class="paragraph"> 5779<p>When you are using the demo setup and you want to add your custom classes, you should add a jar containing your classes to the activiti-explorer or activiti-rest webapp lib. Don’t forget to include the dependencies of your custom classes (if any) as well. Alternatively, you can include your dependencies in the libraries directory of your Tomcat installation, <code>${tomcat.home}/lib</code>.</p> 5780</div> 5781</div> 5782<div class="sect3"> 5783<h4 id="_using_spring_beans_from_a_process">6.2.2. Using Spring beans from a process</h4> 5784<div class="paragraph"> 5785<p>When expressions or scripts use Spring beans, those beans have to be available to the engine when executing the process definition. If you are building your own webapp and you configure your process engine in your context as described in <a href="#springintegration">the spring integration section</a>, that is straightforward. But bear in mind that you also should update the Activiti rest webapp with that context if you use it. You can do that by replacing the <code>activiti.cfg.xml</code> in the <code>activiti-rest/lib/activiti-cfg.jar</code> JAR file with an <code>activiti-context.xml</code> file containing your Spring context configuration.</p> 5786</div> 5787</div> 5788<div class="sect3"> 5789<h4 id="_creating_a_single_app">6.2.3. Creating a single app</h4> 5790<div class="paragraph"> 5791<p>Instead of making sure that all process engines have all the delegation classes on their classpath and use the right Spring configuration, you may consider including the Activiti rest webapp inside your own webapp so that there is only a single <code>ProcessEngine</code>.</p> 5792</div> 5793</div> 5794</div> 5795<div class="sect2"> 5796<h3 id="versioningOfProcessDefinitions">6.3. Versioning of process definitions</h3> 5797<div class="paragraph"> 5798<p>BPMN doesn’t have a notion of versioning. That is actually good because the executable BPMN process file will probably live in a version control system repository (e.g. Subversion, Git or Mercurial) as part of your development project. Versions of process definitions are created during deployment. During deployment, Activiti will assign a version to the <code>ProcessDefinition</code> before it is stored in the Activiti DB.</p> 5799</div> 5800<div class="paragraph"> 5801<p>For each process definition in a business archive the following steps are performed to initialize the properties <code>key</code>, <code>version</code>, <code>name</code> and <code>id</code>:</p> 5802</div> 5803<div class="ulist"> 5804<ul> 5805<li> 5806<p>The process definition <code>id</code> attribute in the XML file is used as the process definition <code>key</code> property.</p> 5807</li> 5808<li> 5809<p>The process definition <code>name</code> attribute in the XML file is used as the process definition <code>name</code> property. If the name attribute is not specified, then id attribute is used as the name.</p> 5810</li> 5811<li> 5812<p>The first time a process with a particular key is deployed, version 1 is assigned. For all subsequent deployments of process definitions with the same key, the version will be set 1 higher than the maximum currently deployed version. The key property is used to distinguish process definitions.</p> 5813</li> 5814<li> 5815<p>The id property is set to {processDefinitionKey}:{processDefinitionVersion}:{generated-id}, where <code>generated-id</code> is a unique number added to guarantee uniqueness of the process id for the process definition caches in a clustered environment.</p> 5816</li> 5817</ul> 5818</div> 5819<div class="paragraph"> 5820<p>Take for example the following process</p> 5821</div> 5822<div class="listingblock"> 5823<div class="content"> 5824<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 58252 58263</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"myDefinitions"</span> <span class="tok-nt">></span> 5827 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"myProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"My important process"</span> <span class="tok-nt">></span> 5828 ... 5829</td></tr></table></code></pre> 5830</div> 5831</div> 5832<div class="paragraph"> 5833<p>When deploying this process definition, the process definition in the database will look like this:</p> 5834</div> 5835<table class="tableblock frame-all grid-all spread"> 5836<colgroup> 5837<col style="width: 25%;"> 5838<col style="width: 25%;"> 5839<col style="width: 25%;"> 5840<col style="width: 25%;"> 5841</colgroup> 5842<thead> 5843<tr> 5844<th class="tableblock halign-left valign-top">id</th> 5845<th class="tableblock halign-left valign-top">key</th> 5846<th class="tableblock halign-left valign-top">
5846name</th> 5847<th class="tableblock halign-left valign-top">version</th> 5848</tr> 5849</thead> 5850<tbody> 5851<tr> 5852<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess:1:676</p></td> 5853<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess</p></td> 5854<td class="tableblock halign-left valign-top"><p class="tableblock">My important process</p></td> 5855<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 5856</tr> 5857</tbody> 5858</table> 5859<div class="paragraph"> 5860<p>Suppose we now deploy an updated version of the same process (e.g. changing some user tasks), but the <code>id</code> of the process definition remains the same. The process definition table will now contain the following entries:</p> 5861</div> 5862<table class="tableblock frame-all grid-all spread"> 5863<colgroup> 5864<col style="width: 25%;"> 5865<col style="width: 25%;"> 5866<col style="width: 25%;"> 5867<col style="width: 25%;"> 5868</colgroup> 5869<thead> 5870<tr> 5871<th class="tableblock halign-left valign-top">id</th> 5872<th class="tableblock halign-left valign-top">key</th> 5873<th class="tableblock halign-left valign-top">name</th> 5874<th class="tableblock halign-left valign-top">version</th> 5875</tr> 5876</thead> 5877<tbody> 5878<tr> 5879<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess:1:676</p></td> 5880<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess</p></td> 5881<td class="tableblock halign-left valign-top"><p class="tableblock">My important process</p></td> 5882<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 5883</tr> 5884<tr> 5885<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess:2:870</p></td> 5886<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess</p></td> 5887<td class="tableblock halign-left valign-top"><p class="tableblock">My important process</p></td> 5888<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 5889</tr> 5890</tbody> 5891</table> 5892<div class="paragraph"> 5893<p>When the <code>runtimeService.startProcessInstanceByKey("myProcess")</code> is called, it will now use the process definition with version <code>2</code>, as this is the latest version of the process definition.</p> 5894</div> 5895<div class="paragraph"> 5896<p>Should we create a second process, as defined below and deploy this to Activiti, a third row will be added to the table.</p> 5897</div> 5898<div class="listingblock"> 5899<div class="content"> 5900<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 59012 59023</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"myNewDefinitions"</span> <span class="tok-nt">></span> 5903 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"myNewProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"My important process"</span> <span class="tok-nt">></span> 5904 ... 5905</td></tr></table></code></pre> 5906</div> 5907</div> 5908<div class="paragraph"> 5909<p>The table will look like this:</p> 5910</div> 5911<table class="tableblock frame-all grid-all spread"> 5912<colgroup> 5913<col style="width: 25%;"> 5914<col style="width: 25%;"> 5915<col style="width: 25%;"> 5916<col style="width: 25%;"> 5917</colgroup> 5918<thead> 5919<tr> 5920<th class="tableblock halign-left valign-top">id</th> 5921<th class="tableblock halign-left valign-top">key</th> 5922<th class="tableblock halign-left valign-top">name</th> 5923<th class="tableblock halign-left valign-top">version</th> 5924</tr> 5925</thead> 5926<tbody> 5927<tr> 5928<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess:1:676</p></td> 5929<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess</p></td> 5930<td class="tableblock halign-left valign-top"><p class="tableblock">My important process</p></td> 5931<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 5932</tr> 5933<tr> 5934<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess:2:870</p></td> 5935<td class="tableblock halign-left valign-top"><p class="tableblock">myProcess</p></td> 5936<td class="tableblock halign-left valign-top"><p class="tableblock">My important process</p></td> 5937<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 5938</tr> 5939<tr> 5940<td class="tableblock halign-left valign-top"><p class="tableblock">myNewProcess:1:1033</p></td> 5941<td class="tableblock halign-left valign-top"><p class="tableblock">myNewProcess</p></td> 5942<td class="tableblock halign-left valign-top"><p class="tableblock">My important process</p></td> 5943<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 5944</tr> 5945</tbody> 5946</table> 5947<div class="paragraph"> 5948<p>Note how the key for the new process is different from our first process. Even though the name is the same (we should probably have changed that too), Activiti only considers the <code>id</code> attribute when distinguishing processes. The new process is therefore deployed with version 1.</p> 5949</div> 5950</div> 5951<div class="sect2"> 5952<h3 id="providingProcessDiagram">6.4. Providing a process diagram</h3> 5953<div class="paragraph"> 5954<p>A process diagram image can be added to a deployment. This image will be stored in the Activiti repository and is accessible through the API. This image is also used to visualize the process in Activiti Explorer.</p> 5955</div> 5956<div class="paragraph"> 5957<p>Suppose we have a process on our classpath, <code>org/activiti/expenseProcess.bpmn20.xml</code> that has a process key <em>expense</em>. The following naming conventions for the process diagram image apply (in this specific order):</p> 5958</div> 5959<div class="ulist"> 5960<ul> 5961<li> 5962<p>If an image resource exists in the deployment that has a name of the BPMN 2.0 XML file name concatenated with the process key and an image suffix, this image is used. In our example, this would be <code>org/activiti/expenseProcess.expense.png</code> (or .jpg/gif). In case you have multiple images defined in one BPMN 2.0 XML file, this approach makes most sense. Each diagram image will then have the process key in its file name.</p> 5963</li> 5964<li> 5965<p>If no such image exists, am image resource in the deployment matching the name of the BPMN 2.0 XML file is searched for. In our example this would be <code>org/activiti/expenseProcess.png</code>. Note that this means that <strong>every process definition</strong> defined in the same BPMN 2.0 file has the same process diagram image. In case there is only one process definition in each BPMN 2.0 XML file, this is obviously not a problem.</p> 5966</li> 5967</ul> 5968</div> 5969<div class="paragraph"> 5970<p>Example when deploying programmatically:</p> 5971</div> 5972<div class="listingblock"> 5973<div class="content"> 5974<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 59752 59763 59774 59785</div></td><td class="code"><span></span><span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 5979 <span class="tok-o">.</span><span class="tok-na">name</span><span class="tok-o">(</span><span class="tok-s">"expense-process.bar"</span><span class="tok-o">)</span> 5980 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"org/activiti/expenseProcess.bpmn20.xml"</span><span class="tok-o">)</span> 5981 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"org/activiti/expenseProcess.png"</span><span class="tok-o">)</span> 5982 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 5983</td></tr></table></code></pre> 5984</div> 5985</div> 5986<div class="paragraph"> 5987<p>The image resource can be retrieved through the API afterwards:</p> 5988</div> 5989<div class="listingblock"> 5990<div class="content"> 5991<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 59922 59933 59944 59955 59966 59977</div></td><td class="code"><span></span><span class="tok-n">ProcessDefinition</span> <span class="tok-n">
5997processDefinition</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createProcessDefinitionQuery</span><span class="tok-o">()</span> 5998 <span class="tok-o">.</span><span class="tok-na">processDefinitionKey</span><span class="tok-o">(</span><span class="tok-s">"expense"</span><span class="tok-o">)</span> 5999 <span class="tok-o">.</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 6000 6001<span class="tok-n">String</span> <span class="tok-n">diagramResourceName</span> <span class="tok-o">=</span> <span class="tok-n">processDefinition</span><span class="tok-o">.</span><span class="tok-na">getDiagramResourceName</span><span class="tok-o">();</span> 6002<span class="tok-n">InputStream</span> <span class="tok-n">imageStream</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">getResourceAsStream</span><span class="tok-o">(</span> 6003 <span class="tok-n">processDefinition</span><span class="tok-o">.</span><span class="tok-na">getDeploymentId</span><span class="tok-o">(),</span> <span class="tok-n">diagramResourceName</span><span class="tok-o">);</span> 6004</td></tr></table></code></pre> 6005</div> 6006</div> 6007</div> 6008<div class="sect2"> 6009<h3 id="generatingProcessDiagram">6.5. Generating a process diagram</h3> 6010<div class="paragraph"> 6011<p>In case no image is provided in the deployment, as described in the <a href="#providingProcessDiagram">previous section</a>, the Activiti engine will generate a diagram image if the process definition contains the necessary <em>diagram interchange</em> information.</p> 6012</div> 6013<div class="paragraph"> 6014<p>The resource can be retrieved in exactly the same way as when <a href="#providingProcessDiagram">an image is provided</a> in the deployment.</p> 6015</div> 6016<div class="imageblock" style="text-align: center"> 6017<div class="content"> 6018<img src="images/deployment.image.generation.png" alt="deployment.image.generation"> 6019</div> 6020</div> 6021<div class="paragraph"> 6022<p>If, for some reason, it is not necessary or wanted to generate a diagram during deployment the <code>isCreateDiagramOnDeploy</code> property can be set on the process engine configuration:</p> 6023</div> 6024<div class="listingblock"> 6025<div class="content"> 6026<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"createDiagramOnDeploy"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 6027</td></tr></table></code></pre> 6028</div> 6029</div> 6030<div class="paragraph"> 6031<p>No diagram will be generated now.</p> 6032</div> 6033</div> 6034<div class="sect2"> 6035<h3 id="deploymentCategory">6.6. Category</h3> 6036<div class="paragraph"> 6037<p>Both deployments and process definitions have user defined categories. The process definition category is initialized value in attribute in the BPMN file: <code><definitions …​ targetNamespace="yourCategory" …​</code></p> 6038</div> 6039<div class="paragraph"> 6040<p>The deployment category can be specified in the API like this:</p> 6041</div> 6042<div class="listingblock"> 6043<div class="content"> 6044<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 60452 60463 60474 60485</div></td><td class="code"><span></span><span class="tok-n">repositoryService</span> 6049 <span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 6050 <span class="tok-o">.</span><span class="tok-na">category</span><span class="tok-o">(</span><span class="tok-s">"yourCategory"</span><span class="tok-o">)</span> 6051 <span class="tok-o">...</span> 6052 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 6053</td></tr></table></code></pre> 6054</div> 6055</div> 6056</div> 6057</div> 6058</div> 6059<div class="sect1"> 6060<h2 id="bpmn20">7. BPMN 2.0 Introduction</h2> 6061<div class="sectionbody"> 6062<div class="sect2"> 6063<h3 id="whatIsBpmn">7.1. What is BPMN?</h3> 6064<div class="paragraph"> 6065<p>See our <a href="http://activiti.org/faq.html#WhatIsBpmn20">FAQ entry on BPMN 2.0</a>.</p> 6066</div> 6067</div> 6068<div class="sect2"> 6069<h3 id="bpmnDefiningProcess">7.2. Defining a process</h3> 6070<div class="admonitionblock note"> 6071<table> 6072<tr> 6073<td class="icon"> 6074<i class="fa icon-note" title="Note"></i> 6075</td> 6076<td class="content"> 6077<div class="paragraph"> 6078<p>This introduction is written under the assumption you are using the <a href="http://eclipse.org/">Eclipse IDE</a> to create and edit files. Very little of this is specific to Eclipse, however. You can use any other tool you prefer to create XML files containing BPMN 2.0.</p> 6079</div> 6080</td> 6081</tr> 6082</table> 6083</div> 6084<div class="paragraph"> 6085<p>Create a new XML file (<em>right-click on any project and select New→Other→XML-XML File</em>) and give it a name. Make sure that the file <strong>ends with .bpmn20.xml or .bpmn</strong>, since otherwise the engine won’t pick up this file for deployment.</p> 6086</div> 6087<div class="imageblock" style="text-align: center"> 6088<div class="content"> 6089<img src="images/new.bpmn.procdef.png" alt="new.bpmn.procdef"> 6090</div> 6091</div> 6092<div class="paragraph"> 6093<p>The root element of the BPMN 2.0 schema is the <code>definitions</code> element. Within this element, multiple process definitions can be defined (although we advise to have only one process definition in each file, since this simplifies maintenance later in the development process). An empty process definition looks as listed below. Note that the minimal <code>definitions</code> element only needs the <code>xmlns</code> and <code>targetNamespace</code> declaration. The <code>targetNamespace</code> can be anything, and is useful for categorizing process definitions.</p> 6094</div> 6095<div class="listingblock"> 6096<div class="content"> 6097<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 6098 2 6099 3 6100 4 6101 5 6102 6 6103 7 6104 8 6105 9 610610</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> 6107 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 6108 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 6109 <span class="tok-na">targetNamespace=</span><span class="tok-s">"Examples"</span><span class="tok-nt">></span> 6110 6111 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"myProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"My First Process"</span><span class="tok-nt">></span> 6112 .. 6113 <span class="tok-nt"></process></span> 6114 6115<span class="tok-nt"></definitions></span> 6116</td></tr></table></code></pre> 6117</div> 6118</div> 6119<div class="paragraph"> 6120<p>Optionally you can also add the online schema location of the BPMN 2.0 XML schema, as an alternative to the XML catalog configuration in Eclipse.</p> 6121</div> 6122<div class="listingblock"> 6123<div class="content"> 6124<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 61252 61263</div></td><td class="code"><span></span>xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 6127xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL 6128 http://www.omg.org/spec/BPMN/2.0/20100501/BPMN20.xsd 6129</td></tr></table></code></pre> 6130</div> 6131</div> 6132<div class="paragraph"> 6133<p>The <code>process</code> element has two attributes:</p> 6134</div> 6135<div class="ulist"> 6136<ul> 6137<li> 6138<p><strong>id</strong>: this attribute is <strong>required</strong> and maps to the <strong>key</strong> property of an Activiti <code>ProcessDefinition</code> object. This <code>id</code> can then be used to start a new process instance of the process definition, through the <code>startProcessInstanceByKey</code> method on the <code>RuntimeService</code>. This method will always take the <strong>latest deployed version</strong> of the process definition.</p> 6139</li> 6140</ul> 6141</div> 6142<div class="listingblock"> 6143<div class="content"> 6144<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-n">
6144processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"myProcess"</span><span class="tok-o">);</span> 6145</td></tr></table></code></pre> 6146</div> 6147</div> 6148<div class="ulist"> 6149<ul> 6150<li> 6151<p>Important to note here is that this is not the same as calling the <code>startProcessInstanceById</code> method. This method expects the String id that was generated at deploy time by the Activiti engine, and can be retrieved by calling the <code>processDefinition.getId()</code> method. The format of the generated id is <strong><em>key:version</em></strong>, and the length is <strong>constrained to 64 characters</strong>. If you get an <code>ActivitiException</code> stating that the generated id is too long, limit the text in the <em>key</em> field of the process.</p> 6152</li> 6153<li> 6154<p><strong>name</strong>: this attribute is <strong>optional</strong> and maps to the <em>name</em> property of a <code>ProcessDefinition</code>. The engine itself doesn’t use this property, so it can be used for displaying a more human-friendly name in a user interface, for example.</p> 6155</li> 6156</ul> 6157</div> 6158<div class="paragraph"> 6159<p>[[10minutetutorial]]</p> 6160</div> 6161</div> 6162<div class="sect2"> 6163<h3 id="_getting_started_10_minute_tutorial">7.3. Getting started: 10 minute tutorial</h3> 6164<div class="paragraph"> 6165<p>In this section we will cover a (very simple) business process that we will use to introduce some basic Activiti concepts and the Activiti API.</p> 6166</div> 6167<div class="sect3"> 6168<h4 id="bpmn10MinuteTutorialPrerequisites">7.3.1. Prerequisites</h4> 6169<div class="paragraph"> 6170<p>This tutorial assumes that you have the <a href="#demo.setup.one.minute.version">Activiti demo setup running</a>, and that you are using a standalone H2 server. Edit <code>db.properties</code> and set the <code>jdbc.url=jdbc:h2:tcp://localhost/activiti</code>, and then run the standalone server according to <a href="http://www.h2database.com/html/tutorial.html#using_server">H2’s documentation</a>.</p> 6171</div> 6172</div> 6173<div class="sect3"> 6174<h4 id="bpmn10MinuteTutorialGoal">7.3.2. Goal</h4> 6175<div class="paragraph"> 6176<p>The goal of this tutorial is to learn about Activiti and some basic BPMN 2.0 concepts. The end result will be a simple Java SE program that deploys a process definition, and interacts with this process through the Activiti engine API. We’ll also touch some of the tooling around Activiti. Of course, what you’ll learn in this tutorial can also be used when building your own web applications around your business processes.</p> 6177</div> 6178</div> 6179<div class="sect3"> 6180<h4 id="bpmnFirstExampleUseCase">7.3.3. Use case</h4> 6181<div class="paragraph"> 6182<p>The use case is straightforward: we have a company, let’s call it BPMCorp. In BPMCorp, a financial report needs to be written every month for the company shareholders. This is the responsibility of the accountancy department. When the report is finished, one of the members of the upper management needs to approve the document before it is sent to all the shareholders.</p> 6183</div> 6184</div> 6185<div class="sect3"> 6186<h4 id="bpmnFirstExampleDiagram">7.3.4. Process diagram</h4> 6187<div class="paragraph"> 6188<p>The business process as described above can be graphically visualized using the <a href="#activitiDesigner">Activiti Designer</a>. However, for this tutorial we’ll type the XML ourselves, as we learn the most this way at this point. The graphical BPMN 2.0 notation of our process looks like this:</p> 6189</div> 6190<div class="imageblock" style="text-align: center"> 6191<div class="content"> 6192<img src="images/financial.report.example.diagram.png" alt="financial.report.example.diagram"> 6193</div> 6194</div> 6195<div class="paragraph"> 6196<p>What we see is a <a href="#bpmnNoneStartEvent">none Start Event</a> (circle on the left), followed by two <a href="#bpmnUserTask">User Tasks</a>: <em>'Write monthly financial report'</em> and <em>'Verify monthly financial report'</em>, ending in a <a href="#bpmnNoneEndEvent">none end event</a> (circle with thick border on the right).</p> 6197</div> 6198</div> 6199<div class="sect3"> 6200<h4 id="bpmnFirstExampleXml">7.3.5. XML representation</h4> 6201<div class="paragraph"> 6202<p>The XML version of this business process (<em>FinancialReportProcess.bpmn20.xml</em>) looks as shown below. It’s easy to recognize the main elements of our process (click on the links for going to the detailed section of that BPMN 2.0 construct):</p> 6203</div> 6204<div class="ulist"> 6205<ul> 6206<li> 6207<p>The <a href="#bpmnNoneStartEvent">(none) start event</a> tells us what the <em>entry point</em> to the process is.</p> 6208</li> 6209<li> 6210<p>The <a href="#bpmnUserTask">User Tasks</a> declarations are the representation of the human tasks of our process. Note that the first task is assigned to the <em>accountancy</em> group, while the second task is assigned to the <em>management</em> group. See <a href="#bpmnUserTaskAssignment">the section on user task assignment</a> for more information on how users and groups can be assigned to user tasks.</p> 6211</li> 6212<li> 6213<p>The process ends when the <a href="#bpmnNoneEndEvent">none end event</a> is reached.</p> 6214</li> 6215<li> 6216<p>The elements are connected with each other through <a href="#bpmnSequenceFlow">sequence flows</a>. These sequence flows have a <code>source</code> and <code>target</code>, defining the <em>direction</em>
6216 of the sequence flow.</p> 6217</li> 6218</ul> 6219</div> 6220<div class="listingblock"> 6221<div class="content"> 6222<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 6223 2 6224 3 6225 4 6226 5 6227 6 6228 7 6229 8 6230 9 623110 623211 623312 623413 623514 623615 623716 623817 623918 624019 624120 624221 624322 624423 624524 624625 624726 624827 624928 625029 625130 625231 625332 625433 625534 625635 625736 625837 625938 626039 626140 626241 626342 626443</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"definitions"</span> 6265 <span class="tok-na">targetNamespace=</span><span class="tok-s">"http://activiti.org/bpmn20"</span> 6266 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 6267 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span><span class="tok-nt">></span> 6268 6269 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"financialReport"</span> <span class="tok-na">name=</span><span class="tok-s">"Monthly financial report reminder process"</span><span class="tok-nt">></span> 6270 6271 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 6272 6273 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"writeReportTask"</span> <span class="tok-nt">/></span> 6274 6275 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"writeReportTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Write monthly financial report"</span> <span class="tok-nt">></span> 6276 <span class="tok-nt"><documentation></span> 6277 Write monthly financial report for publication to shareholders. 6278 <span class="tok-nt"></documentation></span> 6279 <span class="tok-nt"><potentialOwner></span> 6280 <span class="tok-nt"><resourceAssignmentExpression></span> 6281 <span class="tok-nt"><formalExpression></span>accountancy<span class="tok-nt"></formalExpression></span> 6282 <span class="tok-nt"></resourceAssignmentExpression></span> 6283 <span class="tok-nt"></potentialOwner></span> 6284 <span class="tok-nt"></userTask></span> 6285 6286 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"writeReportTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"verifyReportTask"</span> <span class="tok-nt">/></span> 6287 6288 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"verifyReportTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Verify monthly financial report"</span> <span class="tok-nt">></span> 6289 <span class="tok-nt"><documentation></span> 6290 Verify monthly financial report composed by the accountancy department. 6291 This financial report is going to be sent to all the company shareholders. 6292 <span class="tok-nt"></documentation></span> 6293 <span class="tok-nt"><potentialOwner></span> 6294 <span class="tok-nt"><resourceAssignmentExpression></span> 6295 <span class="tok-nt"><formalExpression></span>management<span class="tok-nt"></formalExpression></span> 6296 <span class="tok-nt"></resourceAssignmentExpression></span> 6297 <span class="tok-nt"></potentialOwner></span> 6298 <span class="tok-nt"></userTask></span> 6299 6300 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"verifyReportTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 6301 6302 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 6303 6304 <span class="tok-nt"></process></span> 6305 6306<span class="tok-nt"></definitions></span> 6307</td></tr></table></code></pre> 6308</div> 6309</div> 6310</div> 6311<div class="sect3"> 6312<h4 id="bpmnFirstExamplStartProcess">7.3.6. Starting a process instance</h4> 6313<div class="paragraph"> 6314<p>We have now created the <strong>process definition</strong> of our business process. From such a process definition, we can create <strong>process instances</strong>. In this case, one process instance would match with the creation and verification of a single financial report for a particular month. All the process instances share the same process definition.</p> 6315</div> 6316<div class="paragraph"> 6317<p>To be able to create process instances from a given process definition, we must first <strong>deploy</strong> this process definition. Deploying a process definition means two things:</p> 6318</div> 6319<div class="ulist"> 6320<ul> 6321<li> 6322<p>The process definition will be stored in the persistent datastore that is configured for your Activiti engine. So by deploying our business process, we make sure that the engine will find the process definition after an engine reboot.</p> 6323</li> 6324<li> 6325<p>The BPMN 2.0 process file will be parsed to an in-memory object model that can be manipulated through the Activiti API.</p> 6326</li> 6327</ul> 6328</div> 6329<div class="paragraph"> 6330<p>More information on deployment can be found <a href="#chDeployment">in the dedicated section on deployment</a>.</p> 6331</div> 6332<div class="paragraph"> 6333<p>
6333As described in that section, deployment can happen in several ways. One way is through the API as follows. Note that all interaction with the Activiti engine happens through its <em>services</em>.</p> 6334</div> 6335<div class="listingblock"> 6336<div class="content"> 6337<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 63382 63393</div></td><td class="code"><span></span><span class="tok-n">Deployment</span> <span class="tok-n">deployment</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 6340 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"FinancialReportProcess.bpmn20.xml"</span><span class="tok-o">)</span> 6341 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 6342</td></tr></table></code></pre> 6343</div> 6344</div> 6345<div class="paragraph"> 6346<p>Now we can start a new process instance using the <code>id</code> we defined in the process definition (see process element in the XML file). Note that this <code>id</code> in Activiti terminology is called the <strong>key</strong>.</p> 6347</div> 6348<div class="listingblock"> 6349<div class="content"> 6350<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-n">processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"financialReport"</span><span class="tok-o">);</span> 6351</td></tr></table></code></pre> 6352</div> 6353</div> 6354<div class="paragraph"> 6355<p>This will create a process instance that will first go through the start event. After the start event, it follows all the outgoing sequence flows (only one in this case) and the first task (<em>write monthly financial report</em>) is reached. The Activiti engine will now store a task in the persistent database. At this point, the user or group assignments attached to the task are resolved and also stored in the database. It’s important to note that the Activiti engine will continue process execution steps until it reaches a <em>wait state</em>, such as the user task. At such a wait state, the current state of the process instance is stored in the database. It remains in that state until a user decides to complete their task. At that point, the engine will continue until it reaches a new wait state or the end of the process. When the engine reboots or crashes in the meantime, the state of the process is safe and well in the database.</p> 6356</div> 6357<div class="paragraph"> 6358<p>After the task is created, the <code>startProcessInstanceByKey</code> method will return since the user task activity is a <em>wait state</em>. In this case, the task is assigned to a group, which means that every member of the group is a <strong>candidate</strong> to perform the task.</p> 6359</div> 6360<div class="paragraph"> 6361<p>We can now throw this all together and create a simple Java program. Create a new Eclipse project and add the Activiti JARs and dependencies to its classpath (these can be found in the <em>libs</em> folder of the Activiti distribution). Before we can call the Activiti services, we must first construct a <code>ProcessEngine</code> that gives us access to the services. Here we use the <em>'standalone'</em> configuration, which constructs a <code>ProcessEngine</code> that uses the database also used in the demo setup.</p> 6362</div> 6363<div class="paragraph"> 6364<p>You can download the process definition XML <a href="images/FinancialReportProcess.bpmn20.xml">here</a>. This file contains the XML as shown above, but also contains the necessary BPMN <a href="#generatingProcessDiagram">diagram interchange information</a> to visualize the process in the Activiti tools.</p> 6365</div> 6366<div class="listingblock"> 6367<div class="content"> 6368<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 6369 2 6370 3 6371 4 6372 5 6373 6 6374 7 6375 8 6376 9 637710 637811 637912 638013 638114 638215 638316 638417 638518 638619</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kt">void</span> <span class="tok-nf">main</span><span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">[]</span> <span class="tok-n">args</span><span class="tok-o">)</span> <span class="tok-o">{</span> 6387 6388 <span class="tok-c1">// Create Activiti process engine</span> 6389 <span class="tok-n">ProcessEngine</span> <span class="tok-n">
6389processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngineConfiguration</span> 6390 <span class="tok-o">.</span><span class="tok-na">createStandaloneProcessEngineConfiguration</span><span class="tok-o">()</span> 6391 <span class="tok-o">.</span><span class="tok-na">buildProcessEngine</span><span class="tok-o">();</span> 6392 6393 <span class="tok-c1">// Get Activiti services</span> 6394 <span class="tok-n">RepositoryService</span> <span class="tok-n">repositoryService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRepositoryService</span><span class="tok-o">();</span> 6395 <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRuntimeService</span><span class="tok-o">();</span> 6396 6397 <span class="tok-c1">// Deploy the process definition</span> 6398 <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 6399 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"FinancialReportProcess.bpmn20.xml"</span><span class="tok-o">)</span> 6400 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 6401 6402 <span class="tok-c1">// Start a process instance</span> 6403 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"financialReport"</span><span class="tok-o">);</span> 6404<span class="tok-o">}</span> 6405</td></tr></table></code></pre> 6406</div> 6407</div> 6408</div> 6409<div class="sect3"> 6410<h4 id="bpmnFirstExampleCandidateList">7.3.7. Task lists</h4> 6411<div class="paragraph"> 6412<p>We can now retrieve this task through the <code>TaskService</code> by adding the following logic:</p> 6413</div> 6414<div class="listingblock"> 6415<div class="content"> 6416<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskCandidateUser</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 6417</td></tr></table></code></pre> 6418</div> 6419</div> 6420<div class="paragraph"> 6421<p>Note that the user we pass to this operation needs to be a member of the <em>accountancy</em> group, since that was declared in the process definition:</p> 6422</div> 6423<div class="listingblock"> 6424<div class="content"> 6425<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 64262 64273 64284 64295</div></td><td class="code"><span></span><span class="tok-nt"><potentialOwner></span> 6430 <span class="tok-nt"><resourceAssignmentExpression></span> 6431 <span class="tok-nt"><formalExpression></span>accountancy<span class="tok-nt"></formalExpression></span> 6432 <span class="tok-nt"></resourceAssignmentExpression></span> 6433<span class="tok-nt"></potentialOwner></span> 6434</td></tr></table></code></pre> 6435</div> 6436</div> 6437<div class="paragraph"> 6438<p>We could also use the task query API to get the same results using the name of the group. We can now add the following logic to our code:</p> 6439</div> 6440<div class="listingblock"> 6441<div class="content"> 6442<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 64432</div></td><td class="code"><span></span><span class="tok-n">TaskService</span> <span class="tok-n">taskService</span> <span class="tok-o">=</span> <span class="tok-n">
6443processEngine</span><span class="tok-o">.</span><span class="tok-na">getTaskService</span><span class="tok-o">();</span> 6444<span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskCandidateGroup</span><span class="tok-o">(</span><span class="tok-s">"accountancy"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 6445</td></tr></table></code></pre> 6446</div> 6447</div> 6448<div class="paragraph"> 6449<p>Since we’ve configured our <code>ProcessEngine</code> to use the same database as the demo setup is using, we can now log into <a href="http://localhost:8080/activiti-explorer/">Activiti Explorer</a>. By default, no user is in the <em>accountancy</em> group. Login with kermit/kermit, click Groups and then "Create group". Then click Users and add the group to fozzie. Now login with fozzie/fozzie, and we will find that we can start our business process after selecting the <em>Processes</em> page and clicking on the <em>'Start Process'</em> link in the <em>'Actions'</em> column corresponding to the <em>'Monthly financial report'</em> process.</p> 6450</div> 6451<div class="imageblock" style="text-align: center"> 6452<div class="content"> 6453<img src="images/bpmn.financial.report.example.start.process.png" alt="bpmn.financial.report.example.start.process"> 6454</div> 6455</div> 6456<div class="paragraph"> 6457<p>As explained, the process will execute up to the first user task. Since we’re logged in as kermit, we can see that there is a new candidate task available for him after we’ve started a process instance. Select the <em>Tasks</em> page to view this new task. Note that even if the process was started by someone else, the task would still be visible as a candidate task to everyone in the accountancy group.</p> 6458</div> 6459<div class="imageblock" style="text-align: center"> 6460<div class="content"> 6461<img src="images/bpmn.financial.report.example.task.assigned.png" alt="bpmn.financial.report.example.task.assigned"> 6462</div> 6463</div> 6464</div> 6465<div class="sect3"> 6466<h4 id="bpmnFirstExampleClaimTask">7.3.8. Claiming the task</h4> 6467<div class="paragraph"> 6468<p>An accountant now needs to <strong>claim the task</strong>. By claiming the task, the specific user will become the <strong>assignee</strong> of the task and the task will disappear from every task list of the other members of the accountancy group. Claiming a task is programmatically done as follows:</p> 6469</div> 6470<div class="listingblock"> 6471<div class="content"> 6472<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">claim</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-s">"fozzie"</span><span class="tok-o">);</span> 6473</td></tr></table></code></pre> 6474</div> 6475</div> 6476<div class="paragraph"> 6477<p>The task is now in the <strong>personal task list of the one that claimed the task</strong>.</p> 6478</div> 6479<div class="listingblock"> 6480<div class="content"> 6481<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-s">"fozzie"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 6482</td></tr></table></code></pre> 6483</div> 6484</div> 6485<div class="paragraph"> 6486<p>In the Activiti UI App, clicking the <em>claim</em> button will call the same operation. The task will now move to the personal task list of the logged on user. You also see that the assignee of the task changed to the current logged in user.</p> 6487</div> 6488<div class="imageblock" style="text-align: center"> 6489<div class="content"> 6490<img src="images/bpmn.financial.report.example.claim.task.png" alt="bpmn.financial.report.example.claim.task"> 6491</div> 6492</div> 6493</div> 6494<div class="sect3">
6495<h4 id="bpmnFirstExampleCompleteTask">7.3.9. Completing the task</h4> 6496<div class="paragraph"> 6497<p>The accountant can now start working on the financial report. Once the report is finished, he can <strong>complete the task</strong>, which means that all work for that task is done.</p> 6498</div> 6499<div class="listingblock"> 6500<div class="content"> 6501<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 6502</td></tr></table></code></pre> 6503</div> 6504</div> 6505<div class="paragraph"> 6506<p>For the Activiti engine, this is an external signal that the process instance execution must be continued. The task itself is removed from the runtime data. The single outgoing transition out of the task is followed, moving the execution to the second task (<em>'verification of the report'</em>). The same mechanism as described for the first task will now be used to assign the second task, with the small difference that the task will be assigned to the <em>management</em> group.</p> 6507</div> 6508<div class="paragraph"> 6509<p>In the demo setup, completing the task is done by clicking the <em>complete</em> button in the task list. Since Fozzie isn’t an accountant, we need to log out of the Activiti Explorer and login in as <em>kermit</em> (who is a manager). The second task is now visible in the unassigned task lists.</p> 6510</div> 6511</div> 6512<div class="sect3"> 6513<h4 id="bpmnFirstExampleEndingProcess">7.3.10. Ending the process</h4> 6514<div class="paragraph"> 6515<p>The verification task can be retrieved and claimed in exactly the same way as before. Completing this second task will move process execution to the end event, which finishes the process instance. The process instance and all related runtime execution data are removed from the datastore.</p> 6516</div> 6517<div class="paragraph"> 6518<p>When you log into Activiti Explorer you can verify this, since no records will be found in the table where the process executions are stored.</p> 6519</div> 6520<div class="imageblock" style="text-align: center"> 6521<div class="content"> 6522<img src="images/bpmn.financial.report.example.process.ended.png" alt="bpmn.financial.report.example.process.ended"> 6523</div> 6524</div> 6525<div class="paragraph"> 6526<p>Programmatically, you can also verify that the process is ended using the <code>historyService</code></p> 6527</div> 6528<div class="listingblock"> 6529<div class="content"> 6530<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 65312 65323 65334</div></td><td class="code"><span></span><span class="tok-n">HistoryService</span> <span class="tok-n">historyService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getHistoryService</span><span class="tok-o">();</span> 6534<span class="tok-n">HistoricProcessInstance</span> <span class="tok-n">historicProcessInstance</span> <span class="tok-o">=</span> 6535<span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricProcessInstanceQuery</span><span class="tok-o">().</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-n">procId</span><span class="tok-o">).</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 6536<span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Process instance end time: "</span> <span class="tok-o">+</span> <span class="tok-n">historicProcessInstance</span><span class="tok-o">.</span><span class="tok-na">getEndTime</span><span class="tok-o">());</span> 6537</td></tr></table></code></pre> 6538</div> 6539</div> 6540</div> 6541<div class="sect3">
6542<h4 id="bpmnFirstExampleCode">7.3.11. Code overview</h4> 6543<div class="paragraph"> 6544<p>Combine all the snippets from previous sections, and you should have something like this (this code takes in account that you probably will have started a few process instances through the Activiti Explorer UI. As such, it always retrieves a list of tasks instead of one task, so it always works):</p> 6545</div> 6546<div class="listingblock"> 6547<div class="content"> 6548<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 6549 2 6550 3 6551 4 6552 5 6553 6 6554 7 6555 8 6556 9 655710 655811 655912 656013 656114 656215 656316 656417 656518 656619 656720 656821 656922 657023 657124 657225 657326 657427 657528 657629 657730 657831 657932 658033 658134 658235 658336 658437 658538 658639 658740 658841 658942 659043 659144 659245 659346 659447 659548 659649 659750 659851 659952 660053 660154 660255 660356 660457 660558 660659 660760 660861 660962 661063</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">TenMinuteTutorial</span> <span class="tok-o">{</span> 6611 6612 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kt">void</span> <span class="tok-nf">main</span><span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">[]</span> <span class="tok-n">args</span><span class="tok-o">)</span> <span class="tok-o">{</span> 6613 6614 <span class="tok-c1">// Create Activiti process engine</span> 6615 <span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngineConfiguration</span> 6616 <span class="tok-o">.</span><span class="tok-na">createStandaloneProcessEngineConfiguration</span><span class="tok-o">()</span> 6617 <span class="tok-o">.</span><span class="tok-na">buildProcessEngine</span><span class="tok-o">();</span> 6618 6619 <span class="tok-c1">// Get Activiti services</span> 6620 <span class="tok-n">RepositoryService</span> <span class="tok-n">repositoryService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRepositoryService</span><span class="tok-o">();</span> 6621 <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getRuntimeService</span><span class="tok-o">();</span> 6622 6623 <span class="tok-c1">// Deploy the process definition</span> 6624 <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 6625 <span class="tok-o">.</span><span class="tok-na">addClasspathResource</span><span class="tok-o">(</span><span class="tok-s">"FinancialReportProcess.bpmn20.xml"</span><span class="tok-o">)</span> 6626 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 6627 6628 <span class="tok-c1">// Start a process instance</span> 6629 <span class="tok-n">String</span> <span class="tok-n">procId</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"financialReport"</span><span class="tok-o">).</span><span class="tok-na">getId</span><span class="tok-o">();</span> 6630 6631 <span class="tok-c1">// Get the first task</span> 6632 <span class="tok-n">TaskService</span> <span class="tok-n">taskService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getTaskService</span><span class="tok-o">();</span> 6633 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskCandidateGroup</span><span class="tok-o">(</span><span class="tok-s">"accountancy"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 6634 <span class="tok-k">
6634for</span> <span class="tok-o">(</span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">:</span> <span class="tok-n">tasks</span><span class="tok-o">)</span> <span class="tok-o">{</span> 6635 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Following task is available for accountancy group: "</span> <span class="tok-o">+</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 6636 6637 <span class="tok-c1">// claim it</span> 6638 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">claim</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-s">"fozzie"</span><span class="tok-o">);</span> 6639 <span class="tok-o">}</span> 6640 6641 <span class="tok-c1">// Verify Fozzie can now retrieve the task</span> 6642 <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-s">"fozzie"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 6643 <span class="tok-k">for</span> <span class="tok-o">(</span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">:</span> <span class="tok-n">tasks</span><span class="tok-o">)</span> <span class="tok-o">{</span> 6644 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Task for fozzie: "</span> <span class="tok-o">+</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 6645 6646 <span class="tok-c1">// Complete the task</span> 6647 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 6648 <span class="tok-o">}</span> 6649 6650 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Number of tasks for fozzie: "</span> 6651 <span class="tok-o">+</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-s">"fozzie"</span><span class="tok-o">).</span><span class="tok-na">count</span><span class="tok-o">());</span> 6652 6653 <span class="tok-c1">// Retrieve and claim the second task</span> 6654 <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskCandidateGroup</span><span class="tok-o">(</span><span class="tok-s">"management"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 6655 <span class="tok-k">for</span> <span class="tok-o">(</span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">:</span> <span class="tok-n">tasks</span><span class="tok-o">)</span> <span class="tok-o">{</span> 6656 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Following task is available for management group: "</span> <span class="tok-o">+</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span>
6657 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">claim</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-s">"kermit"</span><span class="tok-o">);</span> 6658 <span class="tok-o">}</span> 6659 6660 <span class="tok-c1">// Completing the second task ends the process</span> 6661 <span class="tok-k">for</span> <span class="tok-o">(</span><span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">:</span> <span class="tok-n">tasks</span><span class="tok-o">)</span> <span class="tok-o">{</span> 6662 <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">complete</span><span class="tok-o">(</span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 6663 <span class="tok-o">}</span> 6664 6665 <span class="tok-c1">// verify that the process is actually finished</span> 6666 <span class="tok-n">HistoryService</span> <span class="tok-n">historyService</span> <span class="tok-o">=</span> <span class="tok-n">processEngine</span><span class="tok-o">.</span><span class="tok-na">getHistoryService</span><span class="tok-o">();</span> 6667 <span class="tok-n">HistoricProcessInstance</span> <span class="tok-n">historicProcessInstance</span> <span class="tok-o">=</span> 6668 <span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricProcessInstanceQuery</span><span class="tok-o">().</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-n">procId</span><span class="tok-o">).</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 6669 <span class="tok-n">System</span><span class="tok-o">.</span><span class="tok-na">out</span><span class="tok-o">.</span><span class="tok-na">println</span><span class="tok-o">(</span><span class="tok-s">"Process instance end time: "</span> <span class="tok-o">+</span> <span class="tok-n">historicProcessInstance</span><span class="tok-o">.</span><span class="tok-na">getEndTime</span><span class="tok-o">());</span> 6670 <span class="tok-o">}</span> 6671 6672<span class="tok-o">}</span> 6673</td></tr></table></code></pre> 6674</div> 6675</div> 6676</div> 6677<div class="sect3"> 6678<h4 id="bpmnFirstExampleFutureEnhancements">7.3.12. Future enhancements</h4> 6679<div class="paragraph"> 6680<p>It’s easy to see that this business process is too simple to be usable in reality. However, as you are going through the BPMN 2.0 constructs available in Activiti, you will be able to enhance the business process by:</p> 6681</div> 6682<div class="ulist"> 6683<ul> 6684<li> 6685<p>defining <strong>gateways</strong> that act as decisions. This way, a manager could reject the financial report which would recreate the task for the accountant.</p> 6686</li> 6687<li> 6688<p>declaring and using <strong>variables</strong>, such that we can store or reference the report so that it can be visualized in the form.</p> 6689</li> 6690<li> 6691<p>defining a <strong>service task</strong> at the end of the process that will send the report to every shareholder.</p> 6692</li> 6693<li> 6694<p>etc.</p> 6695</li> 6696</ul> 6697</div> 6698</div> 6699</div> 6700</div> 6701</div> 6702<div class="sect1"> 6703<h2 id="bpmnConstructs">8. BPMN 2.0 Constructs</h2> 6704<div class="sectionbody"> 6705<div class="paragraph"> 6706<p>This chapter covers the BPMN 20 constructs supported by Activiti as well as custom extensions to the BPMN standard.</p> 6707</div> 6708<div class="sect2"> 6709<h3 id="bpmnCustomExtensions">8.1. Custom extensions</h3> 6710<div class="paragraph"> 6711<p>The BPMN 2.0 standard is a good thing for all parties involved. End-users don’t suffer from a vendor lock-in that comes by depending on a proprietary solution. Frameworks, and particularly open-source frameworks such as Activiti, can implement a solution that has the same (and often better implemented ;-) features as those of a big vendor. Due to the BPMN 2.0 standard, the transition from such a big vendor solution towards Activiti is an easy and smooth path.</p> 6712</div> 6713<div class="paragraph"> 6714<p>The downside of a standard however, is the fact that it is always the result of many discu
6714ssions and compromises between different companies (and often visions). As a developer reading the BPMN 2.0 XML of a process definition, sometimes it feels like certain constructs or way to do things are too cumbersome. Since Activiti puts ease of development as a top-priority, we introduced something called the <strong><em>Activiti BPMN extensions</em></strong>. These <em>extensions</em> are new constructs or ways to simplify certain constructs that are not in the BPMN 2.0 specification.</p> 6715</div> 6716<div class="paragraph"> 6717<p>Although the BPMN 2.0 specification clearly states that it was made for custom extension, we make sure that:</p> 6718</div> 6719<div class="ulist"> 6720<ul> 6721<li> 6722<p>The prerequisite of such a custom extension is that there <strong>always</strong> must be a simple transformation to the <strong>standard way of doing things</strong>. So when you decide to use a custom extension, you don’t have to be afraid that there is no way back.</p> 6723</li> 6724<li> 6725<p>When using a custom extension, this is always clearly indicated by giving the new XML element, attribute, etc. the <strong>activiti:</strong> namespace prefix.</p> 6726</li> 6727</ul> 6728</div> 6729<div class="paragraph"> 6730<p>So whether you want to use a custom extension or not, is completely up to you. Several factors will influence this decision (graphical editor usage, company policy, etc.). We only provide them since we believe that some points in the standard can be done simpler or more efficient. Feel free to give us (positive and/or negative) feedback on our extensions, or to post new ideas for custom extensions. Who knows, some day your idea might pop up in the specification!</p> 6731</div> 6732</div> 6733<div class="sect2"> 6734<h3 id="bpmnEvents">8.2. Events</h3> 6735<div class="paragraph"> 6736<p>Events are used to model something that happens during the lifetime process. Events are always visualized as a circle. In BPMN 2.0, there exist two main event categories: <em>catching</em> or <em>throwing</em> event.</p> 6737</div> 6738<div class="ulist"> 6739<ul> 6740<li> 6741<p><strong>Catching:</strong> when process execution arrives in the event, it will wait for a trigger to happen. The type of trigger is defined by the inner icon or the type declaration in the XML. Catching events are visually differentiated from a throwing event by the inner icon that is not filled (i.e. it is white).</p> 6742</li> 6743<li> 6744<p><strong>Throwing:</strong> when process execution arrives in the event, a trigger is fired. The type of trigger is defined by the inner icon or the type declaration in the XML. Throwing events are visually differentiated from a catching event by the inner icon that is filled with black.</p> 6745</li> 6746</ul> 6747</div> 6748<div class="sect3"> 6749<h4 id="eventDefinitions">8.2.1. Event Definitions</h4> 6750<div class="paragraph"> 6751<p>Event definitions define the semantics of an event. Without an event definition, an event "does nothing special". For instance a start event without and event definition does not specify what exactly starts the process. If we add an event definition to the start event (like for instance a timer event definition) we declare what "type" of event starts the process (in the case of a timer event definition the fact that a certain point in time is reached).</p> 6752</div> 6753</div> 6754<div class="sect3"> 6755<h4 id="timerEventDefinitions">8.2.2. Timer Event Definitions</h4> 6756<div class="paragraph"> 6757<p>Timer events are events which are triggered by defined timer. They can be used as <a href="#bpmnTimerStartEvent">start event</a>, <a href="#bpmnIntermediateCatchingEvent">intermediate event</a> or <a href="#bpmnTimerBoundaryEvent">boundary event</a>. The behavior of the time event depends on the business calendar used. Every timer event has a default business calendar, but the business calendar can also be defined on the timer event definition.</p> 6758</div> 6759<div class="listingblock"> 6760<div class="content"> 6761<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 67622 67633</div></td><td class="code"><span></span><span class="tok-nt"><timerEventDefinition</span> <span class="tok-na">activiti:businessCalendarName=</span><span class="tok-s">"custom"</span><span class="tok-nt">></span> 6764 ... 6765<span class="tok-nt"></timerEventDefinition></span> 6766</td></tr></table></code></pre> 6767</div> 6768</div> 6769<div class="paragraph"> 6770<p>Where businessCalendarName points to business calendar in process engine configuration. When business calendar is omitted default business calendars are used.<
6770/p> 6771</div> 6772<div class="paragraph"> 6773<p>Timer definition must have exactly one element from the following:</p> 6774</div> 6775<div class="ulist"> 6776<ul> 6777<li> 6778<p><strong>timeDate</strong>. This format specifies fixed date in <a href="http://en.wikipedia.org/wiki/ISO_8601#Dates">ISO 8601</a> format, when trigger will be fired. Example:</p> 6779</li> 6780</ul> 6781</div> 6782<div class="listingblock"> 6783<div class="content"> 6784<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 67852 67863</div></td><td class="code"><span></span><span class="tok-nt"><timerEventDefinition></span> 6787 <span class="tok-nt"><timeDate></span>2011-03-11T12:13:14<span class="tok-nt"></timeDate></span> 6788<span class="tok-nt"></timerEventDefinition></span> 6789</td></tr></table></code></pre> 6790</div> 6791</div> 6792<div class="ulist"> 6793<ul> 6794<li> 6795<p><strong>timeDuration</strong>. To specify how long the timer should run before it is fired, a <em>timeDuration</em> can be specified as sub-element of <em>timerEventDefinition</em>. The format used is the <a href="http://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601</a> format (as required by the BPMN 2.0 specification). Example (interval lasting 10 days):</p> 6796</li> 6797</ul> 6798</div> 6799<div class="listingblock"> 6800<div class="content"> 6801<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 68022 68033</div></td><td class="code"><span></span><span class="tok-nt"><timerEventDefinition></span> 6804 <span class="tok-nt"><timeDuration></span>P10D<span class="tok-nt"></timeDuration></span> 6805<span class="tok-nt"></timerEventDefinition></span> 6806</td></tr></table></code></pre> 6807</div> 6808</div> 6809<div class="ulist"> 6810<ul> 6811<li> 6812<p><strong>timeCycle</strong>. Specifies repeating interval, which can be useful for starting process periodically, or for sending multiple reminders for overdue user task. Time cycle element can be in two formats. First is the format of recurring time duration, as specified by <a href="http://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals">ISO 8601</a> standard. Example (3 repeating intervals, each lasting 10 hours):</p> 6813</li> 6814</ul> 6815</div> 6816<div class="paragraph"> 6817<p>There is also the possibility to specify the <em>endDate</em> as an optional attribute on the <em>timeCycle</em> or either in the end of the time expression as follows: <code>R3/PT10H/${EndDate}</code>. 6818When the endDate is reached the application will stop creating other jobs for this task. 6819It accepts as value either static values <a href="http://en.wikipedia.org/wiki/ISO_8601#Dates">ISO 8601</a> standard for example <em>"2015-02-25T16:42:11+00:00"</em> or variables <em>${EndDate}</em></p> 6820</div> 6821<div class="listingblock"> 6822<div class="content"> 6823<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 68242 68253</div></td><td class="code"><span></span><span class="tok-nt"><timerEventDefinition></span> 6826 <span class="tok-nt"><timeCycle</span> <span class="tok-na">activiti:endDate=</span><span class="tok-s">"2015-02-25T16:42:11+00:00"</span><span class="tok-nt">></span>R3/PT10H<span class="tok-nt"></timeCycle></span> 6827<span class="tok-nt"></timerEventDefinition></span> 6828</td></tr></table></code></pre> 6829</div> 6830</div> 6831<div class="listingblock"> 6832<div class="content"> 6833<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 68342 68353</div></td><td class="code"><span></span><span class="tok-nt"><timerEventDefinition></span> 6836 <span class="tok-nt"><timeCycle></span>R3/PT10H/${EndDate}<span class="tok-nt"></timeCycle></span> 6837<span class="tok-nt"></timerEventDefinition></span> 6838</td></tr></table></code></pre> 6839</div> 6840</div> 6841<div class="paragraph"> 6842<p>If both are specified then the endDate specified as attribute will be used by the system.</p> 6843</div> 6844<div class="paragraph"> 6845<p>Currently only the <em>BoundaryTimerEvents</em> and <em>CatchTimerEvent</em>
6845 supports <em>EndDate</em> functionality.</p> 6846</div> 6847<div class="paragraph"> 6848<p>Additionally, you can specify time cycle using cron expressions, example below shows trigger firing every 5 minutes, starting at full hour:</p> 6849</div> 6850<div class="listingblock"> 6851<div class="content"> 6852<pre>0 0/5 * * * ?</pre> 6853</div> 6854</div> 6855<div class="paragraph"> 6856<p>Please see <a href="http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html">this tutorial</a> for using cron expressions.</p> 6857</div> 6858<div class="paragraph"> 6859<p><strong>Note:</strong> The first symbol denotes seconds, not minutes as in normal Unix cron.</p> 6860</div> 6861<div class="paragraph"> 6862<p>The recurring time duration is better suited for handling relative timers, which are calculated with respect to some particular point in time (e.g. time when user task was started), while cron expressions can handle absolute timers - which is particularly useful for <a href="#timerStartEventDescription">timer start events</a>.</p> 6863</div> 6864<div class="paragraph"> 6865<p>You can use expressions for the timer event definitions, by doing so you can influence the timer definition 6866based on process variables. The process variables must contain the ISO 8601 (or cron for cycle type) string for appropriate timer type.</p> 6867</div> 6868<div class="listingblock"> 6869<div class="content"> 6870<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 68712 68723 68734 68745</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"escalationTimer"</span> <span class="tok-na">cancelActivity=</span><span class="tok-s">"true"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"firstLineSupport"</span><span class="tok-nt">></span> 6875 <span class="tok-nt"><timerEventDefinition></span> 6876 <span class="tok-nt"><timeDuration></span>${duration}<span class="tok-nt"></timeDuration></span> 6877 <span class="tok-nt"></timerEventDefinition></span> 6878<span class="tok-nt"></boundaryEvent></span> 6879</td></tr></table></code></pre> 6880</div> 6881</div> 6882<div class="paragraph"> 6883<p><strong>Note:</strong> timers are only fired when the job or async executor is enabled (i.e. <em>jobExecutorActivate</em> or <em>asyncExecutorActivate</em> needs to be set to <code>true</code> in the <code>activiti.cfg.xml</code>, since the job and async executor are disabled by default).</p> 6884</div> 6885</div> 6886<div class="sect3"> 6887<h4 id="bpmnErrorEventDefinition">8.2.3. Error Event Definitions</h4> 6888<div class="paragraph"> 6889<p><strong>Important note:</strong> a BPMN error is NOT the same as a Java exception. In fact, the two have nothing in common. BPMN error events are a way of modeling <em>business exceptions</em>. Java exceptions are handled in <a href="#serviceTaskExceptionHandling">their own specific way</a>.</p> 6890</div> 6891<div class="listingblock"> 6892<div class="content"> 6893<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 68942 68953</div></td><td class="code"><span></span><span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myErrorEndEvent"</span><span class="tok-nt">></span> 6896 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"myError"</span> <span class="tok-nt">/></span> 6897<span class="tok-nt"></endEvent></span> 6898</td></tr></table></code></pre> 6899</div> 6900</div> 6901</div> 6902<div class="sect3"> 6903<h4 id="bpmnSignalEventDefinition">8.2.4. Signal Event Definitions</h4> 6904<div class="paragraph"> 6905<p>Signal events are events which reference a named signal. A signal is an event of global scope (broadcast semantics) and is delivered to all active handlers (waiting process instances/catching signal events).</p> 6906</div> 6907<div class="paragraph"> 6908<p>A signal event definition is declared using the <code>signalEventDefinition</code> element. The attribute <code>signalRef</code> references a <code>signal</code> element declared as a child element of the <code>definitions</code> root element. The following is an excerpt of a process where a signal event is thrown and caught by intermediate events.</p> 6909</div> 6910<div class="listingblock"> 6911<div class="content"> 6912<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 6913 2 6914 3 6915 4 6916 5 6917 6 6918 7 6919 8 6920 9 692110 692211 692312 692413 692514 692615 692716 692817</div></td><td class="code"><span></span><span class="tok-nt"><definitions...</span> <span class="tok-nt">></span> 6929 <span class="tok-c"><!-- declaration of the signal --></span> 6930 <span class="tok-nt"><signal</span> <span class="tok-na">id=</span><span class="tok-s">"alertSignal"</span> <span class="tok-na">name=</span><span class="tok-s">"alert"</span> <span class="tok-nt">/></span> 6931 6932 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"catchSignal"</span><span class="tok-nt">></span> 6933 <span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"throwSignalEvent"</span> <span class="tok-na">name=</span><span class="tok-s">"Alert"</span><span class="tok-nt">></span> 6934 <span class="tok-c"><!-- signal event definition --></span> 6935 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">
6935signalRef=</span><span class="tok-s">"alertSignal"</span> <span class="tok-nt">/></span> 6936 <span class="tok-nt"></intermediateThrowEvent></span> 6937 ... 6938 <span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"catchSignalEvent"</span> <span class="tok-na">name=</span><span class="tok-s">"On Alert"</span><span class="tok-nt">></span> 6939 <span class="tok-c"><!-- signal event definition --></span> 6940 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">signalRef=</span><span class="tok-s">"alertSignal"</span> <span class="tok-nt">/></span> 6941 <span class="tok-nt"></intermediateCatchEvent></span> 6942 ... 6943 <span class="tok-nt"></process></span> 6944<span class="tok-nt"></definitions></span> 6945</td></tr></table></code></pre> 6946</div> 6947</div> 6948<div class="paragraph"> 6949<p>The <code>signalEventDefinition</code>s reference the same <code>signal</code> element.</p> 6950</div> 6951<div class="sect4"> 6952<h5 id="bpmnSignalEventDefinitionThrow">Throwing a Signal Event</h5> 6953<div class="paragraph"> 6954<p>A signal can either be thrown by a process instance using a BPMN construct or programmatically using java API. The following methods on the <code>org.activiti.engine.RuntimeService</code> can be used to throw a signal programmatically:</p> 6955</div> 6956<div class="listingblock"> 6957<div class="content"> 6958<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 69592</div></td><td class="code"><span></span><span class="tok-n">RuntimeService</span><span class="tok-o">.</span><span class="tok-na">signalEventReceived</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">signalName</span><span class="tok-o">);</span> 6960<span class="tok-n">RuntimeService</span><span class="tok-o">.</span><span class="tok-na">signalEventReceived</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">signalName</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">);</span> 6961</td></tr></table></code></pre> 6962</div> 6963</div> 6964<div class="paragraph"> 6965<p>The difference between <code>signalEventReceived(String signalName);</code> and <code>signalEventReceived(String signalName, String executionId);</code> is that the first method throws the signal globally to all subscribed handlers (broadcast semantics) and the second method delivers the signal to a specific execution only.</p> 6966</div> 6967</div> 6968<div class="sect4"> 6969<h5 id="bpmnSignalEventDefinitionCatch">Catching a Signal Event</h5> 6970<div class="paragraph"> 6971<p>A signal event can be caught by an intermediate catch signal event or a signal boundary event.</p> 6972</div> 6973</div> 6974<div class="sect4"> 6975<h5 id="bpmnSignalEventDefinitionQuery">Querying for Signal Event subscriptions</h5> 6976<div class="paragraph"> 6977<p>It is possible to query for all executions which have subscribed to a specific signal event:</p> 6978</div> 6979<div class="listingblock"> 6980<div class="content"> 6981<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 69822 69833</div></td><td class="code"><span></span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Execution</span><span class="tok-o">></span> <span class="tok-n">executions</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createExecutionQuery</span><span class="tok-o">()</span> 6984 <span class="tok-o">.</span><span class="tok-na">signalEventSubscriptionName</span><span class="tok-o">(</span><span class="tok-s">"alert"</span><span class="tok-o">)</span> 6985 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 6986</td></tr></table></code></pre> 6987</div> 6988</div> 6989<div class="paragraph"> 6990<p>We could then use the <code>signalEventReceived(String signalName, String executionId)</code> method to deliver the signal to these executions.</p> 6991</div> 6992</div> 6993<div class="sect4"> 6994<h5 id="bpmnSignalEventDefinitionScope">Signal event scope</h5> 6995<div class="paragraph"> 6996<p>By default, signals are <em>broadcast process engine wide</em>. This means that you can throw a signal event in a process instance, and other process instances with different process definitions can react on the occurrence of this event.</p> 6997</div> 6998<div class="paragraph"> 6999<p>However, sometimes it is wanted to react to a signal event only within the <em>same process instance</em>. A use case for example is a synchronization mechanism in the process instance, if two or more activities are mutually exclusive.</p> 7000</div> 7001<div class="paragraph"> 7002<p>To restrict the <em>scope</em> of the signal event, add the (non-BPMN 2.0 standard!) <em>scope attribute</em> to the signal event definition:</p> 7003</div> 7004<div class="listingblock"> 7005<div class="content"> 7006<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><signal</span> <span class="tok-na">id=</span><span class="tok-s">"alertSignal"</span> <span class="tok-na">name=</span><span class="tok-s">"alert"</span> <span class="tok-na">activiti:scope=</span><span class="tok-s">"processInstance"</span><span class="tok-nt">/></span> 7007</td></tr></table></code></pre> 7008</div> 7009</div> 7010<div class="paragraph"> 7011<p>The default value for this is attribute is <em>"global"</em>.</p> 7012</div> 7013</div> 7014<div class="sect4"> 7015<h5 id="bpmnSignalEventDefinitionExample">Signal Event example(s)</h5> 7016<div class="paragraph"> 7017<p>The following is an example of two separate processes communicating using signals. The first process is started if an insurance policy is updated or changed. After the changes have been reviewed by a human participant, a signal event is thrown, signaling that a policy has changed:</p> 7018</div> 7019<div class="imageblock" style="text-align: center"> 7020<div class="content"> 7021<img src="images/bpmn.signal.event.throw.png" alt="bpmn.signal.event.throw"> 7022</div> 7023</div> 7024<div class="paragraph"> 7025<p>This event can now be caught by all process instances which are interested. The following is an example of a process subscribing to the event.</p> 7026</div> 7027<div class="imageblock" style="text-align: center"> 7028<div class="content"> 7029<img src="images/bpmn.signal.event.catch.png" alt="bpmn.signal.event.catch"> 7030</div> 7031</div> 7032<div class="paragraph"> 7033<p><strong>Note:</strong> it is important to understand that a signal event is broadcast to <strong>all</strong> active handlers. This means in the case of the example given above, that all instances of the process catching the signal would receive the event. In this case this is what we want. However, there are also situations where the broadcast behavior is unintended. Consider the following process:</p> 7034</div> 7035<div class="imageblock" style="text-align: center"> 7036<div class="content"> 7037<img src="images/bpmn.signal.event.warning.1.png" alt="bpmn.signal.event.warning.1"> 7038</div> 7039</div> 7040<div class="paragraph"> 7041<p>
7041The pattern described in the process above is not supported by BPMN. The idea is that the error thrown while performing the "do something" task is caught by the boundary error event and would be propagated to the parallel path of execution using the signal throw event and then interrupt the "do something in parallel" task. So far Activiti would perform as expected. The signal would be propagated to the catching boundary event and interrupt the task. <strong>However, due to the broadcast semantics of the signal, it would also be propagated to all other process instances which have subscribed to the signal event.</strong> In this case, this might not be what we want.</p> 7042</div> 7043<div class="paragraph"> 7044<p><strong>Note:</strong> the signal event does not perform any kind of correlation to a specific process instance. On the contrary, it is broadcast to all process instances. If you need to deliver a signal to a specific process instance only, perform correlation manually and use <code>signalEventReceived(String signalName, String executionId)</code> and the appropriate <a href="#bpmnSignalEventDefinitionQuery">query mechanisms</a>.</p> 7045</div> 7046<div class="paragraph"> 7047<p>Activiti does have a way to fix this, by adding the <em>scope</em> attribute to the signal event and set it to <em>processInstance</em>.</p> 7048</div> 7049</div> 7050</div> 7051<div class="sect3"> 7052<h4 id="bpmnMessageEventDefinition">8.2.5. Message Event Definitions</h4> 7053<div class="paragraph"> 7054<p>Message events are events which reference a named message. A message has a name and a payload. Unlike a signal, a message event is always directed at a single receiver.</p> 7055</div> 7056<div class="paragraph"> 7057<p>A message event definition is declared using the <code>messageEventDefinition</code> element. The attribute <code>messageRef</code> references a <code>message</code> element declared as a child element of the <code>definitions</code> root element. The following is an excerpt of a process where two message events is declared and referenced by a start event and an intermediate catching message event.</p> 7058</div> 7059<div class="listingblock"> 7060<div class="content"> 7061<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 7062 2 7063 3 7064 4 7065 5 7066 6 7067 7 7068 8 7069 9 707010 707111 707212 707313 707414 707515 707616 707717 707818 707919 708020 708121 708222</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"definitions"</span> 7083 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 7084 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 7085 <span class="tok-na">targetNamespace=</span><span class="tok-s">"Examples"</span> 7086 <span class="tok-na">xmlns:tns=</span><span class="tok-s">"Examples"</span><span class="tok-nt">></span> 7087 7088 <span class="tok-nt"><message</span> <span class="tok-na">id=</span><span class="tok-s">"newInvoice"</span> <span class="tok-na">name=</span><span class="tok-s">"newInvoiceMessage"</span> <span class="tok-nt">/></span> 7089 <span class="tok-nt"><message</span> <span class="tok-na">id=</span><span class="tok-s">"payment"</span> <span class="tok-na">name=</span><span class="tok-s">"paymentMessage"</span> <span class="tok-nt">/></span> 7090 7091 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"invoiceProcess"</span><span class="tok-nt">></span> 7092 7093 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"messageStart"</span> <span class="tok-nt">></span> 7094 <span class="tok-nt"><messageEventDefinition</span> <span class="tok-na">messageRef=</span><span class="tok-s">"newInvoice"</span> <span class="tok-nt">/></span> 7095 <span class="tok-nt"></startEvent></span> 7096 ... 7097 <span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"paymentEvt"</span> <span class="tok-nt">></span> 7098 <span class="tok-nt"><messageEventDefinition</span> <span class="tok-na">messageRef=</span><span class="tok-s">"payment"</span> <span class="tok-nt">/></span> 7099 <span class="tok-nt"></intermediateCatchEvent></span> 7100 ... 7101 <span class="tok-nt"></process></span> 7102 7103<span class="tok-nt"></definitions></span> 7104</td></tr></table></code></pre> 7105</div> 7106</div> 7107<div class="sect4"> 7108<h5 id="bpmnMessageEventDefinitionThrow">Throwing a Message Event</h5> 7109<div class="paragraph"> 7110<p>As an embeddable process engine, Activiti is not concerned with actually receiving a message. This would be environment dependent and entail platform-specific activities like connecting to a JMS (Java Messaging Service) Queue/Topic or processing a Webservice or REST request. The reception of messages is therefore something you have to implement as part of the application or infrastru
7110cture into which the process engine is embedded.</p> 7111</div> 7112<div class="paragraph"> 7113<p>After you have received a message inside your application, you must decide what to do with it. If the message should trigger the start of a new process instance, choose between the following methods offered by the runtime service:</p> 7114</div> 7115<div class="listingblock"> 7116<div class="content"> 7117<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 71182 71193</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByMessage</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">);</span> 7120<span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByMessage</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">processVariables</span><span class="tok-o">);</span> 7121<span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByMessage</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">businessKey</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">processVariables</span><span class="tok-o">);</span> 7122</td></tr></table></code></pre> 7123</div> 7124</div> 7125<div class="paragraph"> 7126<p>These methods allow starting a process instance using the referenced message.</p> 7127</div> 7128<div class="paragraph"> 7129<p>If the message needs to be received by an existing process instance, you first have to correlate the message to a specific process instance (see next section) and then trigger the continuation of the waiting execution. The runtime service offers the following methods for triggering an execution based on a message event subscription:</p> 7130</div> 7131<div class="listingblock"> 7132<div class="content"> 7133<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 71342</div></td><td class="code"><span></span><span class="tok-kt">void</span> <span class="tok-nf">messageEventReceived</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">);</span> 7135<span class="tok-kt">void</span> <span class="tok-nf">messageEventReceived</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">executionId</span><span class="tok-o">,</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">processVariables</span><span class="tok-o">);</span> 7136</td></tr></table></code></pre> 7137</div> 7138</div> 7139</div> 7140<div class="sect4"> 7141<h5 id="bpmnMessageEventDefinitionQuery">Querying for Message Event subscriptions</h5> 7142<div class="ulist"> 7143<ul> 7144<li> 7145<p>In the case of a message start event, the message event subscription is associated with a particular <em>process definition</em>. Such message subscriptions can be queried using a <code>
7145ProcessDefinitionQuery</code>:</p> 7146</li> 7147</ul> 7148</div> 7149<div class="listingblock"> 7150<div class="content"> 7151<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 71522 71533</div></td><td class="code"><span></span><span class="tok-n">ProcessDefinition</span> <span class="tok-n">processDefinition</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createProcessDefinitionQuery</span><span class="tok-o">()</span> 7154 <span class="tok-o">.</span><span class="tok-na">messageEventSubscription</span><span class="tok-o">(</span><span class="tok-s">"newCallCenterBooking"</span><span class="tok-o">)</span> 7155 <span class="tok-o">.</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 7156</td></tr></table></code></pre> 7157</div> 7158</div> 7159<div class="paragraph"> 7160<p>Since there can only be one process definition for a specific message subscription, the query always returns zero or one results. If a process definition is updated, 7161only the newest version of the process definition has a subscription to the message event.</p> 7162</div> 7163<div class="ulist"> 7164<ul> 7165<li> 7166<p>In the case of an intermediate catch message event, the message event subscription is associated with a 7167particular <em>execution</em>. Such message event subscriptions can be queried using a <code>ExecutionQuery</code>:</p> 7168</li> 7169</ul> 7170</div> 7171<div class="listingblock"> 7172<div class="content"> 7173<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 71742 71753 71764</div></td><td class="code"><span></span><span class="tok-n">Execution</span> <span class="tok-n">execution</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createExecutionQuery</span><span class="tok-o">()</span> 7177 <span class="tok-o">.</span><span class="tok-na">messageEventSubscriptionName</span><span class="tok-o">(</span><span class="tok-s">"paymentReceived"</span><span class="tok-o">)</span> 7178 <span class="tok-o">.</span><span class="tok-na">variableValueEquals</span><span class="tok-o">(</span><span class="tok-s">"orderId"</span><span class="tok-o">,</span> <span class="tok-n">message</span><span class="tok-o">.</span><span class="tok-na">getOrderId</span><span class="tok-o">())</span> 7179 <span class="tok-o">.</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 7180</td></tr></table></code></pre> 7181</div> 7182</div> 7183<div class="paragraph"> 7184<p>Such queries are called correlation queries and usually require knowledge about the processes (in this case that there will be at most one process instance for a given orderId).</p> 7185</div> 7186</div> 7187<div class="sect4"> 7188<h5 id="bpmnMessageEventDefinitionExample">Message Event example(s)</h5> 7189<div class="paragraph"> 7190<p>The following is an example of a process which can be started using two different messages:</p> 7191</div> 7192<div class="imageblock" style="text-align: center"> 7193<div class="content"> 7194<img src="images/bpmn.start.message.event.example.1.png" alt="bpmn.start.message.event.example.1"> 7195</div> 7196</div> 7197<div class="paragraph"> 7198<p>This is useful if the process needs alternative ways to react to different start events but eventually continues in a uniform way.</p> 7199</div> 7200</div> 7201</div> 7202<div class="sect3"> 7203<h4 id="bpmnStartEvents">8.2.6. Start Events</h4> 7204<div class="paragraph"> 7205<p>A start event indicates where a process starts. The type of start event (process starts on arrival of message, on specific time intervals, etc.), defining <em>how</em> the process is started is shown as a small icon in the visual representation of the event. In the XML representation, the type is given by the declaration of a sub-element.</p> 7206</div> 7207<div class="paragraph"> 7208<p>Start events <strong>are always catching</strong>: conceptually the event is (at any time) waiting until a certain trigger happens.</p> 7209</div> 7210<div class="paragraph"> 7211<p>In a start event, following Activiti-specific properties can be specified:</p> 7212</div> 7213<div class="ulist"> 7214<ul> 7215<li> 7216<p><strong>initiator</strong>
7216: identifies the variable name in which the authenticated user id will be stored when the process is started. Example:</p> 7217</li> 7218</ul> 7219</div> 7220<div class="listingblock"> 7221<div class="content"> 7222<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"request"</span> <span class="tok-na">activiti:initiator=</span><span class="tok-s">"initiator"</span> <span class="tok-nt">/></span> 7223</td></tr></table></code></pre> 7224</div> 7225</div> 7226<div class="paragraph"> 7227<p>The authenticated user must be set with the method <code>IdentityService.setAuthenticatedUserId(String)</code> in a try-finally block like this:</p> 7228</div> 7229<div class="listingblock"> 7230<div class="content"> 7231<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 72322 72333 72344 72355 72366</div></td><td class="code"><span></span><span class="tok-k">try</span> <span class="tok-o">{</span> 7237 <span class="tok-n">identityService</span><span class="tok-o">.</span><span class="tok-na">setAuthenticatedUserId</span><span class="tok-o">(</span><span class="tok-s">"bono"</span><span class="tok-o">);</span> 7238 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"someProcessKey"</span><span class="tok-o">);</span> 7239<span class="tok-o">}</span> <span class="tok-k">finally</span> <span class="tok-o">{</span> 7240 <span class="tok-n">identityService</span><span class="tok-o">.</span><span class="tok-na">setAuthenticatedUserId</span><span class="tok-o">(</span><span class="tok-kc">null</span><span class="tok-o">);</span> 7241<span class="tok-o">}</span> 7242</td></tr></table></code></pre> 7243</div> 7244</div> 7245<div class="paragraph"> 7246<p>This code is baked into the Activiti Explorer application. So it works in combination with <a href="#forms">Forms</a>.</p> 7247</div> 7248</div> 7249<div class="sect3"> 7250<h4 id="bpmnNoneStartEvent">8.2.7. None Start Event</h4> 7251<div class="sect4"> 7252<h5 id="noneStartEventDescription">Description</h5> 7253<div class="paragraph"> 7254<p>A <em>none</em> start event technically means that the trigger for starting the process instance is unspecified. This means that the engine cannot anticipate when the process instance must be started. The none start event is used when the process instance is started through the API by calling one of the <em>startProcessInstanceByXXX</em> methods.</p> 7255</div> 7256<div class="listingblock"> 7257<div class="content"> 7258<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-n">processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByXXX</span><span class="tok-o">();</span> 7259</td></tr></table></code></pre> 7260</div> 7261</div> 7262<div class="paragraph"> 7263<p><em>Note:</em> a subprocess always has a none start event.</p> 7264</div> 7265</div> 7266<div class="sect4"> 7267<h5 id="noneStartEventGraphicalNotation">Graphical notation</h5> 7268<div class="paragraph"> 7269<p>A none start event is visualized as a circle with no inner icon (i.e. no trigger type).</p> 7270</div> 7271<div class="imageblock" style="text-align: center"> 7272<div class="content"> 7273<img src="images/bpmn.none.start.event.png" alt="bpmn.none.start.event"> 7274</div> 7275</div> 7276</div> 7277<div class="sect4"> 7278<h5 id="noneStartEventXml">XML representation</h5> 7279<div class="paragraph"> 7280<p>The XML representation of a none start event is the normal start event declaration, without any sub-element (other start event types all have a sub-element declaring the type).</p> 7281</div> 7282<div class="listingblock"> 7283<div class="content"> 7284<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span> <span class="tok-na">name=</span><span class="tok-s">"my start event"</span> <span class="tok-nt">/></span> 7285</td></tr></table></code></pre> 7286</div> 7287</div> 7288</div> 7289<div class="sect4"> 7290<h5 id="noneStartEventCustomExtension">Custom extensions for the none start event</h5> 7291<div class="paragraph"> 7292<p><strong>formKey</strong>: references to a form template that users have to fill in when starting a new process instance. More information can be found in <a href="#forms">the forms section</a> Example:</p> 7293</div> 7294<div class="listingblock"> 7295<div class="content"> 7296<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"request"</span> <span class="tok-na">activiti:formKey=</span><span class="tok-s">"org/activiti/examples/taskforms/request.form"</span> <span class="tok-nt">/></span> 7297</td></tr></table></code></pre> 7298</div> 7299</div> 7300</div> 7301</div> 7302<div class="sect3"> 7303<h4 id="bpmnTimerStartEvent">8.2.8. Timer Start Event</h4> 7304<div class="sect4"> 7305<h5 id="timerStartEventDescription">Description</h5> 7306<div class="paragraph"> 7307<p>A timer start event is used to create process instance at given time. It can be used both for processes which should start only once and for processes that should start in specific time intervals.</p> 7308</div> 7309<div class="paragraph"> 7310<p><em>Note:</em> a subprocess cannot have a timer start event.</p> 7311</div> 7312<div class="paragraph"> 7313<p><em>Note:</em> a start timer event is scheduled as soon as process is deployed. There is no need to call startProcessInstanceByXXX, although calling start process methods is not restricted and will cause one more starting of the process at the time of startProcessInstanceByXXX Invocation.</p> 7314</div> 7315<div class="paragraph"> 7316<p><em>Note:</em> when a new version of a process with a start timer event is deployed, the job c
7316orresponding with the previous timer will be removed. The reasoning is that normally it is not wanted to keep automatically starting new process instances of this old version of the process.</p> 7317</div> 7318</div> 7319<div class="sect4"> 7320<h5 id="timerStartEventGraphicalNotation">Graphical notation</h5> 7321<div class="paragraph"> 7322<p>A none start event is visualized as a circle with clock inner icon.</p> 7323</div> 7324<div class="imageblock" style="text-align: center"> 7325<div class="content"> 7326<img src="images/bpmn.clock.start.event.png" alt="bpmn.clock.start.event"> 7327</div> 7328</div> 7329</div> 7330<div class="sect4"> 7331<h5 id="timerStartEventXml">XML representation</h5> 7332<div class="paragraph"> 7333<p>The XML representation of a timer start event is the normal start event declaration, with timer definition sub-element. Please refer to <a href="#timerEventDefinitions">timer definitions</a> for configuration details.</p> 7334</div> 7335<div class="paragraph"> 7336<p>Example: process will start 4 times, in 5 minute intervals, starting on 11th march 2011, 12:13</p> 7337</div> 7338<div class="listingblock"> 7339<div class="content"> 7340<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 73412 73423 73434 73445</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span><span class="tok-nt">></span> 7345 <span class="tok-nt"><timerEventDefinition></span> 7346 <span class="tok-nt"><timeCycle></span>R4/2011-03-11T12:13/PT5M<span class="tok-nt"></timeCycle></span> 7347<span class="tok-nt"></timerEventDefinition></span> 7348<span class="tok-nt"></startEvent></span> 7349</td></tr></table></code></pre> 7350</div> 7351</div> 7352<div class="paragraph"> 7353<p>Example: process will start once, on selected date</p> 7354</div> 7355<div class="listingblock"> 7356<div class="content"> 7357<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 73582 73593 73604 73615</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span><span class="tok-nt">></span> 7362 <span class="tok-nt"><timerEventDefinition></span> 7363 <span class="tok-nt"><timeDate></span>2011-03-11T12:13:14<span class="tok-nt"></timeDate></span> 7364 <span class="tok-nt"></timerEventDefinition></span> 7365<span class="tok-nt"></startEvent></span> 7366</td></tr></table></code></pre> 7367</div> 7368</div> 7369</div> 7370</div> 7371<div class="sect3"> 7372<h4 id="bpmnMessageStartEvent">8.2.9. Message Start Event</h4> 7373<div class="sect4"> 7374<h5 id="messageStartEventDescription">Description</h5> 7375<div class="paragraph"> 7376<p>A <a href="#bpmnMessageEventDefinition">message</a> start event can be used to start a process instance using a named message. This effectively allows us to <em>select</em> the right start event from a set of alternative start events using the message name.</p> 7377</div> 7378<div class="paragraph"> 7379<p>When <strong>deploying</strong> a process definition with one or more message start events, the following considerations apply:</p> 7380</div> 7381<div class="ulist"> 7382<ul> 7383<li> 7384<p>The name of the message start event must be unique across a given process definition. A process definition must not have multiple message start events with the same name. Activiti throws an exception upon deployment of a process definition such that two or more message start events reference the same message of if two or more message start events reference messages with the same message name.</p> 7385</li> 7386<li> 7387<p>The name of the message start event must be unique across all deployed process definitions. Activiti throws an exception upon deployment of a process definition such that one or more message start events reference a message with the same name as a message start event already deployed by a different process definition.</p> 7388</li> 7389<li> 7390<p>Process versioning: Upon deployment of a new version of a process definition, the message subscriptions of the previous version are cancelled. This is also true for message events that are not present in the new version.</p> 7391</li> 7392</ul> 7393</div> 7394<div class="paragraph"> 7395<p>When <strong>starting</strong> a process instance, a message start event can be triggered using the following methods on the <code>RuntimeService</code>:</p> 7396</div> 7397<div class="listingblock"> 7398<div class="content"> 7399<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 74002 74013</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByMessage</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">);</span> 7402<span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByMessage</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">
7402processVariables</span><span class="tok-o">);</span> 7403<span class="tok-n">ProcessInstance</span> <span class="tok-nf">startProcessInstanceByMessage</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">messageName</span><span class="tok-o">,</span> <span class="tok-n">String</span> <span class="tok-n">businessKey</span><span class="tok-o">,</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o"><</span> <span class="tok-n">processVariables</span><span class="tok-o">);</span> 7404</td></tr></table></code></pre> 7405</div> 7406</div> 7407<div class="paragraph"> 7408<p>The <code>messageName</code> is the name given in the <code>name</code> attribute of the <code>message</code> element referenced by the <code>messageRef</code> attribute of the <code>messageEventDefinition</code>. The following considerations apply when <strong>starting</strong> a process instance:</p> 7409</div> 7410<div class="ulist"> 7411<ul> 7412<li> 7413<p>Message start events are only supported on top-level processes. Message start events are not supported on embedded sub processes.</p> 7414</li> 7415<li> 7416<p>If a process definition has multiple message start events, <code>runtimeService.startProcessInstanceByMessage(…​)</code> allows to select the appropriate start event.</p> 7417</li> 7418<li> 7419<p>If a process definition has multiple message start events and a single none start event, <code>runtimeService.startProcessInstanceByKey(…​)</code> and <code>runtimeService.startProcessInstanceById(…​)</code> starts a process instance using the none start event.</p> 7420</li> 7421<li> 7422<p>If a process definition has multiple message start events and no none start event, <code>runtimeService.startProcessInstanceByKey(…​)</code> and <code>runtimeService.startProcessInstanceById(…​)</code> throw an exception.</p> 7423</li> 7424<li> 7425<p>If a process definition has a single message start event, <code>runtimeService.startProcessInstanceByKey(…​)</code> and <code>runtimeService.startProcessInstanceById(…​)</code> start a new process instance using the message start event.</p> 7426</li> 7427<li> 7428<p>If a process is started from a call activity, message start event(s) are only supported if</p> 7429<div class="ulist"> 7430<ul> 7431<li> 7432<p>in addition to the message start event(s), the process has a single none start event</p> 7433</li> 7434<li> 7435<p>the process has a single message start event and no other start events.</p> 7436</li> 7437</ul> 7438</div> 7439</li> 7440</ul> 7441</div> 7442</div> 7443<div class="sect4"> 7444<h5 id="messageStartEventGraphicalNotation">Graphical notation</h5> 7445<div class="paragraph"> 7446<p>A message start event is visualized as a circle with a message event symbol. The symbol is unfilled, to visualize the catching (receiving) behavior.</p> 7447</div> 7448<div class="imageblock" style="text-align: center"> 7449<div class="content"> 7450<img src="images/bpmn.start.message.event.png" alt="bpmn.start.message.event"> 7451</div> 7452</div> 7453</div> 7454<div class="sect4"> 7455<h5 id="messageStartEventXml">XML representation</h5> 7456<div class="paragraph"> 7457<p>The XML representation of a message start event is the normal start event declaration with a messageEventDefinition child-element:</p> 7458</div> 7459<div class="listingblock"> 7460<div class="content"> 7461<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 7462 2 7463 3 7464 4 7465 5 7466 6 7467 7 7468 8 7469 9 747010 747111 747212 747313 747414 747515 747616 747717</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"definitions"</span> 7478 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 7479 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 7480 <span class="tok-na">targetNamespace=</span><span class="tok-s">"Examples"</span> 7481 <span class="tok-na">xmlns:tns=</span><span class="tok-s">"Examples"</span><span class="tok-nt">></span> 7482 7483 <span class="tok-nt"><message</span> <span class="tok-na">id=</span><span class="tok-s">"newInvoice"</span> <span class="tok-na">name=</span><span class="tok-s">"newInvoiceMessage"</span> <span class="tok-nt">/></span> 7484 7485 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"invoiceProcess"</span><span class="tok-nt">></span> 7486 7487 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"messageStart"</span> <span class="tok-nt">></span> 7488 <span class="tok-nt"><messageEventDefinition</span> <span class="tok-na">messageRef=</span><span class="tok-s">"tns:newInvoice"</span> <span class="tok-nt">/></span> 7489 <span class="tok-nt"></startEvent></span> 7490 ... 7491 <span class="tok-nt"></process></span> 7492 7493<span class="tok-nt"></definitions></span> 7494</td></tr></table></code></pre> 7495</div> 7496</div> 7497</div> 7498</div> 7499<div class="sect3"> 7500<h4 id="bpmnSignalStartEvent">8.2.10. Signal Start Event</h4> 7501<div class="sect4"> 7502<h5 id="bpmnSignalStartEventDescription">Description</h5> 7503<div class="paragraph"> 7504<p>A <a href="#bpmnSignalEventDefinition">signal</a> start event can be used to start a process instance using a named signal. The signal can be <em>fired</em> from within a process instance using the intermediary signal throw event or through the API (<em>runtimeService.signalEventReceivedXXX</em> methods). In both cases, all process definitions that have a signal start event with the same name will be started.</p> 7505</div> 7506<div class="paragraph"> 7507<p>Note that in both cases, it is also possible to choose between a synchronous and asynchronous starting of the process instances.</p> 7508</div> 7509<div class="paragraph"> 7510<p>The <code>signalName</code> that must be passed in the API is the name given in the <code>name</code> attribute of the <code>signal</code> element referenced by the <code>signalRef</code> attribute of the <code>signalEventDefinition</code>.</p> 7511</div> 7512</div> 7513<div class="sect4"> 7514<h5 id="signalStartEventGraphicalNotation">Graphical notation</h5> 7515<div class="paragraph"> 7516<p>A signal start event is visualized as a circle with a signal event symbol. The symbol is unfilled, to visualize the cat
7516ching (receiving) behavior.</p> 7517</div> 7518<div class="imageblock" style="text-align: center"> 7519<div class="content"> 7520<img src="images/bpmn.start.signal.event.png" alt="bpmn.start.signal.event"> 7521</div> 7522</div> 7523</div> 7524<div class="sect4"> 7525<h5 id="signalStartEventXml">XML representation</h5> 7526<div class="paragraph"> 7527<p>The XML representation of a signal start event is the normal start event declaration with a signalEventDefinition child-element:</p> 7528</div> 7529<div class="listingblock"> 7530<div class="content"> 7531<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 7532 2 7533 3 7534 4 7535 5 7536 6 7537 7 7538 8 7539 9 754010 754111</div></td><td class="code"><span></span><span class="tok-nt"><signal</span> <span class="tok-na">id=</span><span class="tok-s">"theSignal"</span> <span class="tok-na">name=</span><span class="tok-s">"The Signal"</span> <span class="tok-nt">/></span> 7542 7543<span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"processWithSignalStart1"</span><span class="tok-nt">></span> 7544 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span><span class="tok-nt">></span> 7545 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">id=</span><span class="tok-s">"theSignalEventDefinition"</span> <span class="tok-na">signalRef=</span><span class="tok-s">"theSignal"</span> <span class="tok-nt">/></span> 7546 <span class="tok-nt"></startEvent></span> 7547 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask"</span> <span class="tok-nt">/></span> 7548 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Task in process A"</span> <span class="tok-nt">/></span> 7549 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 7550 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 7551<span class="tok-nt"></process></span> 7552</td></tr></table></code></pre> 7553</div> 7554</div> 7555</div> 7556</div> 7557<div class="sect3"> 7558<h4 id="bpmnErrorStartEvent">8.2.11. Error Start Event</h4> 7559<div class="sect4"> 7560<h5 id="errorStartEventDescription">Description</h5> 7561<div class="paragraph"> 7562<p>An <a href="#bpmnErrorEventDefinition">error</a> start event can be used to trigger an Event Sub-Process. <strong>An error start event cannot be used for starting a process instance</strong>.</p> 7563</div> 7564<div class="paragraph"> 7565<p>An error start event is always interrupting.</p> 7566</div> 7567</div> 7568<div class="sect4"> 7569<h5 id="errorStartEventGraphicalNotation">Graphical notation</h5> 7570<div class="paragraph"> 7571<p>An error start event is visualized as a circle with an error event symbol. The symbol is unfilled, to visualize the catching (receiving) behavior.</p> 7572</div> 7573<div class="imageblock" style="text-align: center"> 7574<div class="content"> 7575<img src="images/bpmn.start.error.event.png" alt="bpmn.start.error.event"> 7576</div> 7577</div> 7578</div> 7579<div class="sect4"> 7580<h5 id="errorStartEventXml">XML representation</h5> 7581<div class="paragraph"> 7582<p>The XML representation of an error start event is the normal start event declaration with an errorEventDefinition child-element:</p> 7583</div> 7584<div class="listingblock"> 7585<div class="content"> 7586<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 75872 75883</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"messageStart"</span> <span class="tok-nt">></span> 7589 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"someError"</span> <span class="tok-nt">/></span> 7590<span class="tok-nt"></startEvent></span> 7591</td></tr></table></code></pre> 7592</div> 7593</div> 7594</div> 7595</div> 7596<div class="sect3"> 7597<h4 id="bpmnEndEvent">8.2.12. End Events</h4> 7598<div class="paragraph"> 7599<p>An end event signifies the end (of a path) of a (sub)process. An end event is <strong>always throwing</strong>. This means that when process execution arrives in the end event, a <em>result</em> is thrown. The type of result is depicted by the inner black icon of the event. In the XML representation, the type is given by the declaration of a sub-element.</p> 7600</div> 7601</div> 7602<div class="sect3"> 7603<h4 id="bpmnNoneEndEvent">8.2.13. None End Event</h4> 7604<div class="sect4"> 7605<h5 id="noneEndEventDescription">Description</h5> 7606<div class="paragraph"> 7607<p>A <em>none</em> end event means that the <em>result</em> thrown when the event is reached is unspecified. As such, the engine will not do anything extra besides ending the current path of execution.</p> 7608</div> 7609</div> 7610<div class="sect4"> 7611<h5 id="bpmnNoneEndEventDescription">Graphical notation</h5> 7612<div class="paragraph"> 7613<p>A none end event is visualized as a circle with a thick border with no inner icon (no result type).</p> 7614</div> 7615<div class="imageblock" style="text-align: center"> 7616<div class="content"> 7617<img src="images/bpmn.none.end.event.png" alt="bpmn.none.end.event"> 7618</div> 7619</div> 7620</div> 7621<div class="sect4"> 7622<h5 id="bpmnNoneStartEventXml">XML representation</h5> 7623<div class="paragraph"> 7624<p>The XML representation of a none end event is the normal end event declaration, without any sub-element (other end event types all have a sub-element declaring the type).</p> 7625</div> 7626<div class="listingblock"> 7627<div class="content"> 7628<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"end"</span> <span class="tok-na">name=</span><span class="tok-s">"my end event"</span> <span class="tok-nt">/></span> 7629</td></tr></table></code></pre> 7630</div> 7631</div> 7632</div> 7633</div> 7634<div class="sect3"> 7635<h4 id="bpmnErrorEndEvent">8.2.14. Error End Event</h4> 7636<div class="sect4"> 7637<h5 id="bpmnErrorEndEventDescription">Description</h5> 7638<div class="paragraph"> 7639<p>When process execution arrives in an <strong>error end event</strong>, the current path of execution is ended and an error is thrown. This error can <a href="#bpmnBoundaryErrorEvent">caught by a matching intermediate boundary error event</a>. In case no matching boundary error event is found, an exception will be thrown.</p> 7640</div> 7641</div> 7642<div class="sect4"> 7643<h5 id="bpmnErrorEndEventGraphicalNotation">Graphical notation</h5> 7644<div class="paragraph"> 7645<p>An error end event is visualized as a typical end event (circle with thick border), with the error icon inside. The error icon is completely black, to indicate the throwing semantics.</p> 7646</div> 7647<div class="imageblock" style="text-align: center"> 7648<div class="content"> 7649<img src="images/bpmn.error.end.event.png" alt="bpmn.error.end.event"> 7650</div> 7651</div> 7652</div> 7653<div class="sect4"> 7654<h5 id="bpmnErrorEndEventXml">XML representation</h5> 7655<div class="paragraph"> 7656<p>And error end event is represented as an end event, with an <em>errorEventDefinition</em> child element.</p> 7657</div> 7658<div class="listingblock"> 7659<div class="content"> 7660<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 76612 76623</div></td><td class="code"><span></span><span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myErrorEndEvent"</span><span class="tok-nt">></span> 7663 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"myError"</span> <span class="tok-nt">/></span> 7664<span class="tok-nt"></endEvent></span> 7665</td></tr></table></code></pre> 7666</div> 7667</div> 7668<div class="paragraph"> 7669<p>The <em>errorRef</em> attribute can reference an <em>error</em> element that is defined outside the process:</p> 7670</div> 7671<div class="listingblock"> 7672<div class="content"> 7673<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 76742 76753 76764</div></td><td class="code"><span></span><span class="tok-nt"><error</span> <span class="tok-na">id=</span><span class="tok-s">"myError"</span> <span class="tok-na">errorCode=</span><span class="tok-s">"123"</span> <span class="tok-nt">/></span> 7677... 7678<span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"myProcess"</span><span class="tok-nt">></span> 7679... 7680</td></tr></table></code></pre> 7681</div> 7682</div> 7683<div class="paragraph"> 7684<p>The <strong>errorCode</strong> of the <em>error</em> will be used to find the matching catching boundary error event. If the <em>errorRef</em> does not match any defined <em>error</em>, then the <em>errorRef</em> is used as a shortcut for the <em>errorCode</em>. This is an Activiti specific shortcut. More concretely, following snippets are equivalent in functionality.</p> 7685</div> 7686<div class="listingblock"> 7687<div class="content"> 7688<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 76892 76903 76914 76925 76936 76947 76958</div></td><td class="code"><span></span><span class="tok-nt"><error</span> <span class="tok-na">id=</span><span class="tok-s">"myError"</span> <span class="tok-na">errorCode=</span><span class="tok-s">"error123"</span> <span class="tok-nt">/></span> 7696... 7697<span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"myProcess"</span><span class="tok-nt">></span> 7698... 7699 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myErrorEndEvent"</span><span class="tok-nt">></span> 7700 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"myError"</span> <span class="tok-nt">/></span> 7701 <span class="tok-nt"></endEvent></span> 7702... 7703</td></tr></table></code></pre> 7704</div> 7705</div> 7706<div class="paragraph"> 7707<p>is equivalent with</p> 7708</div> 7709<div class="listingblock"> 7710<div class="content"> 7711<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 77122 77133</div></td><td class="code"><span></span><span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myErrorEndEvent"</span><span class="tok-nt">></span> 7714 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"error123"</span> <span class="tok-nt">/></span> 7715<span class="tok-nt"></endEvent></span> 7716</td></tr></table></code></pre> 7717</div> 7718</div> 7719<div class="paragraph"> 7720<p>Note that the <em>errorRef</em> must comply with the BPMN 2.0 schema, and must be a valid QName.</p> 7721</div> 7722</div> 7723</div> 7724<div class="sect3"> 7725<h4 id="bpmnCancelEndEvent">8.2.15. Terminate End Event</h4> 7726<div class="sect4"> 7727<h5 id="_description">Description</h5> 7728<div class="paragraph"> 7729<p>When a <em>terminate end event</em> is reached, the current process instance or sub-process will be terminated. Conceptually, when an execution arrives in a terminate end event, the first <em>scope</em> (process or sub-process) will be determined and ended. Note that in BPMN 2.0, a sub-process can be an embedded sub-process, call activity, event sub-process or transaction sub-process. This rule applies in general: when for example there is a multi-instance call activity or embedded subprocess, only that instance will be ended, the other instances and the process instance are not affected.</p> 7730</div> 7731<div class="paragraph"> 7732<p>There is an optional attribute <em>terminateAll</em> that can be added. When <em>true</em>, regardless of the placement of the terminate end event in the process definition and regardless of being in a sub-process (even nested), the (root) process instance will be terminated.</p> 7733</div> 7734</div> 7735<div class="sect4"> 7736<h5 id="_graphical_notation">Graphical notation</h5> 7737<div class="paragraph"> 7738<p>A cancel end event visualized as a typical end event (circle with thick outline), with a full black circle inside.</p> 7739</div> 7740<div class="imageblock" style="text-align: center"> 7741<div class="content"> 7742<img src="images/bpmn.terminate.end.event.png" alt="bpmn.terminate.end.event"> 7743</div> 7744</div> 7745</div> 7746<div class="sect4"> 7747<h5 id="_xml_representation">XML representation</h5> 7748<div class="paragraph"> 7749<p>A terminate end event is represented as an end event, with a <em>terminateEventDefinition</em> child element.</p> 7750</div> 7751<div class="paragraph"> 7752<p>Note that the <em>terminateAll</em>
7752 attribute is optional (and <em>false</em> by default).</p> 7753</div> 7754<div class="listingblock"> 7755<div class="content"> 7756<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 77572 77583</div></td><td class="code"><span></span><span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myEndEvent ></span> 7759<span class="tok-s"> <terminateEventDefinition activiti:terminateAll="</span><span class="tok-err">true"</span><span class="tok-nt">></terminateEventDefinition></span> 7760<span class="tok-nt"></endEvent></span> 7761</td></tr></table></code></pre> 7762</div> 7763</div> 7764</div> 7765</div> 7766<div class="sect3"> 7767<h4 id="_cancel_end_event">8.2.16. Cancel End Event</h4> 7768<div class="paragraph"> 7769<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnCancelEndEventDescription"></a></p> 7770</div> 7771<div class="sect4"> 7772<h5 id="_description_2">Description</h5> 7773<div class="paragraph"> 7774<p>The cancel end event can only be used in combination with a bpmn transaction subprocess. When the cancel end event is reached, a cancel event is thrown which must be caught by a cancel boundary event. The cancel boundary event then cancels the transaction and triggers compensation.</p> 7775</div> 7776</div> 7777<div class="sect4"> 7778<h5 id="bpmnCancelEndEventGraphicalNotation">Graphical notation</h5> 7779<div class="paragraph"> 7780<p>A cancel end event visualized as a typical end event (circle with thick outline), with the cancel icon inside. The cancel icon is completely black, to indicate the throwing semantics.</p> 7781</div> 7782<div class="imageblock" style="text-align: center"> 7783<div class="content"> 7784<img src="images/bpmn.cancel.end.event.png" alt="bpmn.cancel.end.event"> 7785</div> 7786</div> 7787</div> 7788<div class="sect4"> 7789<h5 id="bpmnCancelEndEventXml">XML representation</h5> 7790<div class="paragraph"> 7791<p>A cancel end event is represented as an end event, with a <em>cancelEventDefinition</em> child element.</p> 7792</div> 7793<div class="listingblock"> 7794<div class="content"> 7795<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 77962 77973</div></td><td class="code"><span></span><span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myCancelEndEvent"</span><span class="tok-nt">></span> 7798 <span class="tok-nt"><cancelEventDefinition</span> <span class="tok-nt">/></span> 7799<span class="tok-nt"></endEvent></span> 7800</td></tr></table></code></pre> 7801</div> 7802</div> 7803</div> 7804</div> 7805<div class="sect3"> 7806<h4 id="bpmnBoundaryEvent">8.2.17. Boundary Events</h4> 7807<div class="paragraph"> 7808<p>Boundary events are <em>catching</em> events that are attached to an activity (a boundary event can never be throwing). This means that while the activity is running, the event is <em>listening</em> for a certain type of trigger. When the event is <em>caught</em>, the activity is interrupted and the sequence flow going out of the event are followed.</p> 7809</div> 7810<div class="paragraph"> 7811<p>All boundary events are defined in the same way:</p> 7812</div> 7813<div class="listingblock"> 7814<div class="content"> 7815<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 78162 78173</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myBoundaryEvent"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"theActivity"</span><span class="tok-nt">></span> 7818 <span class="tok-nt"><XXXEventDefinition/></span> 7819<span class="tok-nt"></boundaryEvent></span> 7820</td></tr></table></code></pre> 7821</div> 7822</div> 7823<div class="paragraph"> 7824<p>A boundary event is defined with</p> 7825</div> 7826<div class="ulist"> 7827<ul> 7828<li> 7829<p>A unique identifier (process-wide)</p> 7830</li> 7831<li> 7832<p>A reference to the activity to which the event is attached through the <strong>attachedToRef</strong> attribute. 7833Note that a boundary event is defined on the same level as the activities to which they are attached (i.e. no inclusion of the boundary event inside the activity).</p> 7834</li> 7835<li> 7836<p>An XML sub-element of the form <em>XXXEventDefinition</em> (e.g. <em>
7836TimerEventDefinition</em>, <em>ErrorEventDefinition</em>, etc.) defining the type of the boundary event. See the specific boundary event types for more details.</p> 7837</li> 7838</ul> 7839</div> 7840</div> 7841<div class="sect3"> 7842<h4 id="bpmnTimerBoundaryEvent">8.2.18. Timer Boundary Event</h4> 7843<div class="sect4"> 7844<h5 id="timerBoundaryEventDescription">Description</h5> 7845<div class="paragraph"> 7846<p>A timer boundary event acts as a stopwatch and alarm clock. When an execution arrives in the activity where the boundary event is attached to, a timer is started. When the timer fires (e.g. after a specified interval), the activity is interrupted boundary event are followed.</p> 7847</div> 7848</div> 7849<div class="sect4"> 7850<h5 id="bpmnTimerBoundaryEventGraphicalNotation">Graphical Notation</h5> 7851<div class="paragraph"> 7852<p>A timer boundary event is visualized as a typical boundary event (i.e. circle on the border), with the timer icon on the inside.</p> 7853</div> 7854<div class="imageblock" style="text-align: center"> 7855<div class="content"> 7856<img src="images/bpmn.boundary.timer.event.png" alt="bpmn.boundary.timer.event"> 7857</div> 7858</div> 7859</div> 7860<div class="sect4"> 7861<h5 id="bpmnTimerBoundaryEventXml">XML Representation</h5> 7862<div class="paragraph"> 7863<p>A timer boundary event is defined as a <a href="#bpmnBoundaryEvent">regular boundary event</a>. The specific type sub-element is in this case a <strong>timerEventDefinition</strong> element.</p> 7864</div> 7865<div class="listingblock"> 7866<div class="content"> 7867<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 78682 78693 78704 78715</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"escalationTimer"</span> <span class="tok-na">cancelActivity=</span><span class="tok-s">"true"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"firstLineSupport"</span><span class="tok-nt">></span> 7872 <span class="tok-nt"><timerEventDefinition></span> 7873 <span class="tok-nt"><timeDuration></span>PT4H<span class="tok-nt"></timeDuration></span> 7874 <span class="tok-nt"></timerEventDefinition></span> 7875<span class="tok-nt"></boundaryEvent></span> 7876</td></tr></table></code></pre> 7877</div> 7878</div> 7879<div class="paragraph"> 7880<p>Please refer to <a href="#timerEventDefinitions">timer event definition</a> for details on timer configuration.</p> 7881</div> 7882<div class="paragraph"> 7883<p>In the graphical representation, the line of the circle is dotted as you can see in this example above:</p> 7884</div> 7885<div class="imageblock" style="text-align: center"> 7886<div class="content"> 7887<img src="images/bpmn.non.interrupting.boundary.timer.event.png" alt="bpmn.non.interrupting.boundary.timer.event"> 7888</div> 7889</div> 7890<div class="paragraph"> 7891<p>A typical use case is sending an escalation email additionally but not interrupt the normal process flow.</p> 7892</div> 7893<div class="paragraph"> 7894<p>Since BPMN 2.0 there is the difference between the interrupting and non interrupting timer event. The interrupting is the default. The non-interrupting leads to the original activity is <strong>not</strong> interrupted but the activity stays there. Instead an additional executions is created and send over the outgoing transition of the event. In the XML representation, the <em>cancelActivity</em> attribute is set to false:</p> 7895</div> 7896<div class="listingblock"> 7897<div class="content"> 7898<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"escalationTimer"</span> <span class="tok-na">cancelActivity=</span><span class="tok-s">"false"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"firstLineSupport"</span><span class="tok-nt">/></span> 7899</td></tr></table></code></pre> 7900</div> 7901</div> 7902<div class="paragraph"> 7903<p><strong>Note:</strong> boundary timer events are only fired when the job or async executor is enabled (i.e. <em>jobExecutorActivate</em> or <em>asyncExecutorActivate</em> needs to be set to <code>true</code> in the <code>activiti.cfg.xml</code>, since the job and async executor are disabled by default).</p> 7904</div> 7905</div> 7906<div class="sect4"> 7907<h5 id="bpmnKnownIssueBoundaryEvent">Known issue with boundary events</h5> 7908<div class="paragraph"> 7909<p>There is a known issue regarding concurrency when using boundary events of any type. Currently, it is not possible to have multiple outgoing sequence flow attached to a boundary event (see issue <a href="https://activiti.atlassian.net/browse/ACT-47">ACT-47</a>). A solution to this problem is to use one outgoing sequence flow that goes to a parallel gateway.</p> 7910</div> 7911<div class="imageblock" style="text-align: center"> 7912<div class="content"> 7913<img src="images/bpmn.known.issue.boundary.event.png" alt="bpmn.known.issue.boundary.event"> 7914</div> 7915</div> 7916</div> 7917</div> 7918<div class="sect3"> 7919<h4 id="bpmnBoundaryErrorEvent">8.2.19. Error Boundary Event</h4> 7920<div class="sect4"> 7921<h5 id="bpmnBoundaryErrorEventDescription">Description</h5> 7922<div class="paragraph"> 7923<p>An intermediate <em>catching</em> error on the boundary of an activity, or <strong>boundary error event</strong> for short, catches errors that are thrown within the scope of the activity on which it is defined.</p> 7924</div> 7925<div class="paragraph"> 7926<p>Defining a boundary error event makes most sense on an <a href="#bpmnSubProcess">embedded subprocess</a>, or a <a href="#bpmnCallActivity">call activity</a>, as a subprocess creates a scope for all activities inside the subprocess. Errors are thrown by <a href="#bpmnErrorEndEvent">error end events</a>. Such an error will propagate its parent scopes upwards until a scope is found on which a boun
7926dary error event is defined that matches the error event definition.</p> 7927</div> 7928<div class="paragraph"> 7929<p>When an error event is caught, the activity on which the boundary event is defined is destroyed, also destroying all current executions within (e.g. concurrent activities, nested subprocesses, etc.). Process execution continues following the outgoing sequence flow of the boundary event.</p> 7930</div> 7931</div> 7932<div class="sect4"> 7933<h5 id="bpmnBoundaryErrorEventgraphicalNotation">Graphical notation</h5> 7934<div class="paragraph"> 7935<p>A boundary error event is visualized as a typical intermediate event (circle with smaller circle inside) on the boundary, with the error icon inside. The error icon is white, to indicate the <em>catch</em> semantics.</p> 7936</div> 7937<div class="imageblock" style="text-align: center"> 7938<div class="content"> 7939<img src="images/bpmn.boundary.error.event.png" alt="bpmn.boundary.error.event"> 7940</div> 7941</div> 7942</div> 7943<div class="sect4"> 7944<h5 id="bpmnBoundaryErrorEventXml">Xml representation</h5> 7945<div class="paragraph"> 7946<p>A boundary error event is defined as a typical <a href="#bpmnBoundaryEvent">boundary event</a>:</p> 7947</div> 7948<div class="listingblock"> 7949<div class="content"> 7950<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 79512 79523</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"catchError"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"mySubProcess"</span><span class="tok-nt">></span> 7953 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"myError"</span><span class="tok-nt">/></span> 7954<span class="tok-nt"></boundaryEvent></span> 7955</td></tr></table></code></pre> 7956</div> 7957</div> 7958<div class="paragraph"> 7959<p>As with the <a href="#bpmnErrorEndEvent">error end event</a>, the <em>errorRef</em> references an error defined outside the process element:</p> 7960</div> 7961<div class="listingblock"> 7962<div class="content"> 7963<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 79642 79653 79664</div></td><td class="code"><span></span><span class="tok-nt"><error</span> <span class="tok-na">id=</span><span class="tok-s">"myError"</span> <span class="tok-na">errorCode=</span><span class="tok-s">"123"</span> <span class="tok-nt">/></span> 7967... 7968<span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"myProcess"</span><span class="tok-nt">></span> 7969... 7970</td></tr></table></code></pre> 7971</div> 7972</div> 7973<div class="paragraph"> 7974<p>The <strong>errorCode</strong> is used to match the errors that are caught:</p> 7975</div> 7976<div class="ulist"> 7977<ul> 7978<li> 7979<p>If <em>errorRef</em> is omitted, the boundary error event will catch <strong>any error event</strong>, regardless of the errorCode of the <em>error</em>.</p> 7980</li> 7981<li> 7982<p>In case an <em>errorRef</em> is provided and it references an existing <em>error</em>, the boundary event will <strong>only catch errors with the same error code</strong>.</p> 7983</li> 7984<li> 7985<p>In case an <em>errorRef</em> is provided, but no <em>error</em> is defined in the BPMN 2.0 file, then the <strong>errorRef is used as errorCode</strong> (similar for with error end events).</p> 7986</li> 7987</ul> 7988</div> 7989</div> 7990<div class="sect4"> 7991<h5 id="bpmnBoundaryErrorEventExample">Example</h5> 7992<div class="paragraph"> 7993<p>Following example process shows how an error end event can be used. When the <em>'Review profitability'</em> user task is completed by stating that not enough information is provided, an error is thrown. When this error is caught on the boundary of the subprocess, all active activities within the <em>'Review sales lead'</em> subprocess are destroyed (even if <em>'Review customer rating'</em> was not yet completed), and the <em>'Provide additional details'</em> user task is created.</p> 7994</div> 7995<div class="imageblock" style="text-align: center"> 7996<div class="content"> 7997<img src="images/bpmn.boundary.error.example.png" alt="bpmn.boundary.error.example"> 7998</div> 7999</div> 8000<div class="paragraph"> 8001<p>This process is shipped as example in the demo setup. The process XML and unit test can be found in the <em>org.activiti.examples.bpmn.event.error</em> package.</p> 8002</div> 8003</div> 8004</div> 8005<div class="sect3"> 8006<h4 id="bpmnBoundarySignalEvent">8.2.20. Signal Boundary Event</h4> 8007<div class="sect4"> 8008<h5 id="bpmnBoundarySignalEventDescription">Description</h5> 8009<div class="paragraph"> 8010<p>An attached intermediate <em>catching</em> <a href="#bpmnSignalEventDefinition">signal</a> on the boundary of an activity, or <strong>boundary signal event</strong> for short, catches signals with the same signal name as the referenced signal definition.</p> 8011</div> 8012<div class="paragraph"> 8013<p><strong>Note:</strong> contrary to other events like the boundary error event, a boundary signal event does not only catch signal events thrown from the scope it is attached to. On the contrary, a signal event has global scope (broadcast semantics) meaning that the signal can be thrown from any place, even from a different process instance.</p> 8014</div> 8015<div class="paragraph"> 8016<p><strong>Note:</strong> contrary to other events like an error event, a signal is not consumed
8016if it is caught. If you have two active signal boundary events catching the same signal event, both boundary events are triggered, even if they are part of different process instances.</p> 8017</div> 8018</div> 8019<div class="sect4"> 8020<h5 id="bpmnBoundarySignalEventGraphicalNotation">Graphical notation</h5> 8021<div class="paragraph"> 8022<p>A boundary signal event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the signal icon inside. The signal icon is white (unfilled), to indicate the <em>catch</em> semantics.</p> 8023</div> 8024<div class="imageblock" style="text-align: center"> 8025<div class="content"> 8026<img src="images/bpmn.boundary.signal.event.png" alt="bpmn.boundary.signal.event"> 8027</div> 8028</div> 8029</div> 8030<div class="sect4"> 8031<h5 id="bpmnBoundarySignalEventXml">XML representation</h5> 8032<div class="paragraph"> 8033<p>A boundary signal event is defined as a typical <a href="#bpmnBoundaryEvent">boundary event</a>:</p> 8034</div> 8035<div class="listingblock"> 8036<div class="content"> 8037<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 80382 80393</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"boundary"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"task"</span> <span class="tok-na">cancelActivity=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 8040 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">signalRef=</span><span class="tok-s">"alertSignal"</span><span class="tok-nt">/></span> 8041<span class="tok-nt"></boundaryEvent></span> 8042</td></tr></table></code></pre> 8043</div> 8044</div> 8045</div> 8046<div class="sect4"> 8047<h5 id="bpmnBoundarySignalEventExample">Example</h5> 8048<div class="paragraph"> 8049<p>See section on <a href="#bpmnSignalEventDefinition">signal event definitions</a>.</p> 8050</div> 8051</div> 8052</div> 8053<div class="sect3"> 8054<h4 id="bpmnBoundaryMessageEvent">8.2.21. Message Boundary Event</h4> 8055<div class="sect4"> 8056<h5 id="bpmnBoundaryMessageEventDescription">Description</h5> 8057<div class="paragraph"> 8058<p>An attached intermediate <em>catching</em> <a href="#bpmnMessageEventDefinition">message</a> on the boundary of an activity, or <strong>boundary message event</strong> for short, catches messages with the same message name as the referenced message definition.</p> 8059</div> 8060</div> 8061<div class="sect4"> 8062<h5 id="bpmnBoundaryMessageEventGraphicalNotation">Graphical notation</h5> 8063<div class="paragraph"> 8064<p>A boundary message event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the message icon inside. The message icon is white (unfilled), to indicate the <em>catch</em> semantics.</p> 8065</div> 8066<div class="imageblock" style="text-align: center"> 8067<div class="content"> 8068<img src="images/bpmn.boundary.message.event.png" alt="bpmn.boundary.message.event"> 8069</div> 8070</div> 8071<div class="paragraph"> 8072<p>Note that boundary message event can be both interrupting (right hand side) and non-interrupting (left hand side).</p> 8073</div> 8074</div> 8075<div class="sect4"> 8076<h5 id="bpmnBoundaryMessageEventXml">XML representation</h5> 8077<div class="paragraph"> 8078<p>A boundary message event is defined as a typical <a href="#bpmnBoundaryEvent">boundary event</a>:</p> 8079</div> 8080<div class="listingblock"> 8081<div class="content"> 8082<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 80832 80843</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"boundary"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"task"</span> <span class="tok-na">cancelActivity=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 8085 <span class="tok-nt"><messageEventDefinition</span> <span class="tok-na">messageRef=</span><span class="tok-s">"newCustomerMessage"</span><span class="tok-nt">/></span> 8086<span class="tok-nt"></boundaryEvent></span> 8087</td></tr></table></code></pre> 8088</div> 8089</div> 8090</div> 8091<div class="sect4"> 8092<h5 id="bpmnBoundaryMessageEventExample">Example</h5> 8093<div class="paragraph"> 8094<p>See section on <a href="#bpmnMessageEventDefinition">message event definitions</a>.</p> 8095</div> 8096</div> 8097</div> 8098<div class="sect3"> 8099<h4 id="bpmnBoundaryCancelEvent">8.2.22. Cancel Boundary Event</h4> 8100<div class="paragraph"> 8101<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnBoundaryCancelEventDescription"></a></p> 8102</div> 8103<div class="sect4"> 8104<h5 id="_description_3">Description</h5> 8105<div class="paragraph"> 8106<p>An attached intermediate <em>catching</em> cancel on the boundary of a transaction subprocess, or <strong>boundary cancel event</strong> for short, is triggered when a transaction is cancelled. When the cancel boundary event is triggered, it first interrupts all executions active in the current scope. Next, it starts compensation of all active compensation boundary events in the scope of the transaction. Compensation is performed synchronously, i.e. the boundary event waits before compensation is completed before leaving the transaction. When compensation is completed, the transaction subprocess is left using the sequence flow(s) running out of the cancel boundary event.</p> 8107</div> 8108<div class="paragraph"> 8109<p><strong>Note:</strong> Only a single cancel boundary event is allowed for a transaction subprocess.</p> 8110</div> 8111<div class="paragraph"> 8112<p><strong>Note:</strong> If the transaction subprocess hosts nested subprocesses, compensation is only triggered for subprocesses that have completed successfully.</p> 8113</div> 8114<div class="paragraph"> 8115<p><strong>Note:</strong> If a cancel boundary event is placed on a transaction subprocess with multi instance characteristics, if one instance triggers cancellation, the boundary event cancels all instances.</p> 8116</div> 8117</div> 8118<div class="sect4"> 8119<h5 id="bpmnBoundaryCancelEventGraphicalNotation">Graphical notation</h5> 8120<div class="paragraph"> 8121<p>A cancel boundary event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the cancel icon inside. The cancel icon is white (unfilled), to indicate the <em>catching</em> semantics.</p> 8122</div> 8123<div class="imageblock" style="text-align: center"> 8124<div class="content"> 8125<img src="images/bpmn.boundary.cancel.event.png" alt="bpmn.boundary.cancel.event"> 8126</div> 8127</div> 8128</div> 8129<div class="sect4"> 8130<h5 id="bpmnBoundarySignalEventXml">XML representation</h5> 8131<div class="paragraph"> 8132<p>A cancel boundary event is defined as a typical <a href="#bpmnBoundaryEvent">boundary event</a>:</p> 8133</div> 8134<div class="listingblock"> 8135<div class="content"> 8136<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 81372 81383</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"boundary"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"transaction"</span> <span class="tok-nt">></span>
8139 <span class="tok-nt"><cancelEventDefinition</span> <span class="tok-nt">/></span> 8140<span class="tok-nt"></boundaryEvent></span> 8141</td></tr></table></code></pre> 8142</div> 8143</div> 8144<div class="paragraph"> 8145<p>Since the cancel boundary event is always interrupting, the <code>cancelActivity</code> attribute is not required.</p> 8146</div> 8147</div> 8148</div> 8149<div class="sect3"> 8150<h4 id="bpmnBoundaryCompensationEvent">8.2.23. Compensation Boundary Event</h4> 8151<div class="paragraph"> 8152<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnBoundaryCompensationEventDescription"></a></p> 8153</div> 8154<div class="sect4"> 8155<h5 id="_description_4">Description</h5> 8156<div class="paragraph"> 8157<p>An attached intermediate <em>catching</em> compensation on the boundary of an activity or <strong>compensation boundary event</strong> for short, can be used to attach a compensation handler to an activity.</p> 8158</div> 8159<div class="paragraph"> 8160<p>The compensation boundary event must reference a single compensation handler using a directed association.</p> 8161</div> 8162<div class="paragraph"> 8163<p>A compensation boundary event has a different activation policy from other boundary events. Other boundary events like for instance the signal boundary event are activated when the activity they are attached to is started. When the activity is left, they are deactivated and the corresponding event subscription is cancelled. The compensation boundary event is different. The compensation boundary event is activated when the activity it is attached to <strong>completes successfully</strong>. At this point, the corresponding subscription to the compensation events is created. The subscription is removed either when a compensation event is triggered or when the corresponding process instance ends. From this, it follows:</p> 8164</div> 8165<div class="ulist"> 8166<ul> 8167<li> 8168<p>When compensation is triggered, the compensation handler associated with the compensation boundary event is invoked the same number of times the activity it is attached to completed successfully.</p> 8169</li> 8170<li> 8171<p>If a compensation boundary event is attached to an activity with multiple instance characteristics, a compensation event subscription is created for each instance.</p> 8172</li> 8173<li> 8174<p>If a compensation boundary event is attached to an activity which is contained inside a loop, a compensation event subscription is created for each time the activity is executed.</p> 8175</li> 8176<li> 8177<p>If the process instance ends, the subscriptions to compensation events are cancelled.</p> 8178</li> 8179</ul> 8180</div> 8181<div class="paragraph"> 8182<p><strong>Note:</strong> the compensation boundary event is not supported on embedded subprocesses.</p> 8183</div> 8184</div> 8185<div class="sect4"> 8186<h5 id="bpmnBoundaryCompensationEventGraphicalNotation">Graphical notation</h5> 8187<div class="paragraph"> 8188<p>A compensation boundary event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the compensation icon inside. The compensation icon is white (unfilled), to indicate the <em>catching</em> semantics. In addition to a compensation boundary event, the following figure shows a compensation handler associated with the boundary event using a unidirectional association:</p> 8189</div> 8190<div class="imageblock" style="text-align: center"> 8191<div class="content"> 8192<img src="images/bpmn.boundary.compensation.event.png" alt="bpmn.boundary.compensation.event"> 8193</div> 8194</div> 8195</div> 8196<div class="sect4"> 8197<h5 id="bpmnBoundaryCompensationEventXml">XML representation</h5> 8198<div class="paragraph"> 8199<p>A compensation boundary event is defined as a typical <a href="#bpmnBoundaryEvent">boundary event</a>:</p> 8200</div> 8201<div class="listingblock"> 8202<div class="content"> 8203<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 82042 82053 82064 82075 82086 82097</div></td><td class="code"><span></span><span class="tok-nt"><boundaryEvent</span> <span class="tok-na">id=</span><span class="tok-s">"compensateBookHotelEvt"</span> <span class="tok-na">attachedToRef=</span><span class="tok-s">"bookHotel"</span> <span class="tok-nt">></span>
8210 <span class="tok-nt"><compensateEventDefinition</span> <span class="tok-nt">/></span> 8211<span class="tok-nt"></boundaryEvent></span> 8212 8213<span class="tok-nt"><association</span> <span class="tok-na">associationDirection=</span><span class="tok-s">"One"</span> <span class="tok-na">id=</span><span class="tok-s">"a1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"compensateBookHotelEvt"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"undoBookHotel"</span> <span class="tok-nt">/></span> 8214 8215<span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"undoBookHotel"</span> <span class="tok-na">isForCompensation=</span><span class="tok-s">"true"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"..."</span> <span class="tok-nt">/></span> 8216</td></tr></table></code></pre> 8217</div> 8218</div> 8219<div class="paragraph"> 8220<p>Since the compensation boundary event is activated after the activity has completed successfully, the <code>cancelActivity</code> attribute is not supported.</p> 8221</div> 8222</div> 8223</div> 8224<div class="sect3"> 8225<h4 id="bpmnIntermediateCatchingEvent">8.2.24. Intermediate Catching Events</h4> 8226<div class="paragraph"> 8227<p>All intermediate catching events are defined in the same way:</p> 8228</div> 8229<div class="listingblock"> 8230<div class="content"> 8231<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 82322 82333</div></td><td class="code"><span></span><span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myIntermediateCatchEvent"</span> <span class="tok-nt">></span> 8234 <span class="tok-nt"><XXXEventDefinition/></span> 8235<span class="tok-nt"></intermediateCatchEvent></span> 8236</td></tr></table></code></pre> 8237</div> 8238</div> 8239<div class="paragraph"> 8240<p>An intermediate catching event is defined with</p> 8241</div> 8242<div class="ulist"> 8243<ul> 8244<li> 8245<p>A unique identifier (process-wide)</p> 8246</li> 8247<li> 8248<p>An XML sub-element of the form <em>XXXEventDefinition</em> (e.g. <em>TimerEventDefinition</em>, etc.) defining the type of the intermediate catching event. See the specific catching event types for more details.</p> 8249</li> 8250</ul> 8251</div> 8252</div> 8253<div class="sect3"> 8254<h4 id="bpmnTimerIntermediateEvent">8.2.25. Timer Intermediate Catching Event</h4> 8255<div class="sect4"> 8256<h5 id="bpmnTimerIntermediateEventDescription">Description</h5> 8257<div class="paragraph"> 8258<p>A timer intermediate event acts as a stopwatch. When an execution arrives in catching event activity, a timer is started. When the timer fires (e.g. after a specified interval), the sequence flow going out of the timer intermediate event is followed.</p> 8259</div> 8260</div> 8261<div class="sect4"> 8262<h5 id="bpmnTimerIntermediateEventGraphicalNotation">Graphical Notation</h5> 8263<div class="paragraph"> 8264<p>A timer intermediate event is visualized as an intermediate catching event, with the timer icon on the inside.</p> 8265</div> 8266<div class="imageblock" style="text-align: center"> 8267<div class="content"> 8268<img src="images/bpmn.intermediate.timer.event.png" alt="bpmn.intermediate.timer.event"> 8269</div> 8270</div> 8271</div> 8272<div class="sect4"> 8273<h5 id="bpmnTimerIntermediateEventXml">XML Representation</h5> 8274<div class="paragraph"> 8275<p>A timer intermediate event is defined as an <a href="#bpmnIntermediateCatchingEvent">intermediate catching event</a>. The specific type sub-element is in this case a <strong>timerEventDefinition</strong> element.</p> 8276</div> 8277<div class="listingblock"> 8278<div class="content"> 8279<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 82802 82813 82824 82835</div></td><td class="code"><span></span><span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"timer"</span><span class="tok-nt">></span> 8284 <span class="tok-nt"><timerEventDefinition></span> 8285 <span class="tok-nt"><timeDuration></span>PT5M<span class="tok-nt"></timeDuration></span> 8286 <span class="tok-nt"></timerEventDefinition></span> 8287<span class="tok-nt"></intermediateCatchEvent></span> 8288</td></tr></table></code></pre> 8289</div> 8290</div> 8291<div class="paragraph"> 8292<p>See <a href="#timerEventDefinitions">timer event definitions</a> for configuration details.</p> 8293</div> 8294</div> 8295</div> 8296<div class="sect3"> 8297<h4 id="bpmnIntermediateSignalEvent">8.2.26. Signal Intermediate Catching Event</h4> 8298<div class="sect4"> 8299<h5 id="bpmnIntermediateSignalEventDescription">Description</h5> 8300<div class="paragraph"> 8301<p>An intermediate <em>catching</em> <a href="#bpmnSignalEventDefinition">signal</a> event catches signals with the same signal name as the referenced signal definition.</p> 8302</div> 8303<div class="paragraph"> 8304<p><strong>Note:</strong> contrary to other events like an error event, a signal is not consumed
8304if it is caught. If you have two active signal boundary events catching the same signal event, both boundary events are triggered, even if they are part of different process instances.</p> 8305</div> 8306</div> 8307<div class="sect4"> 8308<h5 id="bpmnIntermediateSignalEventGraphicalNotation">Graphical notation</h5> 8309<div class="paragraph"> 8310<p>An intermediate signal catch event is visualized as a typical intermediate event (Circle with smaller circle inside), with the signal icon inside. The signal icon is white (unfilled), to indicate the <em>catch</em> semantics.</p> 8311</div> 8312<div class="imageblock" style="text-align: center"> 8313<div class="content"> 8314<img src="images/bpmn.intermediate.signal.catch.event.png" alt="bpmn.intermediate.signal.catch.event"> 8315</div> 8316</div> 8317</div> 8318<div class="sect4"> 8319<h5 id="bpmnIntermediateSignalEventXml">XML representation</h5> 8320<div class="paragraph"> 8321<p>A signal intermediate event is defined as an <a href="#bpmnIntermediateCatchingEvent">intermediate catching event</a>. The specific type sub-element is in this case a <strong>signalEventDefinition</strong> element.</p> 8322</div> 8323<div class="listingblock"> 8324<div class="content"> 8325<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 83262 83273</div></td><td class="code"><span></span><span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"signal"</span><span class="tok-nt">></span> 8328 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">signalRef=</span><span class="tok-s">"newCustomerSignal"</span> <span class="tok-nt">/></span> 8329<span class="tok-nt"></intermediateCatchEvent></span> 8330</td></tr></table></code></pre> 8331</div> 8332</div> 8333</div> 8334<div class="sect4"> 8335<h5 id="bpmnIntermediateSignalEventExample">Example</h5> 8336<div class="paragraph"> 8337<p>See section on <a href="#bpmnSignalEventDefinition">signal event definitions</a>.</p> 8338</div> 8339</div> 8340</div> 8341<div class="sect3"> 8342<h4 id="bpmnIntermediateMessageEvent">8.2.27. Message Intermediate Catching Event</h4> 8343<div class="sect4"> 8344<h5 id="bpmnIntermediateMessageEventDescription">Description</h5> 8345<div class="paragraph"> 8346<p>An intermediate <em>catching</em> <a href="#bpmnMessageEventDefinition">message</a> event catches messages with a specified name.</p> 8347</div> 8348</div> 8349<div class="sect4"> 8350<h5 id="bpmnIntermediateMessageEventGraphicalNotation">Graphical notation</h5> 8351<div class="paragraph"> 8352<p>An intermediate catching message event is visualized as a typical intermediate event (Circle with smaller circle inside), with the message icon inside. The message icon is white (unfilled), to indicate the <em>catch</em> semantics.</p> 8353</div> 8354<div class="imageblock" style="text-align: center"> 8355<div class="content"> 8356<img src="images/bpmn.intermediate.message.catch.event.png" alt="bpmn.intermediate.message.catch.event"> 8357</div> 8358</div> 8359</div> 8360<div class="sect4"> 8361<h5 id="bpmnIntermediateSignalEventXml">XML representation</h5> 8362<div class="paragraph"> 8363<p>A message intermediate event is defined as an <a href="#bpmnIntermediateCatchingEvent">intermediate catching event</a>. The specific type sub-element is in this case a <strong>messageEventDefinition</strong> element.</p> 8364</div> 8365<div class="listingblock"> 8366<div class="content"> 8367<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 83682 83693</div></td><td class="code"><span></span><span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"message"</span><span class="tok-nt">></span> 8370 <span class="tok-nt"><messageEventDefinition</span> <span class="tok-na">signalRef=</span><span class="tok-s">"newCustomerMessage"</span> <span class="tok-nt">/></span> 8371<span class="tok-nt"></intermediateCatchEvent></span> 8372</td></tr></table></code></pre> 8373</div> 8374</div> 8375</div> 8376<div class="sect4"> 8377<h5 id="bpmnIntermediateMessageEventExample">Example</h5> 8378<div class="paragraph"> 8379<p>See section on <a href="#bpmnMessageEventDefinition">message event definitions</a>.</p> 8380</div> 8381</div> 8382</div> 8383<div class="sect3"> 8384<h4 id="bpmnIntermediateThrowEvent">8.2.28. Intermediate Throwing Event</h4> 8385<div class="paragraph"> 8386<p>All intermediate throwing events are defined in the same way:</p> 8387</div> 8388<div class="listingblock"> 8389<div class="content"> 8390<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 83912 83923</div></td><td class="code"><span></span><span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"myIntermediateThrowEvent"</span> <span class="tok-nt">></span>
8393 <span class="tok-nt"><XXXEventDefinition/></span> 8394<span class="tok-nt"></intermediateThrowEvent></span> 8395</td></tr></table></code></pre> 8396</div> 8397</div> 8398<div class="paragraph"> 8399<p>An intermediate throwing event is defined with</p> 8400</div> 8401<div class="ulist"> 8402<ul> 8403<li> 8404<p>A unique identifier (process-wide)</p> 8405</li> 8406<li> 8407<p>An XML sub-element of the form <em>XXXEventDefinition</em> (e.g. <em>signalEventDefinition</em>, etc.) defining the type of the intermediate throwing event. See the specific throwing event types for more details.</p> 8408</li> 8409</ul> 8410</div> 8411</div> 8412<div class="sect3"> 8413<h4 id="bpmnIntermediateThrowNoneEvent">8.2.29. Intermediate Throwing None Event</h4> 8414<div class="paragraph"> 8415<p>The following process diagram shows a simple example of an intermediate none event, which is often used to indicate some state achieved in the process.</p> 8416</div> 8417<div class="imageblock" style="text-align: center"> 8418<div class="content"> 8419<img src="images/bpmn.intermediate.none.event.png" alt="bpmn.intermediate.none.event"> 8420</div> 8421</div> 8422<div class="paragraph"> 8423<p>This can be a good hook to monitor some KPI’s, basically by adding an <a href="#executionListeners">execution listener</a>.</p> 8424</div> 8425<div class="listingblock"> 8426<div class="content"> 8427<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 84282 84293 84304 84315</div></td><td class="code"><span></span><span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"noneEvent"</span><span class="tok-nt">></span> 8432 <span class="tok-nt"><extensionElements></span> 8433 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.test.bpmn.event.IntermediateNoneEventTest$MyExecutionListener"</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span> <span class="tok-nt">/></span> 8434 <span class="tok-nt"></extensionElements></span> 8435<span class="tok-nt"></intermediateThrowEvent></span> 8436</td></tr></table></code></pre> 8437</div> 8438</div> 8439<div class="paragraph"> 8440<p>There you can add some own code to maybe send some event to your BAM tool or DWH. The engine itself doesn’t do anything in that event, it just passes through.</p> 8441</div> 8442</div> 8443<div class="sect3"> 8444<h4 id="bpmnIntermediateThrowSignalEvent">8.2.30. Signal Intermediate Throwing Event</h4> 8445<div class="sect4"> 8446<h5 id="bpmnIntermediateThrowSignalEventDescription">Description</h5> 8447<div class="paragraph"> 8448<p>An intermediate <em>throwing</em> <a href="#bpmnSignalEventDefinition">signal</a> event throws a signal event for a defined signal.</p> 8449</div> 8450<div class="paragraph"> 8451<p>In Activiti, the signal is broadcast to all active handlers (i.e. all catching signal events). Signals can be published synchronous or asynchronous.</p> 8452</div> 8453<div class="ulist"> 8454<ul> 8455<li> 8456<p>In the default configuration, the signal is delivered <strong>synchronously</strong>. This means that the throwing process instance waits until the signal is delivered to all catching process instances. The catching process instances are also notified in the same transaction as the throwing process instance, which means that if one of the notified instances produces a technical error (throws an exception), all involved instances fail.</p> 8457</li> 8458<li> 8459<p>A signal can also be delivered <strong>asynchronously</strong>. In that case it is determined which handlers are active at the time the throwing signal event is reached. For each active handler, an asynchronous notification message (Job) is stored and delivered by the JobExecutor.</p> 8460</li> 8461</ul> 8462</div> 8463</div> 8464<div class="sect4"> 8465<h5 id="bpmnIntermediateThrowSignalEventGraphicalNotation">Graphical notation</h5> 8466<div class="paragraph"> 8467<p>An intermediate signal throw event is visualized as a typical intermediate event (Circle with smaller circle inside), with the signal icon inside. The signal icon is black (filled), to indicate the <em>throw</em> semantics.</p> 8468</div> 8469<div class="imageblock" style="text-align: center"> 8470<div class="content"> 8471<img src="images/bpmn.intermediate.signal.throw.event.png" alt="bpmn.intermediate.signal.throw.event"> 8472</div> 8473</div> 8474</div> 8475<div class="sect4"> 8476<h5 id="bpmnIntermediateThrowSignalEventXml">XML representation</h5> 8477<div class="paragraph"> 8478<p>A signal intermediate event is defined as an <a href="#bpmnIntermediateThrowEvent">intermediate throwing event</a>. The specific type sub-element is in this case a <strong>signalEventDefinition</strong> element.</p> 8479</div> 8480<div class="listingblock"> 8481<div class="content"> 8482<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 84832 84843</div></td><td class="code"><span></span><span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"signal"</span><span class="tok-nt">></span> 8485 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">
8485signalRef=</span><span class="tok-s">"newCustomerSignal"</span> <span class="tok-nt">/></span> 8486<span class="tok-nt"></intermediateThrowEvent></span> 8487</td></tr></table></code></pre> 8488</div> 8489</div> 8490<div class="paragraph"> 8491<p>An asynchronous signal event would look like this:</p> 8492</div> 8493<div class="listingblock"> 8494<div class="content"> 8495<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 84962 84973</div></td><td class="code"><span></span><span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"signal"</span><span class="tok-nt">></span> 8498 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">signalRef=</span><span class="tok-s">"newCustomerSignal"</span> <span class="tok-na">activiti:async=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 8499<span class="tok-nt"></intermediateThrowEvent></span> 8500</td></tr></table></code></pre> 8501</div> 8502</div> 8503</div> 8504<div class="sect4"> 8505<h5 id="bpmnIntermediateSignalEventExample">Example</h5> 8506<div class="paragraph"> 8507<p>See section on <a href="#bpmnSignalEventDefinition">signal event definitions</a>.</p> 8508</div> 8509</div> 8510</div> 8511<div class="sect3"> 8512<h4 id="bpmnIntermediateThrowCompensationEvent">8.2.31. Compensation Intermediate Throwing Event</h4> 8513<div class="paragraph"> 8514<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnIntermediateThrowCompensationEventDescription"></a></p> 8515</div> 8516<div class="sect4"> 8517<h5 id="_description_5">Description</h5> 8518<div class="paragraph"> 8519<p>An intermediate <em>throwing</em> compensation event can be used to trigger compensation.</p> 8520</div> 8521<div class="paragraph"> 8522<p><strong>Triggering compensation:</strong> Compensation can either be triggered for a designated activity or for the scope which hosts the compensation event. Compensation is performed through execution of the compensation handler associated with an activity.</p> 8523</div> 8524<div class="ulist"> 8525<ul> 8526<li> 8527<p>When compensation is thrown for an activity, the associated compensation handler is executed the same number of times the activity competed successfully.</p> 8528</li> 8529<li> 8530<p>If compensation is thrown for the current scope, all activities within the current scope are compensated, which includes activities on concurrent branches.</p> 8531</li> 8532<li> 8533<p>Compensation is triggered hierarchically: if an activity to be compensated is a subprocess, compensation is triggered for all activities contained in the subprocess. If the subprocess has nested activities, compensation is thrown recursively. However, compensation is not propagated to the "upper levels" of the process: if compensation is triggered within a subprocess, it is not propagated to activities outside of the subprocess scope. The BPMN specification states that compensation is triggered for activities at "the same level of subprocess".</p> 8534</li> 8535<li> 8536<p>In Activiti compensation is performed in reverse order of execution. This means that whichever activity completed last is compensated first, etc.</p> 8537</li> 8538<li> 8539<p>The intermediate throwing compensation event can be used to compensate transaction subprocesses which competed successfully.</p> 8540</li> 8541</ul> 8542</div> 8543<div class="paragraph"> 8544<p><strong>Note:</strong> If compensation is thrown within a scope which contains a subprocess and the subprocess contains activities with compensation handlers, compensation is only propagated to the subprocess if it has completed successfully when compensation is thrown. If some of the activities nested inside the subprocess have completed and have attached compensation handlers, the compensation handlers are not executed if the subprocess containing these activities is not completed yet. Consider the following example:</p> 8545</div> 8546<div class="imageblock" style="text-align: center"> 8547<div class="content"> 8548<img src="images/bpmn.throw.compensation.example1.png" alt="bpmn.throw.compensation.example1"> 8549</div> 8550</div> 8551<div class="paragraph"> 8552<p>In this process we have two concurrent executions, one executing the embedded subprocess and one executing the "charge credit card" activity. Let’s assume both executions are started and the first concurrent execution is waiting for a user to complete the "review bookings" task. The second execution performs the "charge credit card" activity and an error is thrown, which causes the "cancel reservations" event to trigger compensation. At this point the parallel subprocess is not yet completed which means that the compensation event is not propagated to the subprocess and thus the "cancel hotel reservation" compensation handler is not executed. If the user task (and thus the embedded subprocess) completes before the "cancel reservations" is performed, compensation is propagated to the embedded subprocess.</p> 8553</div> 8554<div class="paragraph"> 8555<p><strong>Process variables:</strong> When compensating an embedded subprocess, the execution used for executing the compensation handlers has access to the local process variables of the subprocess in the state they were in
8555when the subprocess completed execution. To achieve this, a snapshot of the process variables associated with the scope execution (execution created for executing the subprocess) is taken. Form this, a couple of implications follow:</p> 8556</div> 8557<div class="ulist"> 8558<ul> 8559<li> 8560<p>The compensation handler does not have access to variables added to concurrent executions created inside the subprocess scope.</p> 8561</li> 8562<li> 8563<p>Process variables associated with executions higher up in the hierarchy, (for instance process variables associated with the process instance execution are not contained in the snapshot: the compensation handler has access to these process variables in the state they are in when compensation is thrown.</p> 8564</li> 8565<li> 8566<p>A variable snapshot is only taken for embedded subprocesses, not for other activities.</p> 8567</li> 8568</ul> 8569</div> 8570<div class="paragraph"> 8571<p><strong>Current limitations:</strong></p> 8572</div> 8573<div class="ulist"> 8574<ul> 8575<li> 8576<p><code>waitForCompletion="false"</code> is currently unsupported. When compensation is triggered using the intermediate throwing compensation event, the event is only left, after compensation completed successfully.</p> 8577</li> 8578<li> 8579<p>Compensation itself is currently performed by concurrent executions. The concurrent executions are started in reverse order in which the compensated activities completed. Future versions of activity might include an option to perform compensation sequentially.</p> 8580</li> 8581<li> 8582<p>Compensation is not propagated to sub process instances spawned by call activities.</p> 8583</li> 8584</ul> 8585</div> 8586</div> 8587<div class="sect4"> 8588<h5 id="bpmnIntermediateThrowCompensationEventGraphicalNotation">Graphical notation</h5> 8589<div class="paragraph"> 8590<p>An intermediate compensation throw event is visualized as a typical intermediate event (Circle with smaller circle inside), with the compensation icon inside. The compensation icon is black (filled), to indicate the <em>throw</em> semantics.</p> 8591</div> 8592<div class="imageblock" style="text-align: center"> 8593<div class="content"> 8594<img src="images/bpmn.intermediate.compensation.throw.event.png" alt="bpmn.intermediate.compensation.throw.event"> 8595</div> 8596</div> 8597</div> 8598<div class="sect4"> 8599<h5 id="bpmnIntermediateThrowSignalEventXml">Xml representation</h5> 8600<div class="paragraph"> 8601<p>A compensation intermediate event is defined as an <a href="#bpmnIntermediateThrowEvent">intermediate throwing event</a>. The specific type sub-element is in this case a <strong>compensateEventDefinition</strong> element.</p> 8602</div> 8603<div class="listingblock"> 8604<div class="content"> 8605<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 86062 86073</div></td><td class="code"><span></span><span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"throwCompensation"</span><span class="tok-nt">></span> 8608 <span class="tok-nt"><compensateEventDefinition</span> <span class="tok-nt">/></span> 8609<span class="tok-nt"></intermediateThrowEvent></span> 8610</td></tr></table></code></pre> 8611</div> 8612</div> 8613<div class="paragraph"> 8614<p>In addition, the optional argument <code>activityRef</code> can be used to trigger compensation of a specific scope / activity:</p> 8615</div> 8616<div class="listingblock"> 8617<div class="content"> 8618<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 86192 86203</div></td><td class="code"><span></span><span class="tok-nt"><intermediateThrowEvent</span> <span class="tok-na">id=</span><span class="tok-s">"throwCompensation"</span><span class="tok-nt">></span> 8621 <span class="tok-nt"><compensateEventDefinition</span> <span class="tok-na">activityRef=</span><span class="tok-s">"bookHotel"</span> <span class="tok-nt">/></span> 8622<span class="tok-nt"></intermediateThrowEvent></span> 8623</td></tr></table></code></pre> 8624</div> 8625</div> 8626</div> 8627</div> 8628</div> 8629<div class="sect2"> 8630<h3 id="bpmnSequenceFlow">8.3. Sequence Flow</h3> 8631<div class="sect3"> 8632<h4 id="sequenceFlowDescription">8.3.1. Description</h4> 8633<div class="paragraph"> 8634<p>A sequence flow is the connector between two elements of a process. After an element is visited during process execution, all outgoing sequence flow will be followed. This means that the default nature of BPMN 2.0 is to be parallel: two outgoing sequence flow will create two separate, parallel paths of execution.</p> 8635</div> 8636</div> 8637<div class="sect3"> 8638<h4 id="sequenceFlowGraphicalNotation">8.3.2. Graphical notation</h4> 8639<div class="paragraph"> 8640<p>A sequence flow is visualized as an arrow going from the source element towards the target element. The arrow always points towards the target.</p> 8641</div> 8642<div class="imageblock" style="text-align: center"> 8643<div class="content"> 8644<img src="images/bpmn.sequence.flow.png" alt="bpmn.sequence.flow"> 8645</div> 8646</div> 8647</div> 8648<div class="sect3"> 8649<h4 id="sequenceFlowXml">8.3.3. XML representation</h4> 8650<div class="paragraph"> 8651<p>Sequence flow need to have a process-unique <strong>id</strong>, and a reference to an existing <strong>source</strong> and <strong>target</strong> element.</p> 8652</div> 8653<div class="listingblock"> 8654<div class="content"> 8655<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask"</span> <span class="tok-nt">/></span> 8656</td></tr></table></code></pre> 8657</div> 8658</div> 8659</div> 8660<div class="sect3"> 8661<h4 id="bpmnConditionalSequenceFlow">8.3.4. Conditional sequence flow</h4> 8662<div class="sect4"> 8663<h5 id="condSeqFlowDescription">Description</h5> 8664<div class="paragraph"> 8665<p>A sequence flow can have a condition defined on it. When a BPMN 2.0 activity is left, the default behavior is to evaluate the conditions on the outgoing sequence flow. When a condition evaluates to <em>true</em>, that outgoing sequence flow is selected. When multiple sequence flow are selected that way, multiple <em>executions</em> will be generated and the process will be continued in a parallel way.</p> 8666</div> 8667<div class="paragraph"> 8668<p><strong>Note:</strong> the above holds for BPMN 2.0 activities (and events), but not for gateways. Gateways will handle sequence flow with conditions in specific ways, depending on the gateway type.</p> 8669</div> 8670</div> 8671<div class="sect4"> 8672<h5 id="conditionalSequenceFlowGraphicalNotation">Graphical notation</h5> 8673<div class="paragraph"> 8674<p>A conditional sequence flow is visualized as a regular sequence flow, with a small diamond at the beginning. The condition expression is shown next to the sequence flow.<
8674/p> 8675</div> 8676<div class="imageblock" style="text-align: center"> 8677<div class="content"> 8678<img src="images/bpmn.conditional.sequence.flow.png" alt="bpmn.conditional.sequence.flow"> 8679</div> 8680</div> 8681</div> 8682<div class="sect4"> 8683<h5 id="conditionalSequenceFlowXml">XML representation</h5> 8684<div class="paragraph"> 8685<p>A conditional sequence flow is represented in XML as a regular sequence flow, containing a <strong>conditionExpression</strong> sub-element. Note that for the moment only <em>tFormalExpressions</em> are supported, Omitting the <em>xsi:type=""</em> definition will simply default to this only supported type of expressions.</p> 8686</div> 8687<div class="listingblock"> 8688<div class="content"> 8689<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 86902 86913 86924 86935</div></td><td class="code"><span></span><span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask"</span><span class="tok-nt">></span> 8694 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span> 8695 <span class="tok-cp"><![CDATA[${order.price > 100 && order.price < 250}]]></span> 8696 <span class="tok-nt"></conditionExpression></span> 8697<span class="tok-nt"></sequenceFlow></span> 8698</td></tr></table></code></pre> 8699</div> 8700</div> 8701<div class="paragraph"> 8702<p>Currently conditionalExpressions can <strong>only be used with UEL</strong>, detailed info about these can be found in section <a href="#apiExpressions">Expressions</a>. The expression used should resolve to a boolean value, otherwise an exception is thrown while evaluating the condition.</p> 8703</div> 8704<div class="ulist"> 8705<ul> 8706<li> 8707<p>The example below references data of a process variable, in the typical JavaBean style through getters.</p> 8708</li> 8709</ul> 8710</div> 8711<div class="listingblock"> 8712<div class="content"> 8713<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 87142 87153</div></td><td class="code"><span></span><span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span> 8716 <span class="tok-cp"><![CDATA[${order.price > 100 && order.price < 250}]]></span> 8717<span class="tok-nt"></conditionExpression></span> 8718</td></tr></table></code></pre> 8719</div> 8720</div> 8721<div class="ulist"> 8722<ul> 8723<li> 8724<p>This example invokes a method that resolves to a boolean value.</p> 8725</li> 8726</ul> 8727</div> 8728<div class="listingblock"> 8729<div class="content"> 8730<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 87312 87323</div></td><td class="code"><span></span><span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span> 8733 <span class="tok-cp"><![CDATA[${order.isStandardOrder()}]]></span> 8734<span class="tok-nt"></conditionExpression></span> 8735</td></tr></table></code></pre> 8736</div> 8737</div> 8738<div class="paragraph"> 8739<p>The Activiti distribution contains the following example process using value and method expressions (see <em>org.activiti.examples.bpmn.expression)</em>:</p> 8740</div> 8741<div class="imageblock" style="text-align: center"> 8742<div class="content"> 8743<img src="images/bpmn.uel-expression.on.seq.flow.png" alt="bpmn.uel expression.on.seq.flow"> 8744</div> 8745</div> 8746</div> 8747</div> 8748<div class="sect3"> 8749<h4 id="bpmnDefaultSequenceFlow">8.3.5. Default sequence flow</h4> 8750<div class="sect4"> 8751<h5 id="bpmnDefaultSequenceFlowDescription">Description</h5> 8752<div class="paragraph"> 8753<p>All BPMN 2.0 tasks and gateways can have a <strong>default sequence flow</strong>. This sequence flow is only selected as the outgoing sequence flow for that activity if and only if none of the other sequence flow could be selected. Conditions on a default sequence flow are always ignored.</p> 8754</div> 8755</div> 8756<div class="sect4"> 8757<h5 id="bpmnDefaultSequenceFlowGraphicalNotation">Graphical notation</h5> 8758<div class="paragraph"> 8759<p>A default sequence flow is visualized as a regular sequence flow, with a <em>slash</em> marker at the beginning.</p> 8760</div> 8761<div class="imageblock" style="text-align: center"> 8762<div class="content"> 8763<img src="images/bpmn.default.sequence.flow.png" alt="bpmn.default.sequence.flow"> 8764</div> 8765</div> 8766</div> 8767<div class="sect4"> 8768<h5 id="bpmnDefaultSequenceFlowXmlRepresentation">XML representation</h5> 8769<div class="paragraph"> 8770<p>A default sequence flow for a certain activity is defined by the <strong>default attribute</strong> on that activity. The following XML snippet shows for example an exclusive gateway that has as default sequence flow <em>flow 2</em>. Only when <em>conditionA</em> and <em>conditionB</em> both evaluate to false, will it be chosen as outgoing sequence flow for the gateway.</p> 8771</div> 8772<div class="listingblock"> 8773<div class="content"> 8774<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 87752 87763 87774 87785 87796 87807 87818</div></td><td class="code"><span></span><span class="tok-nt"><exclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">name=</span><span class="tok-s">"Exclusive Gateway"</span> <span class="tok-na">default=</span><span class="tok-s">"flow2"</span> <span class="tok-nt">/></span> 8782<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"task1"</span><span class="tok-nt">></span> 8783 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${conditionA}<span class="tok-nt"></conditionExpression></span> 8784<span class="tok-nt"></sequenceFlow></span> 8785<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"task2"</span><span class="tok-nt">/></span> 8786<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"task3"</span><span class="tok-nt">></span> 8787 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${conditionB}<span class="tok-nt"></conditionExpression></span> 8788<span class="tok-nt"></sequenceFlow></span> 8789</td></tr></table></code></pre> 8790</div> 8791</div> 8792<div class="paragraph"> 8793<p>Which corresponds with the following graphical representation:</p> 8794</div> 8795</div> 8796</div> 8797</div> 8798<div class="sect2"> 8799<h3 id="bpmnGateways">8.4. Gateways</h3> 8800<div class="paragraph"> 8801<p>A gateway is used to control the flow of execution (or as the BPMN 2.0 describes, the <em>tokens</em> of execution). A gateway is capable of <em>consuming</em> or <em>generating</em> tokens.</p> 8802</div> 8803<div class="paragraph"> 8804<p>A gateway is graphically visualized as a diamond shape, with an icon inside. The icon shows the type of gateway.</p> 8805</div> 8806<div class="imageblock" style="text-align: center"> 8807<div class="content"> 8808<img src="images/bpmn.gateway.png" alt="bpmn.gateway"> 8809</div> 8810</div> 8811<div class="sect3"> 8812<h4 id="bpmnExclusiveGateway">8.4.1. Exclusive Gateway</h4> 8813<div class="sect4"> 8814<h5 id="exclusiveGatewayDescription">Description</h5> 8815<div class="paragraph"> 8816<p>An exclusive gateway (also called the <em>XOR gateway</em> or more technical the <em>exclusive data-based gateway</em>), is used to model a <strong>decision</strong> in the process. When the execution arrives at this gateway, all outgoing sequence flow are evaluated in the order in which they are defined. The sequence flow which condition evaluates to true (or which doesn’t have a condition set, conceptually having a <em>'true'</em> defined on the sequence flow) is selected for continuing the process.</p> 8817</div> 8818<div class="paragraph"> 8819<p><strong>Note that the semantics of outgoing sequence flow is different to that of the general case in BPMN 2.0. While in general all sequence flow which condition evaluates to true are selected to continue in a parallel way, only one sequence flow is selected when using the exclusive gateway. In case multiple sequence flow have a condition that evaluates to true, the first one defined in the XML (and only that one!) is selected for continuing the process. If no sequence flow can be selected, an exception will be thrown.</strong></p> 8820</div> 8821</div> 8822<div class="sect4"> 8823<h5 id="exclusiveGatewayGraphNotation">Graphical notation</h5> 8824<div class="paragraph"> 8825<p>An exclusive gateway is visualized as a typical gateway (i.e. a diamond shape) with an <em>X</em> icon inside, referring to the <em>XOR</em> semantics. Note that a gateway without an icon inside defaults to an exclusive gateway. The BPMN 2.0 specification does not allow mixing the diamond with and without an X in the same process definition.</p> 8826</div> 8827<div class="imageblock" style="text-align: center"> 8828<div class="content"> 8829<img src="images/bpmn.exclusive.gateway.notation.png" alt="bpmn.exclusive.gateway.notation"> 8830</div> 8831</div> 8832</div> 8833<div class="sect4"> 8834<h5 id="exclusiveGatewayXML">XML representation</h5> 8835<div class="paragraph"> 8836<p>The XML representation of an exclusive gateway is straight-forward: one line defining the gateway and condition expressions defined on the outgoing sequence flow. See the section on <a href="#bpmnConditionalSequenceFlow">conditional sequence flow</a> to see which options are available for such expressions.</p> 8837</div> 8838<div class="paragraph"> 8839<p>Take for example the following model:</p> 8840</div> 8841<div class="imageblock" style="text-align: center"> 8842<div class="content"> 8843<img src="images/bpmn.exclusive.gateway.png" alt="bpmn.exclusive.gateway"> 8844</div> 8845</div> 8846<div class="paragraph"> 8847<p>Which is represented in XML as follows:</p> 8848</div> 8849<div class="listingblock"> 8850<div class="content"> 8851<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 8852 2 8853 3 8854 4 8855 5 8856 6 8857 7 8858 8 8859 9 886010 886111 886212 886313</div></td><td class="code"><span></span><span class="tok-nt"><exclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">name=</span><span class="tok-s">"Exclusive Gateway"</span> <span class="tok-nt">/></span> 8864 8865<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask1"</span><span class="tok-nt">></span> 8866 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${input == 1}<span class="tok-nt"></conditionExpression></span> 8867<span class="tok-nt"></sequenceFlow></span> 8868 8869<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask2"</span><span class="tok-nt">></span> 8870 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${input == 2}<span class="tok-nt"></conditionExpression></span> 8871<span class="tok-nt"></sequenceFlow></span> 8872 8873<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow4"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theTask3"</span><span class="tok-nt">></span> 8874 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${input == 3}<span class="tok-nt"></conditionExpression></span> 8875<span class="tok-nt"></sequenceFlow></span> 8876</td></tr></table></code></pre> 8877</div> 8878</div> 8879</div> 8880</div> 8881<div class="sect3"> 8882<h4 id="bpmnParallelGateway">8.4.2. Parallel Gateway</h4> 8883<div class="sect4"> 8884<h5 id="bpmnParallelGatewayDescription">Description</h5> 8885<div class="paragraph"> 8886<p>Gateways can also be used to model concurrency in a process. The most straightforward gateway to introduce concurrency in a process model, is the <strong>Parallel Gateway</strong>, which allows to <em>fork</em> into multiple paths of execution or <em>join</em> multiple incoming paths of execution.</p> 8887</div> 8888<div class="paragraph"> 8889<p>The functionality of the parallel gateway is based on the incoming and outgoing sequence flow:</p> 8890</div> 8891<div class="ulist"> 8892<ul> 8893<li> 8894<p><strong>fork:</strong> all outgoing sequence flow are followed in parallel, creating one concurrent execution for each sequence flow.<
8894/p> 8895</li> 8896<li> 8897<p><strong>join:</strong> all concurrent executions arriving at the parallel gateway wait in the gateway until an execution has arrived for each of the incoming sequence flow. Then the process continues past the joining gateway.</p> 8898</li> 8899</ul> 8900</div> 8901<div class="paragraph"> 8902<p>Note that a parallel gateway can have <strong>both fork and join behavior</strong>, if there are multiple incoming and outgoing sequence flow for the same parallel gateway. In that case, the gateway will first join all incoming sequence flow, before splitting into multiple concurrent paths of executions.</p> 8903</div> 8904<div class="paragraph"> 8905<p><strong>An important difference with other gateway types is that the parallel gateway does not evaluate conditions. If conditions are defined on the sequence flow connected with the parallel gateway, they are simply neglected.</strong></p> 8906</div> 8907</div> 8908<div class="sect4"> 8909<h5 id="bpmnParallelGatewayGraphicalNotation">Graphical Notation</h5> 8910<div class="paragraph"> 8911<p>A parallel gateway is visualized as a gateway (diamond shape) with the <em>plus</em> symbol inside, referring to the <em>AND</em> semantics.</p> 8912</div> 8913<div class="imageblock" style="text-align: center"> 8914<div class="content"> 8915<img src="images/bpmn.parallel.gateway.png" alt="bpmn.parallel.gateway"> 8916</div> 8917</div> 8918</div> 8919<div class="sect4"> 8920<h5 id="bpmnParallelGatewayXML">XML representation</h5> 8921<div class="paragraph"> 8922<p>Defining a parallel gateway needs one line of XML:</p> 8923</div> 8924<div class="listingblock"> 8925<div class="content"> 8926<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><parallelGateway</span> <span class="tok-na">id=</span><span class="tok-s">"myParallelGateway"</span> <span class="tok-nt">/></span> 8927</td></tr></table></code></pre> 8928</div> 8929</div> 8930<div class="paragraph"> 8931<p>The actual behavior (fork, join or both), is defined by the sequence flow connected to the parallel gateway.</p> 8932</div> 8933<div class="paragraph"> 8934<p>For example, the model above comes down to the following XML:</p> 8935</div> 8936<div class="listingblock"> 8937<div class="content"> 8938<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 8939 2 8940 3 8941 4 8942 5 8943 6 8944 7 8945 8 8946 9 894710 894811 894912 895013 895114 895215 895316 895417 895518 895619 895720</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 8958<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"fork"</span> <span class="tok-nt">/></span> 8959 8960<span class="tok-nt"><parallelGateway</span> <span class="tok-na">id=</span><span class="tok-s">"fork"</span> <span class="tok-nt">/></span> 8961<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"fork"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"receivePayment"</span> <span class="tok-nt">/></span> 8962<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"fork"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"shipOrder"</span> <span class="tok-nt">/></span> 8963 8964<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"receivePayment"</span> <span class="tok-na">name=</span><span class="tok-s">"Receive Payment"</span> <span class="tok-nt">/></span> 8965<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"receivePayment"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"join"</span> <span class="tok-nt">/></span> 8966 8967<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"shipOrder"</span> <span class="tok-na">name=</span><span class="tok-s">"Ship Order"</span> <span class="tok-nt">/></span> 8968<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"shipOrder"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"join"</span> <span class="tok-nt">/></span> 8969 8970<span class="tok-nt"><parallelGateway</span> <span class="tok-na">id=</span><span class="tok-s">"join"</span> <span class="tok-nt">/></span> 8971<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"join"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"archiveOrder"</span> <span class="tok-nt">/></span> 8972 8973<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"archiveOrder"</span> <span class="tok-na">name=</span><span class="tok-s">"Archive Order"</span> <span class="tok-nt">/></span> 8974<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"archiveOrder"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 8975 8976<span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 8977</td></tr></table></code></pre> 8978</div> 8979</div> 8980<div class="paragraph"> 8981<p>
8981In the above example, after the process is started, two tasks will be created:</p> 8982</div> 8983<div class="listingblock"> 8984<div class="content"> 8985<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 8986 2 8987 3 8988 4 8989 5 8990 6 8991 7 8992 8 8993 9 899410 899511 899612 899713</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-n">pi</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"forkJoin"</span><span class="tok-o">);</span> 8998<span class="tok-n">TaskQuery</span> <span class="tok-n">query</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">()</span> 8999 <span class="tok-o">.</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-n">pi</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">())</span> 9000 <span class="tok-o">.</span><span class="tok-na">orderByTaskName</span><span class="tok-o">()</span> 9001 <span class="tok-o">.</span><span class="tok-na">asc</span><span class="tok-o">();</span> 9002 9003<span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">query</span><span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 9004<span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-mi">2</span><span class="tok-o">,</span> <span class="tok-n">tasks</span><span class="tok-o">.</span><span class="tok-na">size</span><span class="tok-o">());</span> 9005 9006<span class="tok-n">Task</span> <span class="tok-n">task1</span> <span class="tok-o">=</span> <span class="tok-n">tasks</span><span class="tok-o">.</span><span class="tok-na">get</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">);</span> 9007<span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"Receive Payment"</span><span class="tok-o">,</span> <span class="tok-n">task1</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 9008<span class="tok-n">Task</span> <span class="tok-n">task2</span> <span class="tok-o">=</span> <span class="tok-n">tasks</span><span class="tok-o">.</span><span class="tok-na">get</span><span class="tok-o">(</span><span class="tok-mi">1</span><span class="tok-o">);</span> 9009<span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"Ship Order"</span><span class="tok-o">,</span> <span class="tok-n">task2</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 9010</td></tr></table></code></pre> 9011</div> 9012</div> 9013<div class="paragraph"> 9014<p>When these two tasks are completed, the second parallel gateway will join the two executions and since there is only one outgoing sequence flow, no concurrent paths of execution will be created, and only the <em>Archive Order</em> task will be active.</p> 9015</div> 9016<div class="paragraph"> 9017<p>Note that a parallel gateway does not need to be <em>balanced</em> (i.e. a matching number of incoming/outgoing sequence flow for corresponding parallel gateways). A parallel gateway will simply wait for all incoming sequence flow and create a concurrent path of execution for each outgoing sequence flow, not influenced by other constructs in the process model. So, the following process is legal in BPMN 2.0:</p> 9018</div> 9019<div class="imageblock" style="text-align: center"> 9020<div class="content"> 9021<img src="images/bpmn.unbalanced.parallel.gateway.png" alt="bpmn.unbalanced.parallel.gateway"> 9022</div> 9023</div> 9024</div> 9025</div> 9026<div class="sect3"> 9027<h4 id="bpmnInclusiveGateway">8.4.3. Inclusive Gateway</h4> 9028<div class="sect4"> 9029<h5 id="bpmnInclusiveGatewayDescription">Description</h5> 9030<div class="paragraph"> 9031<p>The <strong>Inclusive Gateway</strong> can be seen as a combination of an exclusive and a parallel gateway. Like an exclusive gateway y
9031ou can define conditions on outgoing sequence flows and the inclusive gateway will evaluate them. But the main difference is that the inclusive gateway can take more than one sequence flow, like the parallel gateway.</p> 9032</div> 9033<div class="paragraph"> 9034<p>The functionality of the inclusive gateway is based on the incoming and outgoing sequence flow:</p> 9035</div> 9036<div class="ulist"> 9037<ul> 9038<li> 9039<p><strong>fork:</strong> all outgoing sequence flow conditions are evaluated and for the sequence flow conditions that evaluate to true the flows are followed in parallel, creating one concurrent execution for each sequence flow.</p> 9040</li> 9041<li> 9042<p><strong>join:</strong> all concurrent executions arriving at the inclusive gateway wait in the gateway until an execution has arrived for each of the incoming sequence flows that have a process token. This is an important difference with the parallel gateway. So in other words, the inclusive gateway will only wait for the incoming sequence flows that will be executed. After the join, the process continues past the joining inclusive gateway.</p> 9043</li> 9044</ul> 9045</div> 9046<div class="paragraph"> 9047<p>Note that an inclusive gateway can have <strong>both fork and join behavior</strong>, if there are multiple incoming and outgoing sequence flow for the same inclusive gateway. In that case, the gateway will first join all incoming sequence flows that have a process token, before splitting into multiple concurrent paths of executions for the outgoing sequence flows that have a condition that evaluates to true.</p> 9048</div> 9049</div> 9050<div class="sect4"> 9051<h5 id="bpmnInclusiveGatewayGraphicalNotation">Graphical Notation</h5> 9052<div class="paragraph"> 9053<p>An inclusive gateway is visualized as a gateway (diamond shape) with the <em>circle</em> symbol inside.</p> 9054</div> 9055<div class="imageblock" style="text-align: center"> 9056<div class="content"> 9057<img src="images/bpmn.inclusive.gateway.png" alt="bpmn.inclusive.gateway"> 9058</div> 9059</div> 9060</div> 9061<div class="sect4"> 9062<h5 id="bpmnInclusiveGatewayXML">XML representation</h5> 9063<div class="paragraph"> 9064<p>Defining an inclusive gateway needs one line of XML:</p> 9065</div> 9066<div class="listingblock"> 9067<div class="content"> 9068<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><inclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"myInclusiveGateway"</span> <span class="tok-nt">/></span> 9069</td></tr></table></code></pre> 9070</div> 9071</div> 9072<div class="paragraph"> 9073<p>The actual behavior (fork, join or both), is defined by the sequence flows connected to the inclusive gateway.</p> 9074</div> 9075<div class="paragraph"> 9076<p>For example, the model above comes down to the following XML:</p> 9077</div> 9078<div class="listingblock"> 9079<div class="content"> 9080<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9081 2 9082 3 9083 4 9084 5 9085 6 9086 7 9087 8 9088 9 908910 909011 909112 909213 909314 909415 909516 909617 909718 909819 909920 910021 910122 910223 910324</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 9104<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"fork"</span> <span class="tok-nt">/></span> 9105 9106<span class="tok-nt"><inclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"fork"</span> <span class="tok-nt">/></span> 9107<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"fork"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"receivePayment"</span> <span class="tok-nt">></span> 9108 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${paymentReceived == false}<span class="tok-nt"></conditionExpression></span> 9109<span class="tok-nt"></sequenceFlow></span> 9110<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"fork"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"shipOrder"</span> <span class="tok-nt">></span> 9111 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${shipOrder == true}<span class="tok-nt"></conditionExpression></span> 9112<span class="tok-nt"></sequenceFlow></span> 9113 9114<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"receivePayment"</span> <span class="tok-na">name=</span><span class="tok-s">"Receive Payment"</span> <span class="tok-nt">/></span> 9115<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"receivePayment"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"join"</span> <span class="tok-nt">/></span> 9116 9117<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"shipOrder"</span> <span class="tok-na">name=</span><span class="tok-s">"Ship Order"</span> <span class="tok-nt">/></span> 9118<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"shipOrder"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"join"</span> <span class="tok-nt">/></span> 9119 9120<span class="tok-nt"><inclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"join"</span> <span class="tok-nt">/></span> 9121<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"join"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"archiveOrder"</span> <span class="tok-nt">/></span> 9122 9123<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"archiveOrder"</span> <span class="tok-na">name=</span><span class="tok-s">"Archive Order"</span> <span class="tok-nt">/></span> 9124<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"archiveOrder"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 9125 9126<span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 9127</td></tr></table></code></pre> 9128</div> 9129</div> 9130<div class="paragraph"> 9131<p>
9131In the above example, after the process is started, two tasks will be created if the process variables paymentReceived == false and shipOrder == true. In case only one of these process variables equals to true only one task will be created. If no condition evaluates to true and exception is thrown. This can be prevented by specifying a default outgoing sequence flow. In the following example one task will be created, the ship order task:</p> 9132</div> 9133<div class="listingblock"> 9134<div class="content"> 9135<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9136 2 9137 3 9138 4 9139 5 9140 6 9141 7 9142 8 9143 9 914410 914511 914612 914713 914814</div></td><td class="code"><span></span><span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variableMap</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();</span> 9149 <span class="tok-n">variableMap</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"receivedPayment"</span><span class="tok-o">,</span> <span class="tok-kc">true</span><span class="tok-o">);</span> 9150 <span class="tok-n">variableMap</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"shipOrder"</span><span class="tok-o">,</span> <span class="tok-kc">true</span><span class="tok-o">);</span> 9151 <span class="tok-n">ProcessInstance</span> <span class="tok-n">pi</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"forkJoin"</span><span class="tok-o">);</span> 9152<span class="tok-n">TaskQuery</span> <span class="tok-n">query</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">()</span> 9153 <span class="tok-o">.</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-n">pi</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">())</span> 9154 <span class="tok-o">.</span><span class="tok-na">orderByTaskName</span><span class="tok-o">()</span> 9155 <span class="tok-o">.</span><span class="tok-na">asc</span><span class="tok-o">();</span> 9156 9157<span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">query</span><span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 9158<span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-mi">1</span><span class="tok-o">,</span> <span class="tok-n">tasks</span><span class="tok-o">.</span><span class="tok-na">size</span><span class="tok-o">());</span> 9159 9160<span class="tok-n">Task</span> <span class="tok-n">task</span> <span class="tok-o">=</span> <span class="tok-n">tasks</span><span class="tok-o">.</span><span class="tok-na">get</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">);</span> 9161<span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"Ship Order"</span><span class="tok-o">,</span> <span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getName</span><span class="tok-o">());</span> 9162</td></tr></table></code></pre> 9163</div> 9164</div> 9165<div class="paragraph"> 9166<p>When this task is completed, the second inclusive gateway will join the two executions and since there is only one outgoing sequence flow, no concurrent paths of execution will be created, and only the <em>Archive Order</em> task will be active.</p> 9167</div> 9168<div class="paragraph"> 9169<p>Note that an inclusive gateway does not need to be <em>balanced</em> (i.e. a matching number of incoming/outgoing sequence flow for c
9169orresponding inclusive gateways). An inclusive gateway will simply wait for all incoming sequence flow and create a concurrent path of execution for each outgoing sequence flow, not influenced by other constructs in the process model.</p> 9170</div> 9171</div> 9172</div> 9173<div class="sect3"> 9174<h4 id="bpmnEventbasedGateway">8.4.4. Event-based Gateway</h4> 9175<div class="sect4"> 9176<h5 id="eventBasedGatewayDescription">Description</h5> 9177<div class="paragraph"> 9178<p>The Event-based Gateway allows to take a decision based on events. Each outgoing sequence flow of the gateway needs to be connected to an intermediate catching event. When process execution reaches an Event-based Gateway, the gateway acts like a wait state: execution is suspended. In addition, for each outgoing sequence flow, an event subscription is created.</p> 9179</div> 9180<div class="paragraph"> 9181<p>Note the sequence flows running out of an Event-based Gateway are different from ordinary sequence flows. These sequence flows are never actually "executed". On the contrary, they allow the process engine to determine which events an execution arriving at an Event-based Gateway needs to subscribe to. The following restrictions apply:</p> 9182</div> 9183<div class="ulist"> 9184<ul> 9185<li> 9186<p>An Event-based Gateway must have two or more outgoing sequence flows.</p> 9187</li> 9188<li> 9189<p>An Event-based Gateway must only be connected to elements of type <code>intermediateCatchEvent</code> only. (Receive Tasks after an Event-based Gateway are not supported by Activiti.)</p> 9190</li> 9191<li> 9192<p>An <code>intermediateCatchEvent</code> connected to an Event-based Gateway must have a single incoming sequence flow.</p> 9193</li> 9194</ul> 9195</div> 9196</div> 9197<div class="sect4"> 9198<h5 id="eventBasedGatewayGraphNotation">Graphical notation</h5> 9199<div class="paragraph"> 9200<p>An Event-based Gateway is visualized as a diamond shape like other BPMN gateways with a special icon inside.</p> 9201</div> 9202<div class="imageblock" style="text-align: center"> 9203<div class="content"> 9204<img src="images/bpmn.event.based.gateway.notation.png" alt="bpmn.event.based.gateway.notation"> 9205</div> 9206</div> 9207</div> 9208<div class="sect4"> 9209<h5 id="eventBasedGatewayXML">XML representation</h5> 9210<div class="paragraph"> 9211<p>The XML element used to define an Event-based Gateway is <code>eventBasedGateway</code>.</p> 9212</div> 9213</div> 9214<div class="sect4"> 9215<h5 id="eventBasedGatewayExample">Example(s)</h5> 9216<div class="paragraph"> 9217<p>The following process is an example of a process with an Event-based Gateway. When the execution arrives at the Event-based Gateway, process execution is suspended. In addition, the process instance subscribes to the alert signal event and created a timer which fires after 10 minutes. This effectively causes the process engine to wait for ten minutes for a signal event. If the signal occurs within 10 minutes, the timer is cancelled and execution continues after the signal. If the signal is not fired, execution continues after the timer and the signal subscription is cancelled.</p> 9218</div> 9219<div class="imageblock" style="text-align: center"> 9220<div class="content"> 9221<img src="images/bpmn.event.based.gateway.example.png" alt="bpmn.event.based.gateway.example"> 9222</div> 9223</div> 9224<div class="listingblock"> 9225<div class="content"> 9226<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9227 2 9228 3 9229 4 9230 5 9231 6 9232 7 9233 8 9234 9 923510 923611 923712 923813 923914 924015 924116 924217 924318 924419 924520 924621 924722 924823 924924 925025 925126 925227 925328 925429 925530 925631 925732 925833 925934 926035 926136 926237 926338 926439 926540 926641</div></td><td class="code"><span></span><span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"definitions"</span> 9267 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 9268 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 9269 <span class="tok-na">targetNamespace=</span><span class="tok-s">"Examples"</span><span class="tok-nt">></span> 9270 9271 <span class="tok-nt"><signal</span> <span class="tok-na">id=</span><span class="tok-s">"alertSignal"</span> <span class="tok-na">name=</span><span class="tok-s">"alert"</span> <span class="tok-nt">/></span> 9272 9273 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"catchSignal"</span><span class="tok-nt">></span> 9274 9275 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span> <span class="tok-nt">/></span> 9276 9277 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"start"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"gw1"</span> <span class="tok-nt">/></span> 9278 9279 <span class="tok-nt"><eventBasedGateway</span> <span class="tok-na">id=</span><span class="tok-s">"gw1"</span> <span class="tok-nt">/></span> 9280 9281 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"gw1"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"signalEvent"</span> <span class="tok-nt">/></span> 9282 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"gw1"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"timerEvent"</span> <span class="tok-nt">/></span> 9283 9284 <span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"signalEvent"</span> <span class="tok-na">name=</span><span class="tok-s">"Alert"</span><span class="tok-nt">></span> 9285 <span class="tok-nt"><signalEventDefinition</span> <span class="tok-na">
9285signalRef=</span><span class="tok-s">"alertSignal"</span> <span class="tok-nt">/></span> 9286 <span class="tok-nt"></intermediateCatchEvent></span> 9287 9288 <span class="tok-nt"><intermediateCatchEvent</span> <span class="tok-na">id=</span><span class="tok-s">"timerEvent"</span> <span class="tok-na">name=</span><span class="tok-s">"Alert"</span><span class="tok-nt">></span> 9289 <span class="tok-nt"><timerEventDefinition></span> 9290 <span class="tok-nt"><timeDuration></span>PT10M<span class="tok-nt"></timeDuration></span> 9291 <span class="tok-nt"></timerEventDefinition></span> 9292 <span class="tok-nt"></intermediateCatchEvent></span> 9293 9294 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"timerEvent"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"exGw1"</span> <span class="tok-nt">/></span> 9295 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"signalEvent"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"task"</span> <span class="tok-nt">/></span> 9296 9297 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"task"</span> <span class="tok-na">name=</span><span class="tok-s">"Handle alert"</span><span class="tok-nt">/></span> 9298 9299 <span class="tok-nt"><exclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"exGw1"</span> <span class="tok-nt">/></span> 9300 9301 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"task"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"exGw1"</span> <span class="tok-nt">/></span> 9302 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exGw1"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 9303 9304 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 9305<span class="tok-nt"></process></span> 9306<span class="tok-nt"></definitions></span> 9307</td></tr></table></code></pre> 9308</div> 9309</div> 9310</div> 9311</div> 9312</div> 9313<div class="sect2"> 9314<h3 id="bpmnTask">8.5. Tasks</h3> 9315<div class="sect3"> 9316<h4 id="bpmnUserTask">8.5.1. User Task</h4> 9317<div class="sect4"> 9318<h5 id="bpmnUserTaskDescription">Description</h5> 9319<div class="paragraph"> 9320<p>A <em>user task</em> is used to model work that needs to be done by a human actor. When the process execution arrives at such a user task, a new task is created in the task list of the user(s) or group(s) assigned to that task.</p> 9321</div> 9322</div> 9323<div class="sect4"> 9324<h5 id="bpmnUserTaskGraphicalNotation">Graphical notation</h5> 9325<div class="paragraph"> 9326<p>A user task is visualized as a typical task (rounded rectangle), with a small user icon in the left upper corner.</p> 9327</div> 9328<div class="imageblock" style="text-align: center"> 9329<div class="content"> 9330<img src="images/bpmn.user.task.png" alt="bpmn.user.task"> 9331</div> 9332</div> 9333</div> 9334<div class="sect4"> 9335<h5 id="bpmnUserTaskXml">XML representation</h5> 9336<div class="paragraph"> 9337<p>A user task is defined in XML as follows. The <em>id</em> attribute is required, the <em>name</em> attribute is optional.</p> 9338</div> 9339<div class="listingblock"> 9340<div class="content"> 9341<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Important task"</span> <span class="tok-nt">/></span> 9342</td></tr></table></code></pre> 9343</div> 9344</div> 9345<div class="paragraph"> 9346<p>A user task can have also a description. In fact any BPMN 2.0 element can have a description. A description is defined by adding the <strong>documentation</strong> element.</p> 9347</div> 9348<div class="listingblock"> 9349<div class="content"> 9350<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 93512 93523 93534</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Schedule meeting"</span> <span class="tok-nt">></span> 9354 <span class="tok-nt"><documentation></span> 9355 Schedule an engineering meeting for next week with the new hire. 9356 <span class="tok-nt"></documentation></span> 9357</td></tr></table></code></pre> 9358</div> 9359</div> 9360<div class="paragraph"> 9361<p>The description text can be retrieved from the task in the standard Java way:</p> 9362</div> 9363<div class="listingblock"> 9364<div class="content"> 9365<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">task</span><span class="tok-o">.</span><span class="tok-na">getDescription</span><span class="tok-o">()</span> 9366</td></tr></table></code></pre> 9367</div> 9368</div> 9369</div> 9370<div class="sect4"> 9371<h5 id="bpmnUserTaskDueDate">Due Date</h5> 9372<div class="paragraph"> 9373<p>Each task has a field, indicating the due date of that task. The Query API can be used to query for tasks that are due on, before or after a certain date.</p> 9374</div> 9375<div class="paragraph"> 9376<p>There is an activity extension which allows you to specify an expression in your task-definition to set the initial due date of a task when it is created. The expression <strong>should always resolve to a <code>java.util.Date</code>, <code>java.util.String (ISO8601 formatted)</code>, ISO8601 time-duration (e.g. PT50M) or <code>null</code></strong>. For example, you could use a date that was entered in a previous form in the process or calculated in a previous Service Task. In case a time-duration is used, the due-date is calculated based on the current time, incremented by the given period. For example, when "PT30M" is used as dueDate, the task is due in thirty minutes from now.</p> 9377</div> 9378<div class="listingblock"> 9379<div class="content"> 9380<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Important task"</span> <span class="tok-na">activiti:dueDate=</span><span class="tok-s">"${dateVariable}"</span><span class="tok-nt">/></span> 9381</td></tr></table></code></pre> 9382</div> 9383</div> 9384<div class="paragraph"> 9385<p>The due date of a task can also be altered using the <code>TaskService</code> or in <code>TaskListener</code>s using the passed <code>DelegateTask</code>.</p> 9386</div> 9387</div> 9388<div class="sect4"> 9389<h5 id="bpmnUserTaskAssignment">User assignment</h5> 9390<div class="paragraph"> 9391<p>A user task can be directly assigned to a user. This is done by defining a <strong>humanPerformer</strong> sub element. Such a <em>humanPerformer</em> definition needs a <strong>resourceAssignmentExpression</strong> that actually defines the user. Currently, only <strong>formalExpressions</strong> are supported.</p> 9392</div> 9393<div class="listingblock"> 9394<div class="content"> 9395<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9396 2 9397 3 9398 4 9399 5 9400 6 9401 7 9402 8 9403 9 940410 940511</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-nt">></span> 9406 9407 ... 9408 9409 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">'theTask'</span> <span class="tok-na">name=</span><span class="tok-s">'important task'</span> <span class="tok-nt">></span> 9410 <span class="tok-nt"><humanPerformer></span>
9411 <span class="tok-nt"><resourceAssignmentExpression></span> 9412 <span class="tok-nt"><formalExpression></span>kermit<span class="tok-nt"></formalExpression></span> 9413 <span class="tok-nt"></resourceAssignmentExpression></span> 9414 <span class="tok-nt"></humanPerformer></span> 9415 <span class="tok-nt"></userTask></span> 9416</td></tr></table></code></pre> 9417</div> 9418</div> 9419<div class="paragraph"> 9420<p><strong>Only one</strong> user can be assigned as human performer to the task. In Activiti terminology, this user is called the <strong>assignee</strong>. Tasks that have an assignee are not visible in the task lists of other people and can be found in the so-called <strong>personal task list</strong> of the assignee instead.</p> 9421</div> 9422<div class="paragraph"> 9423<p>Tasks directly assigned to users can be retrieved through the TaskService as follows:</p> 9424</div> 9425<div class="listingblock"> 9426<div class="content"> 9427<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 9428</td></tr></table></code></pre> 9429</div> 9430</div> 9431<div class="paragraph"> 9432<p>Tasks can also be put in the so-called <strong>candidate task list</strong> of people. In that case, the <strong>potentialOwner</strong> construct must be used. The usage is similar to the <em>humanPerformer</em> construct. Do note that it is required to define for each element in the formal expression to specify if it is a user or a group (the engine cannot guess this).</p> 9433</div> 9434<div class="listingblock"> 9435<div class="content"> 9436<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9437 2 9438 3 9439 4 9440 5 9441 6 9442 7 9443 8 9444 9 944510 944611</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-nt">></span> 9447 9448 ... 9449 9450 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">'theTask'</span> <span class="tok-na">name=</span><span class="tok-s">'important task'</span> <span class="tok-nt">></span> 9451 <span class="tok-nt"><potentialOwner></span> 9452 <span class="tok-nt"><resourceAssignmentExpression></span> 9453 <span class="tok-nt"><formalExpression></span>user(kermit), group(management)<span class="tok-nt"></formalExpression></span> 9454 <span class="tok-nt"></resourceAssignmentExpression></span> 9455 <span class="tok-nt"></potentialOwner></span> 9456 <span class="tok-nt"></userTask></span> 9457</td></tr></table></code></pre> 9458</div> 9459</div> 9460<div class="paragraph"> 9461<p>Tasks defines with the <em>potential owner</em> construct, can be retrieved as follows (or a similar <em>TaskQuery</em> usage as for the tasks with an assignee):</p> 9462</div> 9463<div class="listingblock"> 9464<div class="content"> 9465<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Task</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">().</span><span class="tok-na">taskCandidateUser</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">);</span> 9466</td></tr></table></code></pre> 9467</div> 9468</div> 9469<div class="paragraph"> 9470<p>This will retrieve all tasks where kermit is a <strong>candidate user</strong>, i.e. the formal expression contains <em>user(kermit)</em>. This will also retrieve all tasks that are <strong>assigned to a group where kermit is a member of</strong> (e.g. <em>group(management)</em>, if kermit is a member of that group and the Activiti identity component is used). The groups of a user are resolved at runtime and these can be managed through the <a href="#apiEngine">IdentityService</a>.</p> 9471</div> 9472<div class="paragraph"> 9473<p>
9473If no specifics are given whether the given text string is a user or group, the engine defaults to group. So the following would be the same as when <em>group(accountancy) was declared</em>.</p> 9474</div> 9475<div class="listingblock"> 9476<div class="content"> 9477<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><formalExpression></span>accountancy<span class="tok-nt"></formalExpression></span> 9478</td></tr></table></code></pre> 9479</div> 9480</div> 9481</div> 9482<div class="sect4"> 9483<h5 id="bpmnUserTaskUserAssignmentExtension">Activiti extensions for task assignment</h5> 9484<div class="paragraph"> 9485<p>It is clear that user and group assignments are quite cumbersome for use cases where the assignment is not complex. To avoid these complexities, <a href="#bpmnCustomExtensions">custom extensions</a> on the user task are possible.</p> 9486</div> 9487<div class="ulist"> 9488<ul> 9489<li> 9490<p><strong>assignee attribute</strong>: this custom extension allows to directly assign a user task to a given user.</p> 9491</li> 9492</ul> 9493</div> 9494<div class="listingblock"> 9495<div class="content"> 9496<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"my task"</span> <span class="tok-na">activiti:assignee=</span><span class="tok-s">"kermit"</span> <span class="tok-nt">/></span> 9497</td></tr></table></code></pre> 9498</div> 9499</div> 9500<div class="paragraph"> 9501<p>This is exactly the same as using a <strong>humanPerformer</strong> construct as defined <a href="#bpmnUserTaskAssignment">above</a>.</p> 9502</div> 9503<div class="ulist"> 9504<ul> 9505<li> 9506<p><strong>candidateUsers attribute</strong>: this custom extension allows to make a user a candidate for a task.</p> 9507</li> 9508</ul> 9509</div> 9510<div class="listingblock"> 9511<div class="content"> 9512<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"my task"</span> <span class="tok-na">activiti:candidateUsers=</span><span class="tok-s">"kermit, gonzo"</span> <span class="tok-nt">/></span> 9513</td></tr></table></code></pre> 9514</div> 9515</div> 9516<div class="paragraph"> 9517<p>This is exactly the same as using a <strong>potentialOwner</strong> construct as defined <a href="#bpmnUserTaskAssignment">above</a>. Note that it is not required to use the <em>user(kermit)</em> declaration as is the case with the <em>potential owner</em> construct, since the attribute can only be used for users.</p> 9518</div> 9519<div class="ulist"> 9520<ul> 9521<li> 9522<p><strong>candidateGroups attribute</strong>: this custom extension allows to make a group a candidate for a task.</p> 9523</li> 9524</ul> 9525</div> 9526<div class="listingblock"> 9527<div class="content"> 9528<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"my task"</span> <span class="tok-na">activiti:candidateGroups=</span><span class="tok-s">"management, accountancy"</span> <span class="tok-nt">/></span> 9529</td></tr></table></code></pre> 9530</div> 9531</div> 9532<div class="paragraph"> 9533<p>This is exactly the same as using a <strong>potentialOwner</strong> construct as defined <a href="#bpmnUserTaskAssignment">above</a>. Note that it is not required to use the <em>group(management)</em> declaration as is the case with the <em>potential owner</em>
9533 construct, since the attribute can only be used for groups.</p> 9534</div> 9535<div class="ulist"> 9536<ul> 9537<li> 9538<p><em>candidateUsers</em> and <em>candidateGroups</em> can both be defined on the same user task.</p> 9539</li> 9540</ul> 9541</div> 9542<div class="paragraph"> 9543<p>Note: Although Activiti provides an identity management component, which is exposed through the <a href="#apiEngine">IdentityService</a>, no check is done whether a provided user is known by the identity component. This allows Activiti to integrate with existing identity management solutions when it is embedded into an application.</p> 9544</div> 9545</div> 9546<div class="sect4"> 9547<h5 id="bpmnUserTaskUserCustomIdentityLinkAssignmentExtension">Custom identity link types (Experimental)</h5> 9548<div class="paragraph"> 9549<p><a href="#experimental">[EXPERIMENTAL]</a></p> 9550</div> 9551<div class="paragraph"> 9552<p>The BPMN standard supports a single assigned user or <strong>humanPerformer</strong> or a set of users that form a potential pool of <strong>potentialOwners</strong> as defined in <a href="#bpmnUserTaskAssignment">User assignment</a>. In addition, Activiti defines <a href="#bpmnUserTaskUserAssignmentExtension">extension attribute elements</a> for the User Task that can represent the task <strong>assignee</strong> or <strong>candidate owner</strong>.</p> 9553</div> 9554<div class="paragraph"> 9555<p>The supported Activiti identity link types are:</p> 9556</div> 9557<div class="listingblock"> 9558<div class="content"> 9559<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 95602 95613 95624 95635 95646 95657 95668</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">IdentityLinkType</span> <span class="tok-o">{</span> 9567 <span class="tok-cm">/* Activiti native roles */</span> 9568 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">ASSIGNEE</span> <span class="tok-o">=</span> <span class="tok-s">"assignee"</span><span class="tok-o">;</span> 9569 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">CANDIDATE</span> <span class="tok-o">=</span> <span class="tok-s">"candidate"</span><span class="tok-o">;</span> 9570 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">OWNER</span> <span class="tok-o">=</span> <span class="tok-s">"owner"</span><span class="tok-o">;</span> 9571 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">STARTER</span> <span class="tok-o">=</span> <span class="tok-s">"starter"</span><span class="tok-o">;</span> 9572 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">PARTICIPANT</span> <span class="tok-o">=</span> <span class="tok-s">"participant"</span><span class="tok-o">;</span> 9573<span class="tok-o">}</span> 9574</td></tr></table></code></pre> 9575</div> 9576</div> 9577<div class="paragraph"> 9578<p>The BPMN standard and Activiti example authorization identities are <strong>user</strong> and <strong>group</strong>. As mentioned in the previous section, the Activiti identity management implementation is not intended for production use, but should be extended depending upon the supported authorization scheme.</p> 9579</div> 9580<div class="paragraph"> 9581<p>If additional link types are required, custom resources can be defined as extension elements with the following syntax:</p> 9582</div> 9583<div class="listingblock"> 9584<div class="content"> 9585<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 95862 95873 95884 95895 95906 95917 95928 95939</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"theTask"</span> <span class="tok-na">name=</span><span class="tok-s">"make profit"</span><span class="tok-nt">></span> 9594 <span class="tok-nt"><extensionElements></span> 9595 <span class="tok-nt"><activiti:customResource</span> <span class="tok-na">activiti:name=</span><span class="tok-s">"businessAdministrator"</span><span class="tok-nt">></span>
9596 <span class="tok-nt"><resourceAssignmentExpression></span> 9597 <span class="tok-nt"><formalExpression></span>user(kermit), group(management)<span class="tok-nt"></formalExpression></span> 9598 <span class="tok-nt"></resourceAssignmentExpression></span> 9599 <span class="tok-nt"></activiti:customResource></span> 9600 <span class="tok-nt"></extensionElements></span> 9601<span class="tok-nt"></userTask></span> 9602</td></tr></table></code></pre> 9603</div> 9604</div> 9605<div class="paragraph"> 9606<p>The custom link expressions are added to the <em>TaskDefinition</em> class:</p> 9607</div> 9608<div class="listingblock"> 9609<div class="content"> 9610<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9611 2 9612 3 9613 4 9614 5 9615 6 9616 7 9617 8 9618 9 961910 962011 962112 962213 962314 962415 962516 962617 962718 962819 962920 963021 963122 963223 963324</div></td><td class="code"><span></span><span class="tok-kd">protected</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">>></span> <span class="tok-n">customUserIdentityLinkExpressions</span> <span class="tok-o">=</span> 9634 <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">>>();</span> 9635<span class="tok-kd">protected</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">>></span> <span class="tok-n">customGroupIdentityLinkExpressions</span> <span class="tok-o">=</span> 9636 <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">>>();</span> 9637 9638<span class="tok-kd">public</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> 9639 <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">>></span> <span class="tok-nf">getCustomUserIdentityLinkExpressions</span><span class="tok-o">()</span> <span class="tok-o">{</span> 9640 <span class="tok-k">return</span> <span class="tok-n">customUserIdentityLinkExpressions</span><span class="tok-o">;</span> 9641<span class="tok-o">}</span> 9642 9643<span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">addCustomUserIdentityLinkExpression</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">identityLinkType</span><span class="tok-o">,</span> 9644 <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">></span> <span class="tok-n">idList</span><span class="tok-o">)</span> 9645 <span class="tok-n">customUserIdentityLinkExpressions</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-n">identityLinkType</span><span class="tok-o">,</span> <span class="tok-n">idList</span><span class="tok-o">);</span> 9646<span class="tok-o">}</span> 9647 9648<span class="tok-kd">public</span> <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> 9649 <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">>></span> <span class="tok-nf">getCustomGroupIdentityLinkExpressions</span><span class="tok-o">()</span> <span class="tok-o">{</span> 9650 <span class="tok-k">return</span> <span class="tok-n">customGroupIdentityLinkExpressions</span><span class="tok-o">;</span> 9651<span class="tok-o">}</span> 9652 9653<span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">addCustomGroupIdentityLinkExpression</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">identityLinkType</span><span class="tok-o">,</span>
9654 <span class="tok-n">Set</span><span class="tok-o"><</span><span class="tok-n">Expression</span><span class="tok-o">></span> <span class="tok-n">idList</span><span class="tok-o">)</span> <span class="tok-o">{</span> 9655 <span class="tok-n">customGroupIdentityLinkExpressions</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-n">identityLinkType</span><span class="tok-o">,</span> <span class="tok-n">idList</span><span class="tok-o">);</span> 9656<span class="tok-o">}</span> 9657</td></tr></table></code></pre> 9658</div> 9659</div> 9660<div class="paragraph"> 9661<p>which are populated at runtime by the <em>UserTaskActivityBehavior handleAssignments</em> method.</p> 9662</div> 9663<div class="paragraph"> 9664<p>Finally, the <em>IdentityLinkType</em> class must be extended to support the custom identity link types:</p> 9665</div> 9666<div class="listingblock"> 9667<div class="content"> 9668<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 96692 96703 96714 96725 96736 96747 96758 96769</div></td><td class="code"><span></span><span class="tok-kn">package</span> <span class="tok-nn">com.yourco.engine.task</span><span class="tok-o">;</span> 9677 9678<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">IdentityLinkType</span> 9679 <span class="tok-kd">extends</span> <span class="tok-n">org</span><span class="tok-o">.</span><span class="tok-na">activiti</span><span class="tok-o">.</span><span class="tok-na">engine</span><span class="tok-o">.</span><span class="tok-na">task</span><span class="tok-o">.</span><span class="tok-na">IdentityLinkType</span> 9680<span class="tok-o">{</span> 9681 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">ADMINISTRATOR</span> <span class="tok-o">=</span> <span class="tok-s">"administrator"</span><span class="tok-o">;</span> 9682 9683 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">EXCLUDED_OWNER</span> <span class="tok-o">=</span> <span class="tok-s">"excludedOwner"</span><span class="tok-o">;</span> 9684<span class="tok-o">}</span> 9685</td></tr></table></code></pre> 9686</div> 9687</div> 9688</div> 9689<div class="sect4"> 9690<h5 id="bpmnUserTaskUserCustomAssignmentTaskListeners">Custom Assignment via task listeners</h5> 9691<div class="paragraph"> 9692<p>In case the previous approaches are not sufficient, it is possible to delegate to custom assignment logic using a <a href="#taskListeners">task listener</a> on the create event:</p> 9693</div> 9694<div class="listingblock"> 9695<div class="content"> 9696<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 96972 96983 96994 97005</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"task1"</span> <span class="tok-na">name=</span><span class="tok-s">"My task"</span> <span class="tok-nt">></span> 9701 <span class="tok-nt"><extensionElements></span> 9702 <span class="tok-nt"><activiti:taskListener</span> <span class="tok-na">event=</span><span class="tok-s">"create"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyAssignmentHandler"</span> <span class="tok-nt">/></span> 9703 <span class="tok-nt"></extensionElements></span> 9704<span class="tok-nt"></userTask></span> 9705</td></tr></table></code></pre> 9706</div> 9707</div> 9708<div class="paragraph"> 9709<p>The <code>DelegateTask</code> that is passed to the <code>TaskListener</code> implementation, allows to set the assignee and candidate-users/groups:</p> 9710</div> 9711<div class="listingblock"> 9712<div class="content"> 9713<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9714 2 9715 3 9716 4 9717 5 9718 6 9719 7 9720 8 9721 9 972210 972311 972412 972513</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyAssignmentHandler</span> <span class="tok-kd">implements</span> <span class="tok-n">TaskListener</span> <span class="tok-o">{</span> 9726 9727 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">notify</span><span class="tok-o">(</span><span class="tok-n">DelegateTask</span> <span class="tok-n">delegateTask</span><span class="tok-o">)</span> <span class="tok-o">{</span> 9728 <span class="tok-c1">// Execute custom identity lookups here</span> 9729 9730 <span class="tok-c1">// and then for example call following methods:</span> 9731 <span class="tok-n">delegateTask</span><span class="tok-o">.</span><span class="tok-na">setAssignee</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">);</span> 9732 <span class="tok-n">delegateTask</span><span class="tok-o">.</span><span class="tok-na">
9732addCandidateUser</span><span class="tok-o">(</span><span class="tok-s">"fozzie"</span><span class="tok-o">);</span> 9733 <span class="tok-n">delegateTask</span><span class="tok-o">.</span><span class="tok-na">addCandidateGroup</span><span class="tok-o">(</span><span class="tok-s">"management"</span><span class="tok-o">);</span> 9734 <span class="tok-o">...</span> 9735 <span class="tok-o">}</span> 9736 9737<span class="tok-o">}</span> 9738</td></tr></table></code></pre> 9739</div> 9740</div> 9741<div class="paragraph"> 9742<p>When using Spring it is possible to use the custom assignment attributes as described in the section above, and delegate to a Spring bean using a <a href="#taskListeners">task listener</a> with an <a href="#springExpressions">expression</a> that listens to task <em>create</em> events. In the following example, the assignee will be set by calling the <code>findManagerOfEmployee</code> on the <code>ldapService</code> Spring bean. The <em>emp</em> parameter that is passed, is a process variable>.</p> 9743</div> 9744<div class="listingblock"> 9745<div class="content"> 9746<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"task"</span> <span class="tok-na">name=</span><span class="tok-s">"My Task"</span> <span class="tok-na">activiti:assignee=</span><span class="tok-s">"${ldapService.findManagerForEmployee(emp)}"</span><span class="tok-nt">/></span> 9747</td></tr></table></code></pre> 9748</div> 9749</div> 9750<div class="paragraph"> 9751<p>This also works similar for candidate users and groups:</p> 9752</div> 9753<div class="listingblock"> 9754<div class="content"> 9755<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"task"</span> <span class="tok-na">name=</span><span class="tok-s">"My Task"</span> <span class="tok-na">activiti:candidateUsers=</span><span class="tok-s">"${ldapService.findAllSales()}"</span><span class="tok-nt">/></span> 9756</td></tr></table></code></pre> 9757</div> 9758</div> 9759<div class="paragraph"> 9760<p>Note that this will only work if the return type of the invoked methods is <code>String</code> or <code>Collection<String></code> (for candidate users and groups):</p> 9761</div> 9762<div class="listingblock"> 9763<div class="content"> 9764<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 9765 2 9766 3 9767 4 9768 5 9769 6 9770 7 9771 8 9772 9 977310 977411</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">FakeLdapService</span> <span class="tok-o">{</span> 9775 9776 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">findManagerForEmployee</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">employee</span><span class="tok-o">)</span> <span class="tok-o">{</span> 9777 <span class="tok-k">return</span> <span class="tok-s">"Kermit The Frog"</span><span class="tok-o">;</span> 9778 <span class="tok-o">}</span> 9779 9780 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">></span> <span class="tok-nf">findAllSales</span><span class="tok-o">()</span> <span class="tok-o">{</span> 9781 <span class="tok-k">return</span> <span class="tok-n">Arrays</span><span class="tok-o">.</span><span class="tok-na">asList</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">,</span> <span class="tok-s">"gonzo"</span><span class="tok-o">,</span> <span class="tok-s">"fozzie"</span><span class="tok-o">);</span> 9782 <span class="tok-o">}</span> 9783 9784<span class="tok-o">}</span> 9785</td></tr></table></code></pre> 9786</div> 9787</div> 9788</div> 9789</div> 9790<div class="sect3"> 9791<h4 id="bpmnScriptTask">8.5.2. Script Task</h4> 9792<div class="sect4"> 9793<h5 id="bpmnScriptTaskDescription">Description</h5> 9794<div class="paragraph"> 9795<p>A script task is an automatic activity. When a process execution arrives at the script task, the corresponding script is executed.</p> 9796</div> 9797</div> 9798<div class="sect4"> 9799<h5 id="bpmnScriptTaskGraphicalNotation">Graphical Notation</h5> 9800<div class="paragraph"> 9801<p>A script task is visualized as a typical BPMN 2.0 task (rounded rectangle), with a small <em>script</em> icon in the top-left corner of the rectangle.</p> 9802</div> 9803<div class="imageblock" style="text-align: center"> 9804<div class="content"> 9805<img src="images/bpmn.scripttask.png" alt="bpmn.scripttask"> 9806</div> 9807</div> 9808</div> 9809<div class="sect4"> 9810<h5 id="bpmnScriptTaskXml">XML representation</h5> 9811<div class="paragraph"> 9812<p>A script task is defined by specifying the <strong>script</strong> and the <strong>scriptFormat</strong>.</p> 9813</div> 9814<div class="listingblock"> 9815<div class="content"> 9816<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 98172 98183 98194 98205 98216 98227 98238</div></td><td class="code"><span></span><span class="tok-nt"><scriptTask</span> <span class="tok-na">id=</span><span class="tok-s">"theScriptTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Execute script"</span> <span class="tok-na">scriptFormat=</span><span class="tok-s">"groovy"</span><span class="tok-nt">></span> 9824 <span class="tok-nt"><script></span> 9825 sum = 0 9826 for ( i in inputArray ) { 9827 sum += i 9828 } 9829 <span class="tok-nt"></script></span> 9830<span class="tok-nt"></scriptTask></span> 9831</td></tr></table></code></pre> 9832</div> 9833</div> 9834<div class="paragraph"> 9835<p>The value of the <strong>scriptFormat</strong> attribute must be a name that is compatible with the <a href="http://jcp.org/en/jsr/detail?id=223">
9835JSR-223</a> (scripting for the Java platform). By default JavaScript is included in every JDK and as such doesn’t need any additional jars. If you want to use another (JSR-223 compatible) scripting engine, it is sufficient to add the corresponding jar to the classpath and use the appropriate name. For example, the Activiti unit tests often use Groovy because the syntax is pretty similar to that of Java.</p> 9836</div> 9837<div class="paragraph"> 9838<p>Do note that the Groovy scripting engine is bundled with the groovy-all jar. Before version 2.0, the scripting engine was part of the regular Groovy jar. As such, one must now add following dependency:</p> 9839</div> 9840<div class="listingblock"> 9841<div class="content"> 9842<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 98432 98443 98454 98465</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 9847 <span class="tok-nt"><groupId></span>org.codehaus.groovy<span class="tok-nt"></groupId></span> 9848 <span class="tok-nt"><artifactId></span>groovy-all<span class="tok-nt"></artifactId></span> 9849 <span class="tok-nt"><version></span>2.x.x<span class="tok-nt"><version></span> 9850<span class="tok-nt"></dependency></span> 9851</td></tr></table></code></pre> 9852</div> 9853</div> 9854</div> 9855<div class="sect4"> 9856<h5 id="bpmnScriptTaskVariables">Variables in scripts</h5> 9857<div class="paragraph"> 9858<p>All process variables that are accessible through the execution that arrives in the script task, can be used within the script. In the example, the script variable <em>'inputArray'</em> is in fact a process variable (an array of integers).</p> 9859</div> 9860<div class="listingblock"> 9861<div class="content"> 9862<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 98632 98643 98654 98665 98676</div></td><td class="code"><span></span><span class="tok-nt"><script></span> 9868 sum = 0 9869 for ( i in inputArray ) { 9870 sum += i 9871 } 9872<span class="tok-nt"></script></span> 9873</td></tr></table></code></pre> 9874</div> 9875</div> 9876<div class="paragraph"> 9877<p>It’s also possible to set process variables in a script, simply by calling <em>execution.setVariable("variableName", variableValue)</em>. By default, no variables are stored automatically (<strong>Note: before Activiti 5.12 this was the case!</strong>). It is possible to automatically store any variable defined in the script (e.g. <em>sum</em> in the example above) by setting the property <code>autoStoreVariables</code> on the <code>scriptTask</code> to <code>true</code>. However, <strong>the best practice is not to do this and use an explicit execution.setVariable() call</strong>, as on some recent versions of the JDK auto storing of variables does not work for some scripting languages. See <a href="http://www.jorambarrez.be/blog/2013/03/25/bug-on-jdk-1-7-0_17-when-using-scripttask-in-activiti/">this link</a> for more details.</p> 9878</div> 9879<div class="listingblock"> 9880<div class="content"> 9881<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><scriptTask</span> <span class="tok-na">id=</span><span class="tok-s">"script"</span> <span class="tok-na">scriptFormat=</span><span class="tok-s">"JavaScript"</span> <span class="tok-na">activiti:autoStoreVariables=</span><span class="tok-s">"false"</span><span class="tok-nt">></span> 9882</td></tr></table></code></pre> 9883</div> 9884</div> 9885<div class="paragraph"> 9886<p>The default of this parameter is <code>false</code>, meaning that if the parameter is omitted from the script task definition, all the declared variables will only exist during the duration of the script.</p> 9887</div> 9888<div class="paragraph"> 9889<p>Example on how to set a variable in a script:</p> 9890</div> 9891<div class="listingblock"> 9892<div class="content"> 9893<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 98942 98953 98964</div></td><td class="code"><span></span><span class="tok-nt"><script></span> 9897 def scriptVar = "test123" 9898 execution.setVariable("myVar", scriptVar) 9899<span class="tok-nt"></script></span> 9900</td></tr></table></code></pre> 9901</div> 9902</div> 9903<div class="paragraph"> 9904<p>Note: the following names are reserved and <strong>cannot be used</strong> as variable names: <strong>out, out:print, lang:import, context, elcontext</strong>.</p> 9905</div> 9906</div> 9907<div class="sect4"> 9908<h5 id="bpmnScriptTaskResultValue">Script results</h5> 9909<div class="paragraph"> 9910<p>The return value of a script task can be assigned to an already existing or to a new process variable by specifying the process variable name as a literal value for the <em>'activiti:resultVariable'</em> attribute of a script task definition. Any existing value for a specific process variable will be overwritten by the result value of the script execution. When not specifying a result variable name, the script result value gets ignored.</p> 9911</div> 9912<div class="listingblock"> 9913<div class="content"> 9914<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 99152 99163</div></td><td class="code"><span></span><span class="tok-nt"><scriptTask</span> <span class="tok-na">id=</span><span class="tok-s">"theScriptTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Execute script"</span> <span class="tok-na">scriptFormat=</span><span class="tok-s">"juel"</span> <span class="tok-na">activiti:resultVariable=</span><span class="tok-s">"myVar"</span><span class="tok-nt">></span> 9917 <span class="tok-nt"><script></span>#{echo}<span class="tok-nt"></script></span> 9918<span class="tok-nt"></scriptTask></span> 9919</td></tr></table></code></pre> 9920</div> 9921</div> 9922<div class="paragraph"> 9923<p>In the above example, the result of the script execution (the value of the resolved expression <em>'#{echo}'</em>) is set to the process variable named <em>'myVar'</em> after the script completes.</p> 9924</div> 9925</div> 9926<div class="sect4"> 9927<h5 id="_security">Security</h5> 9928<div class="paragraph"> 9929<p>It is also possible when using <em>javascript</em> as scripting language to use <em><em>secure scripting</em></em>. See the <a href="#advancedSecureScripting">secure scripting section</a>.</p> 9930</div> 9931</div> 9932</div> 9933<div class="sect3"> 9934<h4 id="bpmnJavaServiceTask">8.5.3. Java Service Task</h4> 9935<div class="sect4"> 9936<h5 id="bpmnJavaServiceTaskDescription">Description</h5> 9937<div class="paragraph"> 9938<p>A Java service task is used to invoke an external Java class.</p> 9939</div> 9940</div> 9941<div class="sect4"> 9942<h5 id="bpmnJavaServiceTaskGraphicalNotation">Graphical Notation</h5> 9943<div class="paragraph"> 9944<p>A service task is visualized as a rounded rectangle with a small gear icon in the top-left corner.</p> 9945</div> 9946<div class="imageblock" style="text-align: center"> 9947<div class="content"> 9948<img src="images/bpmn.java.service.task.png" alt="bpmn.java.service.task"> 9949</div> 9950</div> 9951</div> 9952<div class="sect4"> 9953<h5 id="bpmnJavaServiceTaskXML">XML representation</h5> 9954<div class="paragraph"> 9955<p>There are 4 ways of declaring how to invoke Java logic:</p> 9956</div> 9957<div class="ulist"> 9958<ul> 9959<li> 9960<p>Specifying a class that implements JavaDelegate or ActivityBehavior</p> 9961</li> 9962<li> 9963<p>Evaluating an expression that resolves to a delegation object</p> 9964</li> 9965<li> 9966<p>Invoking a method expression</p> 9967</li> 9968<li> 9969<p>Evaluating a value expression</p> 9970</li> 9971</ul> 9972</div> 9973<div class="paragraph"> 9974<p>To specify a class that is called during process execution, the fully qualified classname needs to be provided by the <strong><em>activiti:class</em></strong> attribute.</p> 9975</div> 9976<div class="listingblock"> 9977<div class="content"> 9978<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 99792 99803</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span>
9981 <span class="tok-na">name=</span><span class="tok-s">"My Java Service Task"</span> 9982 <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.MyJavaDelegate"</span> <span class="tok-nt">/></span> 9983</td></tr></table></code></pre> 9984</div> 9985</div> 9986<div class="paragraph"> 9987<p>See <a href="#bpmnJavaServiceTaskImplementation">the implementation section</a> for more details on how to use such a class.</p> 9988</div> 9989<div class="paragraph"> 9990<p>It is also possible to use an expression that resolves to an object. This object must follow the same rules as objects that are created when the <code>activiti:class</code> attribute is used (see <a href="#bpmnJavaServiceTaskImplementation">further</a>).</p> 9991</div> 9992<div class="listingblock"> 9993<div class="content"> 9994<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${delegateExpressionBean}"</span> <span class="tok-nt">/></span> 9995</td></tr></table></code></pre> 9996</div> 9997</div> 9998<div class="paragraph"> 9999<p>Here, the <code>delegateExpressionBean</code> is a bean that implements the <code>JavaDelegate</code> interface, defined in for example the Spring container.</p> 10000</div> 10001<div class="paragraph"> 10002<p>To specify a UEL method expression that should be evaluated, use attribute <strong>activiti:expression</strong>.</p> 10003</div> 10004<div class="listingblock"> 10005<div class="content"> 10006<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 100072 100083</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span> 10009 <span class="tok-na">name=</span><span class="tok-s">"My Java Service Task"</span> 10010 <span class="tok-na">activiti:expression=</span><span class="tok-s">"#{printer.printMessage()}"</span> <span class="tok-nt">/></span> 10011</td></tr></table></code></pre> 10012</div> 10013</div> 10014<div class="paragraph"> 10015<p>Method <code>printMessage</code> (without parameters) will be called on the named object called <code>printer</code>.</p> 10016</div> 10017<div class="paragraph"> 10018<p>It’s also possible to pass parameters with an method used in the expression.</p> 10019</div> 10020<div class="listingblock"> 10021<div class="content"> 10022<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 100232 100243</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span> 10025 <span class="tok-na">name=</span><span class="tok-s">"My Java Service Task"</span> 10026 <span class="tok-na">activiti:expression=</span><span class="tok-s">"#{printer.printMessage(execution, myVar)}"</span> <span class="tok-nt">/></span> 10027</td></tr></table></code></pre> 10028</div> 10029</div> 10030<div class="paragraph"> 10031<p>Method <code>printMessage</code> will be called on the object named <code>printer</code>. The first parameter passed is the <code>DelegateExecution</code>, which is available in the expression context by default available as <code>execution</code>. The second parameter passed, is the value of the variable with name <code>myVar</code> in the current execution.</p> 10032</div> 10033<div class="paragraph"> 10034<p>To specify a UEL value expression that should be evaluated, use attribute <strong>activiti:expression</strong>.</p> 10035</div> 10036<div class="listingblock"> 10037<div class="content"> 10038<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 100392 100403</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span>
10041 <span class="tok-na">name=</span><span class="tok-s">"My Java Service Task"</span> 10042 <span class="tok-na">activiti:expression=</span><span class="tok-s">"#{split.ready}"</span> <span class="tok-nt">/></span> 10043</td></tr></table></code></pre> 10044</div> 10045</div> 10046<div class="paragraph"> 10047<p>The getter method of property <code>ready</code>, <code>getReady</code> (without parameters), will be called on the named bean called <code>split</code>. The named objects are resolved in the execution’s process variables and (if applicable) in the Spring context.</p> 10048</div> 10049</div> 10050<div class="sect4"> 10051<h5 id="bpmnJavaServiceTaskImplementation">Implementation</h5> 10052<div class="paragraph"> 10053<p>To implement a class that can be called during process execution, this class needs to implement the <em>org.activiti.engine.delegate.JavaDelegate</em> interface and provide the required logic in the <em>execute</em> method. When process execution arrives at this particular step, it will execute this logic defined in that method and leave the activity in the default BPMN 2.0 way.</p> 10054</div> 10055<div class="paragraph"> 10056<p>Let’s create for example a Java class that can be used to change a process variable String to uppercase. This class needs to implement the <em>org.activiti.engine.delegate.JavaDelegate</em> interface, which requires us to implement the <em>execute(DelegateExecution)</em> method. It’s this operation that will be called by the engine and which needs to contain the business logic. Process instance information such as process variables and other can be accessed and manipulated through the <a href="http://activiti.org/javadocs/org/activiti/engine/delegate/DelegateExecution.html">DelegateExecution</a> interface (click on the link for a detailed Javadoc of its operations).</p> 10057</div> 10058<div class="listingblock"> 10059<div class="content"> 10060<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 100612 100623 100634 100645 100656 100667 100678 100689</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ToUppercase</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10069 10070 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 10071 <span class="tok-n">String</span> <span class="tok-n">var</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">)</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getVariable</span><span class="tok-o">(</span><span class="tok-s">"input"</span><span class="tok-o">);</span> 10072 <span class="tok-n">var</span> <span class="tok-o">=</span> <span class="tok-n">var</span><span class="tok-o">.</span><span class="tok-na">toUpperCase</span><span class="tok-o">();</span> 10073 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"input"</span><span class="tok-o">,</span> <span class="tok-n">var</span><span class="tok-o">);</span> 10074 <span class="tok-o">}</span> 10075 10076<span class="tok-o">}</span> 10077</td></tr></table></code></pre> 10078</div> 10079</div> 10080<div class="paragraph"> 10081<p>Note: there will be <strong>only one instance of that Java class created for the serviceTask it is defined on</strong>. All process-instances share the same class instance that will be used to call <em>execute(DelegateExecution)</em>. This means that the class must not use any member variables and must be thread-safe, since it can be executed simultaneously from different threads. This also influences the way <a href="#serviceTaskFieldInjection">Field injection</a> is handled.</p> 10082</div> 10083<div class="paragraph"> 10084<p>The classes that are referenced in the process definition (i.e. by using <code>activiti:class</code>) are <strong>NOT instantiated during deployment</strong>. Only when a process execution arrives for the first time at the point in the process where the class is used, an instance of that class will be created. If the class cannot be found, an <code>ActivitiException</code> will be thrown. The reasoning for this is that the environment (and more specifically the <em>classpath</em>) when you are deploying is often different from the actual runtime environment. For example when using <em>ant</em> or the business archive upload in Activiti Explorer to deploy processes, the classpath does not contain the referenced classes.</p> 10085</div> 10086<div class="paragraph"> 10087<p><a href="#internal">[INTERNAL: non-public implementation classes]</a> It is also possible to provide a class that implements the <em>org.activiti.engine.impl.pvm.delegate.ActivityBehavior</em> interface. Implementations have then access to the more powerful <em>ActivityExecution</em> that for example also allows to influence the control flow of the process. Note however that this is not a very good practice, and should be avoided as much as possible. So, it is advised to use the <em>ActivityBehavior</em> interface only for advanced use cases and if you know exactly what you’re doing.</p> 10088</div> 10089</div> 10090<div class="sect4"> 10091<h5 id="serviceTaskFieldInjection">Field Injection</h5> 10092<div class="paragraph"> 10093<p>It’s possible to inject values into the fields of the delegated classes. The following types of injection are supported:</p> 10094</div> 10095<div class="ulist"> 10096<ul> 10097<li> 10098<p>Fixed string values</p> 10099</li> 10100<li> 10101<p>Expressions</p> 10102</li> 10103</ul> 10104</div> 10105<div class="paragraph"> 10106<p>If available, the value is injected through a public setter method on your delegated class, following the Java Bean naming conventions (e.g. field <code>firstName</code> has setter <code>setFirstName(…​)</code>). If no setter is available for that field, the value of private member will be set on the delegate. SecurityManagers in some environments don’t allow modifying private fields, so it’s safer to expose a public setter-method for the fields you want to have injected.</p> 10107</div> 10108<div class="paragraph"> 10109<p><strong>Regardless of the type of value declared in the process-definition, the type of the setter/private field on the injection target should always be <code>org.activiti.engine.delegate.Expression</code>
10109. When the expression is resolved it can be cast to the appropriate type.</strong></p> 10110</div> 10111<div class="paragraph"> 10112<p>Field injection is supported when using the <em>'actviiti:class'</em> attribute. Field injection is also possible when using the <em>activiti:delegateExpression</em> attribute, however special rules with regards to thread-safety apply (see next section).</p> 10113</div> 10114<div class="paragraph"> 10115<p>The following code snippet shows how to inject a constant value into a field declared on the class. Note that we need to <strong>declare a <em>extensionElements</em> XML element before the actual field injection declarations</strong>, which is a requirement of the BPMN 2.0 XML Schema.</p> 10116</div> 10117<div class="listingblock"> 10118<div class="content"> 10119<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 101202 101213 101224 101235 101246 101257</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span> 10126 <span class="tok-na">name=</span><span class="tok-s">"Java service invocation"</span> 10127 <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.examples.bpmn.servicetask.ToUpperCaseFieldInjected"</span><span class="tok-nt">></span> 10128 <span class="tok-nt"><extensionElements></span> 10129 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"text"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"Hello World"</span> <span class="tok-nt">/></span> 10130 <span class="tok-nt"></extensionElements></span> 10131<span class="tok-nt"></serviceTask></span> 10132</td></tr></table></code></pre> 10133</div> 10134</div> 10135<div class="paragraph"> 10136<p>The class <code>ToUpperCaseFieldInjected</code> has a field <code>text</code> which is of type <code>org.activiti.engine.delegate.Expression</code>. When calling <code>text.getValue(execution)</code>, the configured string value <code>Hello World</code> will be returned:</p> 10137</div> 10138<div class="listingblock"> 10139<div class="content"> 10140<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 101412 101423 101434 101445 101456 101467 101478 101489</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ToUpperCaseFieldInjected</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10149 10150 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">text</span><span class="tok-o">;</span> 10151 10152 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-o">{</span> 10153 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"var"</span><span class="tok-o">,</span> <span class="tok-o">((</span><span class="tok-n">String</span><span class="tok-o">)</span><span class="tok-n">text</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">)).</span><span class="tok-na">toUpperCase</span><span class="tok-o">());</span> 10154 <span class="tok-o">}</span> 10155 10156<span class="tok-o">}</span> 10157</td></tr></table></code></pre> 10158</div> 10159</div> 10160<div class="paragraph"> 10161<p>Alternatively, for longs texts (e.g. an inline e-mail) the <em>'activiti:string'</em> sub element can be used:</p> 10162</div> 10163<div class="listingblock"> 10164<div class="content"> 10165<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10166 2 10167 3 10168 4 10169 5 10170 6 10171 7 10172 8 10173 9 1017410 1017511</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span> 10176 <span class="tok-na">name=</span><span class="tok-s">"Java service invocation"</span> 10177 <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.examples.bpmn.servicetask.ToUpperCaseFieldInjected"</span><span class="tok-nt">></span> 10178 <span class="tok-nt"><extensionElements></span> 10179 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"text"</span><span class="tok-nt">></span>
10180 <span class="tok-nt"><activiti:string></span> 10181 This is a long string with a lot of words and potentially way longer even! 10182 <span class="tok-nt"></activiti:string></span> 10183 <span class="tok-nt"></activiti:field></span> 10184 <span class="tok-nt"></extensionElements></span> 10185<span class="tok-nt"></serviceTask></span> 10186</td></tr></table></code></pre> 10187</div> 10188</div> 10189<div class="paragraph"> 10190<p>To inject values that are dynamically resolved at runtime, expressions can be used. Those expressions can use process variables, or Spring defined beans (if Spring is used). As noted in <a href="#bpmnJavaServiceTaskImplementation">Service Task Implementation</a>, an instance of the Java class is shared among all process-instances in a service task when using the <em>activiti:class</em> attribute. To have dynamic injection of values in fields, you can inject value and method expressions in a <code>org.activiti.engine.delegate.Expression</code> which can be evaluated/invoked using the <code>DelegateExecution</code> passed in the <code>execute</code> method.</p> 10191</div> 10192<div class="paragraph"> 10193<p>The example class below uses the injected expressions and resolves them using the current <code>DelegateExecution</code>. A <em>generBean</em> method call is used while passing the <em>gender</em> variable. Full code and test can be found in <code>org.activiti.examples.bpmn.servicetask.JavaServiceTaskTest.testExpressionFieldInjection</code></p> 10194</div> 10195<div class="listingblock"> 10196<div class="content"> 10197<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10198 2 10199 3 10200 4 10201 5 10202 6 10203 7 10204 8 10205 9 1020610 1020711 1020812</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span> <span class="tok-na">name=</span><span class="tok-s">"Java service invocation"</span> 10209 <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.examples.bpmn.servicetask.ReverseStringsFieldInjected"</span><span class="tok-nt">></span> 10210 10211 <span class="tok-nt"><extensionElements></span> 10212 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"text1"</span><span class="tok-nt">></span> 10213 <span class="tok-nt"><activiti:expression></span>${genderBean.getGenderString(gender)}<span class="tok-nt"></activiti:expression></span> 10214 <span class="tok-nt"></activiti:field></span> 10215 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"text2"</span><span class="tok-nt">></span> 10216 <span class="tok-nt"><activiti:expression></span>Hello ${gender == 'male' ? 'Mr.' : 'Mrs.'} ${name}<span class="tok-nt"></activiti:expression></span> 10217 <span class="tok-nt"></activiti:field></span> 10218 <span class="tok-nt"></ extensionElements></span> 10219<span class="tok-nt"></ serviceTask></span> 10220</td></tr></table></code></pre> 10221</div> 10222</div> 10223<div class="listingblock"> 10224<div class="content"> 10225<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10226 2 10227 3 10228 4 10229 5 10230 6 10231 7 10232 8 10233 9 1023410 1023511 1023612 1023713</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ReverseStringsFieldInjected</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10238 10239 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">text1</span><span class="tok-o">;</span> 10240 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">text2</span><span class="tok-o">;</span> 10241 10242 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-o">{</span> 10243 <span class="tok-n">String</span> <span class="tok-n">value1</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">)</span> <span class="tok-n">text1</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10244 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"
10244var1"</span><span class="tok-o">,</span> <span class="tok-k">new</span> <span class="tok-n">StringBuffer</span><span class="tok-o">(</span><span class="tok-n">value1</span><span class="tok-o">).</span><span class="tok-na">reverse</span><span class="tok-o">().</span><span class="tok-na">toString</span><span class="tok-o">());</span> 10245 10246 <span class="tok-n">String</span> <span class="tok-n">value2</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">)</span> <span class="tok-n">text2</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10247 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"var2"</span><span class="tok-o">,</span> <span class="tok-k">new</span> <span class="tok-n">StringBuffer</span><span class="tok-o">(</span><span class="tok-n">value2</span><span class="tok-o">).</span><span class="tok-na">reverse</span><span class="tok-o">().</span><span class="tok-na">toString</span><span class="tok-o">());</span> 10248 <span class="tok-o">}</span> 10249<span class="tok-o">}</span> 10250</td></tr></table></code></pre> 10251</div> 10252</div> 10253<div class="paragraph"> 10254<p>Alternatively, you can also set the expressions as an attribute instead of a child-element, to make the XML less verbose.</p> 10255</div> 10256<div class="listingblock"> 10257<div class="content"> 10258<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 102592</div></td><td class="code"><span></span><span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"text1"</span> <span class="tok-na">expression=</span><span class="tok-s">"${genderBean.getGenderString(gender)}"</span> <span class="tok-nt">/></span> 10260<span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"text1"</span> <span class="tok-na">expression=</span><span class="tok-s">"Hello ${gender == 'male' ? 'Mr.' : 'Mrs.'} ${name}"</span> <span class="tok-nt">/></span> 10261</td></tr></table></code></pre> 10262</div> 10263</div> 10264</div> 10265<div class="sect4"> 10266<h5 id="serviceTaskFieldInjectionThreadSafety">Field injection and thread safety</h5> 10267<div class="paragraph"> 10268<p>In general, using service tasks with Java delegates and field injections are thread-safe. However, there are a few situations where thread-safety is not guaranteed, depending on the setup or environment Activiti is running in.</p> 10269</div> 10270<div class="paragraph"> 10271<p>When using the <em>activiti:class</em> attribute, using field injection is always thread safe. For each service task that references a certain class, a new instance will be instantiated and fields will be injected once when the instance is created. Reusing the same class in multiple times in different tasks or process definitions is no problem.</p> 10272</div> 10273<div class="paragraph"> 10274<p>When using the <em>activiti:expression</em> attribute, using field injection is not possible. Parameters are passed via method calls and these are always thread-safe.</p> 10275</div> 10276<div class="paragraph"> 10277<p>When using the <em>activiti:delegateExpression</em> attribute, the thread-safety of the delegate instance will depend on how the expression is resolved. If the delegate expression is reused in various tasks and/or process definitions and the expression always returns the same instance, using field injection <strong>is not thread-safe</strong>. Let’s look at a few examples to clarify.</p> 10278</div> 10279<div class="paragraph"> 10280<p>Suppose the expression is <em>${factory.createDelegate(someVariable)}</em>, where factory is a Java bean known to the engine (for example a Spring bean when using the Spring integration) that creates a new instance each time the expression is resolved. When using field injection in this case, there is no problem with regards to thread-safety: each time the expression is resolved, the fields are injected on this new instance.</p> 10281</div> 10282<div class="paragraph"> 10283<p>However, suppose the expression is <em>${someJavaDelegateBean}</em> that resolves to an implementation of the JavaDelegate class and we’re running in an environment that creates singleton instances of each bean (like Spring, but many others too). When using this expression in different tasks and/or process definitions, the expression will always be resolved to the same instance. In this case, using field injection is not thread-safe. For example:</p> 10284</div> 10285<div class="listingblock"> 10286<div class="content"> 10287<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10288 2 10289 3 10290 4 10291 5 10292 6 10293 7 10294 8 10295 9 1029610 1029711 1029812 1029913</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask1"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${someJavaDelegateBean}"</span><span class="tok-nt">></span> 10300 <span class="tok-nt"><extensionElements></span>
10301 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"someField"</span> <span class="tok-na">expression=</span><span class="tok-s">"${input * 2}"</span><span class="tok-nt">/></span> 10302 <span class="tok-nt"></extensionElements></span> 10303<span class="tok-nt"></serviceTask></span> 10304 10305<span class="tok-c"><!-- other process definition elements --></span> 10306 10307<span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask2"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${someJavaDelegateBean}"</span><span class="tok-nt">></span> 10308 <span class="tok-nt"><extensionElements></span> 10309 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"someField"</span> <span class="tok-na">expression=</span><span class="tok-s">"${input * 2000}"</span><span class="tok-nt">/></span> 10310 <span class="tok-nt"></extensionElements></span> 10311<span class="tok-nt"></serviceTask></span> 10312</td></tr></table></code></pre> 10313</div> 10314</div> 10315<div class="paragraph"> 10316<p>This example snippet has two service tasks that use the same delegate expression, but injects different values for the <em>Expression</em> field. <strong>If the expression resolves to the same instance, there can be race conditions in concurrent scenarios</strong> when it comes to injecting the field <em>someField</em> when the processes are executed.</p> 10317</div> 10318<div class="paragraph"> 10319<p>The easiest solution to solve this, is to either</p> 10320</div> 10321<div class="ulist"> 10322<ul> 10323<li> 10324<p>rewrite the Java delegate to use an expression and passing the needed data to the delegate via a method arguments.</p> 10325</li> 10326<li> 10327<p>return a new instance of the delegate class each time the delegate expression is resolved. For example when using Spring, this means that the scope of the bean must be set to <strong>prototype</strong> (for example by adding the @Scope(SCOPE_PROTOTYPE) annotation to the delegate class)</p> 10328</li> 10329</ul> 10330</div> 10331<div class="paragraph"> 10332<p>As of Activiti version 5.21, the process engine configuration can be configured in a way to disable the use of field injection on delegate epxressions, by setting the value of the <em>delegateExpressionFieldInjectionMode</em> property (which takes one of the values in the <em>org.activiti.engine.imp.cfg.DelegateExpressionFieldInjectionMode</em> enum).</p> 10333</div> 10334<div class="paragraph"> 10335<p>Following settings are possible:</p> 10336</div> 10337<div class="ulist"> 10338<ul> 10339<li> 10340<p><strong>DISABLED</strong> : fully disables field injection when using delegate expressions. No field injection will be attempted. This is the safest mode, when it comes to thread-safety.</p> 10341</li> 10342<li> 10343<p><strong>COMPATIBILITY</strong>: in this mode, the behavior will be exactly as it was before version 5.21: field injection is possible when using delegate expressions and an exception will be thrown when the fields are not defined on the delegate class. This is of course the least safe mode with regards to thread-safety, but it can be needed for backwards compatibility or can be used safely when the delegate expression is used only on one task in a set of process definitions (and thus no concurrent race conditions can happen).</p> 10344</li> 10345<li> 10346<p><strong>MIXED</strong>: Allows injection when using delegateExpressions but will not throw an exception when the fields are not defined on the delegate. This allows for mixed behaviors where some delegates have injection (for example because they are not singletons) and some don’t.</p> 10347</li> 10348<li> 10349<p><strong>The default mode for Activiti version 5.x is COMPATIBILITY.</strong></p> 10350</li> 10351<li> 10352<p><strong>The default mode for Activiti version 6.x is MIXED.</strong></p> 10353</li> 10354</ul> 10355</div> 10356<div class="paragraph"> 10357<p>For example, suppose that we’re using <em>MIXED</em> mode and we’re using the Spring integration. Suppose that we have following beans in the Spring configuration:</p> 10358</div> 10359<div class="listingblock"> 10360<div class="content"> 10361<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 103622 103633 103644 103655 103666</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"singletonDelegateExpressionBean"</span> 10367 <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.test.fieldinjection.SingletonDelegateExpressionBean"</span> <span class="tok-nt">/></span> 10368 10369<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"prototypeDelegateExpressionBean"</span> 10370 <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.test.fieldinjection.PrototypeDelegateExpressionBean"</span> 10371 <span class="tok-na">scope=</span><span class="tok-s">"prototype"</span> <span class="tok-nt">/></span> 10372</td></tr></table></code></pre> 10373</div> 10374</div> 10375<div class="paragraph"> 10376<p>The first bean is a regular Spring bean and thus a singleton. The second one has <em>prototype</em> as scope, and the Spring container will return a new instance every time the bean is requested.</p> 10377</div> 10378<div class="paragraph"> 10379<p>Given following process definition:</p> 10380</div> 10381<div class="listingblock"> 10382<div class="content"> 10383<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10384 2 10385 3 10386 4 10387 5 10388 6 10389 7 10390 8 10391 9 1039210 1039311 1039412 1039513 1039614 1039715 1039816 1039917 1040018 1040119 1040220 1040321 1040422 1040523 1040624 1040725 1040826 1040927 1041028 1041129 1041230 1041331</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask1"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${prototypeDelegateExpressionBean}"</span><span class="tok-nt">></span> 10414 <span class="tok-nt"><extensionElements></span> 10415 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldA"</span> <span class="tok-na">expression=</span><span class="tok-s">"${input * 2}"</span><span class="tok-nt">/></span> 10416 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldB"</span> <span class="tok-na">expression=</span><span class="tok-s">"${1 + 1}"</span><span class="tok-nt">/></span> 10417 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariableName"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"resultServiceTask1"</span><span class="tok-nt">/></span> 10418 <span class="tok-nt"></extensionElements></span> 10419<span class="tok-nt"></serviceTask></span> 10420 10421<span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask2"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${prototypeDelegateExpressionBean}"</span><span class="tok-nt">></span> 10422 <span class="tok-nt"><extensionElements></span> 10423 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldA"</span> <span class="tok-na">expression=</span><span class="tok-s">"${123}"</span><span class="tok-nt">/></span> 10424 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldB"</span> <span class="tok-na">expression=</span><span class="tok-s">"${456}"</span><span class="tok-nt">/></span> 10425 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariableName"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"resultServiceTask2"</span><span class="tok-nt">/></span> 10426 <span class="tok-nt"></extensionElements></span> 10427<span class="tok-nt"></serviceTask></span> 10428 10429<span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask3"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${singletonDelegateExpressionBean}"</span><span class="tok-nt">></span> 10430 <span class="tok-nt"><extensionElements></span> 10431 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldA"</span> <span class="tok-na">expression=</span><span class="tok-s">"${input * 2}"</span><span class="tok-nt">/></span> 10432 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldB"</span> <span class="tok-na">expression=</span><span class="tok-s">"${1 + 1}"</span><span class="tok-nt">/></span> 10433 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariableName"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"resultServiceTask1"</span><span class="tok-nt">/></span> 10434 <span class="tok-nt"></extensionElements></span> 10435<span class="tok-nt"></serviceTask></span> 10436 10437<span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask4"</span> <span class="tok-na">activiti:delegateExpression=</span><span class="tok-s">"${singletonDelegateExpressionBean}"</span><span class="tok-nt">></span> 10438 <span class="tok-nt"><extensionElements></span> 10439 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldA"</span> <span class="tok-na">expression=</span><span class="tok-s">"${123}"</span><span class="tok-nt">/></span> 10440 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fieldB"</span> <span class="tok-na">expression=</span><span class="tok-s">"${456}"</span><span class="tok-nt">/></span> 10441 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariableName"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"resultServiceTask2"</span><span class="tok-nt">/></span> 10442 <span class="tok-nt"></extensionElements></span> 10443<span class="tok-nt"></serviceTask></span> 10444</td></tr></table></code></pre> 10445</div> 10446</div> 10447<div class="paragraph"> 10448<p>We’ve got four service tasks, where the first and the second use the <em>${prototypeDelegateExpressionBean}</em> delegate expression and the third and fourth use the <em>${singletonDelegateExpressionBean}</em> delegate expression.</p> 10449</div> 10450<div class="paragraph"> 10451<p>Let’s look at the prototype bean first:</p> 10452</div> 10453<div class="listingblock"> 10454<div class="content"> 10455<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10456 2 10457 3 10458 4 10459 5 10460 6 10461 7 10462 8 10463 9 1046410 1046511 1046612 1046713 1046814 1046915 1047016 1047117 1047218 1047319 1047420 1047521 1047622 1047723</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">PrototypeDelegateExpressionBean</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10478 10479 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-n">AtomicInteger</span> <span class="tok-n">INSTANCE_COUNT</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">AtomicInteger</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">);</span> 10480 10481 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">fieldA</span><span class="tok-o">;</span> 10482 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">fieldB</span><span class="tok-o">;</span> 10483 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">resultVariableName</span><span class="tok-o">;</span> 10484 10485 <span class="tok-kd">public</span> <span class="tok-nf">PrototypeDelegateExpressionBean</span><span class="tok-o">()</span> <span class="tok-o">{</span> 10486 <span class="tok-n">INSTANCE_COUNT</span><span class="tok-o">.</span><span class="tok-na">incrementAndGet</span><span class="tok-o">();</span> 10487 <span class="tok-o">}</span> 10488 10489 <span class="tok-nd">
10489@Override</span> 10490 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 10491 10492 <span class="tok-n">Number</span> <span class="tok-n">fieldAValue</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">Number</span><span class="tok-o">)</span> <span class="tok-n">fieldA</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10493 <span class="tok-n">Number</span> <span class="tok-n">fieldValueB</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">Number</span><span class="tok-o">)</span> <span class="tok-n">fieldB</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10494 10495 <span class="tok-kt">int</span> <span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-n">fieldAValue</span><span class="tok-o">.</span><span class="tok-na">intValue</span><span class="tok-o">()</span> <span class="tok-o">+</span> <span class="tok-n">fieldValueB</span><span class="tok-o">.</span><span class="tok-na">intValue</span><span class="tok-o">();</span> 10496 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-n">resultVariableName</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">).</span><span class="tok-na">toString</span><span class="tok-o">(),</span> <span class="tok-n">result</span><span class="tok-o">);</span> 10497 <span class="tok-o">}</span> 10498 10499<span class="tok-o">}</span> 10500</td></tr></table></code></pre> 10501</div> 10502</div> 10503<div class="paragraph"> 10504<p>When we check the <em>INSTANCE_COUNT</em> after running a process instance of the process definition above, we’ll get <em>two</em> back, as a new instance is created every time <em>${prototypeDelegateExpressionBean}</em> is resolved. Fields can be injected without any problem here and we can see the three <em>Expression</em> member fields here.</p> 10505</div> 10506<div class="paragraph"> 10507<p>The singleton bean, however, looks slightly different:</p> 10508</div> 10509<div class="listingblock"> 10510<div class="content"> 10511<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10512 2 10513 3 10514 4 10515 5 10516 6 10517 7 10518 8 10519 9 1052010 1052111 1052212 1052313 1052414 1052515 1052616 1052717 1052818 1052919 1053020 1053121 1053222 1053323 1053424</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">SingletonDelegateExpressionBean</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10535 10536 <span class="tok-kd">public</span> <span class="tok-kd">static</span> <span class="tok-n">AtomicInteger</span> <span class="tok-n">INSTANCE_COUNT</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">AtomicInteger</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">);</span> 10537 10538 <span class="tok-kd">public</span> <span class="tok-nf">SingletonDelegateExpressionBean</span><span class="tok-o">()</span> <span class="tok-o">{</span> 10539 <span class="tok-n">INSTANCE_COUNT</span><span class="tok-o">.</span><span class="tok-na">incrementAndGet</span><span class="tok-o">();</span> 10540 <span class="tok-o">}</span> 10541 10542 <span class="tok-nd">@Override</span> 10543 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 10544 10545 <span class="tok-n">Expression</span> <span class="tok-n">fieldAExpression</span> <span class="tok-o">=</span> <span class="tok-n">DelegateHelper</span><span class="tok-o">.</span><span class="tok-na">getFieldExpression</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">,</span> <span class="tok-s">"fieldA"</span><span class="tok-o">);</span> 10546 <span class="tok-n">Number</span> <span class="tok-n">fieldA</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">Number</span><span class="tok-o">)</span> <span class="tok-n">fieldAExpression</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10547 10548 <span class="tok-n">Expression</span> <span class="tok-n">fieldBExpression</span> <span class="tok-o">=</span> <span class="tok-n">DelegateHelper</span><span class="tok-o">.</span><span class="tok-na">getFieldExpression</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">,</span> <span class="tok-s">"fieldB"</span><span class="tok-o">);</span> 10549 <span class="tok-n">Number</span> <span class="tok-n">fieldB</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">Number</span><span class="tok-o">)</span> <span class="tok-n">fieldBExpression</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10550 10551 <span class="tok-kt">int</span> <span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-n">fieldA</span><span class="tok-o">.</span><span class="tok-na">intValue</span><span class="tok-o">()</span> <span class="tok-o">+</span> <span class="tok-n">fieldB</span><span class="tok-o">.</span><span class="tok-na">intValue</span><span class="tok-o">();</span> 10552 10553 <span class="tok-n">String</span> <span class="tok-n">resultVariableName</span> <span class="tok-o">=</span> <span class="tok-n">DelegateHelper</span><span class="tok-o">.</span><span class="tok-na">getFieldExpression</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">,</span> <span class="tok-s">"resultVariableName"</span><span class="tok-o">).</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">).</span><span class="tok-na">toString</span><span class="tok-o">();</span> 10554 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-n">resultVariableName</span><span class="tok-o">,</span> <span class="tok-n">result</span><span class="tok-o">);</span> 10555 <span class="tok-o">}</span> 10556 10557<span class="tok-o">}</span> 10558</td></tr></table></code></pre> 10559</div> 10560</div> 10561<div class="paragraph"> 10562<p>The <em>INSTANCE_COUNT</em> will always be <em>one</em> here, as it is a singleton. In this delegate, there are no <em>Expression</em> member fields. This is possible since we’re running in <em>MIXED</em> mode. In <em>COMPATIBILITY</em> mode, this would throw an exception as it expects the member fields to be there. <em>DISABLED</em> mode would also work for this bean, but it would disallow the use the prototype bean above that does use field injection.</p> 10563</div> 10564<div class="paragraph"> 10565<p>In this delegate code, the <strong>org.activiti.engine.delegate.DelegateHelper</strong> class is used, that has some useful utility methods to execute the same logic, but in a thread-safe way when the delegate is a singleton. Instead of injecting the <em>Expression</em>, it is fetched via the <em>getFieldExpression</em> method. This means that when it comes to the service task xml, the fields are defined exactly the same as for the singleton bean. If you look at the xml snippet above, you can see they are equal in definition and only the implementation logic differs.</p> 10566</div> 10567<div class="paragraph"> 10568<p>(Technical note: the <em>getFieldExpression</em> will introspect the BpmnModel and create the Expression on the fly when the method is executed, making it thread-safe)</p> 10569</div> 10570<div class="ulist"> 10571<ul> 10572<li> 10573<p>For Activiti versions 5.x, the DelegateHelper cannot be used for an <em>ExecutionListener</em> or <em>TaskListener</em> (due to an architectural flaw). To make thread-safe instances of those listeners, use either an expression or make sure a new instance is created every time the delegate expression is resolved.</p> 10574</li> 10575<li> 10576<p>For Activiti version 6.x the DelegateHelper does work in <em>ExecutionListener</em> and <em>TaskListener</em>
10576 implementations. For example in version 6.x, the following code can be written, using the <strong>DelegateHelper</strong>:</p> 10577</li> 10578</ul> 10579</div> 10580<div class="listingblock"> 10581<div class="content"> 10582<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 105832 105843 105854 105865 105876 105887</div></td><td class="code"><span></span><span class="tok-nt"><extensionElements></span> 10589 <span class="tok-nt"><activiti:executionListener</span> 10590 <span class="tok-na">delegateExpression=</span><span class="tok-s">"${testExecutionListener}"</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span><span class="tok-nt">></span> 10591 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"input"</span> <span class="tok-na">expression=</span><span class="tok-s">"${startValue}"</span> <span class="tok-nt">/></span> 10592 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVar"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"processStartValue"</span> <span class="tok-nt">/></span> 10593 <span class="tok-nt"></activiti:executionListener></span> 10594<span class="tok-nt"></extensionElements></span> 10595</td></tr></table></code></pre> 10596</div> 10597</div> 10598<div class="paragraph"> 10599<p>Where <em>testExecutionListener</em> resolves to an instance implementing the ExecutionListener interface:</p> 10600</div> 10601<div class="listingblock"> 10602<div class="content"> 10603<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10604 2 10605 3 10606 4 10607 5 10608 6 10609 7 10610 8 10611 9 1061210 1061311 1061412 1061513 1061614 1061715</div></td><td class="code"><span></span><span class="tok-nd">@Component</span><span class="tok-o">(</span><span class="tok-s">"testExecutionListener"</span><span class="tok-o">)</span> 10618<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">TestExecutionListener</span> <span class="tok-kd">implements</span> <span class="tok-n">ExecutionListener</span> <span class="tok-o">{</span> 10619 10620 <span class="tok-nd">@Override</span> 10621 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">notify</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-o">{</span> 10622 <span class="tok-n">Expression</span> <span class="tok-n">inputExpression</span> <span class="tok-o">=</span> <span class="tok-n">DelegateHelper</span><span class="tok-o">.</span><span class="tok-na">getFieldExpression</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">,</span> <span class="tok-s">"input"</span><span class="tok-o">);</span> 10623 <span class="tok-n">Number</span> <span class="tok-n">input</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">Number</span><span class="tok-o">)</span> <span class="tok-n">inputExpression</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 10624 10625 <span class="tok-kt">int</span> <span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-n">input</span><span class="tok-o">.</span><span class="tok-na">intValue</span><span class="tok-o">()</span> <span class="tok-o">*</span> <span class="tok-mi">100</span><span class="tok-o">;</span> 10626 10627 <span class="tok-n">Expression</span> <span class="tok-n">resultVarExpression</span> <span class="tok-o">=</span> <span class="tok-n">DelegateHelper</span><span class="tok-o">.</span><span class="tok-na">getFieldExpression</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">,</span> <span class="tok-s">"resultVar"</span><span class="tok-o">);</span> 10628 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-n">resultVarExpression</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">).</span><span class="tok-na">toString</span><span class="tok-o">(),</span> <span class="tok-n">result</span><span class="tok-o">);</span> 10629 <span class="tok-o">}</span> 10630 10631<span class="tok-o">}</span> 10632</td></tr></table></code></pre> 10633</div> 10634</div> 10635</div> 10636<div class="sect4"> 10637<h5 id="serviceTaskResultValue">Service task results</h5> 10638<div class="paragraph"> 10639<p>The return value of a service execution (for service task using expression only) can be assigned to an already existing or to a new process variable by specifying the process variable name as a literal value for the <em>'activiti:resultVariable'</em> attribute of a service task definition. Any existing value for a specific process variable will be overwritten by the result value of the service execution. When not specifying a result variable name, the service execution result value gets ignored.</p> 10640</div> 10641<div class="listingblock"> 10642<div class="content"> 10643<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 106442 106453</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"aMethodExpressionServiceTask"</span> 10646 <span class="tok-na">activiti:expression=</span><span class="tok-s">"#{myService.doSomething()}"</span> 10647 <span class="tok-na">activiti:resultVariable=</span><span class="tok-s">"myVar"</span> <span class="tok-nt">/></span> 10648</td></tr></table></code></pre> 10649</div> 10650</div> 10651<div class="paragraph"> 10652<p>In the example above, the result of the service execution (the return value of the <em>'doSomething()'</em> method invocation on an object that is made available under the name <em>'myService'</em> either in the process variables or as a Spring bean) is set to the process variable named <em>'myVar'</em> after the service execution completes.</p> 10653</div> 10654</div> 10655<div class="sect4"> 10656<h5 id="serviceTaskExceptionHandling">Handling exceptions</h5> 10657<div class="paragraph"> 10658<p>When custom logic is executed, it is often required to catch certain business exceptions and handle them inside the surrounding process. Activiti provides different options to do that.</p> 10659</div> 10660<div class="sect5"> 10661<h6 id="serviceTaskBpmnErrors">Throwing BPMN Errors</h6> 10662<div class="paragraph"> 10663<p>
10663It is possible to throw BPMN Errors from user code inside Service Tasks or Script Tasks. In order to do this, a special ActivitiException called <em>BpmnError</em> can be thrown in JavaDelegates, scripts, expressions and delegate expressions. The engine will catch this exception and forward it to an appropriate error handler, e.g., a Boundary Error Event or an Error Event Sub-Process.</p> 10664</div> 10665<div class="listingblock"> 10666<div class="content"> 10667<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10668 2 10669 3 10670 4 10671 5 10672 6 10673 7 10674 8 10675 9 1067610 1067711</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ThrowBpmnErrorDelegate</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10678 10679 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 10680 <span class="tok-k">try</span> <span class="tok-o">{</span> 10681 <span class="tok-n">executeBusinessLogic</span><span class="tok-o">();</span> 10682 <span class="tok-o">}</span> <span class="tok-k">catch</span> <span class="tok-o">(</span><span class="tok-n">BusinessException</span> <span class="tok-n">e</span><span class="tok-o">)</span> <span class="tok-o">{</span> 10683 <span class="tok-k">throw</span> <span class="tok-k">new</span> <span class="tok-n">BpmnError</span><span class="tok-o">(</span><span class="tok-s">"BusinessExceptionOccurred"</span><span class="tok-o">);</span> 10684 <span class="tok-o">}</span> 10685 <span class="tok-o">}</span> 10686 10687<span class="tok-o">}</span> 10688</td></tr></table></code></pre> 10689</div> 10690</div> 10691<div class="paragraph"> 10692<p>The constructor argument is an error code, which will be used to determine the error handler that is responsible for the error. See <a href="#bpmnBoundaryErrorEvent">Boundary Error Event</a> for information on how to catch a BPMN Error.</p> 10693</div> 10694<div class="paragraph"> 10695<p>This mechanism should be used <strong>only for business faults</strong> that shall be handled by a Boundary Error Event or Error Event Sub-Process modeled in the process definition. Technical errors should be represented by other exception types and are usually not handled inside a process.</p> 10696</div> 10697</div> 10698<div class="sect5"> 10699<h6 id="exceptionMapping">Exception mapping</h6> 10700<div class="paragraph"> 10701<p>It is also possible to directly map a java exception to business exception by using <code>mapException</code> extension. Single mapping is the simplest form:</p> 10702</div> 10703<div class="listingblock"> 10704<div class="content"> 10705<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 107062 107073 107084 107095 107106</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"servicetask1"</span> <span class="tok-na">name=</span><span class="tok-s">"Service Task"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"..."</span><span class="tok-nt">></span> 10711 <span class="tok-nt"><extensionElements></span> 10712 <span class="tok-nt"><activiti:mapException</span> 10713 <span class="tok-na">errorCode=</span><span class="tok-s">"myErrorCode1"</span><span class="tok-nt">></span>org.activiti.SomeException<span class="tok-nt"></activiti:mapException></span> 10714 <span class="tok-nt"></extensionElements></span> 10715<span class="tok-nt"></serviceTask></span> 10716</td></tr></table></code></pre> 10717</div> 10718</div> 10719<div class="paragraph"> 10720<p>In above code, if an instance of <code>org.activiti.SomeException</code> is thrown in service task, it would be caught and converted to a BPMN exception with the given errorCode. From this point on, it will be handled exactly like a normal BPMN exception. 10721Any other exception will be treated as if there is no mapping in place. It will be propagated to the API caller.</p> 10722</div> 10723<div class="paragraph"> 10724<p>One can map all the child exception of a certain exception in a single line by using <code>includeChildExceptions</code> attribute.</p> 10725</div> 10726<div class="listingblock"> 10727<div class="content"> 10728<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 107292 107303 107314 107325 107336</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"servicetask1"</span> <span class="tok-na">name=</span><span class="tok-s">"Service Task"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"..."</span><span class="tok-nt">></span> 10734 <span class="tok-nt"><extensionElements></span> 10735 <span class="tok-nt"><activiti:mapException</span> <span class="tok-na">errorCode=</span><span class="tok-s">"myErrorCode1"</span>
10736 <span class="tok-na">includeChildExceptions=</span><span class="tok-s">"true"</span><span class="tok-nt">></span>org.activiti.SomeException<span class="tok-nt"></activiti:mapException></span> 10737 <span class="tok-nt"></extensionElements></span> 10738<span class="tok-nt"></serviceTask></span> 10739</td></tr></table></code></pre> 10740</div> 10741</div> 10742<div class="paragraph"> 10743<p>The above code will cause activiti to convert any direct or indirect descendent of <code>SomeException</code> to a BPMN error with the given error code. 10744<code>includeChildExceptions</code> will be considered "false" when not given.</p> 10745</div> 10746<div class="paragraph"> 10747<p>The most generic mapping is a default map. Default map is a map with no class. It will match any java exception:</p> 10748</div> 10749<div class="listingblock"> 10750<div class="content"> 10751<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 107522 107533 107544 107555</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"servicetask1"</span> <span class="tok-na">name=</span><span class="tok-s">"Service Task"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"..."</span><span class="tok-nt">></span> 10756 <span class="tok-nt"><extensionElements></span> 10757 <span class="tok-nt"><activiti:mapException</span> <span class="tok-na">errorCode=</span><span class="tok-s">"myErrorCode1"</span><span class="tok-nt">/></span> 10758 <span class="tok-nt"></extensionElements></span> 10759<span class="tok-nt"></serviceTask></span> 10760</td></tr></table></code></pre> 10761</div> 10762</div> 10763<div class="paragraph"> 10764<p>The mappings are checked in order, from top to bottom and the first found match will be followed, except for the default map. Default map is selected only after all maps are unsuccessfully checked. 10765Only the first map with no class will be considered as default map. <code>includeChildExceptions</code> is ignored for default Map.</p> 10766</div> 10767</div> 10768<div class="sect5"> 10769<h6 id="serviceTaskExceptionSequenceFlow">Exception Sequence Flow</h6> 10770<div class="paragraph"> 10771<p><a href="#internal">[INTERNAL: non-public implementation classes]</a></p> 10772</div> 10773<div class="paragraph"> 10774<p>Another option is to route process execution through another path in case some exception occurs. The following example shows how this is done.</p> 10775</div> 10776<div class="listingblock"> 10777<div class="content"> 10778<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 107792 107803 107814 107825 107836 107847</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"javaService"</span> 10785 <span class="tok-na">name=</span><span class="tok-s">"Java service invocation"</span> 10786 <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.ThrowsExceptionBehavior"</span><span class="tok-nt">></span> 10787<span class="tok-nt"></serviceTask></span> 10788 10789<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"no-exception"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"javaService"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 10790<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"exception"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"javaService"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"fixException"</span> <span class="tok-nt">/></span> 10791</td></tr></table></code></pre> 10792</div> 10793</div> 10794<div class="paragraph"> 10795<p>Here, the service task has two outgoing sequence flow, called <code>exception</code> and <code>no-exception</code>. This sequence flow id will be used to direct process flow in case of an exception:</p> 10796</div> 10797<div class="listingblock"> 10798<div class="content"> 10799<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10800 2 10801 3 10802 4 10803 5 10804 6 10805 7 10806 8 10807 9 1080810 1080911 1081012 1081113 1081214 1081315 1081416</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ThrowsExceptionBehavior</span> <span class="tok-kd">implements</span> <span class="tok-n">ActivityBehavior</span> <span class="tok-o">{</span> 10815 10816 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">ActivityExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 10817 <span class="tok-n">String</span> <span class="tok-n">var</span> <span class="tok-o">=</span> <span class="tok-o">(</span><span class="tok-n">String</span><span class="tok-o">)</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getVariable</span><span class="tok-o">(</span><span class="tok-s">"var"</span><span class="tok-o">);</span> 10818 10819 <span class="tok-n">PvmTransition</span> <span class="tok-n">transition</span> <span class="tok-o">=</span> <span class="tok-kc">null</span><span class="tok-o">;</span> 10820 <span class="tok-k">try</span> <span class="tok-o">{</span>
10821 <span class="tok-n">executeLogic</span><span class="tok-o">(</span><span class="tok-n">var</span><span class="tok-o">);</span> 10822 <span class="tok-n">transition</span> <span class="tok-o">=</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getActivity</span><span class="tok-o">().</span><span class="tok-na">findOutgoingTransition</span><span class="tok-o">(</span><span class="tok-s">"no-exception"</span><span class="tok-o">);</span> 10823 <span class="tok-o">}</span> <span class="tok-k">catch</span> <span class="tok-o">(</span><span class="tok-n">Exception</span> <span class="tok-n">e</span><span class="tok-o">)</span> <span class="tok-o">{</span> 10824 <span class="tok-n">transition</span> <span class="tok-o">=</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getActivity</span><span class="tok-o">().</span><span class="tok-na">findOutgoingTransition</span><span class="tok-o">(</span><span class="tok-s">"exception"</span><span class="tok-o">);</span> 10825 <span class="tok-o">}</span> 10826 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">take</span><span class="tok-o">(</span><span class="tok-n">transition</span><span class="tok-o">);</span> 10827 <span class="tok-o">}</span> 10828 10829<span class="tok-o">}</span> 10830</td></tr></table></code></pre> 10831</div> 10832</div> 10833</div> 10834</div> 10835<div class="sect4"> 10836<h5 id="serviceTaskCallActivitiService">Using an Activiti service from within a JavaDelegate</h5> 10837<div class="paragraph"> 10838<p>For some use cases, it might be needed to use the Activiti services from within a Java service task (e.g. starting a process instance through the RuntimeService, if the callActivity doesn’t suit your needs). The <em>org.activiti.engine.delegate.DelegateExecution</em> allows to easily use these services through the <em>org.activiti.engine.EngineServices</em> interface:</p> 10839</div> 10840<div class="listingblock"> 10841<div class="content"> 10842<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 108432 108443 108454 108465 108476 108487 108498</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">StartProcessInstanceTestDelegate</span> <span class="tok-kd">implements</span> <span class="tok-n">JavaDelegate</span> <span class="tok-o">{</span> 10850 10851 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">DelegateExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 10852 <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span> <span class="tok-o">=</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getEngineServices</span><span class="tok-o">().</span><span class="tok-na">getRuntimeService</span><span class="tok-o">();</span> 10853 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"myProcess"</span><span class="tok-o">);</span> 10854 <span class="tok-o">}</span> 10855 10856<span class="tok-o">}</span> 10857</td></tr></table></code></pre> 10858</div> 10859</div> 10860<div class="paragraph"> 10861<p>All of the Activiti service API’s are available through this interface.</p> 10862</div> 10863<div class="paragraph"> 10864<p>All data changes that occur as an effect of using these API calls, will be part of the current transaction. This also works in environments with dependency injection like Spring and CDI with or without a JTA enabled datasource. For example, the following snippet of code will do the same as the snippet above, but now the RuntimeService is injected rather than it is being fetched through the <em>org.activiti.engine.EngineServices</em> interface.</p> 10865</div> 10866<div class="listingblock"> 10867<div class="content"> 10868<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10869 2 10870 3 10871 4 10872 5 10873 6 10874 7 10875 8 10876 9 1087710 1087811</div></td><td class="code"><span></span><span class="tok-nd">@Component</span><span class="tok-o">(</span><span class="tok-s">"startProcessInstanceDelegate"</span><span class="tok-o">)</span> 10879<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">StartProcessInstanceTestDelegateWithInjection</span> <span class="tok-o">{</span> 10880 10881 <span class="tok-nd">@Autowired</span> 10882 <span class="tok-kd">private</span> <span class="tok-n">RuntimeService</span> <span class="tok-n">runtimeService</span><span class="tok-o">;</span> 10883 10884 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">startProcess</span><span class="tok-o">()</span> <span class="tok-o">{</span>
10885 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"oneTaskProcess"</span><span class="tok-o">);</span> 10886 <span class="tok-o">}</span> 10887 10888<span class="tok-o">}</span> 10889</td></tr></table></code></pre> 10890</div> 10891</div> 10892<div class="paragraph"> 10893<p><strong>Important technical note:</strong> since the service call is being done as part of the current transaction any data that was produced or altered <em>before</em> the service task is executed, is not yet flushed to the database. All API calls work on the database data, which means that these uncommitted changes are not be <em>visible</em> within the api call of the service task.</p> 10894</div> 10895</div> 10896</div> 10897<div class="sect3"> 10898<h4 id="bpmnWebserviceTask">8.5.4. Web Service Task</h4> 10899<div class="paragraph"> 10900<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnWebserviceTaskDescription"></a></p> 10901</div> 10902<div class="sect4"> 10903<h5 id="_description_6">Description</h5> 10904<div class="paragraph"> 10905<p>A Web Service task is used to synchronously invoke an external Web service.</p> 10906</div> 10907</div> 10908<div class="sect4"> 10909<h5 id="bpmnWebserviceTaskGraphicalNotation">Graphical Notation</h5> 10910<div class="paragraph"> 10911<p>A Web Service task is visualized the same as a Java service task.</p> 10912</div> 10913<div class="imageblock" style="text-align: center"> 10914<div class="content"> 10915<img src="images/bpmn.web.service.task.png" alt="bpmn.web.service.task"> 10916</div> 10917</div> 10918</div> 10919<div class="sect4"> 10920<h5 id="bpmnWebserviceTaskXML">XML representation</h5> 10921<div class="paragraph"> 10922<p>To use a Web service we need to import its operations and complex types. This can be done automatically by using the import tag pointing to the WSDL of the Web service:</p> 10923</div> 10924<div class="listingblock"> 10925<div class="content"> 10926<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 109272 109283</div></td><td class="code"><span></span><span class="tok-nt"><import</span> <span class="tok-na">importType=</span><span class="tok-s">"http://schemas.xmlsoap.org/wsdl/"</span> 10929 <span class="tok-na">location=</span><span class="tok-s">"http://localhost:63081/counter?wsdl"</span> 10930 <span class="tok-na">namespace=</span><span class="tok-s">"http://webservice.activiti.org/"</span> <span class="tok-nt">/></span> 10931</td></tr></table></code></pre> 10932</div> 10933</div> 10934<div class="paragraph"> 10935<p>The previous declaration tells Activiti to import the definitions but it doesn’t create the item definitions and messages for you. Let’s suppose we want to invoke a specific method called <em>prettyPrint</em>, therefore we will need to create the corresponding message and item definitions for the request and response messages:</p> 10936</div> 10937<div class="listingblock"> 10938<div class="content"> 10939<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 109402 109413 109424 109435</div></td><td class="code"><span></span><span class="tok-nt"><message</span> <span class="tok-na">id=</span><span class="tok-s">"prettyPrintCountRequestMessage"</span> <span class="tok-na">itemRef=</span><span class="tok-s">"tns:prettyPrintCountRequestItem"</span> <span class="tok-nt">/></span> 10944<span class="tok-nt"><message</span> <span class="tok-na">id=</span><span class="tok-s">"prettyPrintCountResponseMessage"</span> <span class="tok-na">itemRef=</span><span class="tok-s">"tns:prettyPrintCountResponseItem"</span> <span class="tok-nt">/></span> 10945 10946<span class="tok-nt"><itemDefinition</span> <span class="tok-na">id=</span><span class="tok-s">"prettyPrintCountRequestItem"</span> <span class="tok-na">structureRef=</span><span class="tok-s">"counter:prettyPrintCount"</span> <span class="tok-nt">/></span> 10947<span class="tok-nt"><itemDefinition</span> <span class="tok-na">id=</span><span class="tok-s">"prettyPrintCountResponseItem"</span> <span class="tok-na">structureRef=</span><span class="tok-s">"counter:prettyPrintCountResponse"</span> <span class="tok-nt">/></span> 10948</td></tr></table></code></pre> 10949</div> 10950</div> 10951<div class="paragraph"> 10952<p>Before declaring the service task, we have to define the BPMN interfaces and operations that actually reference the Web service ones. Basically, we define and <em>interface</em> and the required <em>operation’s</em>. For each operation we reuse the previous defined message for in and out. For example, the following declaration defines the <em>counter</em> interface and the <em>prettyPrintCountOperation</em> operation:</p> 10953</div> 10954<div class="listingblock"> 10955<div class="content"> 10956<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 109572 109583 109594 109605 109616 109627</div></td><td class="code"><span></span><span class="tok-nt"><interface</span> <span class="tok-na">name=</span><span class="tok-s">"Counter Interface"</span> <span class="tok-na">implementationRef=</span><span class="tok-s">"counter:Counter"</span><span class="tok-nt">></span> 10963 <span class="tok-nt"><operation</span> <span class="tok-na">id=</span><span class="tok-s">"prettyPrintCountOperation"</span> <span class="tok-na">name=</span><span class="tok-s">"prettyPrintCount Operation"</span> 10964 <span class="tok-na">implementationRef=</span><span class="tok-s">"counter:prettyPrintCount"</span><span class="tok-nt">></span> 10965 <span class="tok-nt"><inMessageRef></span>tns:prettyPrintCountRequestMessage<span class="tok-nt"></inMessageRef></span> 10966 <span class="tok-nt"><outMessageRef></span>tns:prettyPrintCountResponseMessage<span class="tok-nt"></outMessageRef></span> 10967 <span class="tok-nt"></operation></span> 10968<span class="tok-nt"></interface></span> 10969</td></tr></table></code></pre> 10970</div> 10971</div> 10972<div class="paragraph"> 10973<p>Then we can declare a Web Service Task by using the ##WebService implementation and a reference to the Web service operation.</p> 10974</div> 10975<div class="listingblock"> 10976<div class="content"> 10977<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 109782 109793 109804</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"webService"</span> 10981 <span class="tok-na">name=</span><span class="tok-s">"Web service invocation"</span> 10982 <span class="tok-na">implementation=</span><span class="tok-s">"##WebService"</span> 10983 <span class="tok-na">operationRef=</span><span class="tok-s">"tns:prettyPrintCountOperation"</span><span class="tok-nt">></span> 10984</td></tr></table></code></pre> 10985</div> 10986</div> 10987</div> 10988<div class="sect4"> 10989<h5 id="bpmnWebserviceTaskIOSpecification">Web Service Task IO Specification</h5> 10990<div class="paragraph"> 10991<p>Unless we are using the simplistic approach for data input and output associations (See below), each Web Service Task needs to declare an IO Specification which states which are the inputs and outputs of the task. The approach is pretty straightforward and BPMN 2.0 complaint, for our prettyPrint example we define the input and output sets according to the previously declared item definitions:</p> 10992</div> 10993<div class="listingblock"> 10994<div class="content"> 10995<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 10996 2 10997 3 10998 4 10999 5 11000 6 11001 7 11002 8 11003 9 1100410</div></td><td class="code"><span></span><span class="tok-nt"><ioSpecification></span> 11005 <span class="tok-nt"><dataInput</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"tns:prettyPrintCountRequestItem"</span> <span class="tok-na">id=</span><span class="tok-s">"dataInputOfServiceTask"</span> <span class="tok-nt">/></span> 11006 <span class="tok-nt"><dataOutput</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"tns:prettyPrintCountResponseItem"</span> <span class="tok-na">id=</span><span class="tok-s">"dataOutputOfServiceTask"</span> <span class="tok-nt">/></span> 11007 <span class="tok-nt"><inputSet></span> 11008 <span class="tok-nt"><dataInputRefs></span>dataInputOfServiceTask<span class="tok-nt"></dataInputRefs></span> 11009 <span class="tok-nt"></inputSet></span> 11010 <span class="tok-nt"><outputSet></span> 11011 <span class="tok-nt"><dataOutputRefs></span>dataOutputOfServiceTask<span class="tok-nt"></dataOutputRefs></span> 11012 <span class="tok-nt"></outputSet></span> 11013<span class="tok-nt"></ioSpecification></span> 11014</td></tr></table></code></pre> 11015</div> 11016</div> 11017</div> 11018<div class="sect4"> 11019<h5 id="bpmnWebserviceTaskDataInputAssociation">Web Service Task data input associations</h5> 11020<div class="paragraph"> 11021<p>There are 2 ways of specifying data input associations:</p> 11022</div> 11023<div class="ulist"> 11024<ul> 11025<li> 11026<p>Using expressions</p> 11027</li> 11028<li> 11029<p>Using the simplistic approach</p> 11030</li> 11031</ul> 11032</div> 11033<div class="paragraph"> 11034<p>To specify the data input association using expressions we need to define the source and target items and specify the corresponding assignments between the fields of each item. In the following example we assign prefix and suffix fields of the items:</p> 11035</div> 11036<div class="listingblock"> 11037<div class="content"> 11038<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 11039 2 11040 3 11041 4 11042 5 11043 6 11044 7 11045 8 11046 9 1104710 1104811
1104912</div></td><td class="code"><span></span><span class="tok-nt"><dataInputAssociation></span> 11050 <span class="tok-nt"><sourceRef></span>dataInputOfProcess<span class="tok-nt"></sourceRef></span> 11051 <span class="tok-nt"><targetRef></span>dataInputOfServiceTask<span class="tok-nt"></targetRef></span> 11052 <span class="tok-nt"><assignment></span> 11053 <span class="tok-nt"><from></span>${dataInputOfProcess.prefix}<span class="tok-nt"></from></span> 11054 <span class="tok-nt"><to></span>${dataInputOfServiceTask.prefix}<span class="tok-nt"></to></span> 11055 <span class="tok-nt"></assignment></span> 11056 <span class="tok-nt"><assignment></span> 11057 <span class="tok-nt"><from></span>${dataInputOfProcess.suffix}<span class="tok-nt"></from></span> 11058 <span class="tok-nt"><to></span>${dataInputOfServiceTask.suffix}<span class="tok-nt"></to></span> 11059 <span class="tok-nt"></assignment></span> 11060<span class="tok-nt"></dataInputAssociation></span> 11061</td></tr></table></code></pre> 11062</div> 11063</div> 11064<div class="paragraph"> 11065<p>On the other hand we can use the simplistic approach which is much more simple. The <em>sourceRef</em> element is an Activiti variable name and the <em>targetRef</em> element is a property of the item definition. In the following example we assign to the <em>prefix</em> field the value of the variable <em>PrefixVariable</em> and to the <em>suffix</em> field the value of the variable <em>SuffixVariable</em>.</p> 11066</div> 11067<div class="listingblock"> 11068<div class="content"> 11069<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 110702 110713 110724 110735 110746 110757 110768</div></td><td class="code"><span></span><span class="tok-nt"><dataInputAssociation></span> 11077 <span class="tok-nt"><sourceRef></span>PrefixVariable<span class="tok-nt"></sourceRef></span> 11078 <span class="tok-nt"><targetRef></span>prefix<span class="tok-nt"></targetRef></span> 11079<span class="tok-nt"></dataInputAssociation></span> 11080<span class="tok-nt"><dataInputAssociation></span> 11081 <span class="tok-nt"><sourceRef></span>SuffixVariable<span class="tok-nt"></sourceRef></span> 11082 <span class="tok-nt"><targetRef></span>suffix<span class="tok-nt"></targetRef></span> 11083<span class="tok-nt"></dataInputAssociation></span> 11084</td></tr></table></code></pre> 11085</div> 11086</div> 11087</div> 11088<div class="sect4"> 11089<h5 id="bpmnWebserviceTaskDataOutputAssociation">Web Service Task data output associations</h5> 11090<div class="paragraph"> 11091<p>There are 2 ways of specifying data out associations:</p> 11092</div> 11093<div class="ulist"> 11094<ul> 11095<li> 11096<p>Using expressions</p> 11097</li> 11098<li> 11099<p>Using the simplistic approach</p> 11100</li> 11101</ul> 11102</div> 11103<div class="paragraph"> 11104<p>To specify the data out association using expressions we need to define the target variable and the source expression. The approach is pretty straightforward and similar data input associations:</p> 11105</div> 11106<div class="listingblock"> 11107<div class="content"> 11108<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 111092 111103 111114</div></td><td class="code"><span></span><span class="tok-nt"><dataOutputAssociation></span> 11112 <span class="tok-nt"><targetRef></span>dataOutputOfProcess<span class="tok-nt"></targetRef></span> 11113 <span class="tok-nt"><transformation></span>${dataOutputOfServiceTask.prettyPrint}<span class="tok-nt"></transformation></span> 11114<span class="tok-nt"></dataOutputAssociation></span> 11115</td></tr></table></code></pre> 11116</div> 11117</div> 11118<div class="paragraph"> 11119<p>On the other hand we can use the simplistic approach which is much more simple. The <em>sourceRef</em> element is a property of the item definition and the <em>targetRef</em> element is an Activiti variable name. The approach is pretty straightforward and similar data input associations:</p> 11120</div> 11121<div class="listingblock"> 11122<div class="content"> 11123<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 111242 111253 111264</div></td><td class="code"><span></span><span class="tok-nt"><dataOutputAssociation></span> 11127 <span class="tok-nt"><sourceRef></span>prettyPrint<span class="tok-nt"></sourceRef></span> 11128 <span class="tok-nt"><targetRef></span>OutputVariable<span class="tok-nt"></targetRef></span> 11129<span class="tok-nt"></dataOutputAssociation></span> 11130</td></tr></table></code></pre> 11131</div> 11132</div> 11133</div> 11134</div> 11135<div class="sect3"> 11136<h4 id="bpmnBusinessRuleTask">8.5.5. Business Rule Task</h4> 11137<div class="paragraph"> 11138<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnBusinessRuleTaskDescription"></a></p> 11139</div> 11140<div class="sect4"> 11141<h5 id="_description_7">Description</h5> 11142<div class="paragraph"> 11143<p>A Business Rule task is used to synchronously execute one or more rules. Activiti uses Drools Expert, the Drools rule engine to execute business rules. Currently, the .drl files containing the business rules have to be deployed together with the process definition that defines a business rule task to execute those rules. This means that all .drl files that are used in a process have to be packaged in the process BAR file like for example the task forms. For more information about creating business rules for Drools Expert please refer to the Drools documentation at <a href="http://www.jboss.org/drools/documentation">JBoss Drools</a></p> 11144</div> 11145<div class="paragraph"> 11146<p>If you want to plug in your implementation of the rule task, e.g. be
11146cause you want to use Drools differently or you want to use a completely different rule engine, then you can use the class or expression attribute on the BusinessRuleTask and it will behave exactly like a <a href="#bpmnJavaServiceTask">ServiceTask</a></p> 11147</div> 11148</div> 11149<div class="sect4"> 11150<h5 id="bpmnBusinessRuleTaskGraphicalNotation">Graphical Notation</h5> 11151<div class="paragraph"> 11152<p>A Business Rule task is visualized the with a table icon.</p> 11153</div> 11154<div class="imageblock" style="text-align: center"> 11155<div class="content"> 11156<img src="images/bpmn.business.rule.task.png" alt="bpmn.business.rule.task"> 11157</div> 11158</div> 11159</div> 11160<div class="sect4"> 11161<h5 id="bpmnBusinessRuleTaskXML">XML representation</h5> 11162<div class="paragraph"> 11163<p>To execute one or more business rules that are deployed in the same BAR file as the process definition, we need to define the input and result variables. For the input variable definition a list of process variables can be defined separated by a comma. The output variable definition can only contain one variable name that will be used to store the output objects of the executed business rules in a process variable. Note that the result variable will contain a List of objects. If no result variable name is specified by default org.activiti.engine.rules.OUTPUT is used.</p> 11164</div> 11165<div class="paragraph"> 11166<p>The following business rule task executes all business rules deployed with the process definition:</p> 11167</div> 11168<div class="listingblock"> 11169<div class="content"> 11170<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 11171 2 11172 3 11173 4 11174 5 11175 6 11176 7 11177 8 11178 9 1117910 1118011 1118112 1118213</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"simpleBusinessRuleProcess"</span><span class="tok-nt">></span> 11183 11184 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 11185 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"businessRuleTask"</span> <span class="tok-nt">/></span> 11186 11187 <span class="tok-nt"><businessRuleTask</span> <span class="tok-na">id=</span><span class="tok-s">"businessRuleTask"</span> <span class="tok-na">activiti:ruleVariablesInput=</span><span class="tok-s">"${order}"</span> 11188 <span class="tok-na">activiti:resultVariable=</span><span class="tok-s">"rulesOutput"</span> <span class="tok-nt">/></span> 11189 11190 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"businessRuleTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 11191 11192 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 11193 11194<span class="tok-nt"></process></span> 11195</td></tr></table></code></pre> 11196</div> 11197</div> 11198<div class="paragraph"> 11199<p>
11199The business rule task can also be configured to execute only a defined set of rules from the deployed .drl files. A list of rule names separated by a comma must be specified for this.</p> 11200</div> 11201<div class="listingblock"> 11202<div class="content"> 11203<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 112042</div></td><td class="code"><span></span><span class="tok-nt"><businessRuleTask</span> <span class="tok-na">id=</span><span class="tok-s">"businessRuleTask"</span> <span class="tok-na">activiti:ruleVariablesInput=</span><span class="tok-s">"${order}"</span> 11205 <span class="tok-na">activiti:rules=</span><span class="tok-s">"rule1, rule2"</span> <span class="tok-nt">/></span> 11206</td></tr></table></code></pre> 11207</div> 11208</div> 11209<div class="paragraph"> 11210<p>In this case only rule1 and rule2 are executed.</p> 11211</div> 11212<div class="paragraph"> 11213<p>You can also define a list of rules that should be excluded from execution.</p> 11214</div> 11215<div class="listingblock"> 11216<div class="content"> 11217<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 112182</div></td><td class="code"><span></span><span class="tok-nt"><businessRuleTask</span> <span class="tok-na">id=</span><span class="tok-s">"businessRuleTask"</span> <span class="tok-na">activiti:ruleVariablesInput=</span><span class="tok-s">"${order}"</span> 11219 <span class="tok-na">activiti:rules=</span><span class="tok-s">"rule1, rule2"</span> <span class="tok-na">exclude=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 11220</td></tr></table></code></pre> 11221</div> 11222</div> 11223<div class="paragraph"> 11224<p>In this case all rules deployed in the same BAR file as the process definition will be executed, except for rule1 and rule2.</p> 11225</div> 11226<div class="paragraph"> 11227<p>As mentioned earlier another option is to hook in the implementation of the BusinessRuleTask yourself:</p> 11228</div> 11229<div class="listingblock"> 11230<div class="content"> 11231<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><businessRuleTask</span> <span class="tok-na">id=</span><span class="tok-s">"businessRuleTask"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"${MyRuleServiceDelegate}"</span> <span class="tok-nt">/></span> 11232</td></tr></table></code></pre> 11233</div> 11234</div> 11235<div class="paragraph"> 11236<p>Now the BusinessRuleTask behaves exactly like a ServiceTask, but still keeps the BusinessRuleTask icon to visualize that we do business rule processing here.</p> 11237</div> 11238</div> 11239</div> 11240<div class="sect3"> 11241<h4 id="bpmnEmailTask">8.5.6. Email Task</h4> 11242<div class="paragraph"> 11243<p>Activiti allows to enhance business processes with automatic mail service tasks that send e-mails to one or more recipients, including support for cc, bcc, HTML content, …​ etc. Note that the mail task is <strong>not</strong> an <em>official</em> task of the BPMN 2.0 spec (and it does not have a dedicated icon as a consequence). Hence, in Activiti the mail task is implemented as a dedicated service task.</p> 11244</div> 11245<div class="sect4"> 11246<h5 id="bpmnEmailTaskServerConfiguration">Mail server configuration</h5> 11247<div class="paragraph"> 11248<p>The Activiti engine sends e-mails trough an external mail server with SMTP capabilities. To actually send e-mails, the engine needs to know how to reach the mail server. Following properties can be set in the <em>activiti.cfg.xml</em> configuration file:</p> 11249</div> 11250<table class="tableblock frame-all grid-all spread"> 11251<colgroup> 11252<col style="width: 33.3333%;"> 11253<col style="width: 33.3333%;"> 11254<col style="width: 33.3334%;"> 11255</colgroup> 11256<thead> 11257<tr> 11258<th class="tableblock halign-left valign-top">Property</th> 11259<th class="tableblock halign-left valign-top">Required?</th> 11260<th class="tableblock halign-left valign-top">Description</th> 11261</tr> 11262</thead> 11263<tbody> 11264<tr> 11265<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerHost</p></td> 11266<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11267<td class="tableblock halign-left valign-top"><p class="tableblock">The hostname of your mail server (e.g. mail.mycorp.com). Default is <code>localhost</code></p></td> 11268</tr> 11269<tr> 11270<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerPort</p></td> 11271<td class="tableblock halign-left valign-top"><p class="tableblock">yes, if not on the default port</p></td> 11272<td class="tableblock halign-left valign-top"><p class="tableblock">The port for SMTP traffic on the mail server. The default is <em>25</em></p></td> 11273</tr> 11274<tr> 11275<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerDefaultFrom</p></td> 11276<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11277<td class="tableblock halign-left valign-top"><p class="tableblock">The default e-mail address of the sender of e-mails, when none is provided by the user. By default this is <em>[email protected]</em></p></td> 11278</tr> 11279<tr> 11280<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerUsername</p></td> 11281<td class="tableblock halign-left valign-top"><p class="tableblock">if applicable for your server</p></td> 11282<td class="tableblock halign-left valign-top"><p class="tableblock">Some mail servers require credentials for sending e-mail. By default not set.</p></td> 11283</tr> 11284<tr> 11285<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerPassword</p></td> 11286<td class="tableblock halign-left valign-top"><p class="tableblock">if applicable for your server</p></td> 11287<td class="tableblock halign-left valign-top"><p class="tableblock">Some mail servers require credentials for sending e-mail. By default not set.</p></td> 11288</tr> 11289<tr> 11290<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerUseSSL</p></td> 11291<td class="tableblock halign-left valign-top"><p class="tableblock">if applicable for your server</p></td> 11292<td class="tableblock halign-left valign-top"><p class="tableblock">Some mail servers require ssl communication. By default set to false.</p></td> 11293</tr> 11294<tr> 11295<td class="tableblock halign-left valign-top"><p class="tableblock">mailServerUseTLS</p></td> 11296<td class="tableblock halign-left valign-top"><p class="tableblock">if applicable for your server</p></td> 11297<td class="tableblock halign-left valign-top"><p class="tableblock">Some mail servers (for instance gmail) require TLS communication. By default set to false.</p></td> 11298</tr> 11299</tbody> 11300</table> 11301</div> 11302<div class="sect4"> 11303<h5 id="bpmnEmailTaskUsage">Defining an Email Task</h5> 11304<div class="paragraph"> 11305<p>The Email task is implemented as a dedicated <a href="#bpmnJavaServiceTask">Service Task</a> and is defined by setting <em>'mail'</em> for the <em>type</em> of the service task.</p> 11306</div> 11307<div class="listingblock"> 11308<div class="content"> 11309<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"sendMail"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"mail"</span><span class="tok-nt">></span> 11310</td></tr></table></code></pre> 11311</div> 11312</div> 11313<div class="paragraph"> 11314<p>The Email task is configured by <a href="#serviceTaskFieldInjection">field injection</a>. All the values for these properties can contain EL expression, which are resolved at runtime during process execution. Following properties can be set:</p> 11315</div> 11316<table class="tableblock frame-all grid-all spread"> 11317<colgroup> 11318<col style="width: 33.3333%;"> 11319<col style="width: 33.3333%;"> 11320<col style="width: 33.3334%;"> 11321</colgroup> 11322<thead> 11323<tr> 11324<th class="tableblock halign-left valign-top">Property</th> 11325<th class="tableblock halign-left valign-top">Required?</th> 11326<th class="tableblock halign-left valign-top">Description</th> 11327</tr> 11328</thead> 11329<tbody> 11330<tr> 11331<td class="tableblock halign-left valign-top"><p class="tableblock">to</p></td> 11332<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td> 11333<td class="tableblock halign-left valign-top"><p class="tableblock">The recipients if the e-mail. Multiple recipients are defined in a comma-separated list</p></td> 11334</tr> 11335<tr> 11336<td class="tableblock halign-left valign-top"><p class="tableblock">from</p></td> 11337<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11338<td class="tableblock halign-left valign-top"><p class="tableblock">The sender e-mail address. If not provided, the <a href="#bpmnEmailTaskServerConfiguration">default configured</a> from address is used.</p></td> 11339</tr> 11340<tr> 11341<td class="tableblock halign-left valign-top"><p class="tableblock">subject</p></td> 11342<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11343<td class="tableblock halign-left valign-top"><p class="tableblock">The subject of the e-mail.</p></td> 11344</tr> 11345<tr> 11346<td class="tableblock halign-left valign-top"><p class="tableblock">cc</p></td> 11347<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11348<td class="tableblock halign-left valign-top"><p class="tableblock">The cc’s of the e-mail. Multiple recipients are defined in a comma-separated list</p></td> 11349</tr> 11350<tr> 11351<td class="tableblock halign-left valign-top"><p class="tableblock">bcc</p></td> 11352<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11353<td class="tableblock halign-left valign-top"><p class="tableblock">The bcc’s of the e-mail. Multiple recipients are defined in a comma-separated list</p></td> 11354</tr> 11355<tr> 11356<td class="tableblock halign-left valign-top"><p class="tableblock">charset</p></td> 11357<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11358<td class="tableblock halign-left valign-top"><p class="tableblock">Allows to change the charset of the email, which is necessary for many 11359 non-English languages.</p></td> 11360</tr> 11361<tr> 11362<td class="tableblock halign-left valign-top"><p class="tableblock">html</p></td> 11363<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11364<td class="tableblock halign-left valign-top"><p class="tableblock">A piece of HTML that is the content of the e-mail.</p></td> 11365</tr> 11366<tr> 11367<td class="tableblock halign-left valign-top"><p class="tableblock">text</p></td> 11368<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11369<td class="tableblock halign-left valign-top"><p class="tableblock">The content of the e-mail, in case one needs to send plain none-rich e-mails. 11370 Can be used in combination with <em>html</em>, for e-mail clients 11371 that don’t support rich content. The client will then fall back to this text-only alternative.</p></td> 11372</tr> 11373<tr> 11374<td class="tableblock halign-left valign-top"><p class="tableblock">htmlVar</p></td> 11375<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11376<td class="tableblock halign-left valign-top"><p class="tableblock">The name of a process variable that holds the HTML that is the content of the e-mail. The key difference between this and html is that this content will have expressions replaced before being sent by the mail task.</p></td> 11377</tr> 11378<tr> 11379<td class="tableblock halign-left valign-top"><p class="tableblock">textVar</p></td> 11380<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11381<td class="tableblock halign-left valign-top"><p class="tableblock">The name of a process variable that holds the plain text content of the e-mail. The key difference between this and html is that this content will have expressions replaced before being sent by the mail task.</p></td> 11382</tr> 11383<tr> 11384<td class="tableblock halign-left valign-top"><p class="tableblock">ignoreException</p></td> 11385<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11386<td class="tableblock halign-left valign-top"><p class="tableblock">Whether an failure when handling the e-mail throws an ActivitiException. By default this is set to false.</p></td> 11387</tr> 11388<tr> 11389<td class="tableblock halign-left valign-top"><p class="tableblock">exceptionVariableName</p></td> 11390<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11391<td class="tableblock halign-left valign-top"><p class="tableblock">When email handling does not throw an exception since <em>ignoreException = true</em> a variable with the given name is used to hold a failure message</p></td> 11392</tr> 11393</tbody> 11394</table> 11395</div> 11396<div class="sect4"> 11397<h5 id="bpmnEmailTaskExampleUsage">Example usage</h5> 11398<div class="paragraph"> 11399<p>The following XML snippet shows an example of using the Email Task.</p> 11400</div> 11401<div class="listingblock"> 11402<div class="content"> 11403<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 11404 2 11405 3 11406 4 11407 5 11408 6 11409 7 11410 8 11411 9 1141210 1141311 1141412 1141513 1141614 1141715 1141816 1141917 1142018 1142119 1142220 1142321 1142422 1142523 1142624</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"sendMail"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"mail"</span><span class="tok-nt">></span> 11427 <span class="tok-nt"><extensionElements></span> 11428 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"from"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"[email protected]"</span> <span class="tok-nt">/></span> 11429 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"to"</span> <span class="tok-na">expression=</span><span class="tok-s">"${recipient}"</span> <span class="tok-nt">/></span> 11430 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"subject"</span> <span class="tok-na">expression=</span><span class="tok-s">"Your order ${orderId} has been shipped"</span> <span class="tok-nt">/></span> 11431 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"html"</span><span class="tok-nt">></span>
11432 <span class="tok-nt"><activiti:expression></span> 11433 <span class="tok-cp"><![CDATA[</span> 11434<span class="tok-cp"> <html></span> 11435<span class="tok-cp"> <body></span> 11436<span class="tok-cp"> Hello ${male ? 'Mr.' : 'Mrs.' } ${recipientName},<br/><br/></span> 11437 11438<span class="tok-cp"> As of ${now}, your order has been <b>processed and shipped</b>.<br/><br/></span> 11439 11440<span class="tok-cp"> Kind regards,<br/></span> 11441 11442<span class="tok-cp"> TheCompany.</span> 11443<span class="tok-cp"> </body></span> 11444<span class="tok-cp"> </html></span> 11445<span class="tok-cp"> ]]></span> 11446 <span class="tok-nt"></activiti:expression></span> 11447 <span class="tok-nt"></activiti:field></span> 11448 <span class="tok-nt"></extensionElements></span> 11449<span class="tok-nt"></serviceTask></span> 11450</td></tr></table></code></pre> 11451</div> 11452</div> 11453<div class="paragraph"> 11454<p>with the following result:</p> 11455</div> 11456<div class="imageblock" style="text-align: center"> 11457<div class="content"> 11458<img src="images/email.task.result.png" alt="email.task.result"> 11459</div> 11460</div> 11461</div> 11462</div> 11463<div class="sect3"> 11464<h4 id="bpmnMuleTask">8.5.7. Mule Task</h4> 11465<div class="paragraph"> 11466<p>The mule task allows to send messages to Mule enhancing the integration features of Activiti. Note that the mule task is <strong>not</strong> an <em>official</em> task of the BPMN 2.0 spec (and it does not have a dedicated icon as a consequence). Hence, in Activiti the mule task is implemented as a dedicated service task.</p> 11467</div> 11468<div class="sect4"> 11469<h5 id="bpmnMuleTaskUsage">Defining an Mule Task</h5> 11470<div class="paragraph"> 11471<p>The Mule task is implemented as a dedicated <a href="#bpmnJavaServiceTask">Service Task</a> and is defined by setting <em>'mule'</em> for the <em>type</em> of the service task.</p> 11472</div> 11473<div class="listingblock"> 11474<div class="content"> 11475<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"sendMule"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"mule"</span><span class="tok-nt">></span> 11476</td></tr></table></code></pre> 11477</div> 11478</div> 11479<div class="paragraph"> 11480<p>The Mule task is configured by <a href="#serviceTaskFieldInjection">field injection</a>. All the values for these properties can contain EL expression, which are resolved at runtime during process execution. Following properties can be set:</p> 11481</div> 11482<table class="tableblock frame-all grid-all spread"> 11483<colgroup> 11484<col style="width: 33.3333%;"> 11485<col style="width: 33.3333%;"> 11486<col style="width: 33.3334%;"> 11487</colgroup> 11488<thead> 11489<tr> 11490<th class="tableblock halign-left valign-top">Property</th> 11491<th class="tableblock halign-left valign-top">Required?</th> 11492<th class="tableblock halign-left valign-top">Description</th> 11493</tr> 11494</thead> 11495<tbody> 11496<tr> 11497<td class="tableblock halign-left valign-top"><p class="tableblock">endpointUrl</p></td> 11498<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td> 11499<td class="tableblock halign-left valign-top"><p class="tableblock">The Mule endpoint you want to invoke.</p></td> 11500</tr> 11501<tr> 11502<td class="tableblock halign-left valign-top"><p class="tableblock">language</p></td> 11503<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td> 11504<td class="tableblock halign-left valign-top"><p class="tableblock">The language you want to use to evaluate the payloadExpression field.</p></td> 11505</tr> 11506<tr> 11507<td class="tableblock halign-left valign-top"><p class="tableblock">payloadExpression</p></td> 11508<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td> 11509<td class="tableblock halign-left valign-top"><p class="tableblock">An expression that will be the message’s payload.</p></td> 11510</tr> 11511<tr> 11512<td class="tableblock halign-left valign-top"><p class="tableblock">resultVariable</p></td> 11513<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 11514<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable which will store the result of the invocation.</p></td> 11515</tr> 11516</tbody> 11517</table> 11518</div> 11519<div class="sect4"> 11520<h5 id="bpmnMuleTaskExampleUsage">Example usage</h5> 11521<div class="paragraph"> 11522<p>The following XML snippet shows an example of using the Mule Task.</p> 11523</div> 11524<div class="listingblock"> 11525<div class="content"> 11526<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 11527 2 11528 3 11529 4 11530 5 11531 6 11532 7 11533 8 11534 9 1153510 1153611 1153712 1153813 1153914</div></td><td class="code"><span></span><span class="tok-nt"><extensionElements></span> 11540 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"endpointUrl"</span><span class="tok-nt">></span> 11541 <span class="tok-nt"><activiti:string></span>vm://in<span class="tok-nt"></activiti:string></span> 11542 <span class="tok-nt"></activiti:field></span> 11543 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"language"</span><span class="tok-nt">></span> 11544 <span class="tok-nt"><activiti:string></span>juel<span class="tok-nt"></activiti:string></span> 11545 <span class="tok-nt"></activiti:field></span> 11546 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"payloadExpression"</span><span class="tok-nt">></span> 11547 <span class="tok-nt"><activiti:string></span>"hi"
11547<span class="tok-nt"></activiti:string></span> 11548 <span class="tok-nt"></activiti:field></span> 11549 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariable"</span><span class="tok-nt">></span> 11550 <span class="tok-nt"><activiti:string></span>theVariable<span class="tok-nt"></activiti:string></span> 11551 <span class="tok-nt"></activiti:field></span> 11552<span class="tok-nt"></extensionElements></span> 11553</td></tr></table></code></pre> 11554</div> 11555</div> 11556</div> 11557</div> 11558<div class="sect3"> 11559<h4 id="bpmnCamelTask">8.5.8. Camel Task</h4> 11560<div class="paragraph"> 11561<p>The Camel task allows to send messages to and receive messages from Camel and thereby enhances the integration features of Activiti. Note that the Camel task is <strong>not</strong> an <em>official</em> task of the BPMN 2.0 spec (and it does not have a dedicated icon as a consequence). Hence, in Activiti the Camel task is implemented as a dedicated service task. Also note to include the Activiti Camel module in your project to use the Camel task functionality.</p> 11562</div> 11563<div class="sect4"> 11564<h5 id="bpmnCamelTaskUsage">Defining a Camel Task</h5> 11565<div class="paragraph"> 11566<p>The Camel task is implemented as a dedicated <a href="#bpmnJavaServiceTask">Service Task</a> and is defined by setting <em>'camel'</em> for the <em>type</em> of the service task.</p> 11567</div> 11568<div class="listingblock"> 11569<div class="content"> 11570<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"sendCamel"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"camel"</span><span class="tok-nt">></span> 11571</td></tr></table></code></pre> 11572</div> 11573</div> 11574<div class="paragraph"> 11575<p>The process definition itself needs nothing else then the camel type definition on a service task. The integration logic is all delegated to the Camel container. By default the Activiti Engine looks for a camelContext bean in the Spring container. The camelContext bean defines the Camel routes that will be loaded by the Camel container. In the following example the routes are loaded from a specific Java package, but you can also define routes directly in the Spring configuration itself.</p> 11576</div> 11577<div class="listingblock"> 11578<div class="content"> 11579<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 115802 115813 115824 115835</div></td><td class="code"><span></span><span class="tok-nt"><camelContext</span> <span class="tok-na">id=</span><span class="tok-s">"camelContext"</span> <span class="tok-na">xmlns=</span><span class="tok-s">"http://camel.apache.org/schema/spring"</span><span class="tok-nt">></span> 11584 <span class="tok-nt"><packageScan></span> 11585 <span class="tok-nt"><package></span>org.activiti.camel.route<span class="tok-nt"></package></span> 11586 <span class="tok-nt"></packageScan></span> 11587<span class="tok-nt"></camelContext></span> 11588</td></tr></table></code></pre> 11589</div> 11590</div> 11591<div class="paragraph"> 11592<p>For more documentation about Camel routes you can look on the <a href="http://camel.apache.org/">Camel website</a>. The basic concepts are demonstrated through a few small samples here in this document. In the first sample, we will do the simplest form of Camel call from an Activiti workflow. Let’s call it SimpleCamelCall.</p> 11593</div> 11594<div class="paragraph"> 11595<p>If you want to define multiple Camel context beans and/or want to use a different bean name, this can be overridden on the Camel task definition like this:</p> 11596</div> 11597<div class="listingblock"> 11598<div class="content"> 11599<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 116002 116013 116024 116035</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask1"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"camel"</span><span class="tok-nt">></span> 11604 <span class="tok-nt"><extensionElements></span> 11605 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"camelContext"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"customCamelContext"</span> <span class="tok-nt">/></span> 11606 <span class="tok-nt"></extensionElements></span> 11607<span class="tok-nt"></serviceTask></span> 11608</td></tr></table></code></pre> 11609</div> 11610</div> 11611</div> 11612<div class="sect4">
11613<h5 id="bpmnCamelTaskSimpleCamelCall">Simple Camel Call example</h5> 11614<div class="paragraph"> 11615<p>All the files related to this example can be found in org.activiti.camel.examples.simpleCamelCall package of activiti-camel module. The target is simply activating a specific camel route. First of all we need an Spring context which contains the introduction to the routes as mentioned previously. This part of the file serves this purpose:</p> 11616</div> 11617<div class="listingblock"> 11618<div class="content"> 11619<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 116202 116213 116224 116235</div></td><td class="code"><span></span><span class="tok-nt"><camelContext</span> <span class="tok-na">id=</span><span class="tok-s">"camelContext"</span> <span class="tok-na">xmlns=</span><span class="tok-s">"http://camel.apache.org/schema/spring"</span><span class="tok-nt">></span> 11624 <span class="tok-nt"><packageScan></span> 11625 <span class="tok-nt"><package></span>org.activiti.camel.examples.simpleCamelCall<span class="tok-nt"></package></span> 11626 <span class="tok-nt"></packageScan></span> 11627<span class="tok-nt"></camelContext></span> 11628</td></tr></table></code></pre> 11629</div> 11630</div> 11631<div class="listingblock"> 11632<div class="content"> 11633<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 116342 116353 116364 116375 116386 116397</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">SimpleCamelCallRoute</span> <span class="tok-kd">extends</span> <span class="tok-n">RouteBuilder</span> <span class="tok-o">{</span> 11640 11641 <span class="tok-nd">@Override</span> 11642 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">configure</span><span class="tok-o">()</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 11643 <span class="tok-n">from</span><span class="tok-o">(</span><span class="tok-s">"activiti:SimpleCamelCallProcess:simpleCall"</span><span class="tok-o">).</span><span class="tok-na">to</span><span class="tok-o">(</span><span class="tok-s">"log:org.activiti.camel.examples.SimpleCamelCall"</span><span class="tok-o">);</span> 11644 <span class="tok-o">}</span> 11645<span class="tok-o">}</span> 11646</td></tr></table></code></pre> 11647</div> 11648</div> 11649<div class="paragraph"> 11650<p>The route just logs the message body and nothing more. Notice the format of the from endpoint. It is consisted of three parts:</p> 11651</div> 11652<table class="tableblock frame-all grid-all spread"> 11653<colgroup> 11654<col style="width: 50%;"> 11655<col style="width: 50%;"> 11656</colgroup> 11657<thead> 11658<tr> 11659<th class="tableblock halign-left valign-top">Endpoint Url Part</th> 11660<th class="tableblock halign-left valign-top">Description</th> 11661</tr> 11662</thead> 11663<tbody> 11664<tr> 11665<td class="tableblock halign-left valign-top"><p class="tableblock">activiti</p></td> 11666<td class="tableblock halign-left valign-top"><p class="tableblock">refers to Activiti endpoint</p></td> 11667</tr> 11668<tr> 11669<td class="tableblock halign-left valign-top"><p class="tableblock">SimpleCamelCallProcess</p></td> 11670<td class="tableblock halign-left valign-top"><p class="tableblock">name of the process</p></td> 11671</tr> 11672<tr> 11673<td class="tableblock halign-left valign-top"><p class="tableblock">simpleCall</p></td> 11674<td class="tableblock halign-left valign-top"><p class="tableblock">name of the Camel service in the process</p></td> 11675</tr> 11676</tbody> 11677</table> 11678<div class="paragraph"> 11679<p>Ok, our route is now properly configured and accessible to the Camel. Now comes the workflow part. The workflow looks like:</p> 11680</div> 11681<div class="listingblock"> 11682<div class="content"> 11683<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 116842 116853 116864 116875 116886 116897 116908 116919</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"SimpleCamelCallProcess"</span><span class="tok-nt">></span> 11692 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span><span class="tok-nt">/></span> 11693 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"start"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"simpleCall"</span><span class="tok-nt">/></span> 11694 11695 <span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"simpleCall"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"camel"</span><span class="tok-nt">/></span> 11696 11697 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"simpleCall"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"end"</span><span class="tok-nt">/></span> 11698 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"end"</span><span class="tok-nt">/></span> 11699<span class="tok-nt"></process></span> 11700</td></tr></table></code></pre> 11701</div> 11702</div> 11703</div> 11704<div class="sect4"> 11705<h5 id="bpmnCamelTaskPingPong">Ping Pong example</h5> 11706<div class="paragraph"> 11707<p>Our example worked but nothing is really transferred between Camel and Activiti and there is not much merit in it. In this example we try to send and receive data to and from Camel. We send a string, camel concatenates something to it and returns back the result. The sender part is trivial, we send our message in form of a variable to Camel Task. Here is our
11707caller code:</p> 11708</div> 11709<div class="listingblock"> 11710<div class="content"> 11711<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 11712 2 11713 3 11714 4 11715 5 11716 6 11717 7 11718 8 11719 9 1172010 1172111 1172212 1172313</div></td><td class="code"><span></span><span class="tok-nd">@Deployment</span> 11724<span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">testPingPong</span><span class="tok-o">()</span> <span class="tok-o">{</span> 11725 <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();</span> 11726 11727 <span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"input"</span><span class="tok-o">,</span> <span class="tok-s">"Hello"</span><span class="tok-o">);</span> 11728 <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">String</span><span class="tok-o">></span> <span class="tok-n">outputMap</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">String</span><span class="tok-o">>();</span> 11729 <span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"outputMap"</span><span class="tok-o">,</span> <span class="tok-n">outputMap</span><span class="tok-o">);</span> 11730 11731 <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"PingPongProcess"</span><span class="tok-o">,</span> <span class="tok-n">variables</span><span class="tok-o">);</span> 11732 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-mi">1</span><span class="tok-o">,</span> <span class="tok-n">outputMap</span><span class="tok-o">.</span><span class="tok-na">size</span><span class="tok-o">());</span> 11733 <span class="tok-n">assertNotNull</span><span class="tok-o">(</span><span class="tok-n">outputMap</span><span class="tok-o">.</span><span class="tok-na">get</span><span class="tok-o">(</span><span class="tok-s">"outputValue"</span><span class="tok-o">));</span> 11734 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"Hello World"</span><span class="tok-o">,</span> <span class="tok-n">outputMap</span><span class="tok-o">.</span><span class="tok-na">get</span><span class="tok-o">(</span><span class="tok-s">"outputValue"</span><span class="tok-o">));</span> 11735<span class="tok-o">}</span> 11736</td></tr></table></code></pre> 11737</div> 11738</div> 11739<div class="paragraph"> 11740<p>The variable "input" is actually the input for the Camel route and outputMap is there to capture the result back from Camel. The process should be something like this:</p> 11741</div> 11742<div class="listingblock"> 11743<div class="content"> 11744<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 117452 117463 117474 117485 117496 117507 117518 117529</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"PingPongProcess"</span><span class="tok-nt">></span> 11753 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span><span class="tok-nt">/></span> 11754 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"start"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"ping"</span><span class="tok-nt">/></span> 11755 <span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"ping"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"camel"</span><span class="tok-nt">/></span> 11756 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"ping"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"saveOutput"</span><span class="tok-nt">/></span> 11757 <span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"saveOutput"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.camel.examples.pingPong.SaveOutput"</span> <span class="tok-nt">/></span> 11758 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"saveOutput"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"end"</span><span class="tok-nt">/></span> 11759 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"end"</span><span class="tok-nt">/></span> 11760<span class="tok-nt"></process></span> 11761</td></tr></table></code></pre> 11762</div> 11763</div> 11764<div class="paragraph"> 11765<p>Note that SaveOutput Service task, stores the value of "Output" variable from context to the previously mentioned OutputMap. Now we have to know how the variables are send to Camel and returned back. Here comes the notion of Camel behaviour into the play. The way variables are communicated to Camel is configurable via CamelBehavior. Here we use Default one in our sample, a short description of the other ones comes afterwards. With such a code you can configure the desired camel behaviour:</p> 11766</div> 11767<div class="listingblock"> 11768<div class="content"> 11769<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 117702 117713 117724 117735</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceTask1"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"camel"</span><span class="tok-nt">></span> 11774 <span class="tok-nt"><extensionElements></span> 11775 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"camelBehaviorClass"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"org.activiti.camel.impl.CamelBehaviorCamelBodyImpl"</span> <span class="tok-nt">/></span> 11776 <span class="tok-nt"></extensionElements></span> 11777<span class="tok-nt"></serviceTask></span> 11778</td></tr></table></code></pre> 11779</div> 11780</div> 11781<div class="paragraph"> 11782<p>If you do not specify and specific behaviour then, org.activiti.camel.impl.CamelBehaviorDefaultImpl will be set. This behaviour copies the variables to Camel properties of the same name. In return regardless of selected behaviour, if the camel message body is a map, then each of its elements is copied as a variable, else the whole object is copied into a specific variable with the name of "camelBody". Knowing that, this camel route concludes our second example:</p> 11783</div> 11784<div class="listingblock"> 11785<div class="content"> 11786<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 117872 117883 117894</div></td><td class="code"><span></span><span class="tok-nd">
11789@Override</span> 11790<span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">configure</span><span class="tok-o">()</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 11791 <span class="tok-n">from</span><span class="tok-o">(</span><span class="tok-s">"activiti:PingPongProcess:ping"</span><span class="tok-o">).</span><span class="tok-na">transform</span><span class="tok-o">().</span><span class="tok-na">simple</span><span class="tok-o">(</span><span class="tok-s">"${property.input} World"</span><span class="tok-o">);</span> 11792<span class="tok-o">}</span> 11793</td></tr></table></code></pre> 11794</div> 11795</div> 11796<div class="paragraph"> 11797<p>In this route, the string "world" is concatenated to the end of property named "input" and the result will be in the message body. It is accessible by checking "camelBody" variable in the java service task and copied to "outputMap" and checked in test case. Now that the example on its default behaviour works, lets see what are the other possibilities. In starting every camel route, the Process Instance ID will be copied into a camel property with the specific name of "PROCESS_ID_PROPERTY". It is later used for correlating the process instance and camel route. Also it can be exploited in the Camel route.</p> 11798</div> 11799<div class="paragraph"> 11800<p>There are three different behaviours already available out of the box in Activiti. The behaviour can be overwritten by a specific phrase in the route URL. Here is an example of overriding the already defined behaviour in URL:</p> 11801</div> 11802<div class="listingblock"> 11803<div class="content"> 11804<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">from</span><span class="tok-o">(</span><span class="tok-s">"activiti:asyncCamelProcess:serviceTaskAsync2?copyVariablesToProperties=true"</span><span class="tok-o">).</span> 11805</td></tr></table></code></pre> 11806</div> 11807</div> 11808<div class="paragraph"> 11809<p>the following table provides an overview of three available camel behaviours:</p> 11810</div> 11811<table class="tableblock frame-all grid-all spread"> 11812<colgroup> 11813<col style="width: 33.3333%;"> 11814<col style="width: 33.3333%;"> 11815<col style="width: 33.3334%;"> 11816</colgroup> 11817<thead> 11818<tr> 11819<th class="tableblock halign-left valign-top">Behaviour</th> 11820<th class="tableblock halign-left valign-top">In Url</th> 11821<th class="tableblock halign-left valign-top">Description</th> 11822</tr> 11823</thead> 11824<tbody> 11825<tr> 11826<td class="tableblock halign-left valign-top"><p class="tableblock">CamelBehaviorDefaultImpl</p></td> 11827<td class="tableblock halign-left valign-top"><p class="tableblock">copyVariablesToProperties</p></td> 11828<td class="tableblock halign-left valign-top"><p class="tableblock">Copy Activiti variables as Camel properties</p></td> 11829</tr> 11830<tr> 11831<td class="tableblock halign-left valign-top"><p class="tableblock">CamelBehaviorCamelBodyImpl</p></td> 11832<td class="tableblock halign-left valign-top"><p class="tableblock">copyCamelBodyToBody</p></td> 11833<td class="tableblock halign-left valign-top"><p class="tableblock">Copy only Activiti variable named "camelBody" as camel message body</p></td> 11834</tr> 11835<tr> 11836<td class="tableblock halign-left valign-top"><p class="tableblock">CamelBehaviorBodyAsMapImpl</p></td> 11837<td class="tableblock halign-left valign-top"><p class="tableblock">copyVariablesToBodyAsMap</p></td> 11838<td class="tableblock halign-left valign-top"><p class="tableblock">Copy all the Activiti variables in a map as Camel message body</p></td> 11839</tr> 11840</tbody> 11841</table> 11842<div class="paragraph"> 11843<p>The above table explains how Activiti variables are going to be transferred to Camel. The following table explains how the Camel variables are returned back to Activiti. This can only be configured in route URLs.</p> 11844</div> 11845<table class="tableblock frame-all grid-all spread"> 11846<colgroup> 11847<col style="width: 50%;"> 11848<col style="width: 50%;"> 11849</colgroup> 11850<thead> 11851<tr> 11852<th class="tableblock halign-left valign-top">Url</th> 11853<th class="tableblock halign-left valign-top">Description</th> 11854</tr> 11855</thead> 11856<tbody> 11857<tr> 11858<td class="tableblock halign-left valign-top"><p class="tableblock">Default</p></td> 11859<td class="tableblock halign-left valign-top"><p class="tableblock">If Camel body is a map, copy each element as Activiti variable, otherwise copy the whole Camel body as "camelBody" Activiti variable</p></td> 11860</tr> 11861<tr> 11862<td class="tableblock halign-left valign-top"><p class="tableblock">copyVariablesFromProperties</p></td> 11863<td class="tableblock halign-left valign-top"><p class="tableblock">
11863Copy Camel properties as Activiti variables of the same name</p></td> 11864</tr> 11865<tr> 11866<td class="tableblock halign-left valign-top"><p class="tableblock">copyCamelBodyToBodyAsString</p></td> 11867<td class="tableblock halign-left valign-top"><p class="tableblock">like default, but if camel Body is not a map, first convert it to String and then copy it in "camelBody"</p></td> 11868</tr> 11869<tr> 11870<td class="tableblock halign-left valign-top"><p class="tableblock">copyVariablesFromHeader</p></td> 11871<td class="tableblock halign-left valign-top"><p class="tableblock">Additionally copy camel headers to Activiti variables of the same names</p></td> 11872</tr> 11873</tbody> 11874</table> 11875</div> 11876<div class="sect4"> 11877<h5 id="_returning_back_the_variables">Returning back the variables</h5> 11878<div class="paragraph"> 11879<p>What is mentioned above about passing variables, only holds for start side of the variable transfer, in both directions from Camel to Activiti and vice versa.<br> 11880It is important to notice that because of special non blocking behavior of Activiti, variables are not automatically returned back from Activiti to Camel. 11881For that to happen, a special syntax is available. There can be one or more parameters in Camel route URL in format of <code>var.return.someVariableName</code>. 11882All variables having a name equal to one of these parameters without <code>var.return</code> part, will be considered as output variables and will be copied back as camel properties with the same names.<br> 11883For example in a route like:</p> 11884</div> 11885<div class="listingblock"> 11886<div class="content"> 11887<pre>from("direct:start").to("activiti:process?var.return.exampleVar").to("mock:result");</pre> 11888</div> 11889</div> 11890<div class="paragraph"> 11891<p>Activiti variable with the name of <code>exampleVar</code> will be considered as output variable and will be copied back as a property in camel with the same name.</p> 11892</div> 11893</div> 11894<div class="sect4"> 11895<h5 id="bpmnCamelTaskAsyncPingPong">Asynchronous Ping Pong example</h5> 11896<div class="paragraph"> 11897<p>Previous examples were all synchronous. The workflow stops, until the camel route is concluded and returned. In some cases, we might need the Activiti workflow to continue. For such purposes the asynchronous capability of the Camel service task is useful. You can make use of this feature by setting the async property of the Camel service task to true.</p> 11898</div> 11899<div class="listingblock"> 11900<div class="content"> 11901<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"serviceAsyncPing"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"camel"</span> <span class="tok-na">activiti:async=</span><span class="tok-s">"true"</span><span class="tok-nt">/></span> 11902</td></tr></table></code></pre> 11903</div> 11904</div> 11905<div class="paragraph"> 11906<p>By setting this feature the specified Camel route is activated asynchronously by the Activiti job executor. When you define a queue in the Camel route the Activiti process will continue with the activities after the Camel service task. The Camel route will be executed fully asynchronously from the process execution. If you want to wait for a response of the Camel service task somewhere in your process definition, you can use a receive task.</p> 11907</div> 11908<div class="listingblock"> 11909<div class="content"> 11910<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><receiveTask</span> <span class="tok-na">id=</span><span class="tok-s">"receiveAsyncPing"</span> <span class="tok-na">name=</span><span class="tok-s">"Wait State"</span> <span class="tok-nt">/></span> 11911</td></tr></table></code></pre> 11912</div> 11913</div> 11914<div class="paragraph"> 11915<p>The process instance will wait until a signal is received, for example from Camel. In Camel you can send a signal to the process instance by sending a message to the proper Activiti endpoint.</p> 11916</div> 11917<div class="listingblock"> 11918<div class="content"> 11919<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span> <span class="tok-n">from</span><span class="tok-o">(</span><span class="tok-s">"activiti:asyncPingProcess:serviceAsyncPing"</span><span class="tok-o">).</span><span class="tok-na">to</span><span class="tok-o">(</span><span class="tok-s">"activiti:asyncPingProcess:receiveAsyncPing"</span><span class="tok-o">);</span> 11920</td></tr></table></code></pre> 11921</div> 11922</div> 11923<div class="ulist"> 11924<ul> 11925<li> 11926<p>constant string "activiti"</p> 11927</li> 11928<li> 11929<p>process name</p> 11930</li> 11931<li> 11932<p>receive task name</p> 11933</li> 11934</ul> 11935</div> 11936</div> 11937<div class="sect4"> 11938<h5 id="bpmnCamelTaskAsyncPingPong">Instantiate workflow from Camel route</h5> 11939<div class="paragraph"> 11940<p>In our all previous examples Activiti workflow started first and the Camel route was started within workflow. It is also possible from the other side. It is possible that a workflow is instantiated from an already started camel route. It is very similar to signalling receive task, except that the last part is not there. Here is a sample route:</p> 11941</div> 11942<div class="listingblock"> 11943<div class="content"> 11944<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">from</span><span class="tok-o">(</span><span class="tok-s">"direct:start"</span><span class="tok-o">).</span><span class="tok-na">to</span><span class="tok-o">(</span><span class="tok-s">"activiti:camelProcess"</span><span class="tok-o">);</span> 11945</td></tr></table></code></pre> 11946</div> 11947</div> 11948<div class="paragraph"> 11949<p>as you see the url has two parts, the first is constant string "activiti" and the second name is the name of the process. Obviously the process should already be deployed and startable by engine configuration.</p> 11950</div> 11951<div class="paragraph"> 11952<p>It is also possible to set the initiator of the process to some authenticated user id that is provided in a Camel header. To achieve this first of all an initiator variable must be specified in the process definition:</p> 11953</div> 11954<div class="listingblock"> 11955<div class="content"> 11956<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span> <span class="tok-na">activiti:initiator=</span><span class="tok-s">"initiator"</span> <span class="tok-nt">/></span> 11957</td></tr></table></code></pre> 11958</div> 11959</div> 11960<div class="paragraph"> 11961<p>Then given that the user id is contained in a Camel header named <em>CamelProcessInitiatorHeader</em> the Camel route could be defined as follows:</p> 11962</div> 11963<div class="listingblock"> 11964<div class="content"> 11965<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 119662 119673</div></td><td class="code"><span></span><span class="tok-n">from</span><span class="tok-o">(</span><span class="tok-s">"direct:startWithInitiatorHeader"</span><span class="tok-o">)</span> 11968 <span class="tok-o">.</span><span class="tok-na">setHeader</span><span class="tok-o">(</span><span class="tok-s">"CamelProcessInitiatorHeader"</span><span class="tok-o">,</span> <span class="tok-n">constant</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">))</span> 11969 <span class="tok-o">.</span><span class="tok-na">to</span><span class="tok-o">(</span><span class="tok-s">"activiti:InitiatorCamelCallProcess?processInitiatorHeaderName=CamelProcessInitiatorHeader"</span><span class="tok-o">);</span> 11970</td></tr></table></code></pre> 11971</div> 11972</div> 11973</div> 11974</div> 11975<div class="sect3"> 11976<h4 id="bpmnManualTask">8.5.9. Manual Task</h4> 11977<div class="sect4"> 11978<h5 id="bpmnManualTaskDescription">Description</h5> 11979<div class="paragraph"> 11980<p>A <em>Manual Task</em> defines a task that is external to the BPM engine. It is used to model work that is done by somebody, which the engine does not need to know of, nor is there a system or UI interface. For the engine, a manual task is handled as a <strong>pass-through activity</strong>, automatically continuing the process from the moment process execution arrives into it.</p> 11981</div> 11982</div> 11983<div class="sect4"> 11984<h5 id="bpmnManualTaskGraphicalNotation">Graphical Notation</h5> 11985<div class="paragraph"> 11986<p>A manual task is visualized as a rounded rectangle, with a little <em>hand</em> icon in the upper left corner</p> 11987</div> 11988<div class="imageblock" style="text-align: center"> 11989<div class="content"> 11990<img src="images/bpmn.manual.task.png" alt="bpmn.manual.task"> 11991</div> 11992</div> 11993</div> 11994<div class="sect4"> 11995<h5 id="bpmnManualTaskXml">XML representation</h5> 11996<div class="listingblock"> 11997<div class="content"> 11998<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><manualTask</span> <span class="tok-na">id=</span><span class="tok-s">"myManualTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Call client for more information"</span> <span class="tok-nt">/></span> 11999</td></tr></table></code></pre> 12000</div> 12001</div> 12002</div> 12003</div> 12004<div class="sect3"> 12005<h4 id="bpmnReceiveTask">8.5.10. Java Receive Task</h4> 12006<div class="sect4"> 12007<h5 id="bpmnReceiveTaskDescription">Description</h5> 12008<div class="paragraph"> 12009<p>A Receive Task is a simple task that waits for the arrival of a certain message. Currently, we have only implemented Java semantics for this task. When process execution arrives at a Receive Task, the process state is committed to the persistence store. This means that the process will stay in this wait state, until a specific message is received by the engine, which triggers the continuation of the process past the Receive Task.</p> 12010</div> 12011</div> 12012<div class="sect4"> 12013<h5 id="_graphical_notation_2">Graphical notation</h5> 12014<div class="paragraph"> 12015<p>A Receive Task is visualized as a task (rounded rectangle) with a message icon in the top left corner. The message is white (a black message icon would have send semantics)</p> 12016</div> 12017<div class="imageblock" style="text-align: center"> 12018<div class="content"> 12019<img src="images/bpmn.receive.task.png" alt="bpmn.receive.task"> 12020</div> 12021</div> 12022</div> 12023<div class="sect4"> 12024<h5 id="_xml_representation_2">XML representation</h5> 12025<div class="listingblock"> 12026<div class="content"> 12027<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><receiveTask</span> <span class="tok-na">id=</span><span class="tok-s">"waitState"</span> <span class="tok-na">name=</span><span class="tok-s">"wait"</span> <span class="tok-nt">/></span> 12028</td></tr></table></code></pre> 12029</div> 12030</div> 12031<div class="paragraph"> 12032<p>To continue a process instance that is currently waiting at such a Receive Task, the <em>runtimeService.signal(executionId)</em> must be called using the id of the execution that arrived in the Receive Task. The following code snippet shows how this works in practice:</p> 12033</div> 12034<div class="listingblock"> 12035<div class="content"> 12036<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 120372 120383 120394 120405 120416 120427 120438</div></td><td class="code"><span></span><span class="tok-n">ProcessInstance</span> <span class="tok-n">
12043pi</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"receiveTask"</span><span class="tok-o">);</span> 12044<span class="tok-n">Execution</span> <span class="tok-n">execution</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createExecutionQuery</span><span class="tok-o">()</span> 12045 <span class="tok-o">.</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-n">pi</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">())</span> 12046 <span class="tok-o">.</span><span class="tok-na">activityId</span><span class="tok-o">(</span><span class="tok-s">"waitState"</span><span class="tok-o">)</span> 12047 <span class="tok-o">.</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 12048<span class="tok-n">assertNotNull</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">);</span> 12049 12050<span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">signal</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 12051</td></tr></table></code></pre> 12052</div> 12053</div> 12054</div> 12055</div> 12056<div class="sect3"> 12057<h4 id="bpmnShellTask">8.5.11. Shell Task</h4> 12058<div class="sect4"> 12059<h5 id="bpmnShellTaskDescription">Description</h5> 12060<div class="paragraph"> 12061<p>The shell task allows to run shell scripts and commands. Note that the Shell task is <strong>not</strong> an <em>official</em> task of BPMN 2.0 spec (and it does not have a dedicated icon as a consequence).</p> 12062</div> 12063</div> 12064<div class="sect4"> 12065<h5 id="bpmnShellTaskUsage">Defining a shell task</h5> 12066<div class="paragraph"> 12067<p>The shell task is implemented as a dedicated <a href="#bpmnJavaServiceTask">Service Task</a> and is defined by setting <em>'shell'</em> for the <em>type</em> of the service task.</p> 12068</div> 12069<div class="listingblock"> 12070<div class="content"> 12071<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"shellEcho"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"shell"</span><span class="tok-nt">></span> 12072</td></tr></table></code></pre> 12073</div> 12074</div> 12075<div class="paragraph"> 12076<p>The Shell task is configured by <a href="#serviceTaskFieldInjection">field injection</a>. All the values for these properties can contain EL expression, which are resolved at runtime during process execution. Following properties could be set:</p> 12077</div> 12078<table class="tableblock frame-all grid-all spread"> 12079<colgroup> 12080<col style="width: 20%;"> 12081<col style="width: 20%;"> 12082<col style="width: 20%;"> 12083<col style="width: 20%;"> 12084<col style="width: 20%;"> 12085</colgroup> 12086<thead> 12087<tr> 12088<th class="tableblock halign-left valign-top">Property</th> 12089<th class="tableblock halign-left valign-top">Required?</th> 12090<th class="tableblock halign-left valign-top">Type</th> 12091<th class="tableblock halign-left valign-top">Description</th> 12092<th class="tableblock halign-left valign-top">Default</th> 12093</tr> 12094</thead> 12095<tbody> 12096<tr> 12097<td class="tableblock halign-left valign-top"><p class="tableblock">command</p></td> 12098<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td> 12099<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 12100<td class="tableblock halign-left valign-top"><p class="tableblock">Shell command to execute.</p></td> 12101<td class="tableblock halign-left valign-top"></td> 12102</tr> 12103<tr> 12104<td class="tableblock halign-left valign-top"><p class="tableblock">arg0-5</p></td> 12105<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12106<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 12107<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter 0 to Parameter 5</p></td> 12108<td class="tableblock halign-left valign-top"></td> 12109</tr> 12110<tr> 12111<td class="tableblock halign-left valign-top"><p class="tableblock">wait</p></td> 12112<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12113<td class="tableblock halign-left valign-top"><p class="tableblock">true/false</p></td> 12114<td class="tableblock halign-left valign-top"><p class="tableblock">wait if necessary, until the shell process has terminated.</p></td> 12115<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> 12116</tr> 12117<tr> 12118<td class="tableblock halign-left valign-top"><p class="tableblock">redirectError</p></td> 12119<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12120<td class="tableblock halign-left valign-top"><p class="tableblock">true/false</p></td> 12121<td class="tableblock halign-left valign-top"><p class="tableblock">Merge standard error with the standard output.</p></td> 12122<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> 12123</tr> 12124<tr> 12125<td class="tableblock halign-left valign-top"><p class="tableblock">cleanEnv</p></td> 12126<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12127<td class="tableblock halign-left valign-top"><p class="tableblock">true/false</p></td> 12128<td class="tableblock halign-left valign-top"><p class="tableblock">Shell process does not inherit current environment.</p></td> 12129<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> 12130</tr> 12131<tr> 12132<td class="tableblock halign-left valign-top"><p class="tableblock">outputVariable</p></td> 12133<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12134<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 12135<td class="tableblock halign-left valign-top"><p class="tableblock">Name of variable to contain the output</p></td> 12136<td class="tableblock halign-left valign-top"><p class="tableblock">Output is not recorded.</p></td> 12137</tr> 12138<tr> 12139<td class="tableblock halign-left valign-top"><p class="tableblock">errorCodeVariable</p></td> 12140<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12141<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 12142<td class="tableblock halign-left valign-top"><p class="tableblock">Name of variable to contain result error code</p></td> 12143<td class="tableblock halign-left valign-top"><p class="tableblock">Error level is not registered.</p></td> 12144</tr> 12145<tr> 12146<td class="tableblock halign-left valign-top"><p class="tableblock">directory</p></td> 12147<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td> 12148<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 12149<td class="tableblock halign-left valign-top"><p class="tableblock">Default directory of shell process</p></td> 12150<td class="tableblock halign-left valign-top"><p class="tableblock">Current directory</p></td> 12151</tr> 12152</tbody> 12153</table> 12154</div> 12155<div class="sect4"> 12156<h5 id="bpmnShellTaskExampleUsage">Example usage</h5> 12157<div class="paragraph"> 12158<p>The following XML snippet shows an example of using the shell Task. It runs shell script "cmd /c echo Ec
12158hoTest", waits for it to be terminated and puts the result in resultVar</p> 12159</div> 12160<div class="listingblock"> 12161<div class="content"> 12162<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12163 2 12164 3 12165 4 12166 5 12167 6 12168 7 12169 8 12170 9 1217110</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"shellEcho"</span> <span class="tok-na">activiti:type=</span><span class="tok-s">"shell"</span> <span class="tok-nt">></span> 12172 <span class="tok-nt"><extensionElements></span> 12173 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"command"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"cmd"</span> <span class="tok-nt">/></span> 12174 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"arg1"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"/c"</span> <span class="tok-nt">/></span> 12175 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"arg2"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"echo"</span> <span class="tok-nt">/></span> 12176 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"arg3"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"EchoTest"</span> <span class="tok-nt">/></span> 12177 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"wait"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 12178 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"outputVariable"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"resultVar"</span> <span class="tok-nt">/></span> 12179 <span class="tok-nt"></extensionElements></span> 12180<span class="tok-nt"></serviceTask></span> 12181</td></tr></table></code></pre> 12182</div> 12183</div> 12184</div> 12185</div> 12186<div class="sect3"> 12187<h4 id="executionListeners">8.5.12. Execution listener</h4> 12188<div class="paragraph"> 12189<p><strong>Compatibility note</strong>: After releasing 5.3, we discovered that execution listeners and task listeners and expressions were still in non-public API. Those classes were in subpackages of <code>org.activiti.engine.impl…​</code>, which has <code>impl</code> in it). <code>org.activiti.engine.impl.pvm.delegate.ExecutionListener</code>, <code>org.activiti.engine.impl.pvm.delegate.TaskListener</code> and <code>org.activiti.engine.impl.pvm.el.Expression</code> have been deprecated. From now on, you should use <code>org.activiti.engine.delegate.ExecutionListener</code>, <code>org.activiti.engine.delegate.TaskListener</code> and <code>org.activiti.engine.delegate.Expression</code>. In the new publicly available API, access to <code>ExecutionListenerExecution.getEventSource()</code> has been removed. Apart from the deprecation compiler warning, the existing code should run fine. But consider switching to the new public API interfaces (without .impl. in the package name).</p> 12190</div> 12191<div class="paragraph"> 12192<p>Execution listeners allow you to execute external Java code or evaluate an expression when certain events occur during process execution. The events that can be captured are:</p> 12193</div> 12194<div class="ulist"> 12195<ul> 12196<li> 12197<p>Start and ending of a process instance.</p> 12198</li> 12199<li> 12200<p>Taking a transition.</p> 12201</li> 12202<li> 12203<p>Start and ending of an activity.</p> 12204</li> 12205<li> 12206<p>Start and ending of a gateway.</p> 12207</li> 12208<li> 12209<p>Start and ending of intermediate events.</p> 12210</li> 12211<li> 12212<p>Ending a start event or starting an end event.</p> 12213</li> 12214</ul> 12215</div> 12216<div class="paragraph"> 12217<p>The following process definition contains 3 execution listeners:</p> 12218</div> 12219<div class="listingblock"> 12220<div class="content"> 12221<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12222 2 12223 3 12224 4 12225 5 12226 6 12227 7 12228 8 12229 9 1223010 1223111 1223212 1223313 1223414 1223515 1223616 1223717 1223818 1223919 1224020 1224121 1224222 1224323 1224424 1224525 1224626 1224727 1224828 1224929</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"executionListenersProcess"</span><span class="tok-nt">></span> 12250 12251 <span class="tok-nt"><extensionElements></span> 12252 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.examples.bpmn.executionlistener.ExampleExecutionListenerOne"</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span> <span class="tok-nt">/></span> 12253 <span class="tok-nt"></extensionElements></span> 12254 12255 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 12256 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"firstTask"</span> <span class="tok-nt">/></span> 12257 12258 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"firstTask"</span> <span class="tok-nt">/></span> 12259 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"firstTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"secondTask"</span><span class="tok-nt">></span> 12260 <span class="tok-nt"><extensionElements></span>
12261 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.examples.bpmn.executionListener.ExampleExecutionListenerTwo"</span> <span class="tok-nt">/></span> 12262 <span class="tok-nt"></extensionElements></span> 12263 <span class="tok-nt"></sequenceFlow></span> 12264 12265 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"secondTask"</span> <span class="tok-nt">></span> 12266 <span class="tok-nt"><extensionElements></span> 12267 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">expression=</span><span class="tok-s">"${myPojo.myMethod(execution.event)}"</span> <span class="tok-na">event=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 12268 <span class="tok-nt"></extensionElements></span> 12269 <span class="tok-nt"></userTask></span> 12270 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"secondTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"thirdTask"</span> <span class="tok-nt">/></span> 12271 12272 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"thirdTask"</span> <span class="tok-nt">/></span> 12273 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"thirdTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 12274 12275 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 12276 12277<span class="tok-nt"></process></span> 12278</td></tr></table></code></pre> 12279</div> 12280</div> 12281<div class="paragraph"> 12282<p>The first execution listener is notified when the process starts. The listener is an external Java-class (like <code>ExampleExecutionListenerOne</code>) and should implement <code>org.activiti.engine.delegate.ExecutionListener</code> interface. When the event occurs (in this case <code>end</code> event) the method <code>notify(ExecutionListenerExecution execution)</code> is called.</p> 12283</div> 12284<div class="listingblock"> 12285<div class="content"> 12286<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 122872 122883 122894 122905 122916 122927</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ExampleExecutionListenerOne</span> <span class="tok-kd">implements</span> <span class="tok-n">ExecutionListener</span> <span class="tok-o">{</span> 12293 12294 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">notify</span><span class="tok-o">(</span><span class="tok-n">ExecutionListenerExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 12295 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"variableSetInExecutionListener"</span><span class="tok-o">,</span> <span class="tok-s">"firstValue"</span><span class="tok-o">);</span> 12296 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"eventReceived"</span><span class="tok-o">,</span> <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">getEventName</span><span class="tok-o">());</span> 12297 <span class="tok-o">}</span> 12298<span class="tok-o">}</span> 12299</td></tr></table></code></pre> 12300</div> 12301</div> 12302<div class="paragraph"> 12303<p>It is also possible to use a delegation class that implements the <code>org.activiti.engine.delegate.JavaDelegate</code> interface. These delegation classes can then be reused in other constructs, such as a delegation for a serviceTask.</p> 12304</div> 12305<div class="paragraph"> 12306<p>The second execution listener is called when the transition is taken. Note that the <code>listener</code> element doesn’t define an <code>event</code>, since only <code>take</code> events are fired on transitions. <strong>Values in the <code>event</code> attribute are ignored when a listener is defined on a transition.</strong></p> 12307</div> 12308<div class="paragraph"> 12309<p>The last execution listener is called when activity <code>secondTask</code> ends. Instead of using the <code>class</code> on the listener declaration, a <code>expression</code> is defined instead which is evaluated/invoked when the event is fired.</p> 12310</div> 12311<div class="listingblock"> 12312<div class="content"> 12313<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">expression=</span><span class="tok-s">"${myPojo.myMethod(execution.eventName)}"</span> <span class="tok-na">event=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 12314</td></tr></table></code></pre> 12315</div> 12316</div> 12317<div class="paragraph"> 12318<p>As with other expressions, execution variables are resolved and can be used. Because the execution implementation object has a property that exposes the event name, it’s possible to pass the event-name to your methods using <code>execution.eventName</code>.</p> 12319</div> 12320<div class="paragraph"> 12321<p>Execution listeners also support using a <code>delegateExpression</code>, <a href="#bpmnJavaServiceTaskXML">similar to a service task</a>.</p> 12322</div> 12323<div class="listingblock"> 12324<div class="content"> 12325<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span> <span class="tok-na">delegateExpression=</span><span class="tok-s">"${myExecutionListenerBean}"</span> <span class="tok-nt">/></span> 12326</td></tr></table></code></pre> 12327</div> 12328</div> 12329<div class="paragraph"> 12330<p>In Activiti 5.12 we also introduced a new type of execution listener, the org.activiti.engine.impl.bpmn.listener.ScriptExecutionListener. This script execution listener allows you to execute a piece of script logic for an execution listener event.</p> 12331</div> 12332<div class="listingblock"> 12333<div class="content"> 12334<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12335 2 12336 3 12337 4 12338 5 12339 6 12340 7 12341 8 12342 9 1234310 1234411
1234512</div></td><td class="code"><span></span><span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.bpmn.listener.ScriptExecutionListener"</span> <span class="tok-nt">></span> 12346 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"script"</span><span class="tok-nt">></span> 12347 <span class="tok-nt"><activiti:string></span> 12348 def bar = "BAR"; // local variable 12349 foo = "FOO"; // pushes variable to execution context 12350 execution.setVariable("var1", "test"); // test access to execution instance 12351 bar // implicit return value 12352 <span class="tok-nt"></activiti:string></span> 12353 <span class="tok-nt"></activiti:field></span> 12354 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"language"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"groovy"</span> <span class="tok-nt">/></span> 12355 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariable"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"myVar"</span> <span class="tok-nt">/></span> 12356<span class="tok-nt"></activiti:executionListener></span> 12357</td></tr></table></code></pre> 12358</div> 12359</div> 12360<div class="sect4"> 12361<h5 id="executionListenerFieldInjection">Field injection on execution listeners</h5> 12362<div class="paragraph"> 12363<p>When using an execution listener that is configured with the <code>class</code> attribute, field injection can be applied. This is exactly the same mechanism as used <a href="#serviceTaskFieldInjection">Service task field injection</a>, which contains an overview of the possibilities provided by field injection.</p> 12364</div> 12365<div class="paragraph"> 12366<p>The fragment below shows a simple example process with an execution listener with fields injected.</p> 12367</div> 12368<div class="listingblock"> 12369<div class="content"> 12370<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12371 2 12372 3 12373 4 12374 5 12375 6 12376 7 12377 8 12378 9 1237910 1238011 1238112 1238213 1238314 1238415 1238516</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"executionListenersProcess"</span><span class="tok-nt">></span> 12386 <span class="tok-nt"><extensionElements></span> 12387 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.examples.bpmn.executionListener.ExampleFieldInjectedExecutionListener"</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span><span class="tok-nt">></span> 12388 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"fixedValue"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"Yes, I am "</span> <span class="tok-nt">/></span> 12389 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"dynamicValue"</span> <span class="tok-na">expression=</span><span class="tok-s">"${myVar}"</span> <span class="tok-nt">/></span> 12390 <span class="tok-nt"></activiti:executionListener></span> 12391 <span class="tok-nt"></extensionElements></span> 12392 12393 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 12394 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"firstTask"</span> <span class="tok-nt">/></span> 12395 12396 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"firstTask"</span> <span class="tok-nt">/></span> 12397 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"firstTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 12398 12399 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theEnd"</span> <span class="tok-nt">/></span> 12400<span class="tok-nt"></process></span> 12401</td></tr></table></code></pre> 12402</div> 12403</div> 12404<div class="listingblock"> 12405<div class="content"> 12406<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12407 2 12408 3 12409 4 12410 5 12411 6 12412 7 12413 8 12414 9 1241510</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ExampleFieldInjectedExecutionListener</span> <span class="tok-kd">implements</span> <span class="tok-n">ExecutionListener</span> <span class="tok-o">{</span> 12416 12417 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">fixedValue</span><span class="tok-o">;</span> 12418 12419 <span class="tok-kd">private</span> <span class="tok-n">Expression</span> <span class="tok-n">dynamicValue</span><span class="tok-o">;</span> 12420 12421 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">notify</span><span class="tok-o">(</span><span class="tok-n">ExecutionListenerExecution</span> <span class="tok-n">execution</span><span class="tok-o">)</span> <span class="tok-kd">throws</span> <span class="tok-n">Exception</span> <span class="tok-o">{</span> 12422 <span class="tok-n">execution</span><span class="tok-o">.</span><span class="tok-na">setVariable</span><span class="tok-o">(</span><span class="tok-s">"var"</span><span class="tok-o">,</span> <span class="tok-n">fixedValue</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">).</span><span class="tok-na">toString</span><span class="tok-o">()</span> <span class="tok-o">+</span> <span class="tok-n">dynamicValue</span><span class="tok-o">.</span><span class="tok-na">getValue</span><span class="tok-o">(</span><span class="tok-n">execution</span><span class="tok-o">).</span><span class="tok-na">toString</span><span class="tok-o">());</span> 12423 <span class="tok-o">}</span> 12424<span class="tok-o">}</span> 12425</td></tr></table></code></pre> 12426</div> 12427</div> 12428<div class="paragraph"> 12429<p>The class <code>ExampleFieldInjectedExecutionListener</code> concatenates the 2 injected fields (one fixed an the other dynamic) and stores this in the process variable <em><code>var</code></em>.</p> 12430</div> 12431<div class="listingblock"> 12432<div class="content"> 12433<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12434 2 12435 3 12436 4 12437 5 12438 6 12439 7 12440 8 12441 9 1244210 1244311 1244412 1244513 1244614</div></td><td class="code"><span></span><span class="tok-nd">@Deployment</span><span class="tok-o">(</span><span class="tok-n">resources</span> <span class="tok-o">=</span> <span class="tok-o">{</span><span class="tok-s">"org/activiti/examples/bpmn/executionListener/ExecutionListenersFieldInjectionProcess.bpmn20.xml"</span><span class="tok-o">})</span> 12447<span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">testExecutionListenerFieldInjection</span><span class="tok-o">()</span> <span class="tok-o">{</span> 12448 <span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();
12448</span> 12449 <span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"myVar"</span><span class="tok-o">,</span> <span class="tok-s">"listening!"</span><span class="tok-o">);</span> 12450 12451 <span class="tok-n">ProcessInstance</span> <span class="tok-n">processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"executionListenersProcess"</span><span class="tok-o">,</span> <span class="tok-n">variables</span><span class="tok-o">);</span> 12452 12453 <span class="tok-n">Object</span> <span class="tok-n">varSetByListener</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">getVariable</span><span class="tok-o">(</span><span class="tok-n">processInstance</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-s">"var"</span><span class="tok-o">);</span> 12454 <span class="tok-n">assertNotNull</span><span class="tok-o">(</span><span class="tok-n">varSetByListener</span><span class="tok-o">);</span> 12455 <span class="tok-n">assertTrue</span><span class="tok-o">(</span><span class="tok-n">varSetByListener</span> <span class="tok-k">instanceof</span> <span class="tok-n">String</span><span class="tok-o">);</span> 12456 12457 <span class="tok-c1">// Result is a concatenation of fixed injected field and injected expression</span> 12458 <span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"Yes, I am listening!"</span><span class="tok-o">,</span> <span class="tok-n">varSetByListener</span><span class="tok-o">);</span> 12459<span class="tok-o">}</span> 12460</td></tr></table></code></pre> 12461</div> 12462</div> 12463<div class="paragraph"> 12464<p>Note that the same rules with regards to thread-safety apply as for service task. Please read the <a href="#serviceTaskFieldInjectionThreadSafety">relevant section</a> for more information.</p> 12465</div> 12466</div> 12467</div> 12468<div class="sect3"> 12469<h4 id="taskListeners">8.5.13. Task listener</h4> 12470<div class="paragraph"> 12471<p>A <em>task listener</em> is used to execute custom Java logic or an expression upon the occurrence of a certain task-related event.</p> 12472</div> 12473<div class="paragraph"> 12474<p>A task listener can only be added in the process definition as a child element of a <a href="#bpmnUserTask">user task</a>. Note that this also must happen as a child of the <em>BPMN 2.0 extensionElements</em> and in the <em>activiti</em> namespace, since a task listener is an Activiti-specific construct.</p> 12475</div> 12476<div class="listingblock"> 12477<div class="content"> 12478<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 124792 124803 124814 124825</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"myTask"</span> <span class="tok-na">name=</span><span class="tok-s">"My Task"</span> <span class="tok-nt">></span> 12483 <span class="tok-nt"><extensionElements></span> 12484 <span class="tok-nt"><activiti:taskListener</span> <span class="tok-na">event=</span><span class="tok-s">"create"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyTaskCreateListener"</span> <span class="tok-nt">/></span> 12485 <span class="tok-nt"></extensionElements></span> 12486<span class="tok-nt"></userTask></span> 12487</td></tr></table></code></pre> 12488</div> 12489</div> 12490<div class="paragraph"> 12491<p>A <em>task listener</em> supports following attributes:</p> 12492</div> 12493<div class="ulist"> 12494<ul> 12495<li> 12496<p><strong>event</strong> (required): the type of task event on which the task listener will be invoked. Possible events are</p> 12497<div class="ulist"> 12498<ul> 12499<li> 12500<p><strong>create</strong>: occurs when the task has been created an <strong>all task properties are set</strong>.</p> 12501</li> 12502<li> 12503<p><strong>assignment</strong>: occurs when the task is assigned to somebody. Note: when process execution arrives in a userTask, first an <em>assignment</em> event will be fired, <strong>before</strong> the <em>create</em> event is fired. This might seem an unnatural order, but the reason is pragmatic: when receiving the <em>create</em> event, we usually want to inspect all properties of the task including the assignee.</p> 12504</li> 12505<li> 12506<p><strong>complete</strong>: occurs when the task is completed and just before the task is deleted from the runtime data.</p> 12507</li> 12508<li> 12509<p><strong>delete</strong>: occurs just before the task is going to be deleted. Notice that it will also be executed when task is normally finished via completeTask.</p> 12510</li> 12511</ul> 12512</div> 12513</li> 12514<li> 12515<p><strong>class</strong>: the delegation class that must be called. This class must implement the <code>org.activiti.engine.delegate.TaskListener</code> interface.</p> 12516</li> 12517</ul> 12518</div> 12519<div class="listingblock"> 12520<div class="content"> 12521<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 125222 125233 125244 125255 125266 125277</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyTaskCreateListener</span> <span class="tok-kd">implements</span> <span class="tok-n">TaskListener</span> <span class="tok-o">{</span> 12528 12529 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">notify</span><span class="tok-o">(</span><span class="tok-n">DelegateTask</span> <span class="tok-n">delegateTask</span><span class="tok-o">)</span> <span class="tok-o">{</span> 12530 <span class="tok-c1">
12530// Custom logic goes here</span> 12531 <span class="tok-o">}</span> 12532 12533<span class="tok-o">}</span> 12534</td></tr></table></code></pre> 12535</div> 12536</div> 12537<div class="paragraph"> 12538<p>It is also possible to use <a href="#serviceTaskFieldInjection">field injection</a> to pass process variables or the execution to the delegation class. Note that an instance of the delegation class is created upon process deployment (as is the case with any class delegation in Activiti), which means that the instance is shared between all process instance executions.</p> 12539</div> 12540<div class="ulist"> 12541<ul> 12542<li> 12543<p><strong>expression</strong>: (cannot be used together with the <em>class</em> attribute): specifies an expression that will be executed when the event happens. It is possible to pass the <code>DelegateTask</code> object and the name of the event (using <code>task.eventName</code>) as parameter to the called object.</p> 12544</li> 12545</ul> 12546</div> 12547<div class="listingblock"> 12548<div class="content"> 12549<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-o"><</span><span class="tok-n">activiti</span><span class="tok-o">:</span><span class="tok-n">taskListener</span> <span class="tok-n">event</span><span class="tok-o">=</span><span class="tok-s">"create"</span> <span class="tok-n">expression</span><span class="tok-o">=</span><span class="tok-s">"${myObject.callMethod(task, task.eventName)}"</span> <span class="tok-o">/></span> 12550</td></tr></table></code></pre> 12551</div> 12552</div> 12553<div class="ulist"> 12554<ul> 12555<li> 12556<p><strong>delegateExpression</strong> allows to specify an expression that resolves to an object implementing the <code>TaskListener</code> interface, <a href="#bpmnJavaServiceTaskXML">similar to a service task</a>.</p> 12557</li> 12558</ul> 12559</div> 12560<div class="listingblock"> 12561<div class="content"> 12562<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><activiti:taskListener</span> <span class="tok-na">event=</span><span class="tok-s">"create"</span> <span class="tok-na">delegateExpression=</span><span class="tok-s">"${myTaskListenerBean}"</span> <span class="tok-nt">/></span> 12563</td></tr></table></code></pre> 12564</div> 12565</div> 12566<div class="ulist"> 12567<ul> 12568<li> 12569<p>In Activiti 5.12 we also introduced a new type of task listener, the org.activiti.engine.impl.bpmn.listener.ScriptTaskListener. This script task listener allows you to execute a piece of script logic for an task listener event.</p> 12570</li> 12571</ul> 12572</div> 12573<div class="listingblock"> 12574<div class="content"> 12575<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12576 2 12577 3 12578 4 12579 5 12580 6 12581 7 12582 8 12583 9 1258410 1258511 1258612</div></td><td class="code"><span></span><span class="tok-nt"><activiti:taskListener</span> <span class="tok-na">event=</span><span class="tok-s">"complete"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.bpmn.listener.ScriptTaskListener"</span> <span class="tok-nt">></span> 12587 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"script"</span><span class="tok-nt">></span> 12588 <span class="tok-nt"><activiti:string></span> 12589 def bar = "BAR"; // local variable 12590 foo = "FOO"; // pushes variable to execution context 12591 task.setOwner("kermit"); // test access to task instance 12592 bar // implicit return value 12593 <span class="tok-nt"></activiti:string></span> 12594 <span class="tok-nt"></activiti:field></span> 12595 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"language"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"groovy"</span> <span class="tok-nt">/></span> 12596 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"resultVariable"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"myVar"</span> <span class="tok-nt">/></span> 12597<span class="tok-nt"></activiti:taskListener></span> 12598</td></tr></table></code></pre> 12599</div> 12600</div> 12601</div> 12602<div class="sect3"> 12603<h4 id="bpmnMultiInstance">8.5.14. Multi-instance (for each)</h4> 12604<div class="sect4"> 12605<h5 id="bpmnMultiInstanceDescription">Description</h5> 12606<div class="paragraph"> 12607<p>A <em>multi-instance activity</em> is a way of defining repetition for a certain step in a business process. In programming concepts, a multi-instance matches the <strong>for each</strong> construct: it allows to execute a certain step or even a complete subprocess for each item in a given collection, <strong>sequentially or in parallel</strong>.</p> 12608</div> 12609<div class="paragraph"> 12610<p>A <em>multi-instance</em> is a regular activity that has extra properties defined (so-called <em>'multi-instance</em> characteristics'') which will cause the activity to be executed multiple times at runtime. Following activities can become a <em>multi-instance activity:</em></p> 12611</div> 12612<div class="ulist"> 12613<ul> 12614<li> 12615<p><a href="#bpmnUserTask">User Task</a></p> 12616</li> 12617<li> 12618<p><a href="#bpmnScriptTask">Script Task</a></p> 12619</li> 12620<li> 12621<p><a href="#bpmnJavaServiceTask">Java Service Task</a></p> 12622</li> 12623<li> 12624<p><a href="#bpmnWebserviceTask">Web Service Task</a></p> 12625</li> 12626<li> 12627<p><a href="#bpmnBusinessRuleTask">Business Rule Task</a></p> 12628</li> 12629<li> 12630<p><a href="#bpmnEmailTask">Email Task</a></p> 12631</li> 12632<li> 12633<p><a href="#bpmnManualTask">Manual Task</a></p> 12634</li> 12635<li> 12636<p><a href="#bpmnReceiveTask">Receive Task</a></p> 12637</li> 12638<li> 12639<p><a href="#bpmnSubProcess">
12639(Embedded) Sub-Process</a></p> 12640</li> 12641<li> 12642<p><a href="#bpmnCallActivity">Call Activity</a></p> 12643</li> 12644</ul> 12645</div> 12646<div class="paragraph"> 12647<p>A <a href="#bpmnGateways">Gateway</a> or <a href="#bpmnEvents">Event</a> <strong>cannot</strong> become multi-instance.</p> 12648</div> 12649<div class="paragraph"> 12650<p>As required by the spec, each parent execution of the created executions for each instance will have following variables:</p> 12651</div> 12652<div class="ulist"> 12653<ul> 12654<li> 12655<p><strong>nrOfInstances</strong>: the total number of instances</p> 12656</li> 12657<li> 12658<p><strong>nrOfActiveInstances</strong>: the number of currently active, i.e. not yet finished, instances. For a sequential multi-instance, this will always be 1.</p> 12659</li> 12660<li> 12661<p><strong>nrOfCompletedInstances</strong>: the number of already completed instances.</p> 12662</li> 12663</ul> 12664</div> 12665<div class="paragraph"> 12666<p>These values can be retrieved by calling the <code>execution.getVariable(x)</code> method.</p> 12667</div> 12668<div class="paragraph"> 12669<p>Additionally, each of the created executions will have an execution-local variable (i.e. not visible for the other executions, and not stored on process instance level) :</p> 12670</div> 12671<div class="ulist"> 12672<ul> 12673<li> 12674<p><strong>loopCounter</strong>: indicates the <em>index in the for-each loop</em> of that particular instance. loopCounter variable can be renamed by Activiti <strong>elementIndexVariable</strong> attribute.</p> 12675</li> 12676</ul> 12677</div> 12678</div> 12679<div class="sect4"> 12680<h5 id="bpmnMultiInstanceGraphicalNotation">Graphical notation</h5> 12681<div class="paragraph"> 12682<p>If an activity is multi-instance, this is indicated by three short lines at the bottom of that activity. Three <em>vertical</em> lines indicates that the instances will be executed in parallel, while three <em>horizontal</em> lines indicate sequential execution.</p> 12683</div> 12684<div class="imageblock" style="text-align: center"> 12685<div class="content"> 12686<img src="images/bpmn.multi.instance.png" alt="bpmn.multi.instance"> 12687</div> 12688</div> 12689</div> 12690<div class="sect4"> 12691<h5 id="bpmnMultiInstanceXml">Xml representation</h5> 12692<div class="paragraph"> 12693<p>To make an activity multi-instance, the activity xml element must have a <code>multiInstanceLoopCharacteristics</code> child element.</p> 12694</div> 12695<div class="listingblock"> 12696<div class="content"> 12697<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 126982 126993</div></td><td class="code"><span></span><span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"false|true"</span><span class="tok-nt">></span> 12700 ... 12701<span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12702</td></tr></table></code></pre> 12703</div> 12704</div> 12705<div class="paragraph"> 12706<p>The <strong>isSequential</strong> attribute indicates if the instances of that activity are executed sequentially or parallel.</p> 12707</div> 12708<div class="paragraph"> 12709<p>The number of instances are <strong>calculated once, when entering the activity</strong>. There are a few ways of configuring this. On way is directly specifying a number, by using the <strong>loopCardinality</strong> child element.</p> 12710</div> 12711<div class="listingblock"> 12712<div class="content"> 12713<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 127142 127153</div></td><td class="code"><span></span><span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"false|true"</span><span class="tok-nt">></span> 12716 <span class="tok-nt"><loopCardinality></span>5<span class="tok-nt"></loopCardinality></span> 12717<span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12718</td></tr></table></code></pre> 12719</div> 12720</div> 12721<div class="paragraph"> 12722<p>Expressions that resolve to a positive number are also possible:</p> 12723</div> 12724<div class="listingblock"> 12725<div class="content"> 12726<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 127272 127283</div></td><td class="code"><span></span><span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"false|true"</span><span class="tok-nt">></span> 12729 <span class="tok-nt"><loopCardinality></span>${nrOfOrders-nrOfCancellations}<span class="tok-nt"></loopCardinality></span> 12730<span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12731</td></tr></table></code></pre> 12732</div> 12733</div> 12734<div class="paragraph"> 12735<p>Another way to define the number of instances, is to specify the name of a process variable which is a collection using the <code>loopDataInputRef</code> child element. For each item in the collection, an instance will be created. Optionally, it is possible to set that specific item of the collection for the instance using the <code>inputDataItem</code> child element. This is shown in the following XML example:</p> 12736</div> 12737<div class="listingblock"> 12738<div class="content"> 12739<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 127402 127413 127424 127435 127446</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"miTasks"</span> <span class="tok-na">name=</span><span class="tok-s">"My Task ${loopCounter}"</span> <span class="tok-na">activiti:assignee=</span><span class="tok-s">"${assignee}"</span><span class="tok-nt">></span> 12745 <span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"false"</span><span class="tok-nt">></span> 12746 <span class="tok-nt"><loopDataInputRef></span>assigneeList<span class="tok-nt"></loopDataInputRef></span> 12747 <span class="tok-nt"><inputDataItem</span> <span class="tok-na">name=</span><span class="tok-s">"assignee"</span> <span class="tok-nt">/></span> 12748 <span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12749<span class="tok-nt"></userTask></span> 12750</td></tr></table></code></pre> 12751</div> 12752</div> 12753<div class="paragraph"> 12754<p>Suppose the variable <code>assigneeList</code> contains the values <code>\[kermit, gonzo, fozzie\]</code>. In the snippet above, three user tasks will be created in parallel. Each of the executions will have a process variable named <code>assignee</code> containing one value of the collection, which is used to assign the user task in this example.</p> 12755</div> 12756<div class="paragraph"> 12757<p>The downside of the <code>loopDataInputRef</code> and <code>inputDataItem</code> is that 1) the names are pretty hard to remember and 2) due to the BPMN 2.0 schema restrictions they can’t contain expressions. Activiti solves this by offering the <strong>collection</strong> and <strong>elementVariable</strong> attributes on the <code>multiInstanceCharacteristics</code>:</p> 12758</div> 12759<div class="listingblock"> 12760<div class="content"> 12761<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 127622 127633 127644 127655</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"miTasks"</span> <span class="tok-na">name=</span><span class="tok-s">"My Task"</span> <span class="tok-na">activiti:assignee=</span><span class="tok-s">"${assignee}"</span><span class="tok-nt">></span> 12766 <span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"true"</span> 12767 <span class="tok-na">activiti:collection=</span><span class="tok-s">"${myService.resolveUsersForTask()}"</span> <span class="tok-na">activiti:elementVariable=</span><span class="tok-s">"assignee"</span> <span class="tok-nt">></span> 12768 <span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12769<span class="tok-nt"></userTask></span> 12770</td></tr></table></code></pre> 12771</div> 12772</div> 12773<div class="paragraph"> 12774<p>A multi-instance activity ends when all instances are finished. However, it is possible to specify an expression that is evaluated every time one instance ends. When this expression evaluates to true, all remaining instances are destroyed and the multi-instance activity ends, continuing the process. Such an expression must be defined in the <strong>completionCondition</strong> child element.</p> 12775</div> 12776<div class="listingblock"> 12777<div class="content"> 12778<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 127792 127803 127814 127825 127836</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"miTasks"</span> <span class="tok-na">name=</span><span class="tok-s">"My Task"</span> <span class="tok-na">activiti:assignee=</span><span class="tok-s">"${assignee}"</span><span class="tok-nt">></span> 12784 <span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"false"</span> 12785 <span class="tok-na">activiti:collection=</span><span class="tok-s">"assigneeList"</span> <span class="tok-na">activiti:elementVariable=</span><span class="tok-s">"assignee"</span> <span class="tok-nt">></span> 12786 <span class="tok-nt"><completionCondition></span>${nrOfCompletedInstances/nrOfInstances >= 0.6 }<span class="tok-nt"></completionCondition></span> 12787 <span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12788<span class="tok-nt"></userTask></span> 12789</td></tr></table></code></pre> 12790</div> 12791</div> 12792<div class="paragraph"> 12793<p>In this example, there will be parallel instances created for each element of the <code>assigneeList</code> collection. However, when 60% of the tasks are completed, the other tasks are deleted and the process continues.</p> 12794</div> 12795</div> 12796<div class="sect4"> 12797<h5 id="bpmnMultiInstanceBoundaryEvent">Boundary events and multi-instance</h5> 12798<div class="paragraph"> 12799<p>Since a multi-instance is a regular activity, it is possible to define a <a href="#bpmnBoundaryEvent">boundary event</a> on its boundary. In case of an interrupting boundary event, when the event is caught, <strong>all instances</strong> that are still active will be destroyed. Take for example following multi-instance subprocess:</p> 12800</div> 12801<div class="imageblock" style="text-align: center"> 12802<div class="content"> 12803<img src="images/bpmn.multi.instance.boundary.event.png" alt="bpmn.multi.instance.boundary.event"> 12804</div> 12805</div> 12806<div class="paragraph"> 12807<p>Here, all instances of the subprocess will be destroyed when the timer fires, regardless of how many instances there are or which inner activities are currently not yet completed.</p> 12808</div> 12809</div> 12810<div class="sect4"> 12811<h5 id="bpmnCompensationHandlers">Multi instance and execution listeners</h5> 12812<div class="paragraph"> 12813<p>(Valid for Activiti 5.18 and up)</p> 12814</div> 12815<div class="paragraph"> 12816<p>There is a caveat when using execution listeners in combination with multi instance. Take for example the following snippet of BPMN 2.0 xml, which is defined on the same level as the <em>multiInstanceLoopCharacteristics</em> xml element is set:</p> 12817</div> 12818<div class="listingblock"> 12819<div class="content"> 12820<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 128212 128223 128234</div></td><td class="code"><span></span><span class="tok-nt"><extensionElements></span> 12824 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyStartListener"</span><span class="tok-nt">/></span> 12825 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"end"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyEndListener"</span><span class="tok-nt">/></span> 12826<span class="tok-nt"></extensionElements></span> 12827</td></tr></table></code></pre> 12828</div> 12829</div> 12830<div class="paragraph"> 12831<p>For a normal BPMN activity, there would be an invocation of these listeners when the activity is started and ended.</p> 12832</div> 12833<div class="paragraph"> 12834<p>However, when the activity is multi instance, the behavior is different:</p> 12835</div> 12836<div class="ulist"> 12837<ul> 12838<li> 12839<p>When the multi instance activity is entered, before any of the <em>inner</em> activities is executed, a start event is thrown. The <em>loopCounter</em> variable is not yet set (is null).</p> 12840</li> 12841<li> 12842<p>For each of the actual activities visited, a start event is thrown. The <em>loopCounter</em> variable is set.</p> 12843</li> 12844</ul> 12845</div> 12846<div class="paragraph"> 12847<p>The same reasoning applies for the end event:</p> 12848</div> 12849<div class="ulist"> 12850<ul> 12851<li> 12852<p>When the actual activity is left, an end even is thrown. The <em>loopCounter</em> variable is set.</p> 12853</li> 12854<li> 12855<p>When the multi instance activity has finished as a whole, an end event is thrown. The <em>loopCounter</em> variable is not set.</p> 12856</li> 12857</ul> 12858</div> 12859<div class="paragraph"> 12860<p>For example:</p> 12861</div> 12862<div class="listingblock"> 12863<div class="content"> 12864<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 12865 2 12866 3 12867 4 12868 5 12869 6 12870 7 12871 8 12872 9 1287310 1287411 1287512 1287613</div></td><td class="code"><span></span><span class="tok-nt"><subProcess</span> <span class="tok-na">id=</span><span class="tok-s">"subprocess1"</span> <span class="tok-na">name=</span><span class="tok-s">"Sub Process"</span><span class="tok-nt">></span> 12877 <span class="tok-nt"><extensionElements></span> 12878 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"start"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyStartListener"</span><span class="tok-nt">/></span> 12879 <span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"end"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.MyEndListener"</span><span class="tok-nt">/></span> 12880 <span class="tok-nt"></extensionElements></span> 12881 <span class="tok-nt"><multiInstanceLoopCharacteristics</span> <span class="tok-na">isSequential=</span><span class="tok-s">"false"</span><span class="tok-nt">></span> 12882 <span class="tok-nt"><loopDataInputRef></span>assignees<span class="tok-nt"></loopDataInputRef></span> 12883 <span class="tok-nt"><inputDataItem</span> <span class="tok-na">name=</span><span class="tok-s">"assignee"</span><span class="tok-nt">></inputDataItem></span> 12884 <span class="tok-nt"></multiInstanceLoopCharacteristics></span> 12885 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"startevent2"</span> <span class="tok-na">name=</span><span class="tok-s">"Start"</span><span class="tok-nt">></startEvent></span> 12886 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"endevent2"</span> <span class="tok-na">name=</span><span class="tok-s">"End"</span><span class="tok-nt">></endEvent></span> 12887 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">name=</span><span class="tok-s">""</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"startevent2"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"endevent2"</span><span class="tok-nt">></sequenceFlow></span> 12888<span class="tok-nt"></subProcess></span> 12889</td></tr></table></code></pre> 12890</div> 12891</div> 12892<div class="paragraph"> 12893<p>In this example, suppose the <em>assignees</em> list has three items. The following happens at runtime:</p> 12894</div>
12894 12895<div class="ulist"> 12896<ul> 12897<li> 12898<p>A start event is thrown for the multi instance as a whole. The <em>start</em> execution listener is invoked. The <em>loopCounter</em> nor the <em>assignee</em> variable will not be set (i.e. they will be null).</p> 12899</li> 12900<li> 12901<p>A start event is thrown for each activity instance. The <em>start</em> execution listener is invoked three times. The <em>loopCounter</em> nor the <em>assignee</em> variable will be set (i.e. different from null).</p> 12902</li> 12903<li> 12904<p>So in total, the start execution listener is invoked four times.</p> 12905</li> 12906</ul> 12907</div> 12908<div class="paragraph"> 12909<p>Note that the same applies when the <em>multiInstanceLoopCharacteristics</em> are defined on something else than a subprocess too. For example in case the example above would be a simple userTask, the same reasoning still applies.</p> 12910</div> 12911</div> 12912</div> 12913<div class="sect3"> 12914<h4 id="_compensation_handlers">8.5.15. Compensation Handlers</h4> 12915<div class="sect4"> 12916<h5 id="bpmnCompensationHandlerDescription">Description</h5> 12917<div class="paragraph"> 12918<p><a href="#experimental">[EXPERIMENTAL]</a></p> 12919</div> 12920<div class="paragraph"> 12921<p>If an activity is used for compensating the effects of another activity, it can be declared to be a compensation handler. Compensation handlers are not contained in normal flow and are only executed when a compensation event is thrown.</p> 12922</div> 12923<div class="paragraph"> 12924<p>Compensation handlers must not have incoming or outgoing sequence flows.</p> 12925</div> 12926<div class="paragraph"> 12927<p>A compensation handler must be associated with a compensation boundary event using a directed association.</p> 12928</div> 12929</div> 12930<div class="sect4"> 12931<h5 id="bpmnCompensationHandlerGraphicalNotation">Graphical notation</h5> 12932<div class="paragraph"> 12933<p>If an activity is a compensation handler, the compensation event icon is displayed in the center bottom area. The following excerpt from a process diagram shows a service task with an attached compensation boundary event which is associated to a compensation handler. Notice the compensation handler icon in the bottom canter area of the "cancel hotel reservation" service task.</p> 12934</div> 12935<div class="imageblock" style="text-align: center"> 12936<div class="content"> 12937<img src="images/bpmn.boundary.compensation.event.png" alt="bpmn.boundary.compensation.event"> 12938</div> 12939</div> 12940</div> 12941<div class="sect4"> 12942<h5 id="bpmnCompensationHandlerXml">XML representation</h5> 12943<div class="paragraph"> 12944<p>In order to declare an activity to be a compensation handler, we need to set the attribute isForCompensation to true:</p> 12945</div> 12946<div class="listingblock"> 12947<div class="content"> 12948<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 129492</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"undoBookHotel"</span> <span class="tok-na">isForCompensation=</span><span class="tok-s">"true"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"..."</span><span class="tok-nt">></span> 12950<span class="tok-nt"></serviceTask></span> 12951</td></tr></table></code></pre> 12952</div> 12953</div> 12954</div> 12955</div> 12956</div> 12957<div class="sect2"> 12958<h3 id="bpmnSubprocessAndCallActivity">8.6. Sub-Processes and Call Activities</h3> 12959<div class="sect3"> 12960<h4 id="bpmnSubProcess">8.6.1. Sub-Process</h4> 12961<div class="sect4"> 12962<h5 id="bpmnSubProcessDescription">Description</h5> 12963<div class="paragraph"> 12964<p>A <em>Sub-Process</em> is an activity that contains other activities, gateways, events, etc. which on itself form a process that is part of the bigger process. A <em>Sub-Process</em> is completely defined inside a parent process (that’s why it’s often called an <em>embedded</em> Sub-Process).</p> 12965</div> 12966<div class="paragraph"> 12967<p>Sub-Processes have two major use cases:</p> 12968</div> 12969<div class="ulist"> 12970<ul> 12971<li> 12972<p>Sub-Processes allow <strong>hierarchical modeling</strong>. Many modeling tools allow that Sub-Processes can be <em>collapsed</em>, hiding all the details of the Sub-Process and displaying a high-level end-to-e
12972nd overview of the business process.</p> 12973</li> 12974<li> 12975<p>A Sub-Process creates a new <strong>scope for events</strong>. Events that are thrown during execution of the Sub-Process, can be caught by <a href="#bpmnBoundaryEvent">a boundary event</a> on the boundary of the Sub-Process, thus creating a scope for that event limited to the Sub-Process.</p> 12976</li> 12977</ul> 12978</div> 12979<div class="paragraph"> 12980<p>Using a Sub-Process does impose some constraints:</p> 12981</div> 12982<div class="ulist"> 12983<ul> 12984<li> 12985<p>A Sub-Process can only have <strong>one none start event</strong>, no other start event types are allowed. A Sub-Process must <strong>at least have one end event</strong>. Note that the BPMN 2.0 specification allows to omit the start and end events in a Sub-Process, but the current Activiti implementation does not support this.</p> 12986</li> 12987<li> 12988<p><strong>Sequence flow cannot cross Sub-Process boundaries.</strong></p> 12989</li> 12990</ul> 12991</div> 12992</div> 12993<div class="sect4"> 12994<h5 id="bpmnSubProcessGraphicalNotation">Graphical Notation</h5> 12995<div class="paragraph"> 12996<p>A Sub-Process is visualized as a typical activity, i.e. a rounded rectangle. In case the Sub-Process is <em>collapsed</em>, only the name and a plus-sign are displayed, giving a high-level overview of the process:</p> 12997</div> 12998<div class="imageblock" style="text-align: center"> 12999<div class="content"> 13000<img src="images/bpmn.collapsed.subprocess.png" alt="bpmn.collapsed.subprocess"> 13001</div> 13002</div> 13003<div class="paragraph"> 13004<p>In case the Sub-Process is <em>expanded</em>, the steps of the Sub-Process are displayed within the Sub-Process boundaries:</p> 13005</div> 13006<div class="imageblock" style="text-align: center"> 13007<div class="content"> 13008<img src="images/bpmn.expanded.subprocess.png" alt="bpmn.expanded.subprocess"> 13009</div> 13010</div> 13011<div class="paragraph"> 13012<p>One of the main reasons to use a Sub-Process, is to define a scope for a certain event. The following process model shows this: both the <em>investigate software/investigate hardware</em> tasks need to be done in parallel, but both tasks need to be done within a certain time, before <em>Level 2 support</em> is consulted. Here, the scope of the timer (i.e. which activities must be done in time) is constrained by the Sub-Process.</p> 13013</div> 13014<div class="imageblock" style="text-align: center"> 13015<div class="content"> 13016<img src="images/bpmn.subprocess.with.boundary.timer.png" alt="bpmn.subprocess.with.boundary.timer"> 13017</div> 13018</div> 13019</div> 13020<div class="sect4"> 13021<h5 id="bpmnSubProcessXML">XML representation</h5> 13022<div class="paragraph"> 13023<p>A Sub-Process is defined by the <em>subprocess</em> element. All activities, gateways, events, etc. that are part of the Sub-Process, need to be enclosed within this element.</p> 13024</div> 13025<div class="listingblock"> 13026<div class="content"> 13027<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 130282 130293 130304 130315 130326 130337 130348 130359</div></td><td class="code"><span></span><span class="tok-nt"><subProcess</span> <span class="tok-na">id=</span><span class="tok-s">"subProcess"</span><span class="tok-nt">></span> 13036 13037 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"subProcessStart"</span> <span class="tok-nt">/></span> 13038 13039 ... other Sub-Process elements ... 13040 13041 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"subProcessEnd"</span> <span class="tok-nt">/></span> 13042 13043 <span class="tok-nt"></subProcess></span> 13044</td></tr></table></code></pre> 13045</div> 13046</div> 13047</div> 13048</div> 13049<div class="sect3"> 13050<h4 id="bpmnEventSubprocess">8.6.2. Event Sub-Process</h4> 13051<div class="sect4"> 13052<h5 id="bpmnEventSubprocessDescription">Description</h5> 13053<div class="paragraph"> 13054<p>The Event Sub-Process is new in BPMN 2.0. An Event Sub-Process is a subprocess that is triggered by an event. An Event Sub-Process can be added at the process level or at any subprocess level. The event used to trigger an event subprocess is configured using a start event. From this, it follows that none start events are not supported for Event Sub-Processes. An Event Sub-Process might be triggered using events like message events, error events, signal events, timer events, or compensation events. The subscription to the start event is created when the scope (process instance or subprocess) hosting the Event Sub-Process is created. The subscription is removed when the scope is destroyed.</p> 13055</div> 13056<div class="paragraph"> 13057<p>An Event Sub-Process may be interrupting or non-interrupting. An interrupting subprocess cancels any executions in the current scope. A non-interrupting Event Sub-Process spawns a new concurrent execution. While an interrupting Event Sub-Process can only be triggered once for each activation of the scope hosting it, a non-interrupting Event Sub-Process can be triggered multiple times. The fact whether the subprocess is interrupting is configured using the start event triggering the Event Sub-Process.</p> 13058</div> 13059<div class="paragraph"> 13060<p>An Event Sub-Process must not have any incoming or outgoing sequence flows. Since an Event Sub-Process is triggered by an event, an incoming sequence flow makes no sense. When an Event Sub-Process is ended, either the current scope is ended (in case of an interrupting Event Sub-Process), or the concurrent execution spawned for the non-interrupting subprocess is ended.</p> 13061</div> 13062<div class="paragraph"> 13063<p><strong>Current limitations:</strong></p> 13064</div> 13065<div class="ulist"> 13066<ul> 13067<li> 13068<p>Activiti only supports interrupting Event Sub-Processes.</p> 13069</li> 13070<li> 13071<p>Activiti only supports Event Sub-Process triggered using an Error Start Event or Message Start Event.</p> 13072</li> 13073</ul> 13074</div> 13075</div> 13076<div class="sect4"> 13077<h5 id="bpmnEventSubprocessGraphicalNotation">Graphical Notation</h5> 13078<div class="paragraph"> 13079<p>An Event Sub-Process might be visualized as a an <a href="#bpmnSubProcessGraphicalNotation">embedded subprocess</a> with a dotted outline.</p> 13080</div> 13081<div class="imageblock" style="text-align: center"> 13082<div class="content"> 13083<img src="images/bpmn.subprocess.eventSubprocess.png" alt="bpmn.subprocess.eventSubprocess"> 13084</div> 13085</div> 13086</div> 13087<div class="sect4"> 13088<h5 id="bpmnEventSubprocessXMLRepresentation">XML representation</h5> 13089<div class="paragraph"> 13090<p>An Event Sub-Process is represented using XML in the same way as a an embedded subprocess. In addition the attribute <code>triggeredByEvent</code> must have the value <code>true</code>:</p> 13091</div> 13092<div class="listingblock"> 13093<div class="content"> 13094<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 130952 130963</div></td><td class="code"><span></span><span class="tok-nt"><subProcess</span> <span class="tok-na">id=</span><span class="tok-s">"eventSubProcess"</span> <span class="tok-na">triggeredByEvent=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 13097 ... 13098<span class="tok-nt"></subProcess></span> 13099</td></tr></table></code></pre> 13100</div> 13101</div> 13102</div> 13103<div class="sect4"> 13104<h5 id="bpmnEventSubprocessExample">Example</h5> 13105<div class="paragraph"> 13106<p>The following is an example of an Event Sub-Process triggered using an Error Start Event. The Event Sub-Process is located at the "process level", i.e. is scoped to the process instance:</p> 13107</div> 13108<div class="imageblock" style="text-align: center"> 13109<div class="content"> 13110<img src="images/bpmn.subprocess.eventSubprocess.example.1.png" alt="bpmn.subprocess.eventSubprocess.example.1"> 13111</div> 13112</div> 13113<div class="paragraph"> 13114<p>This is how the Event Sub-Process would look like in XML:</p> 13115</div> 13116<div class="listingblock"> 13117<div class="content"> 13118<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 131192 131203 131214 131225 131236 131247</div></td><td class="code"><span></span><span class="tok-nt"><subProcess</span> <span class="tok-na">id=</span><span class="tok-s">"eventSubProcess"</span> <span class="tok-na">triggeredByEvent=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 13125 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"catchError"</span><span class="tok-nt">></span> 13126 <span class="tok-nt"><errorEventDefinition</span> <span class="tok-na">errorRef=</span><span class="tok-s">"error"</span> <span class="tok-nt">/></span> 13127 <span class="tok-nt"></startEvent></span> 13128 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"catchError"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"taskAfterErrorCatch"</span> <span class="tok-nt">/></span> 13129 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"taskAfterErrorCatch"</span> <span class="tok-na">name=</span><span class="tok-s">"Provide additional data"</span> <span class="tok-nt">/></span> 13130<span class="tok-nt"></subProcess></span> 13131</td></tr></table></code></pre> 13132</div> 13133</div> 13134<div class="paragraph"> 13135<p>As already stated, an Event Sub-Process can also be added to an embedded subprocess. If it is added to an embedded subprocess, it becomes an alternative to a boundary event. Consider the two following process diagrams. In both cases the embedded subprocess throws an error event. Both times the error is caught and handled using a user task.</p> 13136</div> 13137<div class="imageblock" style="text-align: center"> 13138<div class="content"> 13139<img src="images/bpmn.subprocess.eventSubprocess.example.2a.png" alt="bpmn.subprocess.eventSubprocess.example.2a"> 13140</div> 13141</div> 13142<div class="paragraph"> 13143<p>as opposed to:</p> 13144</div> 13145<div class="imageblock" style="text-align: center"> 13146<div class="content"> 13147<img src="images/bpmn.subprocess.eventSubprocess.example.2b.png" alt="bpmn.subprocess.eventSubprocess.example.2b"> 13148</div> 13149</div> 13150<div class="paragraph"> 13151<p>In both cases the same tasks are executed. However, there are differences between both modelling alternatives:</p> 13152</div> 13153<div class="ulist"> 13154<ul> 13155<li> 13156<p>The embedded subprocess is executed using the same execution which executed the scope it is hosted in. This means that an embedded subprocess has access to the variables local to it’s scope. When using a boundary event, the execution created for executing the embedded subprocess is deleted by the sequence flow leaving the boundary event. This means that the variables created by the embedded subprocess are not available anymore.</p> 13157</li> 13158<li> 13159<p>When using an Event Sub-Process, the event is completely handled by the subprocess it is added to. When using a boundary event, the event is handled by the parent process.</p> 13160</li> 13161</ul> 13162</div> 13163<div class="paragraph"> 13164<p>These two differences can help you decide whether a boundary event or an embedded subprocess is better suited for solving a particular process modeling / implementation problem.</p> 13165</div> 13166</div> 13167</div> 13168<div class="sect3"> 13169<h4 id="bpmnTransactionSubprocess">8.6.3. Transaction subprocess</h4> 13170<div class="paragraph"> 13171<p><a href="#experimental">[EXPERIMENTAL]</a><a id="bpmnTransactionSubprocessDescription"></a></p> 13172</div> 13173<div class="sect4"> 13174<h5 id="_description_8">Description</h5> 13175<div class="paragraph"> 13176<p>A transaction subprocess is an embedded subprocess, which can be used to group multiple activities to a transaction. A transaction is a logical unit of work which allows to group a set of individual activities, such that they either succeed or fail collectively.</p> 13177</div> 13178<div class="paragraph"> 13179<p><strong>Possible outcomes of a transaction:</strong> A transaction can have three different outcomes:</p> 13180</div> 13181<div class="ulist"> 13182<ul> 13183<li> 13184<p>A transaction is <em>successful</em>, if it is neither cancelled not terminated by a hazard. If a transaction subprocess is successful, it is left using the outgoing sequenceflow(s). A successful transaction might be compensated if a compensation event is thrown later in the process. <em>Note:</em> just as "ordinary" embedded subprocesses, a transaction may be compensated after successful completion using an intermediary throwing compensation event.</p> 13185</li> 13186<li> 13187<p>A transaction is <em>cancelled</em>, if an execution reaches the cancel end event. In that case, all executions are terminated and removed. A single remaining execution is then set to the cancel boundary event, which triggers compensation. After compensation is completed, the transaction subprocess is left using the outgoing sequence flow(s) of the cancel boundary event.</p> 13188</li> 13189<li> 13190<p>A transaction is ended by a <em>hazard</em>, if an error event is thrown, that is not caught within the scope of the transaction subprocess. (This also applies if the error is caught on the boundary of the transaction subprocess.) In this case, compensation is not performed.</p> 13191</li> 13192</ul> 13193</div> 13194<div class="paragraph"> 13195<p>The following diagram illustrates the three different outcomes:</p> 13196</div> 13197<div class="imageblock" style="text-align: center"> 13198<div class="content"> 13199<img src="images/bpmn.transaction.subprocess.example.1.png" alt="bpmn.transaction.subprocess.example.1"> 13200</div> 13201</div> 13202<div class="paragraph"> 13203<p><strong>Relation to ACID transactions:</strong> it is important not to confuse the bpmn transaction subprocess with technical (ACID) transactions. The bpmn transaction subprocess is not a way to scope technical transactions. In order to understand transaction management in Activiti, read the section on <a href="#bpmnConcurrencyAndTransactions">concurrency and transactions</a>. A bpmn transaction is different from a technical transaction in the following ways:</p> 13204</div> 13205<div class="ulist"> 13206<ul> 13207<li> 13208<p>
13208While an ACID transaction is typically short lived, a bpmn transaction may take hours, days or even months to complete. (Consider the case where one of the activities grouped by a transaction is a usertask, typically people have longer response times than applications. Or, in another situation, a bpmn transaction might wait for some business event to occur, like the fact that a particular order has been fulfilled.) Such operations usually take considerably longer to complete than updating a record in a database, or storing a message using a transactional queue.</p> 13209</li> 13210<li> 13211<p>Because it is impossible to scope a technical transaction to the duration of a business activity, a bpmn transaction typically spans multiple ACID transactions.</p> 13212</li> 13213<li> 13214<p>Since a bpmn transaction spans multiple ACID transactions, we loose ACID properties. For example, consider the example given above. Let’s assume the "book hotel" and the "charge credit card" operations are performed in separate ACID transactions. Let’s also assume that the "book hotel" activity is successful. Now we have an intermediary inconsistent state, because we have performed an hotel booking but have not yet charged the credit card. Now, in an ACID transaction, we would also perform different operations sequentially and thus also have an intermediary inconsistent state. What is different here, is that the inconsistent state is visible outside of the scope of the transaction. For example, if the reservations are made using an external booking service, other parties using the same booking service might already see that the hotel is booked. This means, that when implementing business transactions, we completely loose the isolation property (Granted: we usually also relax isolation when working with ACID transactions to allow for higher levels of concurrency, but there we have fine grained control and intermediary inconsistencies are only present for very short periods of times).</p> 13215</li> 13216<li> 13217<p>A bpmn business transaction can also not be rolled back in the traditional sense. Since it spans multiple ACID transactions, some of these ACID transactions might already be committed at the time the bpmn transaction is cancelled. At this point, they cannot be rolled back anymore.</p> 13218</li> 13219</ul> 13220</div> 13221<div class="paragraph"> 13222<p>Since bpmn transactions are long-running in nature, the lack of isolation and a rollback mechanism need to be dealt with differently. In practice, there is usually no better solution than to deal with these problems in a domain specific way:</p> 13223</div> 13224<div class="ulist"> 13225<ul> 13226<li> 13227<p>The rollback is performed using compensation. If a cancel event is thrown in the scope of a transaction, the effects of all activities that executed successfully and have a compensation handler are compensated.</p> 13228</li> 13229<li> 13230<p>The lack of isolation is also often dealt with using domain specific solutions. For instance, in the example above, an hotel room might appear to be booked to a second customer, before we have actually made sure that the first customer can pay for it. Since this might be undesirable from a business perspective, a booking service might choose to allow for a certain amount of overbooking.</p> 13231</li> 13232<li> 13233<p>In addition, since the transaction can be aborted in case of a hazard, the booking service has to deal with the situation where a hotel room is booked but payment is never attempted (since the transaction was aborted). In that case the booking service might choose a strategy where a hotel room is reserved for a maximum period of time and if payment is not received until then, the booking is cancelled.</p> 13234</li> 13235</ul> 13236</div> 13237<div class="paragraph"> 13238<p>To sum it up: while ACID transactions offer a generic solution to such problems (rollback, isolation levels and heuristic outcomes), we need to find domain specific solutions to these problems when implementing business transactions.</p> 13239</div> 13240<div class="paragraph"> 13241<p><strong>Current limitations:</strong></p> 13242</div> 13243<div class="ulist"> 13244<ul> 13245<li> 13246<p>The BPMN specification requires that the process engine reacts to events issued by the underlying transaction protocol and for instance that a transaction is cancelled, if a cancel event occurs in the underlying protocol. As an embeddable engine, Activiti does currently not support this. (For some ramifications of this, see paragraph on consistency below.)</p> 13247</li> 13248</ul> 13249</div> 13250<div class="paragraph"> 13251<p><strong>Consistency on top of ACID transactions and optimistic concurrency:</strong> A bpmn transaction guarantees consistency in the sense that either all activities compete successfully, or if some activity cannot be performed, the effects of all other successful activities are compensated. So either way we end up in a consistent state. However, it is important to re
13251cognize that in Activiti, the consistency model for bpmn transactions is superposed on top of the consistency model for process execution. Activiti executes processes in a transactional way. Concurrency is addressed using optimistic locking. In Activiti, bpmn error, cancel and compensation events are built on top of the same acid transactions and optimistic locking. For example, a cancel end event can only trigger compensation if it is actually reached. It is not reached if some undeclared exception is thrown by a service task before. Or, the effects of a compensation handler cannot be committed if some other participant in the underlying ACID transaction sets the transaction to the state rollback-only. Or, when two concurrent executions reach a cancel end event, compensation might be triggered twice and fail with an optimistic locking exception. All of this is to say that when implementing bpmn transactions in Activiti, the same set of rules apply as when implementing "ordinary" processes and subprocesses. So to effectively guarantee consistency, it is important to implement processes in a way that does take the optimistic, transactional execution model into consideration.</p> 13252</div> 13253</div> 13254<div class="sect4"> 13255<h5 id="bpmnEventSubprocessGraphicalNotation">Graphical Notation</h5> 13256<div class="paragraph"> 13257<p>An transaction subprocess might be visualized as a an <a href="#bpmnSubProcessGraphicalNotation">embedded subprocess</a> with a double outline.</p> 13258</div> 13259<div class="imageblock" style="text-align: center"> 13260<div class="content"> 13261<img src="images/bpmn.transaction.subprocess.png" alt="bpmn.transaction.subprocess"> 13262</div> 13263</div> 13264</div> 13265<div class="sect4"> 13266<h5 id="bpmnEventSubprocessXMLRepresentation">XML representation</h5> 13267<div class="paragraph"> 13268<p>A transaction subprocess is represented using xml using the <code>transaction</code> tag:</p> 13269</div> 13270<div class="listingblock"> 13271<div class="content"> 13272<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 132732 132743</div></td><td class="code"><span></span><span class="tok-nt"><transaction</span> <span class="tok-na">id=</span><span class="tok-s">"myTransaction"</span> <span class="tok-nt">></span> 13275 ... 13276<span class="tok-nt"></transaction></span> 13277</td></tr></table></code></pre> 13278</div> 13279</div> 13280</div> 13281<div class="sect4"> 13282<h5 id="bpmnEventSubprocessExample">Example</h5> 13283<div class="paragraph"> 13284<p>The following is an example of a transaction subprocess:</p> 13285</div> 13286<div class="imageblock" style="text-align: center"> 13287<div class="content"> 13288<img src="images/bpmn.transaction.subprocess.example.2.png" alt="bpmn.transaction.subprocess.example.2"> 13289</div> 13290</div> 13291</div> 13292</div> 13293<div class="sect3"> 13294<h4 id="bpmnCallActivity">8.6.4. Call activity (subprocess)</h4> 13295<div class="sect4"> 13296<h5 id="bpmnCallActivityDescription">Description</h5> 13297<div class="paragraph"> 13298<p>BPMN 2.0 makes a distinction between a regular <em><a href="#bpmnSubProcess">subprocess</a></em>, often also called <em>embedded subprocess</em>, and the call activity, which looks very similar. From a conceptual point of view, both will call a subprocess when process execution arrives at the activity.</p> 13299</div> 13300<div class="paragraph"> 13301<p>The difference is that the call activity references a process that is external to the process definition, whereas the <em><a href="#bpmnSubProcess">subprocess</a></em> is embedded within the original process definition. The main use case for the call activity is to have a reusable process definition that can be called from multiple other process definitions.</p> 13302</div> 13303<div class="paragraph"> 13304<p>When process execution arrives in the <em>call activity</em>, a new execution is created that is a sub-execution of the execution that arrives in the call activity. This sub-execution is then used to execute the subprocess, potentially creating parallel child execution as within a regular process. The super-execution waits until the subprocess is completely ended, and continues the original process afterwards.<
13304/p> 13305</div> 13306</div> 13307<div class="sect4"> 13308<h5 id="bpmnCallActivityGraphicalNotation">Graphical Notation</h5> 13309<div class="paragraph"> 13310<p>A call activity is visualized the same as a <a href="#bpmnSubProcessGraphicalNotation">subprocess</a>, however with a thick border (collapsed and expanded). Depending on the modeling tool, a call activity can also be expanded, but the default visualization is the collapsed subprocess representation.</p> 13311</div> 13312<div class="imageblock" style="text-align: center"> 13313<div class="content"> 13314<img src="images/bpmn.collapsed.call.activity.png" alt="bpmn.collapsed.call.activity"> 13315</div> 13316</div> 13317</div> 13318<div class="sect4"> 13319<h5 id="bpmnCallActivityXMLRepresentation">XML representation</h5> 13320<div class="paragraph"> 13321<p>A call activity is a regular activity, that requires a <em>calledElement</em> that references a process definition by its <strong>key</strong>. In practice, this means that the <strong>id of the process</strong> is used in the <em>calledElement</em>.</p> 13322</div> 13323<div class="listingblock"> 13324<div class="content"> 13325<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><callActivity</span> <span class="tok-na">id=</span><span class="tok-s">"callCheckCreditProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"Check credit"</span> <span class="tok-na">calledElement=</span><span class="tok-s">"checkCreditProcess"</span> <span class="tok-nt">/></span> 13326</td></tr></table></code></pre> 13327</div> 13328</div> 13329<div class="paragraph"> 13330<p>Note that the process definition of the subprocess is <strong>resolved at runtime</strong>. This means that the subprocess can be deployed independently from the calling process, if needed.</p> 13331</div> 13332</div> 13333<div class="sect4"> 13334<h5 id="bpmnCallActivityPassVariables">Passing variables</h5> 13335<div class="paragraph"> 13336<p>You can pass process variables to the sub process and vice versa. The data is copied into the subprocess when it is started and copied back into the main process when it ends.</p> 13337</div> 13338<div class="listingblock"> 13339<div class="content"> 13340<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 133412 133423 133434 133445 133456</div></td><td class="code"><span></span><span class="tok-nt"><callActivity</span> <span class="tok-na">id=</span><span class="tok-s">"callSubProcess"</span> <span class="tok-na">calledElement=</span><span class="tok-s">"checkCreditProcess"</span> <span class="tok-nt">></span> 13346 <span class="tok-nt"><extensionElements></span> 13347 <span class="tok-nt"><activiti:in</span> <span class="tok-na">source=</span><span class="tok-s">"someVariableInMainProcess"</span> <span class="tok-na">target=</span><span class="tok-s">"nameOfVariableInSubProcess"</span> <span class="tok-nt">/></span> 13348 <span class="tok-nt"><activiti:out</span> <span class="tok-na">source=</span><span class="tok-s">"someVariableInSubProcess"</span> <span class="tok-na">target=</span><span class="tok-s">"nameOfVariableInMainProcess"</span> <span class="tok-nt">/></span> 13349 <span class="tok-nt"></extensionElements></span> 13350<span class="tok-nt"></callActivity></span> 13351</td></tr></table></code></pre> 13352</div> 13353</div> 13354<div class="paragraph"> 13355<p>We use an Activiti Extension as a shortcut for the BPMN standard elements called <em>dataInputAssociation</em> and <em>dataOutputAssociation</em>, which only work if you declare process variables in the BPMN 2.0 standard way.</p> 13356</div> 13357<div class="paragraph"> 13358<p>It is possible to use expressions here as well:</p> 13359</div> 13360<div class="listingblock"> 13361<div class="content"> 13362<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 133632 133643 133654 133665 133676</div></td><td class="code"><span></span><span class="tok-nt"><callActivity</span> <span class="tok-na">id=</span><span class="tok-s">"callSubProcess"</span> <span class="tok-na">calledElement=</span><span class="tok-s">"checkCreditProcess"</span> <span class="tok-nt">></span> 13368 <span class="tok-nt"><extensionElements></span> 13369 <span class="tok-nt"><activiti:in</span> <span class="tok-na">sourceExpression=</span><span class="tok-s">"${x+5}"</span> <span class="tok-na">target=</span><span class="tok-s">"y"</span> <span class="tok-nt">/></span> 13370 <span class="tok-nt"><activiti:out</span> <span class="tok-na">source=</span><span class="tok-s">"${y+5}"</span> <span class="tok-na">target=</span><span class="tok-s">"z"</span> <span class="tok-nt">/></span> 13371 <span class="tok-nt"></extensionElements></span> 13372<span class="tok-nt"></callActivity></span> 13373</td></tr></table></code></pre> 13374</div> 13375</div> 13376<div class="paragraph"> 13377<p>So in the end z = y+5 = x+5+5</p> 13378</div> 13379<div class="paragraph"> 13380<p>The callActivity element also supports setting the business key on the started subprocess instance using a custom activiti attribute extension. The <em>businessKey</em> attribute can be used to set a custom business key value on the subprocess instance.</p> 13381</div> 13382<div class="listingblock"> 13383<div class="content"> 13384<pre><callActivity id="callSubProcess" calledElement="checkCreditProcess" activiti:businessKey="${myVariable}"> 13385... 13386</callActivity></pre> 13387</div> 13388</div> 13389<div class="paragraph"> 13390<p>Defining the <em>inheritBusinessKey</em> attribute with a value of true will set the business key value on the subprocess to the value of the business key as defined in the calling process.</p> 13391</div> 13392<div class="listingblock"> 13393<div class="content"> 13394<pre><callActivity id="callSubProcess" calledElement="checkCreditProcess" activiti:inheritBusinessKey="true"> 13395... 13396</callActivity></pre> 13397</div> 13398</div> 13399</div> 13400<div class="sect4"> 13401<h5 id="bpmnCallActivityExample">Example</h5> 13402<div class="paragraph"> 13403<p>The following process diagram shows a simple handling of an order. Since the checking of the customer’s credit could be common to many other processes, the <em>check credit step</em> is modeled here as a call activity.</p> 13404</div> 13405<div class="imageblock" style="text-align: center"> 13406<div class="content">
13407<img src="images/bpmn.call.activity.super.process.png" alt="bpmn.call.activity.super.process"> 13408</div> 13409</div> 13410<div class="paragraph"> 13411<p>The process looks as follows:</p> 13412</div> 13413<div class="listingblock"> 13414<div class="content"> 13415<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 13416 2 13417 3 13418 4 13419 5 13420 6 13421 7 13422 8 13423 9 1342410 1342511 1342612 1342713</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span> <span class="tok-nt">/></span> 13428<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"theStart"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"receiveOrder"</span> <span class="tok-nt">/></span> 13429 13430<span class="tok-nt"><manualTask</span> <span class="tok-na">id=</span><span class="tok-s">"receiveOrder"</span> <span class="tok-na">name=</span><span class="tok-s">"Receive Order"</span> <span class="tok-nt">/></span> 13431<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"receiveOrder"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"callCheckCreditProcess"</span> <span class="tok-nt">/></span> 13432 13433<span class="tok-nt"><callActivity</span> <span class="tok-na">id=</span><span class="tok-s">"callCheckCreditProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"Check credit"</span> <span class="tok-na">calledElement=</span><span class="tok-s">"checkCreditProcess"</span> <span class="tok-nt">/></span> 13434<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow3"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"callCheckCreditProcess"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"prepareAndShipTask"</span> <span class="tok-nt">/></span> 13435 13436<span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"prepareAndShipTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Prepare and Ship"</span> <span class="tok-nt">/></span> 13437<span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"flow4"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"prepareAndShipTask"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 13438 13439<span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">"end"</span> <span class="tok-nt">/></span> 13440</td></tr></table></code></pre> 13441</div> 13442</div> 13443<div class="paragraph"> 13444<p>The subprocess looks as follows:</p> 13445</div> 13446<div class="imageblock" style="text-align: center"> 13447<div class="content"> 13448<img src="images/bpmn.call.activity.sub.process.png" alt="bpmn.call.activity.sub.process"> 13449</div> 13450</div> 13451<div class="paragraph"> 13452<p>There is nothing special to the process definition of the subprocess. It could as well be used without being called from another process.</p> 13453</div> 13454</div> 13455</div> 13456</div> 13457<div class="sect2"> 13458<h3 id="bpmnConcurrencyAndTransactions">8.7. Transactions and Concurrency</h3> 13459<div class="sect3"> 13460<h4 id="asyncContinuations">8.7.1. Asynchronous Continuations</h4> 13461<div class="paragraph"> 13462<p>Activiti executes processes in a transactional way which can be configured to suite your needs. Lets start by looking at how Activiti scopes transactions normally. If you trigger Activiti (i.e. start a process, complete a task, signal an execution), Activiti is going to advance in the process, until it reaches wait states on each active path of execution. More concretely speaking it performs a depth-first search through the process graph and returns if it has reached wait states on every branch of execution. A wait state is a task which is performed "later" which means that Activiti persists the current execution and waits to be triggered again. The trigger can either come from an external source for example if we have a user task or a receive message task, or from Activiti itself, if we have a timer event. This is illustrated in the following picture:</p> 13463</div> 13464<div class="imageblock" style="text-align: center"> 13465<div class="content"> 13466<img src="images/activiti.async.example.no.async.PNG" alt="activiti.async.example.no.async"> 13467</div> 13468</div> 13469<div class="paragraph"> 13470<p>We see a segment of a BPMN processes with a usertask, a service task and a timer event. Completing the usertask and validating the address is part of the same unit of work, so it should succeed or fail atomically. That means that if the service task throws an exception we want to rollback the current transaction, such that the execution tracks back to the user task and the user task is still present in the database. This is also the default behavior of Activiti. In (1) an application or client thread completes the task. In that same thread Activiti is now executing the service and advances until it reaches a wait state, in this case the timer event (2). Then it returns the control to the caller (3) potentially committing the transaction (if it was started by Activiti).</p> 13471</div> 13472<div class="paragraph"> 13473<p>In some cases this is not what we want. Sometimes we need custom control over transaction boundaries in a process, in order to be able to scope logical units of work. This is where asynchronous continuations come into play. Consider the following process (fragment):</p> 13474</div> 13475<div class="imageblock" style="text-align: center"> 13476<div class="content"> 13477<img src="images/activiti.async.example.async.PNG" alt="activiti.async.example.async"> 13478</div> 13479</div> 13480<div class="paragraph"> 13481<p>This time we are completing the user task, generating an invoice and then send that invoice to the customer. This time the generation of the invoice is not part of the same unit of work so we do not want to rollback the completion of the usertask if generating an invoice fails. So what we want Activiti to do is complete the user task (1), commit the transaction and return the control to the calling application. Then we want to generate the invoice asynchronously, in a background thread. This background thread is the Activiti job executor (actually a thread pool) which periodically polls the database for jobs. So behind the scenes, when we reach the "generate invoice" task, we are creating a job "message" for Activiti to continue the process later and persisting it into the database. This
13481job is then picked up by the job executor and executed. We are also giving the local job executor a little hint that there is a new job, to improve performance.</p> 13482</div> 13483<div class="paragraph"> 13484<p>In order to use this feature, we can use the <em>activiti:async="true"</em> extension. So for example, the service task would look like this:</p> 13485</div> 13486<div class="listingblock"> 13487<div class="content"> 13488<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"service1"</span> <span class="tok-na">name=</span><span class="tok-s">"Generate Invoice"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"my.custom.Delegate"</span> <span class="tok-na">activiti:async=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 13489</td></tr></table></code></pre> 13490</div> 13491</div> 13492<div class="paragraph"> 13493<p><em>activiti:async</em> can be specified on the following BPMN task types: task, serviceTask, scriptTask, businessRuleTask, sendTask, receiveTask, userTask, subProcess, callActivity</p> 13494</div> 13495<div class="paragraph"> 13496<p>On a userTask, receiveTask or other wait states, the async continuation allows us to execute the start execution listeners in a separate thread/transaction.</p> 13497</div> 13498</div> 13499<div class="sect3"> 13500<h4 id="failRetry">8.7.2. Fail Retry</h4> 13501<div class="paragraph"> 13502<p>Activiti, in its default configuration, reruns a job 3 times in case of any exception in execution of a job. This holds also for asynchronous task jobs. In some cases more flexibility is required. There are two parameters to be configured:</p> 13503</div> 13504<div class="ulist"> 13505<ul> 13506<li> 13507<p>Number of retries</p> 13508</li> 13509<li> 13510<p>Delay between retries These parameters can be configured by <code>activiti:failedJobRetryTimeCycle</code> element. Here is a sample usage:</p> 13511</li> 13512</ul> 13513</div> 13514<div class="listingblock"> 13515<div class="content"> 13516<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 135172 135183 135194 135205</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"failingServiceTask"</span> <span class="tok-na">activiti:async=</span><span class="tok-s">"true"</span> <span class="tok-na">activiti:class=</span><span class="tok-s">"org.activiti.engine.test.jobexecutor.RetryFailingDelegate"</span><span class="tok-nt">></span> 13521 <span class="tok-nt"><extensionElements></span> 13522 <span class="tok-nt"><activiti:failedJobRetryTimeCycle></span>R5/PT7M<span class="tok-nt"></activiti:failedJobRetryTimeCycle></span> 13523 <span class="tok-nt"></extensionElements></span> 13524<span class="tok-nt"></serviceTask></span> 13525</td></tr></table></code></pre> 13526</div> 13527</div> 13528<div class="paragraph"> 13529<p>Time cycle expression follows ISO 8601 standard, just like timer event expressions. The above example, makes the job executor to retry the job 5 times and wait 7 minutes between before each retry.</p> 13530</div> 13531</div> 13532<div class="sect3"> 13533<h4 id="exclusiveJobs">8.7.3. Exclusive Jobs</h4> 13534<div class="paragraph"> 13535<p>Since Activiti 5.9, the JobExecutor makes sure that jobs from a single process instance are never executed concurrently. Why is this?</p> 13536</div> 13537<div class="sect4"> 13538<h5 id="_why_exclusive_jobs">Why exclusive Jobs?</h5> 13539<div class="paragraph"> 13540<p>Consider the following process definition:</p> 13541</div> 13542<div class="imageblock" style="text-align: center"> 13543<div class="content"> 13544<img src="images/bpmn.why.exclusive.jobs.png" alt="bpmn.why.exclusive.jobs"> 13545</div> 13546</div> 13547<div class="paragraph"> 13548<p>We have a parallel gateway followed by three service tasks which all perform an asynchronous continuation. As a result of this, three jobs are added to the database. Once such a job is present in the database it can be processes by the JobExecutor. The JobExecutor acquires the jobs and delegates them to a thread pool of worker threads which actually process the jobs. This means that using an asynchronous continuation, you can distribute the work to this thread pool (and in a clustered scenario even across multiple thread pools in the cluster). This is usually a good thing. However it also bears an inherent problem: consistency. Consider the parallel join after the service tasks. When execution of a service tasks is completed, we arrive at the parallel join and need to decide whether to wait for the other executions or whether we can move forward. That means, for each branch arriving at the parallel join, we need to take a decision whether we can continue or whether we need to wait for one or more other executions on the other branches.</p> 13549</div> 13550<div class="paragraph"> 13551<p>Why is this a problem? Since the service tasks are configured using an asynchronous continuation, it is possible that the corresponding jobs are all acquired at the same time and delegated to different worker threads by the JobExecutor. The consequence is that the transactions in which the services are executed and in which the 3 individual executions arrive at the parallel join can overlap. And if they do so, each individual transaction will not "see", that another transaction is arriving at the same parallel join concurrently and thus assume that it has to wait for the others. However, if each transaction assumes that it has to wait for the other ones, none will c
13551ontinue the process after the parallel join and the process instance will remain in that state forever.</p> 13552</div> 13553<div class="paragraph"> 13554<p>How does Activiti address this problem? Activiti performs optimistic locking. Whenever we take a decision based on data that might not be current (because another transaction might modify it before we commit, we make sure to increment the version of the same database row in both transactions). This way, whichever transaction commits first wins and the other ones fail with an optimistic locking exception. This solves the problem in the case of the process discussed above: if multiple executions arrive at the parallel join concurrently, they all assume that they have to wait, increment the version of their parent execution (the process instance) and then try to commit. Whichever execution is first will be able to commit and the other ones will fail with an optimistic locking exception. Since the executions are triggered by a job, Activiti will retry to perform the same job after waiting for a certain amount of time and hopefully this time pass the synchronizing gateway.</p> 13555</div> 13556<div class="paragraph"> 13557<p>Is this a good solution? As we have seen, optimistic locking allows Activiti to prevent inconsistencies. It makes sure that we do not "keep stuck at the joining gateway", meaning: either all executions have passed the gateway or, there are jobs in the database making sure that we retry passing it. However, while this is a perfectly fine solution from the point of view of persistence and consistency, this might not always be desirable behavior at an higher level:</p> 13558</div> 13559<div class="ulist"> 13560<ul> 13561<li> 13562<p>Activiti will retry the same job for a fixed maximum number of times only (<em>3</em> in the default configuration). After that, the job will still be present in the database but not be retried actively anymore. That means that an operator would need to trigger the job manually.</p> 13563</li> 13564<li> 13565<p>If a job has non-transactional side effects, those will not be rolled back by the failing transaction. For instance, if the "book concert tickets" service does not share the same transaction as Activiti, we might book multiple tickets if we retry the job.</p> 13566</li> 13567</ul> 13568</div> 13569</div> 13570<div class="sect4"> 13571<h5 id="_what_are_exclusive_jobs">What are exclusive jobs?</h5> 13572<div class="paragraph"> 13573<p>An exclusive job cannot be performed at the same time as another exclusive job from the same process instance. Consider the process shown above: if we declare the service tasks to be exclusive, the JobExecutor will make sure that the corresponding jobs are not executed concurrently. Instead, it will make sure that whenever it acquires an exclusive job from a certain process instance, it acquires all other exclusive jobs from the same process instance and delegates them to the same worker thread. This ensures sequential execution execution of the jobs.</p> 13574</div> 13575<div class="paragraph"> 13576<p>How can I enable this feature? Since Activiti 5.9, exclusive jobs are the default configuration. All asynchronous continuations and timer events are thus exclusive by default. In addition, if you want a job to be non-exclusive, you can configure it as such using <code>activiti:exclusive="false"</code>. For example, the following servicetask would be asynchronous but non-exclusive.</p> 13577</div> 13578<div class="listingblock"> 13579<div class="content"> 13580<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">"service"</span> <span class="tok-na">activiti:expression=</span><span class="tok-s">"${myService.performBooking(hotel, dates)}"</span> <span class="tok-na">activiti:async=</span><span class="tok-s">"true"</span> <span class="tok-na">activiti:exclusive=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 13581</td></tr></table></code></pre> 13582</div> 13583</div> 13584<div class="paragraph"> 13585<p>Is this a good solution? We had some people asking whether this was a good solution. Their concern was that this would to prevent you from "doing things" in parallel and would thus be a performance problem. Again, two things have to be taken into consideration:</p> 13586</div> 13587<div class="ulist"> 13588<ul> 13589<li> 13590<p>It can be turned off if you are an expert and know what you are doing (and have understood the section named "Why exclusive Jobs?"). Other than that, it is more intuitive for most users if things like asynchronous continuations and timers just work.</p> 13591</li> 13592<li> 13593<p>It is actually not a performance issue. Performance is an issue under heavy load. Heavy load means that all worker threads of the job executor are busy all the time. With exclusive jobs, Activiti will simply distribute the load differently. Exclusive jobs means that jobs from a single process instance are performed by the same thread sequentially. But consider: you have more than one single process instance. And jobs from other process instances are delegated to other threads and executed concurrently. This means that with exclusive jobs Activiti will not execute jobs from the same process instance concurrently, but it will still execute multiple instances concurrently. From an overall throughput perspective this is desirable in most scenarios as it usually leads to individual instances being done more quickly. Furthermore, data that is required for executing subsequent jobs of the same process instance will already be in the cache of the executing cluster node. If the jobs do not have this node affinity, that data might need to be fetched from the database again.</p> 13594</li> 13595</ul> 13596</div> 13597</div> 13598</div> 13599</div> 13600<div class="sect2"> 13601<h3 id="security">8.8. Process Initiation Authorization</h3> 13602<div class="paragraph"> 13603<p>By default everyone is allowed to start a new process instance of deployed process definitions. The process initiation authorization functionality allows to define users and groups so that web clients can optionally restrict users to start a new process instance. NOTE that the authorization definition is NOT validated by the Activiti Engine in any way. This functionality is only meant for developers to ease the implementation of authorization rules in a web client. The syntax is similar to the syntax of user assignment for a user task. A user or group can be assigned as potential initiator of a process using <activiti:potentialStarter> tag. Here is an example:</p> 13604</div> 13605<div class="listingblock"> 13606<div class="content"> 13607<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 13608 2 13609 3 13610 4 13611 5 13612 6 13613 7 13614 8 13615 9 1361610 1361711</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"potentialStarter"</span><span class="tok-nt">></span> 13618 <span class="tok-nt"><extensionElements></span> 13619 <span class="tok-nt"><activiti:potentialStarter></span>
13620 <span class="tok-nt"><resourceAssignmentExpression></span> 13621 <span class="tok-nt"><formalExpression></span>group2, group(group3), user(user3)<span class="tok-nt"></formalExpression></span> 13622 <span class="tok-nt"></resourceAssignmentExpression></span> 13623 <span class="tok-nt"></activiti:potentialStarter></span> 13624 <span class="tok-nt"></extensionElements></span> 13625 13626 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"theStart"</span><span class="tok-nt">/></span> 13627 ... 13628</td></tr></table></code></pre> 13629</div> 13630</div> 13631<div class="paragraph"> 13632<p>In the above xml excerpt user(user3) refers directly to user user3 and group(group3) to group group3. No indicator will default to a group type. It is also possible to use attributes of the <process> tag, namely <activiti:candidateStarterUsers> and <activiti:candidateStarterGroups>. Here is an example:</p> 13633</div> 13634<div class="listingblock"> 13635<div class="content"> 13636<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 136372 136383</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"potentialStarter"</span> <span class="tok-na">activiti:candidateStarterUsers=</span><span class="tok-s">"user1, user2"</span> 13639 <span class="tok-na">activiti:candidateStarterGroups=</span><span class="tok-s">"group1"</span><span class="tok-nt">></span> 13640 ... 13641</td></tr></table></code></pre> 13642</div> 13643</div> 13644<div class="paragraph"> 13645<p>It is possible to use both attributes simultaneously.</p> 13646</div> 13647<div class="paragraph"> 13648<p>After the process initiation authorizations are defined, a developer can retrieve the authorization definition using the following methods. 13649This code retrieves the list of process definitions which can be initiated by the given user:</p> 13650</div> 13651<div class="listingblock"> 13652<div class="content"> 13653<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">processDefinitions</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">
13653createProcessDefinitionQuery</span><span class="tok-o">().</span><span class="tok-na">startableByUser</span><span class="tok-o">(</span><span class="tok-s">"userxxx"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 13654</td></tr></table></code></pre> 13655</div> 13656</div> 13657<div class="paragraph"> 13658<p>It’s also possible to retrieve all identity links that are defined as potential starter for a specific process definition</p> 13659</div> 13660<div class="listingblock"> 13661<div class="content"> 13662<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">identityLinks</span> <span class="tok-o">=</span> <span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">getIdentityLinksForProcessDefinition</span><span class="tok-o">(</span><span class="tok-s">"processDefinitionId"</span><span class="tok-o">);</span> 13663</td></tr></table></code></pre> 13664</div> 13665</div> 13666<div class="paragraph"> 13667<p>The following example shows how to get list of users who can initiate the given process:</p> 13668</div> 13669<div class="listingblock"> 13670<div class="content"> 13671<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">User</span><span class="tok-o">></span> <span class="tok-n">authorizedUsers</span> <span class="tok-o">=</span> <span class="tok-n">identityService</span><span class="tok-o">().</span><span class="tok-na">createUserQuery</span><span class="tok-o">().</span><span class="tok-na">potentialStarter</span><span class="tok-o">(</span><span class="tok-s">"processDefinitionId"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 13672</td></tr></table></code></pre> 13673</div> 13674</div> 13675<div class="paragraph"> 13676<p>Exactly the same way, the list of groups that is configured as a potential starter to a given process definition can be retrieved:</p> 13677</div> 13678<div class="listingblock"> 13679<div class="content"> 13680<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Group</span><span class="tok-o">></span> <span class="tok-n">authorizedGroups</span> <span class="tok-o">=</span> <span class="tok-n">identityService</span><span class="tok-o">().</span><span class="tok-na">createGroupQuery</span><span class="tok-o">().</span><span class="tok-na">potentialStarter</span><span class="tok-o">(</span><span class="tok-s">"processDefinitionId"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 13681</td></tr></table></code></pre> 13682</div> 13683</div> 13684</div> 13685<div class="sect2"> 13686<h3 id="dataobjects">8.9. Data objects</h3> 13687<div class="paragraph"> 13688<p><a href="#experimental">[EXPERIMENTAL]</a></p> 13689</div> 13690<div class="paragraph"> 13691<p>BPMN provides the possibility to define data objects as part of a process or sub process element. According to the BPMN specification it’s possible to include complex XML structures that might be imported from XSD definitions. As a first start to support data objects in Activiti the following XSD types are supported:</p> 13692</div> 13693<div class="listingblock"> 13694<div class="content"> 13695<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 136962 136973 136984 136995 137006</div></td><td class="code"><span></span><span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj1"</span> <span class="tok-na">name=</span><span class="tok-s">"StringTest"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:string"</span><span class="tok-nt">/></span> 13701<span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj2"</span> <span class="tok-na">name=</span><span class="tok-s">"BooleanTest"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:boolean"</span><span class="tok-nt">/></span> 13702<span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj3"</span> <span class="tok-na">name=</span><span class="tok-s">"DateTest"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:datetime"</span><span class="tok-nt">/></span> 13703<span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj4"</span> <span class="tok-na">name=</span><span class="tok-s">"DoubleTest"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:double"</span><span class="tok-nt">/></span> 13704<span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj5"</span> <span class="tok-na">name=</span><span class="tok-s">"IntegerTest"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:int"</span><span class="tok-nt">/></span> 13705<span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj6"</span> <span class="tok-na">name=</span><span class="tok-s">"LongTest"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:long"</span><span class="tok-nt">/></span> 13706</td></tr></table></code></pre> 13707</div> 13708</div> 13709<div class="paragraph"> 13710<p>The data object definitions will be automatically converted to process variables using the <em>
13710name</em> attribute value as the name for the new variable. In addition to the definition of the data object Activiti also provides an extension element to assign a default value to the variable. The following BPMN snippet provides an example:</p> 13711</div> 13712<div class="listingblock"> 13713<div class="content"> 13714<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 137152 137163 137174 137185 137196 137207</div></td><td class="code"><span></span><span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"dataObjectScope"</span> <span class="tok-na">name=</span><span class="tok-s">"Data Object Scope"</span> <span class="tok-na">isExecutable=</span><span class="tok-s">"true"</span><span class="tok-nt">></span> 13721 <span class="tok-nt"><dataObject</span> <span class="tok-na">id=</span><span class="tok-s">"dObj123"</span> <span class="tok-na">name=</span><span class="tok-s">"StringTest123"</span> <span class="tok-na">itemSubjectRef=</span><span class="tok-s">"xsd:string"</span><span class="tok-nt">></span> 13722 <span class="tok-nt"><extensionElements></span> 13723 <span class="tok-nt"><activiti:value></span>Testing123<span class="tok-nt"></activiti:value></span> 13724 <span class="tok-nt"></extensionElements></span> 13725 <span class="tok-nt"></dataObject></span> 13726 ... 13727</td></tr></table></code></pre> 13728</div> 13729</div> 13730</div> 13731</div> 13732</div> 13733<div class="sect1"> 13734<h2 id="forms">9. Forms</h2> 13735<div class="sectionbody"> 13736<div class="paragraph"> 13737<p>Activiti provides a convenient and flexible way to add forms for the manual steps of your business processes. We support two strategies to work with forms: Build-in form rendering with form properties and external form rendering.</p> 13738</div> 13739<div class="sect2"> 13740<h3 id="formProperties">9.1. Form properties</h3> 13741<div class="paragraph"> 13742<p>All information relevant to a business process is either included in the process variables themselves or referenced through the process variables. Activiti supports complex Java objects to be stored as process variables like <code>Serializable</code> objects, JPA entities or whole XML documents as <code>String</code>s.</p> 13743</div> 13744<div class="paragraph"> 13745<p>Starting a process and completing user tasks is where people are involved into a process. Communicating with people requires forms to be rendered in some UI technology. In order to facilitate multiple UI technologies easy, the process definition can include the logic of transforming of the complex Java typed objects in the process variables to a <code>Map<String,String></code> of <strong><em>properties</em></strong>.</p> 13746</div> 13747<div class="paragraph"> 13748<p>Any UI technology can then build a form on top of those properties, using the Activiti API methods that expose the property information. The properties can provide a dedicated (and more limited) view on the process variables. The properties needed to display a form are available in the <strong>FormData</strong> return values of for example</p> 13749</div> 13750<div class="listingblock"> 13751<div class="content"> 13752<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">StartFormData</span> <span class="tok-n">FormService</span><span class="tok-o">.</span><span class="tok-na">getStartFormData</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">processDefinitionId</span><span class="tok-o">)</span> 13753</td></tr></table></code></pre> 13754</div> 13755</div> 13756<div class="paragraph"> 13757<p>or</p> 13758</div> 13759<div class="listingblock"> 13760<div class="content"> 13761<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">TaskFormdata</span> <span class="tok-n">FormService</span><span class="tok-o">.</span><span class="tok-na">getTaskFormData</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">taskId</span><span class="tok-o">)</span> 13762</td></tr></table></code></pre> 13763</div> 13764</div> 13765<div class="paragraph"> 13766<p>By default, the build-in form engines, <em>sees</em> the properties as well as the process variables. So there is no need to declare task form properties if they match 1-1 with the process variables. For example, with the following declaration:</p> 13767</div> 13768<div class="listingblock"> 13769<div class="content"> 13770<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span> <span class="tok-nt">/></span> 13771</td></tr></table></code></pre> 13772</div> 13773</div> 13774<div class="paragraph"> 13775<p>All process variables are available when execution arrives in the startEvent, but</p> 13776</div> 13777<div class="listingblock"> 13778<div class="content"> 13779<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">formService</span><span class="tok-o">.</span><span class="tok-na">getStartFormData</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">
13779processDefinitionId</span><span class="tok-o">).</span><span class="tok-na">getFormProperties</span><span class="tok-o">()</span> 13780</td></tr></table></code></pre> 13781</div> 13782</div> 13783<div class="paragraph"> 13784<p>will be empty since no specific mapping was defined.</p> 13785</div> 13786<div class="paragraph"> 13787<p>In the above case, all the submitted properties will be stored as process variables. This means that by simply adding a new input field in the form, a new variable can be stored.</p> 13788</div> 13789<div class="paragraph"> 13790<p>Properties are derived from process variables, but they don’t have to be stored as process variables. For example, a process variable could be a JPA entity of class Address. And a form property <code>StreetName</code> used by the UI technology could be linked with an expression <code>#{address.street}</code></p> 13791</div> 13792<div class="paragraph"> 13793<p>Analogue, the properties that a user is supposed to submit in a form can be stored as a process variable or as a nested property in one of the process variables with a UEL value expression like e.g. <code>#{address.street}</code> .</p> 13794</div> 13795<div class="paragraph"> 13796<p>Analogue the default behavior of properties that are submitted is that they will be stored as process variables unless a <code>formProperty</code> declaration specifies otherwise.</p> 13797</div> 13798<div class="paragraph"> 13799<p>Also type conversions can be applied as part of the processing between form properties and process variables.</p> 13800</div> 13801<div class="paragraph"> 13802<p>For example:</p> 13803</div> 13804<div class="listingblock"> 13805<div class="content"> 13806<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 138072 138083 138094 138105 138116 138127 138138</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"task"</span><span class="tok-nt">></span> 13814 <span class="tok-nt"><extensionElements></span> 13815 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"room"</span> <span class="tok-nt">/></span> 13816 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"duration"</span> <span class="tok-na">type=</span><span class="tok-s">"long"</span><span class="tok-nt">/></span> 13817 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"speaker"</span> <span class="tok-na">variable=</span><span class="tok-s">"SpeakerName"</span> <span class="tok-na">writable=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 13818 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"street"</span> <span class="tok-na">expression=</span><span class="tok-s">"#{address.street}"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 13819 <span class="tok-nt"></extensionElements></span> 13820<span class="tok-nt"></userTask></span> 13821</td></tr></table></code></pre> 13822</div> 13823</div> 13824<div class="ulist"> 13825<ul> 13826<li> 13827<p>Form property <code>room</code> will be mapped to process variable <code>room</code> as a String</p> 13828</li> 13829<li> 13830<p>Form property <code>duration</code> will be mapped to process variable <code>duration</code> as a java.lang.Long</p> 13831</li> 13832<li> 13833<p>Form property <code>speaker</code> will be mapped to process variable <code>SpeakerName</code>. It will only be available in the TaskFormData object. If property speaker is submitted, an ActivitiException will be thrown. Analogue, with attribute <code>readable="false"</code>, a property can be excluded from the FormData, but still be processed in the submit.</p> 13834</li> 13835<li> 13836<p>Form property <code>street</code> will be mapped to Java bean property <code>street</code> in process variable <code>address</code> as a String. And required="true" will throw an exception during the submit if the property is not provided.
13836</p> 13837</li> 13838</ul> 13839</div> 13840<div class="paragraph"> 13841<p>It’s also possible to provide type metadata as part of the FormData that is returned from methods <code>StartFormData FormService.getStartFormData(String processDefinitionId)</code> and <code>TaskFormdata FormService.getTaskFormData(String taskId)</code></p> 13842</div> 13843<div class="paragraph"> 13844<p>We support the following form property types:</p> 13845</div> 13846<div class="ulist"> 13847<ul> 13848<li> 13849<p><code>string</code> (org.activiti.engine.impl.form.StringFormType</p> 13850</li> 13851<li> 13852<p><code>long</code> (org.activiti.engine.impl.form.LongFormType)</p> 13853</li> 13854<li> 13855<p><code>enum</code> (org.activiti.engine.impl.form.EnumFormType)</p> 13856</li> 13857<li> 13858<p><code>date</code> (org.activiti.engine.impl.form.DateFormType)</p> 13859</li> 13860<li> 13861<p><code>boolean</code> (org.activiti.engine.impl.form.BooleanFormType)</p> 13862</li> 13863</ul> 13864</div> 13865<div class="paragraph"> 13866<p>For each form property declared, the following <code>FormProperty</code> information will be made available through <code>List<FormProperty> formService.getStartFormData(String processDefinitionId).getFormProperties()</code> and <code>List<FormProperty> formService.getTaskFormData(String taskId).getFormProperties()</code></p> 13867</div> 13868<div class="listingblock"> 13869<div class="content"> 13870<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 13871 2 13872 3 13873 4 13874 5 13875 6 13876 7 13877 8 13878 9 1387910 1388011 1388112 1388213 1388314 1388415 1388516 1388617 1388718</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">interface</span> <span class="tok-nc">FormProperty</span> <span class="tok-o">{</span> 13888 <span class="tok-cm">/** the key used to submit the property in {@link FormService#submitStartFormData(String, java.util.Map)}</span> 13889<span class="tok-cm"> * or {@link FormService#submitTaskFormData(String, java.util.Map)} */</span> 13890 <span class="tok-n">String</span> <span class="tok-nf">getId</span><span class="tok-o">();</span> 13891 <span class="tok-cm">/** the display label */</span> 13892 <span class="tok-n">String</span> <span class="tok-nf">getName</span><span class="tok-o">();</span> 13893 <span class="tok-cm">/** one of the types defined in this interface like e.g. {@link #TYPE_STRING} */</span> 13894 <span class="tok-n">FormType</span> <span class="tok-nf">getType</span><span class="tok-o">();</span> 13895 <span class="tok-cm">/** optional value that should be used to display in this property */</span> 13896 <span class="tok-n">String</span> <span class="tok-nf">getValue</span><span class="tok-o">();</span> 13897 <span class="tok-cm">/** is this property read to be displayed in the form and made accessible with the methods</span> 13898<span class="tok-cm"> * {@link FormService#getStartFormData(String)} and {@link FormService#getTaskFormData(String)}. */</span> 13899 <span class="tok-kt">boolean</span> <span class="tok-nf">isReadable</span><span class="tok-o">();</span> 13900 <span class="tok-cm">/** is this property expected when a user submits the form? */</span> 13901 <span class="tok-kt">boolean</span> <span class="tok-nf">isWritable</span><span class="tok-o">();</span> 13902 <span class="tok-cm">/** is this property a required input field */</span> 13903 <span class="tok-kt">boolean</span> <span class="tok-nf">isRequired</span><span class="tok-o">();</span> 13904<span class="tok-o">}</span> 13905</td></tr></table></code></pre> 13906</div> 13907</div> 13908<div class="paragraph"> 13909<p>For example:</p> 13910</div> 13911<div class="listingblock"> 13912<div class="content"> 13913<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 13914 2 13915 3 13916 4 13917 5 13918 6 13919 7 13920 8 13921 9 1392210 1392311 1392412 1392513 1392614 1392715 1392816 1392917 1393018 1393119 1393220</div></td><td class="code"><span></span><span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span><span class="tok-nt">></span> 13933 <span class="tok-nt"><extensionElements></span> 13934 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"speaker"</span> 13935 <span class="tok-na">name=</span><span class="tok-s">"Speaker"</span>
13936 <span class="tok-na">variable=</span><span class="tok-s">"SpeakerName"</span> 13937 <span class="tok-na">type=</span><span class="tok-s">"string"</span> <span class="tok-nt">/></span> 13938 13939 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"start"</span> 13940 <span class="tok-na">type=</span><span class="tok-s">"date"</span> 13941 <span class="tok-na">datePattern=</span><span class="tok-s">"dd-MMM-yyyy"</span> <span class="tok-nt">/></span> 13942 13943 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"direction"</span> <span class="tok-na">type=</span><span class="tok-s">"enum"</span><span class="tok-nt">></span> 13944 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"left"</span> <span class="tok-na">name=</span><span class="tok-s">"Go Left"</span> <span class="tok-nt">/></span> 13945 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"right"</span> <span class="tok-na">name=</span><span class="tok-s">"Go Right"</span> <span class="tok-nt">/></span> 13946 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"up"</span> <span class="tok-na">name=</span><span class="tok-s">"Go Up"</span> <span class="tok-nt">/></span> 13947 <span class="tok-nt"><activiti:value</span> <span class="tok-na">id=</span><span class="tok-s">"down"</span> <span class="tok-na">name=</span><span class="tok-s">"Go Down"</span> <span class="tok-nt">/></span> 13948 <span class="tok-nt"></activiti:formProperty></span> 13949 13950 <span class="tok-nt"></extensionElements></span> 13951<span class="tok-nt"></startEvent></span> 13952</td></tr></table></code></pre> 13953</div> 13954</div> 13955<div class="paragraph"> 13956<p>All that information is accessible through the API. The type names can be obtained with <code>formProperty.getType().getName()</code>. And even the date pattern is available with <code>formProperty.getType().getInformation("datePattern")</code> and the enumeration values are accessible with <code>formProperty.getType().getInformation("values")</code></p> 13957</div> 13958<div class="paragraph"> 13959<p>Activiti explorer supports the form properties and will render the form accordingly to the form definition. The following XML snippet</p> 13960</div> 13961<div class="listingblock"> 13962<div class="content"> 13963<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 139642 139653 139664 139675 139686 139697</div></td><td class="code"><span></span><span class="tok-nt"><startEvent></span> 13970 <span class="tok-nt"><extensionElements></span> 13971 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"numberOfDays"</span> <span class="tok-na">name=</span><span class="tok-s">"Number of days"</span> <span class="tok-na">value=</span><span class="tok-s">"${numberOfDays}"</span> <span class="tok-na">type=</span><span class="tok-s">"long"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span><span class="tok-nt">/></span> 13972 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"startDate"</span> <span class="tok-na">name=</span><span class="tok-s">"First day of holiday (dd-MM-yyy)"</span> <span class="tok-na">value=</span><span class="tok-s">"${startDate}"</span> <span class="tok-na">datePattern=</span><span class="tok-s">"dd-MM-yyyy hh:mm"</span> <span class="tok-na">type=</span><span class="tok-s">"date"</span> <span class="tok-na">required=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 13973 <span class="tok-nt"><activiti:formProperty</span> <span class="tok-na">id=</span><span class="tok-s">"vacationMotivation"</span> <span class="tok-na">name=</span><span class="tok-s">"Motivation"</span> <span class="tok-na">value=</span><span class="tok-s">"${vacationMotivation}"</span> <span class="tok-na">type=</span><span class="tok-s">"
13973string"</span> <span class="tok-nt">/></span> 13974 <span class="tok-nt"></extensionElements></span> 13975<span class="tok-nt"></userTask></span> 13976</td></tr></table></code></pre> 13977</div> 13978</div> 13979<div class="paragraph"> 13980<p>will render to a process start form when used in Activiti Explorer</p> 13981</div> 13982<div class="imageblock" style="text-align: center"> 13983<div class="content"> 13984<img src="images/forms.explorer.png" alt="forms.explorer"> 13985</div> 13986</div> 13987</div> 13988<div class="sect2"> 13989<h3 id="externalFormRendering">9.2. External form rendering</h3> 13990<div class="paragraph"> 13991<p>The API also allows for you to perform your own task form rendering outside of the Activiti Engine. These steps explain the hooks that you can use to render your task forms yourself.</p> 13992</div> 13993<div class="paragraph"> 13994<p>Essentially, all the data that’s needed to render a form is assembled in one of these two service methods: <code>StartFormData FormService.getStartFormData(String processDefinitionId)</code> and <code>TaskFormdata FormService.getTaskFormData(String taskId)</code>.</p> 13995</div> 13996<div class="paragraph"> 13997<p>Submitting form properties can be done with <code>ProcessInstance FormService.submitStartFormData(String processDefinitionId, Map<String,String> properties)</code> and <code>void FormService.submitTaskFormData(String taskId, Map<String,String> properties)</code></p> 13998</div> 13999<div class="paragraph"> 14000<p>To learn about how form properties map to process variables, see <a href="#formProperties">Form properties</a></p> 14001</div> 14002<div class="paragraph"> 14003<p>You can place any form template resource inside the business archives that you deploy (in case you want to store them versioned with the process). It will be available as a resource in the deployment, which you can retrieve using: <code>String ProcessDefinition.getDeploymentId()</code> and <code>InputStream RepositoryService.getResourceAsStream(String deploymentId, String resourceName);</code> This could be your template definition file, which you can use to render/show the form in your own application.</p> 14004</div> 14005<div class="paragraph"> 14006<p>You can use this capability of accessing the deployment resources beyond task forms for any other purposes as well.</p> 14007</div> 14008<div class="paragraph"> 14009<p>The attribute <code><userTask activiti:formKey="…​"</code> is exposed by the API through <code>String FormService.getStartFormData(String processDefinitionId).getFormKey()</code> and <code>String FormService.getTaskFormData(String taskId).getFormKey()</code>. You could use this to store the full name of the template within your deployment (e.g. <code>org/activiti/example/form/my-custom-form.xml</code>), but this is not required at all. For instance, you could also store a generic key in the form attribute and apply an algorithm or transformation to get to the actual template that needs to be used. This might be handy when you want to render different forms for different UI technologies like e.g. one form for usage in a web app of normal screen size, one form for mobile phone’s small screens and maybe even a template for an IM form or an email form.</p> 14010</div> 14011</div> 14012</div> 14013</div> 14014<div class="sect1"> 14015<h2 id="_jpa">10. JPA</h2> 14016<div class="sectionbody"> 14017<div class="paragraph"> 14018<p>You can use JPA-Entities as process variables, allowing you to:</p> 14019</div> 14020<div class="ulist"> 14021<ul> 14022<li> 14023<p>Updating existing JPA-entities based on process variables that can be filled in on a form in a userTask or generated in a serviceTask.</p> 14024</li> 14025<li> 14026<p>Reusing existing domain model without having to write explicit services to fetch the entities and update the values</p> 14027</li> 14028<li> 14029<p>Make decisions (gateways) based on properties of existing entities.</p> 14030</li> 14031<li> 14032<p>…​</p> 14033</li> 14034</ul> 14035</div> 14036<div class="sect2"> 14037<h3 id="_requirements">10.1. Requirements</h3> 14038<div class="paragraph"> 14039<p>Only entities that comply with the following are supported:</p> 14040</div> 14041<div class="ulist"> 14042<ul> 14043<li> 14044<p>Entities should be configured using JPA-annotations, we support both field and property-access. Mapped super classes can also be used.<
14044/p> 14045</li> 14046<li> 14047<p>Entity should have a primary key annotated with <code>@Id</code>, compound primary keys are not supported (<code>@EmbeddedId</code> and <code>@IdClass</code>). The Id field/property can be of any type supported in the JPA-spec: Primitive types and their wrappers (excluding boolean), <code>String</code>, <code>BigInteger</code>, <code>BigDecimal</code>, <code>java.util.Date</code> and <code>java.sql.Date</code>.</p> 14048</li> 14049</ul> 14050</div> 14051</div> 14052<div class="sect2"> 14053<h3 id="jpaconfiguration">10.2. Configuration</h3> 14054<div class="paragraph"> 14055<p>To be able to use JPA-entities, the engine must have a reference to an <code>EntityManagerFactory</code>. This can be done by configuring a reference or by supplying a persistence-unit name. JPA-entities used as variables will be detected automatically and will be handled accordingly.</p> 14056</div> 14057<div class="paragraph"> 14058<p>The example configuration below uses the jpaPersistenceUnitName:</p> 14059</div> 14060<div class="listingblock"> 14061<div class="content"> 14062<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 14063 2 14064 3 14065 4 14066 5 14067 6 14068 7 14069 8 14070 9 1407110 1407211 1407312 1407413 1407514 1407615 1407716 1407817</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> 14079 <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration"</span><span class="tok-nt">></span> 14080 14081<span class="tok-c"><!-- Database configurations --></span> 14082<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 14083<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jdbcUrl"</span> <span class="tok-na">value=</span><span class="tok-s">"jdbc:h2:mem:JpaVariableTest;DB_CLOSE_DELAY=1000"</span> <span class="tok-nt">/></span> 14084 14085<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaPersistenceUnitName"</span> <span class="tok-na">value=</span><span class="tok-s">"activiti-jpa-pu"</span> <span class="tok-nt">/></span> 14086<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaHandleTransaction"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 14087<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaCloseEntityManager"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 14088 14089<span class="tok-c"><!-- job executor configurations --></span> 14090<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jobExecutorActivate"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 14091 14092<span class="tok-c"><!-- mail server configurations --></span> 14093<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"mailServerPort"</span> <span class="tok-na">value=</span><span class="tok-s">"5025"</span> <span class="tok-nt">/></span> 14094<span class="tok-nt"></bean></span> 14095</td></tr></table></code></pre> 14096</div> 14097</div> 14098<div class="paragraph"> 14099<p>The next example configuration below provides a <code>EntityManagerFactory</code> which we define ourselves (in this case, an open-jpa entity manager). Note that the snippet only contains the beans that are relevant for the example, the others are omitted. Full working example with open-jpa entity manager can be found in the activiti-spring-examples (<code>/activiti-spring/src/test/java/org/activiti/spring/test/jpa/JPASpringTest.java</code>)</p> 14100</div> 14101<div class="listingblock"> 14102<div class="content"> 14103<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 14104 2 14105 3 14106 4 14107 5 14108 6 14109 7 14110 8 14111 9 1411210 1411311 1411412 1411513 1411614 1411715 1411816 1411917 1412018</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"entityManagerFactory"</span> <span class="tok-na">class=</span><span class="tok-s">"
14120org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"</span><span class="tok-nt">></span> 14121 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"persistenceUnitManager"</span> <span class="tok-na">ref=</span><span class="tok-s">"pum"</span><span class="tok-nt">/></span> 14122 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaVendorAdapter"</span><span class="tok-nt">></span> 14123 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.springframework.orm.jpa.vendor.OpenJpaVendorAdapter"</span><span class="tok-nt">></span> 14124 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databasePlatform"</span> <span class="tok-na">value=</span><span class="tok-s">"org.apache.openjpa.jdbc.sql.H2Dictionary"</span> <span class="tok-nt">/></span> 14125 <span class="tok-nt"></bean></span> 14126 <span class="tok-nt"></property></span> 14127<span class="tok-nt"></bean></span> 14128 14129<span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.spring.SpringProcessEngineConfiguration"</span><span class="tok-nt">></span> 14130 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"dataSource"</span> <span class="tok-na">ref=</span><span class="tok-s">"dataSource"</span> <span class="tok-nt">/></span> 14131 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">ref=</span><span class="tok-s">"transactionManager"</span> <span class="tok-nt">/></span> 14132 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 14133 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaEntityManagerFactory"</span> <span class="tok-na">ref=</span><span class="tok-s">"entityManagerFactory"</span> <span class="tok-nt">/></span> 14134 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaHandleTransaction"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 14135 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jpaCloseEntityManager"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 14136 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jobExecutorActivate"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 14137<span class="tok-nt"></bean></span> 14138</td></tr></table></code></pre> 14139</div> 14140</div> 14141<div class="paragraph"> 14142<p>The same configurations can also be done when building an engine programmatically, example:</p> 14143</div> 14144<div class="listingblock"> 14145<div class="content"> 14146<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 141472 141483 141494</div></td><td class="code"><span></span><span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngineConfiguration</span> 14150<span class="tok-o">.</span><span class="tok-na">createProcessEngineConfigurationFromResourceDefault</span><span class="tok-o">()</span> 14151<span class="tok-o">.</span><span class="tok-na">setJpaPersistenceUnitName</span><span class="tok-o">(</span><span class="tok-s">"activiti-pu"</span><span class="tok-o">)</span> 14152<span class="tok-o">.</span><span class="tok-na">buildProcessEngine</span><span class="tok-o">();</span> 14153</td></tr></table></code></pre> 14154</div> 14155</div> 14156<div class="paragraph"> 14157<p>Configuration properties:</p> 14158</div> 14159<div class="ulist"> 14160<ul> 14161<li> 14162<p><code>jpaPersistenceUnitName</code>: The name of the persistence-unit to use. (Make sure the persistence-unit is available on the classpath. According to the spec, the default location is <code>/META-INF/persistence.xml</code>). Use either <code>jpaEntityManagerFactory</code> or <code>jpaPersistenceUnitName</code>.</p> 14163</li> 14164<li> 14165<p><code>jpaEntityManagerFactory</code>: An reference to a bean implementing <code>
14165javax.persistence.EntityManagerFactory</code> that will be used to load the Entities and flushing the updates. Use either <em>jpaEntityManagerFactory</em> or <em>jpaPersistenceUnitName</em>.</p> 14166</li> 14167<li> 14168<p><code>jpaHandleTransaction</code>: Flag indicating that the engine should begin and commit/rollback the transaction on the used <em>EntityManager</em> instances. Set to false when <em>Java Transaction API (JTA)</em> is used.</p> 14169</li> 14170<li> 14171<p><code>jpaCloseEntityManager</code>: Flag indicating that the engine should close the <code>EntityManager</code> instance that was obtained from the <code>EntityManagerFactory</code>. Set to false when the <em>EntityManager</em> is container-managed (e.g. when using an Extended Persistence Context which isn’t scoped to a single transaction').</p> 14172</li> 14173</ul> 14174</div> 14175</div> 14176<div class="sect2"> 14177<h3 id="_usage">10.3. Usage</h3> 14178<div class="sect3"> 14179<h4 id="_simple_example">10.3.1. Simple Example</h4> 14180<div class="paragraph"> 14181<p>Examples for using JPA variables can be found in JPAVariableTest in the Activiti source code. We’ll explain <code>JPAVariableTest.testUpdateJPAEntityValues</code> step by step.</p> 14182</div> 14183<div class="paragraph"> 14184<p>First of all, we create an <em>EntityManagerFactory</em> for our persistence-unit, which is based on <code>META-INF/persistence.xml</code>. This contains classes which should be included in the persistence unit and some vendor-specific configuration.</p> 14185</div> 14186<div class="paragraph"> 14187<p>We are using a simple entity in the test, having an id and <code>String</code> value property, which is also persisted. Before running the test, we create an entity and save this.</p> 14188</div> 14189<div class="listingblock"> 14190<div class="content"> 14191<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 14192 2 14193 3 14194 4 14195 5 14196 6 14197 7 14198 8 14199 9 1420010 1420111 1420212 1420313 1420414 1420515 1420616 1420717 1420818 1420919 1421020 1421121 1421222 1421323 1421424 1421525 1421626 1421727 1421828 1421929</div></td><td class="code"><span></span><span class="tok-nd">@Entity</span><span class="tok-o">(</span><span class="tok-n">name</span> <span class="tok-o">=</span> <span class="tok-s">"JPA_ENTITY_FIELD"</span><span class="tok-o">)</span> 14220<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">FieldAccessJPAEntity</span> <span class="tok-o">{</span> 14221 14222 <span class="tok-nd">@Id</span> 14223 <span class="tok-nd">@Column</span><span class="tok-o">(</span><span class="tok-n">name</span> <span class="tok-o">=</span> <span class="tok-s">"ID_"</span><span class="tok-o">)</span> 14224 <span class="tok-kd">private</span> <span class="tok-n">Long</span> <span class="tok-n">id</span><span class="tok-o">;</span> 14225 14226 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">value</span><span class="tok-o">;</span> 14227 14228 <span class="tok-kd">public</span> <span class="tok-nf">FieldAccessJPAEntity</span><span class="tok-o">()</span> <span class="tok-o">{</span> 14229 <span class="tok-c1">// Empty constructor needed for JPA</span> 14230 <span class="tok-o">}</span> 14231 14232 <span class="tok-kd">public</span> <span class="tok-n">Long</span> <span class="tok-nf">getId</span><span class="tok-o">()</span> <span class="tok-o">{</span> 14233 <span class="tok-k">return</span> <span class="tok-n">id</span><span class="tok-o">;</span> 14234 <span class="tok-o">}</span> 14235 14236 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setId</span><span class="tok-o">(</span><span class="tok-n">Long</span> <span class="tok-n">id</span><span class="tok-o">)</span> <span class="tok-o">{</span> 14237 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">id</span> <span class="tok-o">=</span> <span class="tok-n">id</span><span class="tok-o">;</span> 14238 <span class="tok-o">}</span> 14239 14240 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getValue</span><span class="tok-o">()</span> <span class="tok-o">{</span> 14241 <span class="tok-k">return</span> <span class="tok-n">value</span><span class="tok-o">;</span> 14242 <span class="tok-o">}</span> 14243 14244 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">setValue</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">value</span><span class="tok-o">)</span> <span class="tok-o">{</span> 14245 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">value</span> <span class="tok-o">=</span> <span class="tok-n">value</span><span class="tok-o">;</span> 14246 <span class="tok-o">}</span> 14247<span class="tok-o">}</span> 14248</td></tr></table></code></pre> 14249</div> 14250</div> 14251<div class="paragraph"> 14252<p>We start a new process instance, adding the entity as a variable. As with other variables, they are stored in the persistent storage of the engine. When the variable is requested the next time, it will be loaded from the <code>EntityManager</code> based on the class and Id stored.</p> 14253</div> 14254<div class="listingblock"> 14255<div class="content"> 14256<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 142572 142583 142594</div></td><td class="code"><span></span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">></span> <span class="tok-n">variables</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">HashMap</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>();
14259</span> 14260<span class="tok-n">variables</span><span class="tok-o">.</span><span class="tok-na">put</span><span class="tok-o">(</span><span class="tok-s">"entityToUpdate"</span><span class="tok-o">,</span> <span class="tok-n">entityToUpdate</span><span class="tok-o">);</span> 14261 14262<span class="tok-n">ProcessInstance</span> <span class="tok-n">processInstance</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">startProcessInstanceByKey</span><span class="tok-o">(</span><span class="tok-s">"UpdateJPAValuesProcess"</span><span class="tok-o">,</span> <span class="tok-n">variables</span><span class="tok-o">);</span> 14263</td></tr></table></code></pre> 14264</div> 14265</div> 14266<div class="paragraph"> 14267<p>The first node in our process definition contains a <code>serviceTask</code> that will invoke the method <code>setValue</code> on <code>entityToUpdate</code>, which resolves to the JPA variable we set earlier when starting the process instance and will be loaded from the <code>EntityManager</code> associated with the current engine’s context'.</p> 14268</div> 14269<div class="listingblock"> 14270<div class="content"> 14271<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 142722</div></td><td class="code"><span></span><span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">'theTask'</span> <span class="tok-na">name=</span><span class="tok-s">'updateJPAEntityTask'</span> 14273 <span class="tok-na">activiti:expression=</span><span class="tok-s">"${entityToUpdate.setValue('updatedValue')}"</span> <span class="tok-nt">/></span> 14274</td></tr></table></code></pre> 14275</div> 14276</div> 14277<div class="paragraph"> 14278<p>When the service-task is finished, the process instance waits in a userTask defined in the process definition, which allows us to inspect the process instance. At this point, the <code>EntityManager</code> has been flushed and the changes to the entity have been pushed to the database. When we get the value of the variable <code>entityToUpdate</code>, it’s loaded again and we get the entity with its <code>value</code> property set to <code>updatedValue</code>.</p> 14279</div> 14280<div class="listingblock"> 14281<div class="content"> 14282<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 142832 142843 142854</div></td><td class="code"><span></span><span class="tok-c1">// Servicetask in process 'UpdateJPAValuesProcess' should have set value on entityToUpdate.</span> 14286<span class="tok-n">Object</span> <span class="tok-n">updatedEntity</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">getVariable</span><span class="tok-o">(</span><span class="tok-n">processInstance</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">(),</span> <span class="tok-s">"entityToUpdate"</span><span class="tok-o">);</span> 14287<span class="tok-n">assertTrue</span><span class="tok-o">(</span><span class="tok-n">updatedEntity</span> <span class="tok-k">instanceof</span> <span class="tok-n">FieldAccessJPAEntity</span><span class="tok-o">);</span> 14288<span class="tok-n">assertEquals</span><span class="tok-o">(</span><span class="tok-s">"updatedValue"</span><span class="tok-o">,</span> <span class="tok-o">((</span><span class="tok-n">FieldAccessJPAEntity</span><span class="tok-o">)</span><span class="tok-n">updatedEntity</span><span class="tok-o">).</span><span class="tok-na">getValue</span><span class="tok-o">());</span> 14289</td></tr></table></code></pre> 14290</div> 14291</div> 14292</div> 14293<div class="sect3"> 14294<h4 id="_query_jpa_process_variables">10.3.2. Query JPA process variables</h4> 14295<div class="paragraph"> 14296<p>You can query for <code>ProcessInstance</code>s and <code>Execution</code>s that have a certain JPA-entity as variable value. <strong>Note that only <code>variableValueEquals(name, entity)</code> is supported for JPA-Entities on <code>ProcessInstanceQuery</code> and <code>ExecutionQuery</code></strong>. Methods <code>variableValueNotEquals</code>, <code>variableValueGreaterThan</code>, <code>variableValueGreaterThanOrEqual</code>, <code>variableValueLessThan</code> and <code>variableValueLessThanOrEqual</code> are unsupported and will throw an <code>ActivitiException</code> when a JPA-Entity is passed as value.</p> 14297</div> 14298<div class="listingblock"> 14299<div class="content"> 14300<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1
143012</div></td><td class="code"><span></span> <span class="tok-n">ProcessInstance</span> <span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceQuery</span><span class="tok-o">()</span> 14302 <span class="tok-o">.</span><span class="tok-na">variableValueEquals</span><span class="tok-o">(</span><span class="tok-s">"entityToQuery"</span><span class="tok-o">,</span> <span class="tok-n">entityToQuery</span><span class="tok-o">).</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 14303</td></tr></table></code></pre> 14304</div> 14305</div> 14306</div> 14307<div class="sect3"> 14308<h4 id="_advanced_example_using_spring_beans_and_jpa">10.3.3. Advanced example using Spring beans and JPA</h4> 14309<div class="paragraph"> 14310<p>A more advanced example, <code>JPASpringTest</code>, can be found in <code>activiti-spring-examples</code>. It describes the following simple use case:</p> 14311</div> 14312<div class="ulist"> 14313<ul> 14314<li> 14315<p>An existing Spring-bean which uses JPA entities already exists which allows for Loan Requests to be stored.</p> 14316</li> 14317<li> 14318<p>Using Activiti, we can use the existing entities, obtained through the existing bean, and use them as variable in our process. Process is defined in the following steps:</p> 14319<div class="ulist"> 14320<ul> 14321<li> 14322<p>Service task that creates a new LoanRequest, using the existing <code>LoanRequestBean</code> using variables received when starting the process (e.g. could come from a start form). The created entity is stored as a variable, using <code>activiti:resultVariable</code> which stores the expression result as a variable.</p> 14323</li> 14324<li> 14325<p>UserTask that allows a manager to review the request and approve/disapprove, which is stored as a boolean variable <code>approvedByManager</code></p> 14326</li> 14327<li> 14328<p>ServiceTask that updates the loan request entity so the entity is in sync with the process.</p> 14329</li> 14330<li> 14331<p>Depending on the value of the entity property <code>approved</code>, an exclusive gateway is used to make a decision about what path to take next: When the request is approved, process ends, otherwise, an extra task will become available (Send rejection letter), so the customer can be notified manually by a rejection letter.</p> 14332</li> 14333</ul> 14334</div> 14335</li> 14336</ul> 14337</div> 14338<div class="paragraph"> 14339<p>Please note that the process doesn’t contain any forms, since it is only used in a unit test.</p> 14340</div> 14341<div class="imageblock" style="text-align: center"> 14342<div class="content"> 14343<img src="images/jpa.spring.example.process.png" alt="jpa.spring.example.process"> 14344</div> 14345</div> 14346<div class="listingblock"> 14347<div class="content"> 14348<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 14349 2 14350 3 14351 4 14352 5 14353 6 14354 7 14355 8 14356 9 1435710 1435811 1435912 1436013 1436114 1436215 1436316 1436417 1436518 1436619 1436720 1436821 1436922 1437023 1437124 1437225 1437326 1437427 1437528 1437629 1437730 1437831 1437932 1438033 1438134 1438235 1438336 1438437 1438538 1438639</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="UTF-8"?></span> 14387<span class="tok-nt"><definitions</span> <span class="tok-na">id=</span><span class="tok-s">"taskAssigneeExample"</span> 14388 <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.omg.org/spec/BPMN/20100524/MODEL"</span> 14389 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 14390 <span class="tok-na">xmlns:activiti=</span><span class="tok-s">"http://activiti.org/bpmn"</span> 14391 <span class="tok-na">targetNamespace=</span><span class="tok-s">"org.activiti.examples"</span><span class="tok-nt">></span> 14392 14393 <span class="tok-nt"><process</span> <span class="tok-na">id=</span><span class="tok-s">"LoanRequestProcess"</span> <span class="tok-na">name=</span><span class="tok-s">"Process creating and handling loan request"</span><span class="tok-nt">></span> 14394 <span class="tok-nt"><startEvent</span> <span class="tok-na">id=</span><span class="tok-s">'theStart'</span> <span class="tok-nt">/></span> 14395 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">'flow1'</span> <span class="tok-na">sourceRef=</span><span class="tok-s">'theStart'</span> <span class="tok-na">targetRef=</span><span class="tok-s">'createLoanRequest'</span> <span class="tok-nt">/></span> 14396 14397 <span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">'createLoanRequest'</span> <span class="tok-na">name=</span><span class="tok-s">'Create loan request'</span>
14398 <span class="tok-na">activiti:expression=</span><span class="tok-s">"${loanRequestBean.newLoanRequest(customerName, amount)}"</span> 14399 <span class="tok-na">activiti:resultVariable=</span><span class="tok-s">"loanRequest"</span><span class="tok-nt">/></span> 14400 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">'flow2'</span> <span class="tok-na">sourceRef=</span><span class="tok-s">'createLoanRequest'</span> <span class="tok-na">targetRef=</span><span class="tok-s">'approveTask'</span> <span class="tok-nt">/></span> 14401 14402 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"approveTask"</span> <span class="tok-na">name=</span><span class="tok-s">"Approve request"</span> <span class="tok-nt">/></span> 14403 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">'flow3'</span> <span class="tok-na">sourceRef=</span><span class="tok-s">'approveTask'</span> <span class="tok-na">targetRef=</span><span class="tok-s">'approveOrDissaprove'</span> <span class="tok-nt">/></span> 14404 14405 <span class="tok-nt"><serviceTask</span> <span class="tok-na">id=</span><span class="tok-s">'approveOrDissaprove'</span> <span class="tok-na">name=</span><span class="tok-s">'Store decision'</span> 14406 <span class="tok-na">activiti:expression=</span><span class="tok-s">"${loanRequest.setApproved(approvedByManager)}"</span> <span class="tok-nt">/></span> 14407 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">'flow4'</span> <span class="tok-na">sourceRef=</span><span class="tok-s">'approveOrDissaprove'</span> <span class="tok-na">targetRef=</span><span class="tok-s">'exclusiveGw'</span> <span class="tok-nt">/></span> 14408 14409 <span class="tok-nt"><exclusiveGateway</span> <span class="tok-na">id=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">name=</span><span class="tok-s">"Exclusive Gateway approval"</span> <span class="tok-nt">/></span> 14410 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"endFlow1"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"theEnd"</span><span class="tok-nt">></span> 14411 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${loanRequest.approved}<span class="tok-nt"></conditionExpression></span> 14412 <span class="tok-nt"></sequenceFlow></span> 14413 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">"endFlow2"</span> <span class="tok-na">sourceRef=</span><span class="tok-s">"exclusiveGw"</span> <span class="tok-na">targetRef=</span><span class="tok-s">"sendRejectionLetter"</span><span class="tok-nt">></span> 14414 <span class="tok-nt"><conditionExpression</span> <span class="tok-na">xsi:type=</span><span class="tok-s">"tFormalExpression"</span><span class="tok-nt">></span>${!loanRequest.approved}<span class="tok-nt"></conditionExpression></span> 14415 <span class="tok-nt"></sequenceFlow></span> 14416 14417 <span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"sendRejectionLetter"</span> <span class="tok-na">name=</span><span class="tok-s">"Send rejection letter"</span> <span class="tok-nt">/></span> 14418 <span class="tok-nt"><sequenceFlow</span> <span class="tok-na">id=</span><span class="tok-s">'flow5'</span> <span class="tok-na">sourceRef=</span><span class="tok-s">'sendRejectionLetter'</span> <span class="tok-na">targetRef=</span><span class="tok-s">'theOtherEnd'</span> <span class="tok-nt">/></span> 14419 14420 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">'theEnd'</span> <span class="tok-nt">/></span> 14421 <span class="tok-nt"><endEvent</span> <span class="tok-na">id=</span><span class="tok-s">'theOtherEnd'</span> <span class="tok-nt">/></span> 14422 <span class="tok-nt"></process></span> 14423 14424<span class="tok-nt"></definitions></span> 14425</td></tr></table></code></pre> 14426</div> 14427</div> 14428<div class="paragraph"> 14429<p>Although the example above is quite simple, it shows the power of using JPA combined with Spring and parametrized method-expressions. The process requires no custom java-code at all (except for the Spring-bean off course) and speeds up development drastically.</p> 14430</div> 14431</div> 14432</div> 14433</div> 14434</div> 14435<div class="sect1"> 14436<h2 id="history">11. History</h2> 14437<div class="sectionbody"> 14438<div class="paragraph"> 14439<p>History is the component that captures what happened during process execution and stores it permanently. In contrast to the runtime data, the history data will remain present in the DB also after process instances have completed.</p> 14440</div> 14441<div class="paragraph"> 14442<p>There are 5 history entities:</p> 14443</div> 14444<div class="ulist"> 14445<ul> 14446<li> 14447<p><code>HistoricProcessInstance</code>s containing information about current and past process instances.</p> 14448</li> 14449<li> 14450<p><code>HistoricVariableInstance</code>s containing the latest value of a process variable or task variable.</p> 14451</li> 14452<li> 14453<p><code>HistoricActivityInstance</code>s containing information about a single execution of an activity (node in the process).</p> 14454</li> 14455<li> 14456<p><code>HistoricTaskInstance</code>s containing information about current and past (completed and deleted) task instances.</p> 14457</li> 14458<li> 14459<p><code>HistoricDetail</code>s containing various kinds of information related to either a historic process instances, an activity instance or a task instance.</p> 14460</li> 14461</ul> 14462</div> 14463<div class="paragraph"> 14464<p>Since the DB contains historic entities for past as well as ongoing instances, you might want to consider querying these tables in order to minimize access to the runtime process instance data and that way keeping the runtime execution performant.</p> 14465</div> 14466<div class="paragraph"> 14467<p>Later on, this information will be exposed in Activiti Explorer. Also, it will be the information from which the reports will be generated.</p> 14468</div> 14469<div class="sect2"> 14470<h3 id="historyQuery">11.1. Querying history</h3> 14471<div class="paragraph"> 14472<p>In the API, it’s possible to query all 5 of the History entities. The HistoryService exposes the methods <code>createHistoricProcessInstanceQuery()</code>, <code>createHistoricVariableInstanceQuery()</code>, <code>createHistoricActivityInstanceQuery()</code>, <code>createHistoricDetailQuery()</code> and <code>createHistoricTaskInstanceQuery()</code>.</p> 14473</div> 14474<div class="paragraph"> 14475<p>Below are a couple of examples that show some of the possibilities of the query API for history. Full description of the possibilities can be found in the <a href="http://activiti.org/javadocs/index.html">javadocs</a>, in the <code>org.activiti.engine.history</code> package.</p> 14476</div> 14477<div class="sect3"> 14478<h4 id="historyQueryProcessInstance">11.1.1. HistoricProcessInstanceQuery</h4> 14479<div class="paragraph"> 14480<p>Get 10 <code>HistoricProcessInstances</code> that are finished and which took the most time to complete (the longest duration) of all finished processes with definition <em>XXX</em>.</p> 14481</div> 14482<div class="listingblock"> 14483<div class="content"> 14484<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 144852 144863 144874 144885</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricProcessInstanceQuery</span><span class="tok-o">()</span> 14489 <span class="tok-o">.</span><span class="tok-na">finished</span><span class="tok-o">()</span> 14490 <span class="tok-o">.</span><span class="tok-na">processDefinitionId</span><span class="tok-o">(</span><span class="tok-s">"XXX"</span><span class="tok-o">)</span> 14491 <span class="tok-o">.</span><span class="tok-na">orderByProcessInstanceDuration</span><span class="tok-o">().</span><span class="tok-na">desc</span><span class="tok-o">()</span> 14492 <span class="tok-o">.</span><span class="tok-na">listPage</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-mi">10</span><span class="tok-o">);</span> 14493</td></tr></table></code></pre> 14494</div> 14495</div> 14496</div> 14497<div class="sect3"> 14498<h4 id="historyQueryVariableInstance">11.1.2. HistoricVariableInstanceQuery</h4> 14499<div class="paragraph"> 14500<p>Get all <code>HistoricVariableInstances</code>
14500 from a finished process instance with id <em>xxx</em> ordered by variable name.</p> 14501</div> 14502<div class="listingblock"> 14503<div class="content"> 14504<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 145052 145063 145074</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricVariableInstanceQuery</span><span class="tok-o">()</span> 14508 <span class="tok-o">.</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-s">"XXX"</span><span class="tok-o">)</span> 14509 <span class="tok-o">.</span><span class="tok-na">orderByVariableName</span><span class="tok-o">.</span><span class="tok-na">desc</span><span class="tok-o">()</span> 14510 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 14511</td></tr></table></code></pre> 14512</div> 14513</div> 14514</div> 14515<div class="sect3"> 14516<h4 id="historyQueryActivityInstance">11.1.3. HistoricActivityInstanceQuery</h4> 14517<div class="paragraph"> 14518<p>Get the last <code>HistoricActivityInstance</code> of type <em>serviceTask</em> that has been finished in any process that uses the processDefinition with id XXX.</p> 14519</div> 14520<div class="listingblock"> 14521<div class="content"> 14522<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 145232 145243 145254 145265 145276</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricActivityInstanceQuery</span><span class="tok-o">()</span> 14528 <span class="tok-o">.</span><span class="tok-na">activityType</span><span class="tok-o">(</span><span class="tok-s">"serviceTask"</span><span class="tok-o">)</span> 14529 <span class="tok-o">.</span><span class="tok-na">processDefinitionId</span><span class="tok-o">(</span><span class="tok-s">"XXX"</span><span class="tok-o">)</span> 14530 <span class="tok-o">.</span><span class="tok-na">finished</span><span class="tok-o">()</span> 14531 <span class="tok-o">.</span><span class="tok-na">orderByHistoricActivityInstanceEndTime</span><span class="tok-o">().</span><span class="tok-na">desc</span><span class="tok-o">()</span> 14532 <span class="tok-o">.</span><span class="tok-na">listPage</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-mi">1</span><span class="tok-o">);</span> 14533</td></tr></table></code></pre> 14534</div> 14535</div> 14536</div> 14537<div class="sect3"> 14538<h4 id="historyQueryDetail">11.1.4. HistoricDetailQuery</h4> 14539<div class="paragraph"> 14540<p>The next example, gets all variable-updates that have been done in process with id 123. Only <code>HistoricVariableUpdate</code>s will be returned by this query. Note that it’s possible that a certain variable name has multiple <code>HistoricVariableUpdate</code> entries, for each time the variable was updated in the process. You can use <code>orderByTime</code> (the time the variable update was done) or <code>orderByVariableRevision</code> (revision of runtime variable at the time of updating) to find out in what order they occurred.</p> 14541</div> 14542<div class="listingblock"> 14543<div class="content"> 14544<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 145452 145463 145474 145485</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricDetailQuery</span><span class="tok-o">()</span> 14549 <span class="tok-o">.</span><span class="tok-na">variableUpdates</span><span class="tok-o">()</span> 14550 <span class="tok-o">.</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-s">"123"</span><span class="tok-o">)</span> 14551 <span class="tok-o">.</span><span class="tok-na">orderByVariableName</span><span class="tok-o">().</span><span class="tok-na">asc</span><span class="tok-o">()</span> 14552 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">()</span> 14553</td></tr></table></code></pre> 14554</div> 14555</div> 14556<div class="paragraph"> 14557<p>This example gets all <a href="#formProperties">form-properties</a> that were submitted in any task or when starting the process with id "123". Only <code>HistoricFormProperties</code>s will be returned by this query.</p> 14558</div> 14559<div class="listingblock"> 14560<div class="content"> 14561<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 145622 145633 145644 145655</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricDetailQuery</span><span class="tok-o">()</span> 14566 <span class="tok-o">.</span><span class="tok-na">formProperties</span><span class="tok-o">()</span> 14567 <span class="tok-o">.</span><span class="tok-na">processInstanceId</span><span class="tok-o">(</span><span class="tok-s">"123"</span><span class="tok-o">)</span> 14568 <span class="tok-o">.</span><span class="tok-na">orderByVariableName</span><span class="tok-o">().</span><span class="tok-na">asc</span><span class="tok-o">()</span> 14569 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">()</span> 14570</td></tr></table></code></pre> 14571</div> 14572</div> 14573<div class="paragraph"> 14574<p>The last example gets all variable updates that were performed on the task with id "123". This returns all <code>HistoricVariableUpdates</code> for variables that were set on the task (task local variables), and NOT on the process instance.</p> 14575</div> 14576<div class="listingblock"> 14577<div class="content"> 14578<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 145792 145803 145814 145825</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricDetailQuery</span><span class="tok-o">()</span> 14583 <span class="tok-o">.</span><span class="tok-na">variableUpdates</span><span class="tok-o">()</span> 14584 <span class="tok-o">.</span><span class="tok-na">taskId</span><span class="tok-o">(</span><span class="tok-s">"123"</span><span class="tok-o">)</span> 14585 <span class="tok-o">.</span><span class="tok-na">orderByVariableName</span><span class="tok-o">().</span><span class="tok-na">asc</span><span class="tok-o">()</span> 14586 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">()</span> 14587</td></tr></table></code></pre> 14588</div> 14589</div> 14590<div class="paragraph"> 14591<p>Task local variables can be set using the <code>TaskService</code> or on a <code>DelegateTask</code>, inside <code>TaskListener</code>:</p> 14592</div> 14593<div class="listingblock"> 14594<div class="content"> 14595<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">setVariableLocal</span><span class="tok-o">(</span><span class="tok-s">"123"</span><span class="tok-o">,</span> <span class="tok-s">"myVariable"</span><span class="tok-o">,</span> <span class="tok-s">"Variable value"</span><span class="tok-o">);</span> 14596</td></tr></table></code></pre> 14597</div> 14598</div> 14599<div class="listingblock"> 14600<div class="content"> 14601<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 146022 146033</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">notify</span><span class="tok-o">(</span><span class="tok-n">DelegateTask</span> <span class="tok-n">delegateTask</span><span class="tok-o">)</span> <span class="tok-o">{</span> 14604 <span class="tok-n">delegateTask</span><span class="tok-o">.</span><span class="tok-na">setVariableLocal</span><span class="tok-o">(</span><span class="tok-s">"myVariable"</span><span class="tok-o">,</span> <span class="tok-s">"Variable value"</span><span class="tok-o">);</span> 14605<span class="tok-o">}</span> 14606</td></tr></table></code></pre> 14607</div> 14608</div> 14609</div> 14610<div class="sect3"> 14611<h4 id="historyQueryTaskInstance">11.1.5. HistoricTaskInstanceQuery</h4> 14612<div class="paragraph"> 14613<p>Get 10 <code>HistoricTaskInstance</code>s that are finished and which took the most time to complete (the longest duration) of all tasks.</p> 14614</div> 14615<div class="listingblock"> 14616<div class="content"> 14617<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 146182 146193 146204</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricTaskInstanceQuery</span><span class="tok-o">()</span> 14621 <span class="tok-o">.</span><span class="tok-na">finished</span><span class="tok-o">()</span> 14622 <span class="tok-o">.</span><span class="tok-na">orderByHistoricTaskInstanceDuration</span><span class="tok-o">().</span><span class="tok-na">desc</span><span class="tok-o">()</span> 14623 <span class="tok-o">.</span><span class="tok-na">listPage</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-mi">10</span><span class="tok-o">);</span> 14624</td></tr></table></code></pre> 14625</div> 14626</div> 14627<div class="paragraph"> 14628<p>Get <code>HistoricTaskInstance</code>
14628s that are deleted with a delete reason that contains "invalid", which were last assigned to user <em>kermit</em>.</p> 14629</div> 14630<div class="listingblock"> 14631<div class="content"> 14632<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 146332 146343 146354 146365</div></td><td class="code"><span></span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricTaskInstanceQuery</span><span class="tok-o">()</span> 14637 <span class="tok-o">.</span><span class="tok-na">finished</span><span class="tok-o">()</span> 14638 <span class="tok-o">.</span><span class="tok-na">taskDeleteReasonLike</span><span class="tok-o">(</span><span class="tok-s">"%invalid%"</span><span class="tok-o">)</span> 14639 <span class="tok-o">.</span><span class="tok-na">taskAssignee</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">)</span> 14640 <span class="tok-o">.</span><span class="tok-na">listPage</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-mi">10</span><span class="tok-o">);</span> 14641</td></tr></table></code></pre> 14642</div> 14643</div> 14644</div> 14645</div> 14646<div class="sect2"> 14647<h3 id="historyConfig">11.2. History configuration</h3> 14648<div class="paragraph"> 14649<p>The history level can be configured programmatically, using the enum org.activiti.engine.impl.history.HistoryLevel (or <em>HISTORY</em> constants defined on <code>ProcessEngineConfiguration</code> for versions prior to 5.11):</p> 14650</div> 14651<div class="listingblock"> 14652<div class="content"> 14653<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 146542 146553 146564</div></td><td class="code"><span></span><span class="tok-n">ProcessEngine</span> <span class="tok-n">processEngine</span> <span class="tok-o">=</span> <span class="tok-n">ProcessEngineConfiguration</span> 14657 <span class="tok-o">.</span><span class="tok-na">createProcessEngineConfigurationFromResourceDefault</span><span class="tok-o">()</span> 14658 <span class="tok-o">.</span><span class="tok-na">setHistory</span><span class="tok-o">(</span><span class="tok-n">HistoryLevel</span><span class="tok-o">.</span><span class="tok-na">AUDIT</span><span class="tok-o">.</span><span class="tok-na">getKey</span><span class="tok-o">())</span> 14659 <span class="tok-o">.</span><span class="tok-na">buildProcessEngine</span><span class="tok-o">();</span> 14660</td></tr></table></code></pre> 14661</div> 14662</div> 14663<div class="paragraph"> 14664<p>
14664The level can also be configured in activiti.cfg.xml or in a spring-context:</p> 14665</div> 14666<div class="listingblock"> 14667<div class="content"> 14668<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 146692 146703 146714</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration"</span><span class="tok-nt">></span> 14672 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"history"</span> <span class="tok-na">value=</span><span class="tok-s">"audit"</span> <span class="tok-nt">/></span> 14673 ... 14674<span class="tok-nt"></bean></span> 14675</td></tr></table></code></pre> 14676</div> 14677</div> 14678<div class="paragraph"> 14679<p>Following history levels can be configured:</p> 14680</div> 14681<div class="ulist"> 14682<ul> 14683<li> 14684<p><code>none</code>: skips all history archiving. This is the most performant for runtime process execution, but no historical information will be available.</p> 14685</li> 14686<li> 14687<p><code>activity</code>: archives all process instances and activity instances. At the end of the process instance, the latest values of the top level process instance variables will be copied to historic variable instances. No details will be archived.</p> 14688</li> 14689<li> 14690<p><code>audit</code>: This is the default. It archives all process instances, activity instances, keeps variable values continuously in sync and all form properties that are submitted so that all user interaction through forms is traceable and can be audited.</p> 14691</li> 14692<li> 14693<p><code>full</code>: This is the highest level of history archiving and hence the slowest. This level stores all information as in the <code>audit</code> level plus all other possible details, mostly this are process variable updates.</p> 14694</li> 14695</ul> 14696</div> 14697<div class="paragraph"> 14698<p><strong>Prior to Activiti 5.11, the history level was stored in the database (table <code>ACT_GE_PROPERTY</code>, property with name <code>historyLevel</code>). Starting from 5.11, this value is not used anymore and is ignored/deleted from the database. The history can now be changed between 2 boots of the engine, without an exception being thrown in case the level changed from the previous engine-boot.</strong></p> 14699</div> 14700</div> 14701<div class="sect2"> 14702<h3 id="historyFormAuditPurposes">11.3. History for audit purposes</h3> 14703<div class="paragraph"> 14704<p>When <a href="#historyConfig">configuring</a> at least <code>audit</code> level for configuration. Then all properties submitted through methods <code>FormService.submitStartFormData(String processDefinitionId, Map<String, String> properties)</code> and <code>FormService.submitTaskFormData(String taskId, Map<String, String> properties)</code> are recorded.</p> 14705</div> 14706<div class="paragraph"> 14707<p>Form properties can be retrieved with the query API like this:</p> 14708</div> 14709<div class="listingblock"> 14710<div class="content"> 14711<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 147122 147133 147144 147155</div></td><td class="code"><span></span><span class="tok-n">historyService</span> 14716 <span class="tok-o">.</span><span class="tok-na">createHistoricDetailQuery</span><span class="tok-o">()</span> 14717 <span class="tok-o">.</span><span class="tok-na">formProperties</span><span class="tok-o">()</span> 14718 <span class="tok-o">...</span> 14719 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 14720</td></tr></table></code></pre> 14721</div> 14722</div> 14723<div class="paragraph"> 14724<p>In that case only historic details of type <code>HistoricFormProperty</code> are returned.</p> 14725</div> 14726<div class="paragraph"> 14727<p>If you’ve set the authenticated user before calling the submit methods with <code>IdentityService.setAuthenticatedUserId(String)</code> then that authenticated user who submitted the form will be accessible in the history as well with <code>HistoricProcessInstance.getStartUserId()</code> for start forms and <code>HistoricActivityInstance.getAssignee()</code> for task forms.</p> 14728</div> 14729</div> 14730</div> 14731</div> 14732<div class="sect1"> 14733<h2 id="activitiDesigner">12. Eclipse Designer</h2> 14734<div class="sectionbody"> 14735<div class="paragraph"> 14736<p>Activiti comes with an Eclipse plugin, the Activiti Eclipse Designer, that can be used to graphically model, test and deploy BPMN 2.0 processes.</p> 14737</div> 14738<div class="sect2"> 14739<h3 id="eclipseDesignerInstallation">12.1. Installation</h3> 14740<div class="paragraph"> 14741<p>The following installation instructions are verified on <a href="http://www.eclipse.org/downloads/">Eclipse Kepler and Indigo</a>. Note that Eclipse Helios is <strong>NOT</strong> supported.</p> 14742</div> 14743<div class="paragraph"> 14744<p>Go to <strong>Help → Install New Software</strong>. In the following panel, click on <em>Add</em> button and fill in the following fields:</p> 14745</div> 14746<div class="ulist"> 14747<ul> 14748<li> 14749<p>*Name:*Activiti BPMN 2.0 designer</p> 14750</li> 14751<li> 14752<p>*Location:*http://activiti.org/designer/update/</p> 14753</li> 14754</ul> 14755</div> 14756<div class="imageblock" style="text-align: center"> 14757<div class="content"> 14758<img src="images/designer.add.update.site.png" alt="designer.add.update.site"> 14759</div> 14760</div> 14761<div class="paragraph"> 14762<p>Make sure the <strong>"Contact all updates sites.."</strong> checkbox is <strong>checked</strong>, because all the necessary plugins will then be downloaded by Eclipse.</p> 14763</div> 14764</div> 14765<div class="sect2"> 14766<h3 id="eclipseDesignerEditorFeatures">12.2. Activiti Designer editor features</h3> 14767<div class="ulist"> 14768<ul> 14769<li> 14770<p>Create Activiti projects and diagrams.</p> 14771</li> 14772</ul> 14773</div> 14774<div class="imageblock" style="text-align: center"> 14775<div class="content"> 14776<img src="images/designer.create.activiti.project.png" alt="designer.create.activiti.project"> 14777</div> 14778</div> 14779<div class="ulist"> 14780<ul> 14781<li> 14782<p>The Activiti Designer creates a .bpmn file when creating a new Activiti diagram. When opened with the Activiti Diagram Editor view this will provide a graphical modeling canvas and palette. The same file can however be opened with an XML editor and it then shows the BPMN 2.0 XML elements of the process definition. So the Activiti Designer works with only one file for both the graphical diagram as well as the BPMN 2.0 XML. Note that in Activiti 5.9 the .bpmn extension is not yet supported as deployment artifact for a process definition. Therefore the "create deployment artifacts" feature of the Activiti Designer generates a BAR file with a .bpmn20.xml file that contains the content of the .bpmn file. You can also do a quick file rename yourself. Also note that you can open a .bpmn20.xml file with the Activiti Diagram Editor view as well.</p> 14783</li> 14784</ul> 14785</div> 14786<div class="imageblock" style="text-align: center"> 14787<div class="content"> 14788<img src="images/designer.bpmn.file.png" alt="designer.bpmn.file"> 14789</div> 14790</div> 14791<div class="ulist"> 14792<ul> 14793<li> 14794<p>BPMN 2.0 XML files can be imported into the Activiti Designer and a diagram will be created. Just copy the BPMN 2.0 XML file to your project and open the file with the Activiti Diagram Editor view. The Activiti Designer uses the BPMN DI information of the file to create the diagram. If you have a BPMN 2.0 XML file without BPMN DI information, no diagram can be created.</p> 14795</li> 14796</ul> 14797</div> 14798<div class="imageblock" style="text-align: center"> 14799<div class="content"> 14800<img src="images/designer.open.importedfile.png" alt="designer.open.importedfile"> 14801</div> 14802</div> 14803<div class="ulist"> 14804<ul> 14805<li> 14806<p>For deployment a BAR file and optionally a JAR file is created by the Activiti Designer by right-clicking on an Activiti project in the package explorer and choosing the <em>Create deployment artifacts</em> option at the bottom of the popup menu. For more information about the deployment functionality of the Designer look at the <a href="#eclipseDesignerDeployment">deployment</a> section.</p> 14807</li> 14808</ul> 14809</div> 14810<div class="imageblock" style="text-align: center"> 14811<div class="content"> 14812<img src="images/designer.create.deployment.png" alt="designer.create.deployment"> 14813</div> 14814</div> 14815<div class="ulist"> 14816<ul> 14817<li> 14818<p>Generate a unit test (right click on a BPMN 2.0 XML file in the package explorer and select <em>generate unit test</em>
14818) A unit test is generated with an Activiti configuration that runs on an embedded H2 database. You can now run the unit test to test your process definition.</p> 14819</li> 14820</ul> 14821</div> 14822<div class="imageblock" style="text-align: center"> 14823<div class="content"> 14824<img src="images/designer.unittest.generate.png" alt="designer.unittest.generate"> 14825</div> 14826</div> 14827<div class="ulist"> 14828<ul> 14829<li> 14830<p>The Activiti project is generated as a Maven project. To configure the dependencies you need to run <em>mvn eclipse:eclipse</em> and the Maven dependencies will be configured as expected. Note that for process design Maven dependencies are not needed. They are only needed to run unit tests.</p> 14831</li> 14832</ul> 14833</div> 14834<div class="imageblock" style="text-align: center"> 14835<div class="content"> 14836<img src="images/designer.project.maven.png" alt="designer.project.maven"> 14837</div> 14838</div> 14839</div> 14840<div class="sect2"> 14841<h3 id="eclipseDesignerBPMNFeatures">12.3. Activiti Designer BPMN features</h3> 14842<div class="ulist"> 14843<ul> 14844<li> 14845<p>Support for start none event, start error event, timer start event, end none event, end error event, sequence flow, parallel gateway, exclusive gateway, inclusive gateway, event gateway, embedded subprocess, event sub process, call activity, pool, lane, script task, user task, service task, mail task, manual task, business rule task, receive task, timer boundary event, error boundary event, signal boundary event, timer catching event, signal catching event, signal throwing event, none throwing event and four Alfresco specific elements (user, script, mail tasks and start event).</p> 14846</li> 14847</ul> 14848</div> 14849<div class="imageblock" style="text-align: center"> 14850<div class="content"> 14851<img src="images/designer.model.process.png" alt="designer.model.process"> 14852</div> 14853</div> 14854<div class="ulist"> 14855<ul> 14856<li> 14857<p>You can quickly change the type of a task by hovering over the element and choosing the new task type.</p> 14858</li> 14859</ul> 14860</div> 14861<div class="imageblock" style="text-align: center"> 14862<div class="content"> 14863<img src="images/designer.model.quick.change.png" alt="designer.model.quick.change"> 14864</div> 14865</div> 14866<div class="ulist"> 14867<ul> 14868<li> 14869<p>You can quickly add new elements hovering over an element and choosing a new element type.</p> 14870</li> 14871</ul> 14872</div> 14873<div class="imageblock" style="text-align: center"> 14874<div class="content"> 14875<img src="images/designer.model.quick.new.png" alt="designer.model.quick.new"> 14876</div> 14877</div> 14878<div class="ulist"> 14879<ul> 14880<li> 14881<p>Java class, expression or delegate expression configuration is supported for the Java service task. In addition field extensions can be configured.</p> 14882</li> 14883</ul> 14884</div> 14885<div class="imageblock" style="text-align: center"> 14886<div class="content"> 14887<img src="images/designer.servicetask.property.png" alt="designer.servicetask.property"> 14888</div> 14889</div> 14890<div class="ulist"> 14891<ul> 14892<li> 14893<p>Support for pools and lanes. Because Activiti reads different pools as different process definition, it makes the most sense to use only one pool. If you use multiple pools, be aware that drawing sequence flows between the pools will result in problems when deploying the process in the Activiti Engine. You can add as much lanes to a pool as you want.</p> 14894</li> 14895</ul> 14896</div> 14897<div class="imageblock" style="text-align: center"> 14898<div class="content"> 14899<img src="images/designer.model.poolandlanes.png" alt="designer.model.poolandlanes"> 14900</div> 14901</div> 14902<div class="ulist"> 14903<ul> 14904<li> 14905<p>You can add labels to sequence flows by filling the name property. You can position the labels yourself as the position is saved as part of the BPMN 2.0 XML DI information.</p> 14906</li> 14907</ul> 14908</div> 14909<div class="imageblock" style="text-align: center"> 14910<div class="content"> 14911<img src="images/designer.model.labels.png" alt="designer.model.labels"> 14912</div> 14913</div> 14914<div class="ulist"> 14915<ul> 14916<li> 14917<p>Support for event sub processes.</p> 14918</li> 14919</ul> 14920</div> 14921<div class="imageblock" style="text-align: center"> 14922<div class="content"> 14923<img src="images/designer.model.eventsubprocess.png" alt="designer.model.eventsubprocess"> 14924</div> 14925</div> 14926<div class="ulist"> 14927<ul> 14928<li> 14929<p>Support for expanded embedded sub processes. You can also add an embedded sub process in another embedded sub process.</p> 14930</li> 14931</ul> 14932</div> 14933<div class="imageblock" style="text-align: center"> 14934<div class="content"> 14935<img src="images/designer.embeddedprocess.canvas.png" alt="designer.embeddedprocess.canvas"> 14936</div> 14937</div> 14938<div class="ulist"> 14939<ul> 14940<li> 14941<p>Support for timer boundary events on tasks and embedded sub processes. Although, the timer boundary event makes the most sense when using it on a user task or an embedded sub process in the Activiti Designer.</p> 14942</li> 14943</ul> 14944</div> 14945<div class="imageblock" style="text-align: center"> 14946<div class="content"> 14947<img src="images/designer.timerboundary.canvas.png" alt="designer.timerboundary.canvas"> 14948</div> 14949</div> 14950<div class="ulist"> 14951<ul> 14952<li> 14953<p>Support for additional Activiti extensions like the Mail task, the candidate configuration of User tasks and
14953Script task configuration.</p> 14954</li> 14955</ul> 14956</div> 14957<div class="imageblock" style="text-align: center"> 14958<div class="content"> 14959<img src="images/designer.mailtask.property.png" alt="designer.mailtask.property"> 14960</div> 14961</div> 14962<div class="ulist"> 14963<ul> 14964<li> 14965<p>Support for the Activiti execution and task listeners. You can also add field extensions for execution listeners.</p> 14966</li> 14967</ul> 14968</div> 14969<div class="imageblock" style="text-align: center"> 14970<div class="content"> 14971<img src="images/designer.listener.configuration.png" alt="designer.listener.configuration"> 14972</div> 14973</div> 14974<div class="ulist"> 14975<ul> 14976<li> 14977<p>Support for conditions on sequence flows.</p> 14978</li> 14979</ul> 14980</div> 14981<div class="imageblock" style="text-align: center"> 14982<div class="content"> 14983<img src="images/designer.sequence.condition.png" alt="designer.sequence.condition"> 14984</div> 14985</div> 14986</div> 14987<div class="sect2"> 14988<h3 id="eclipseDesignerDeployment">12.4. Activiti Designer deployment features</h3> 14989<div class="paragraph"> 14990<p>Deploying process definitions and task forms on the Activiti Engine is not hard. You need a BAR file containing the process definition BPMN 2.0 XML file and optionally task forms and an image of the process that can be viewed in the Activiti Explorer. In the Activiti Designer it’s made very easy to create a BAR file. When you’ve finished your process implementation just right-click on your Activiti project in the package explorer and choose for the <strong>Create deployment artifacts</strong> option at the bottom of the popup menu.</p> 14991</div> 14992<div class="imageblock" style="text-align: center"> 14993<div class="content"> 14994<img src="images/designer.create.deployment.png" alt="designer.create.deployment"> 14995</div> 14996</div> 14997<div class="paragraph"> 14998<p>Then a deployment directory is created containing the BAR file and optionally a JAR file with the Java classes of your Activiti project.</p> 14999</div> 15000<div class="imageblock" style="text-align: center"> 15001<div class="content"> 15002<img src="images/designer.deployment.dir.png" alt="designer.deployment.dir"> 15003</div> 15004</div> 15005<div class="paragraph"> 15006<p>This file can now be uploaded to the Activiti Engine using the deployments tab in Activiti Explorer, and you are ready to go.</p> 15007</div> 15008<div class="paragraph"> 15009<p>When your project contains Java classes, the deployment is a bit more work. In that case the <strong>Create deployment artifacts</strong> step in the Activiti Designer will also generate a JAR file containing the compiled classes. This JAR file must be deployed to the activiti-XXX/WEB-INF/lib directory in your Activiti Tomcat installation directory. This makes the classes available on the classpath of the Activiti Engine.</p> 15010</div> 15011</div> 15012<div class="sect2"> 15013<h3 id="eclipseDesignerExtending">12.5. Extending Activiti Designer</h3> 15014<div class="paragraph"> 15015<p>You can extend the default functionality offered by Activiti Designer. This section documents which extensions are available, how they can be used and provides some usage examples. Extending Activiti Designer is useful in cases where the default functionality doesn’t suit your needs, you require additional capabilities or have domain specific requirements when modeling business processes. Extension of Activiti Designer falls into two distinct categories, extending the palette and extending output formats. Each of these extension ways requires a specific approach and different technical expertise.</p> 15016</div> 15017<div class="admonitionblock note"> 15018<table> 15019<tr> 15020<td class="icon"> 15021<i class="fa icon-note" title="Note"></i> 15022</td> 15023<td class="content"> 15024<div class="paragraph"> 15025<p>Extending Activiti Designer requires technical knowledge and more specifically, knowledge of programming in Java. Depending on the type of extension you want to create, you might also need to be familiar with Maven, Eclipse, OSGi, Eclipse extensions and SWT.</p> 15026</div> 15027</td> 15028</tr> 15029</table> 15030</div> 15031<div class="sect3"> 15032<h4 id="eclipseDesignerCustomizingPalette">12.5.1. Customizing the palette</h4> 15033<div class="paragraph"> 15034<p>You can customize the palette that is offered to users when modeling processes. The palette is the collection of shapes that can be dragged onto the canvas in a process diagram and is displayed to the right hand side of the canvas. As you can see in the default palette, the default shapes are grouped into compartments (these are called "drawers") for Events, Gateways and so on. There are two options built-in to Activiti Designer to customize the drawers and shapes in the palette:</p> 15035</div> 15036<div class="ulist"> 15037<ul> 15038<li> 15039<p>Adding your own shapes / nodes to existing or new drawers</p> 15040</li> 15041<li> 15042<p>Disabling any or all of the default BPMN 2.0 shapes offered by Activiti Designer, with the exception of the connection and selection tools</p> 15043</li> 15044</ul> 15045</div> 15046<div class="paragraph"> 15047<p>In order to customize the palette, you create a JAR file that is added to a specific installation of Activiti Designer (more on <a href="#eclipseDesignerApplyingExtension">how to do that</a> later). Such a JAR file is called an <em>extension</em>. By writing classes that are included in your extension, Activiti Designer understands which customizations you wish to make. In order for this to work, your classes should implement certain interfaces. There is an integration library available with those interfaces and base classes to extend which you should add to your project’
15047s classpath.</p> 15048</div> 15049<div class="paragraph"> 15050<p>You can find the code examples listed below in source control with Activiti Designer. Take a look in the <code>examples/money-tasks</code> directory in the <code>projects/designer</code> directory of Activiti’s source code.</p> 15051</div> 15052<div class="admonitionblock note"> 15053<table> 15054<tr> 15055<td class="icon"> 15056<i class="fa icon-note" title="Note"></i> 15057</td> 15058<td class="content"> 15059<div class="paragraph"> 15060<p>You can setup your project in whichever tool you prefer and build the JAR with your build tool of choice. For the instructions below, a setup is assumed with Eclipse Kepler or Indigo, using Maven (3.x) as build tool, but any setup should enable you to create the same results.</p> 15061</div> 15062</td> 15063</tr> 15064</table> 15065</div> 15066<div class="sect4"> 15067<h5 id="_extension_setup_eclipse_maven">Extension setup (Eclipse/Maven)</h5> 15068<div class="paragraph"> 15069<p>Download and extract <a href="http://www.eclipse.org/downloads">Eclipse</a> (most recent versions should work) and a recent version (3.x) of <a href="http://maven.apache.org/download.html">Apache Maven</a>. If you use a 2.x version of Maven, you will run into problems when building your project, so make sure your version is up to date. We assume you are familiar with using basic features and the Java editor in Eclipse. It’s up to you whether you prefer to use Eclipse’s features for Maven or run Maven commands from a command prompt.</p> 15070</div> 15071<div class="paragraph"> 15072<p>Create a new project in Eclipse. This can be a general project type. Create a <code>pom.xml</code> file at the root of the project to contain the Maven project setup. Also create folders for the <code>src/main/java</code> and <code>src/main/resources</code> folders, which are Maven conventions for your Java source files and resources respectively. Open the <code>pom.xml</code> file and add the following lines:</p> 15073</div> 15074<div class="listingblock"> 15075<div class="content"> 15076<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 15077 2 15078 3 15079 4 15080 5 15081 6 15082 7 15083 8 15084 9 1508510 1508611 1508712 1508813 1508914</div></td><td class="code"><span></span><span class="tok-nt"><project</span> 15090 <span class="tok-na">xmlns=</span><span class="tok-s">"http://maven.apache.org/POM/4.0.0"</span> 15091 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 15092 <span class="tok-na">xsi:schemaLocation=</span><span class="tok-s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"</span><span class="tok-nt">></span> 15093 15094 <span class="tok-nt"><modelVersion></span>4.0.0<span class="tok-nt"></modelVersion></span> 15095 15096 <span class="tok-nt"><groupId></span>org.acme<span class="tok-nt"></groupId></span> 15097 <span class="tok-nt"><artifactId></span>money-tasks<span class="tok-nt"></artifactId></span> 15098 <span class="tok-nt"><version></span>1.0.0<span class="tok-nt"></version></span> 15099 <span class="tok-nt"><packaging></span>jar<span class="tok-nt"></packaging></span> 15100 <span class="tok-nt"><name></span>Acme Corporation Money Tasks<span class="tok-nt"></name></span> 15101... 15102<span class="tok-nt"></project></span> 15103</td></tr></table></code></pre> 15104</div> 15105</div> 15106<div class="paragraph"> 15107<p>As you can see, this is just a basic pom.xml file that defines a <code>groupId</code>, <code>artifactId</code> and <code>version</code> for the project. We will create a customization that includes a single custom node for our money business.</p> 15108</div> 15109<div class="paragraph"> 15110<p>Add the integration library to your project’s dependencies by including this dependency in your <code>pom.xml</code> file:</p> 15111</div> 15112<div class="listingblock"> 15113<div class="content"> 15114<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 15115 2 15116 3 15117 4 15118 5 15119 6 15120 7 15121 8 15122 9 1512310 1512411 1512512 1512613 1512714 1512815</div></td><td class="code"><span></span><span class="tok-nt"><dependencies></span> 15129 <span class="tok-nt"><dependency></span> 15130 <span class="tok-nt"><groupId></span>org.activiti.designer<span class="tok-nt"></groupId></span> 15131 <span class="tok-nt"><artifactId></span>org.activiti.designer.integration<span class="tok-nt"></artifactId></span> 15132 <span class="tok-nt"><version></span>5.12.0<span class="tok-nt"></version></span> <span class="tok-c"><!-- Use the current Activiti Designer version --></span> 15133 <span class="tok-nt"><scope></span>compile<span class="tok-nt"></scope></span> 15134 <span class="tok-nt"></dependency></span> 15135<span class="tok-nt"></dependencies></span> 15136... 15137<span class="tok-nt"><repositories></span> 15138 <span class="tok-nt"><repository></span>
15139 <span class="tok-nt"><id></span>Activiti<span class="tok-nt"></id></span> 15140 <span class="tok-nt"><url></span>https://maven.alfresco.com/nexus/content/groups/public/<span class="tok-nt"></url></span> 15141 <span class="tok-nt"></repository></span> 15142<span class="tok-nt"></repositories></span> 15143</td></tr></table></code></pre> 15144</div> 15145</div> 15146<div class="paragraph"> 15147<p>Finally, in the<code> pom.xml</code> file, add the configuration for the <code>maven-compiler-plugin</code> so the Java source level is at least 1.5 (see snippet below). You will need this in order to use annotations. You can also include instructions for Maven to generate the JAR’s <code>MANIFEST.MF</code> file. This is not required, but you can use a specific property in the manifest to provide a name for your extension (this name may be shown at certain places in the designer and is primarily intended for future use if you have several extensions in the designer). If you wish to do so, include the following snippet in <code>pom.xml</code>:</p> 15148</div> 15149<div class="listingblock"> 15150<div class="content"> 15151<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 15152 2 15153 3 15154 4 15155 5 15156 6 15157 7 15158 8 15159 9 1516010 1516111 1516212 1516313 1516414 1516515 1516616 1516717 1516818 1516919 1517020 1517121 1517222 1517323 1517424 1517525 1517626 1517727 1517828 1517929 1518030 1518131</div></td><td class="code"><span></span><span class="tok-nt"><build></span> 15182 <span class="tok-nt"><plugins></span> 15183 <span class="tok-nt"><plugin></span> 15184 <span class="tok-nt"><artifactId></span>maven-compiler-plugin<span class="tok-nt"></artifactId></span> 15185 <span class="tok-nt"><configuration></span> 15186 <span class="tok-nt"><source></span>1.5<span class="tok-nt"></source></span> 15187 <span class="tok-nt"><target></span>1.5<span class="tok-nt"></target></span> 15188 <span class="tok-nt"><showDeprecation></span>true<span class="tok-nt"></showDeprecation></span> 15189 <span class="tok-nt"><showWarnings></span>true<span class="tok-nt"></showWarnings></span> 15190 <span class="tok-nt"><optimize></span>true<span class="tok-nt"></optimize></span> 15191 <span class="tok-nt"></configuration></span> 15192 <span class="tok-nt"></plugin></span> 15193 <span class="tok-nt"><plugin></span> 15194 <span class="tok-nt"><groupId></span>org.apache.maven.plugins<span class="tok-nt"></groupId></span> 15195 <span class="tok-nt"><artifactId></span>maven-jar-plugin<span class="tok-nt"></artifactId></span> 15196 <span class="tok-nt"><version></span>2.3.1<span class="tok-nt"></version></span> 15197 <span class="tok-nt"><configuration></span> 15198 <span class="tok-nt"><archive></span> 15199 <span class="tok-nt"><index></span>true<span class="tok-nt"></index></span> 15200 <span class="tok-nt"><manifest></span> 15201 <span class="tok-nt"><addClasspath></span>false<span class="tok-nt"></addClasspath></span> 15202 <span class="tok-nt"><addDefaultImplementationEntries></span>true<span class="tok-nt"></addDefaultImplementationEntries></span> 15203 <span class="tok-nt"></manifest></span> 15204 <span class="tok-nt"><manifestEntries></span> 15205 <span class="tok-nt"><ActivitiDesigner-Extension-Name></span>Acme Money<span class="tok-nt"></ActivitiDesigner-Extension-Name></span> 15206 <span class="tok-nt"></manifestEntries></span> 15207 <span class="tok-nt"></archive></span> 15208 <span class="tok-nt"></configuration></span> 15209 <span class="tok-nt"></plugin></span> 15210 <span class="tok-nt"></plugins></span> 15211<span class="tok-nt"></build></span> 15212</td></tr></table></code></pre> 15213</div> 15214</div> 15215<div class="paragraph"> 15216<p>The name for the extension is described by the <code>ActivitiDesigner-Extension-Name</code> property. The only thing left to do now is tell Eclipse to setup the project according to the instructions in <code>pom.xml</code>. So open up a command shell and go to the root folder of your project in the Eclipse workspace. Then execute the following Maven command:</p> 15217</div> 15218<div class="listingblock"> 15219<div class="content"> 15220<pre>mvn eclipse:eclipse</pre> 15221</div> 15222</div> 15223<div class="paragraph"> 15224<p>Wait until the build is successful. Refresh the project (use the project’s context menu (right-click) and select <code>Refresh</code>). You should now have the <code>src/main/java</code> and <code>src/main/resources</code> folders as source folders in the Eclipse project.</p> 15225</div> 15226<div class="admonitionblock note"> 15227<table> 15228<tr> 15229<td class="icon"> 15230<i class="fa icon-note" title="Note"></i> 15231</td> 15232<td class="content"> 15233<div class="paragraph"> 15234<p>You can of course also use the <a href="http://www.eclipse.org/m2e">m2eclipse</a> plugin and simply enable Maven dependency management from the context menu (right-click) of the project. Then choose <code>Maven</code> > <code>Update project configuration</code> from the project’s context menu. That should setup the source folders as well.</p> 15235</div> 15236</td> 15237</tr> 15238</table> 15239</div> 15240<div class="paragraph"> 15241<p>That’s it for the setup. Now you’re ready to start creating customizations to Activiti Designer!</p> 15242</div> 15243</div> 15244<div class="sect4"> 15245<h5 id="eclipseDesignerApplyingExtension">Applying your extension to Activiti Designer</h5> 15246<div class="paragraph"> 15247<p>You might be wondering how you can add your extension to Activiti Designer so your customizations are applied. These are the steps to do just that: 15248* Once you’ve created your extension JAR (for instance, by performing a mvn install in your project to build it with Maven), you need to transfer the extension to the computer where Activiti Designer is installed; 15249* Store the extension somewhere on the hard drive where it will be able to remain and remember the location. <em>Note:</em> the location must be outside the Eclipse workspace of Activiti Designer - storing the extension inside the workspace will lead to the user getting a popup error message and the extensions being unavailable; 15250* Start Activiti Designer and from the menu, select <code>Window</code> > <code>Preferences</code> 15251* In the preferences screen, type <code>user</code> as keyword. You should see an option to access the <code>User Libraries</code> in Eclipse in the <code>Java</code> section.</p> 15252</div> 15253<div class="imageblock" style="text-align: center"> 15254<div class="content"> 15255<img src="images/designer.preferences.userlibraries.png" alt="designer.preferences.userlibraries"> 15256</div> 15257</div> 15258<div class="ulist"> 15259<ul> 15260<li> 15261<p>Select the User Libraries item and a tree view shows up to the right where you can add libraries. You should see the default group where you can add extensions to Activiti Designer (depending on your Eclipse installation, you might see several others as well).</p> 15262</li> 15263</ul> 15264</div> 15265<div class="imageblock" style="text-align: center"> 15266<div class="content"> 15267<img src="images/designer.preferences.userlibraries.activiti.empty.png" alt="designer.preferences.userlibraries.activiti.empty"> 15268</div> 15269</div> 15270<div class="ulist"> 15271<ul> 15272<li> 15273<p>Select the <code>Activiti Designer Extensions</code> group and click the <code>Add JARs…​</code> button. Navigate to the folder where your extension is stored and select the extension file you want to add. After completing this, your preferences screen should show the extension as part of the <code>Activiti Designer Extensions</code> group, as shown below.</p> 15274</li> 15275</ul> 15276</div> 15277<div class="imageblock" style="text-align: center"> 15278<div class="content"> 15279<img src="images/designer.preferences.userlibraries.activiti.moneytasks.png" alt="designer.preferences.userlibraries.activiti.moneytasks"> 15280</div> 15281</div> 15282<div class="ulist"> 15283<ul> 15284<li> 15285<p>Click the <code>OK</code> button to save and close the preferences dialog. The <code>Activiti Designer Extensions</code> group is automatically added to new Activiti projects you create. You can see the user library as entry in the project’s tree in the Navigator or Package Explorer. If you already had Activiti projects in the workspace, you should also see the new extensions show up in the group. An example is shown below.</p> 15286</li> 15287</ul> 15288</div> 15289<div class="imageblock" style="text-align: center"> 15290<div class="content"> 15291<img src="images/designer.userlibraries.project.png" alt="designer.userlibraries.project"> 15292</div> 15293</div> 15294<div class="paragraph"> 15295<p>Diagrams you open will now have the shapes from the new extension in their palette (or shapes disabled, depending on the customizations in your extension). If you already had a diagram opened, close and reopen it to see the changes in the palette.</p> 15296</div> 15297</div> 15298<div class="sect4"> 15299<h5 id="_adding_shapes_to_the_palette">Adding shapes to the palette</h5> 15300<div class="paragraph"> 15301<p>With your project set up, you can now easily add shapes to the palette. Each shape you wish to add is represented by a class in your JAR. Take note that these classes are not the classes that will be used by the Activiti engine during runtime. In your extension you describe the properties that can be set in Activiti Designer for each shape. From these shapes, you can also define the runtime characteristics that should be used by the engine when a process instance reaches the node in the process. The runtime characteristics can use any of the options that Activiti supports for regular <code>ServiceTask</code>s. See <a href="#eclipseDesignerConfiguringRuntime">this section</a> for more details.</p> 15302</div> 15303<div class="paragraph"> 15304<p>A shape’s class is a simple Java class, to which a number of annotations are added. The class should implement the <code>CustomServiceTask</code> interface, but you shouldn’t implement this interface yourself. Extend the <code>AbstractCustomServiceTask</code> base class instead (at the moment you MUST extend this class directly, so no abstract classes in between). In the Javadoc for that class you can find instructions on the defaults it provides and when you should override any of the methods it already implements. Overrides allow you to do things such as providing icons for the palette and in the shape on the canvas (these can be different) and specifying the base shape you want the node to have (activity, event, gateway).</p> 15305</div> 15306<div class="listingblock"> 15307<div class="content"> 15308<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 153092 153103 153114 153125 153136 153147 153158</div></td><td class="code"><span></span><span class="tok-cm">/**</span> 15316<span class="tok-cm"> * @author John Doe</span> 15317<span class="tok-cm"> * @version 1</span> 15318<span class="tok-cm"> * @since 1.0.0</span> 15319<span class="tok-cm"> */</span> 15320<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">AcmeMoneyTask</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractCustomServiceTask</span> <span class="tok-o">{</span> 15321<span class="tok-o">...</span> 15322<span class="tok-o">}</span> 15323</td></tr></table></code></pre> 15324</div> 15325</div> 15326<div class="paragraph"> 15327<p>You will need to implement the <code>getName()</code> method to determine the name the node will have in the palette. You can also put the nodes in their own drawer and provide an icon. Override the appropriate methods from <code>AbstractCustomServiceTask</code>. If you want to provide an icon, make sure it’s in the <code>src/main/resources</code>
15327 package in your JAR and is about 16x16 pixels and a JPEG or PNG format. The path you supply is relative to that folder.</p> 15328</div> 15329<div class="paragraph"> 15330<p>You can add properties to the shape by adding members to the class and annotating them with the <code>@Property</code> annotation like this:</p> 15331</div> 15332<div class="listingblock"> 15333<div class="content"> 15334<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 153352 153363</div></td><td class="code"><span></span><span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">TEXT</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Account Number"</span><span class="tok-o">)</span> 15337<span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"Provide an account number"</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-n">HELP_ACCOUNT_NUMBER_LONG</span><span class="tok-o">)</span> 15338<span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">accountNumber</span><span class="tok-o">;</span> 15339</td></tr></table></code></pre> 15340</div> 15341</div> 15342<div class="paragraph"> 15343<p>There are several <code>PropertyType</code> values you can use, which are described in more detail in <a href="#eclipseDesignerPropertyTypes">this section</a>. You can make a field required by setting the required attribute to true. A message and red background will appear if the user doesn’t fill out the field.</p> 15344</div> 15345<div class="paragraph"> 15346<p>If you want to ensure the order of the various properties in your class as they appear in the property screen, you should specify the order attribute of the <code>@Property</code> annotation.</p> 15347</div> 15348<div class="paragraph"> 15349<p>As you can see, there’s also a <code>@Help</code> annotation that’s used to provide the user some guidance when filling out the field. You can also use the <code>@Help</code> annotation on the class itself - this information is shown at the top of the property sheet presented to the user.</p> 15350</div> 15351<div class="paragraph"> 15352<p>Below is the listing for a further elaboration of the <code>MoneyTask</code>. A comment field has been added and you can see an icon is included for the node.</p> 15353</div> 15354<div class="listingblock"> 15355<div class="content"> 15356<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 15357 2 15358 3 15359 4 15360 5 15361 6 15362 7 15363 8 15364 9 1536510 1536611 1536712 1536813 1536914 1537015 1537116 1537217 1537318 1537419 1537520 1537621 1537722 1537823 1537924 1538025 1538126 1538227 1538328 1538429 1538530 1538631 1538732 1538833 1538934 1539035 1539136 1539237 1539338 1539439 1539540 1539641 1539742 1539843 1539944</div></td><td class="code"><span></span><span class="tok-cm">/**</span> 15400<span class="tok-cm"> * @author John Doe</span> 15401<span class="tok-cm"> * @version 1</span> 15402<span class="tok-cm"> * @since 1.0.0</span> 15403<span class="tok-cm"> */</span> 15404<span class="tok-nd">@Runtime</span><span class="tok-o">(</span><span class="tok-n">javaDelegateClass</span> <span class="tok-o">=</span> <span class="tok-s">"org.acme.runtime.AcmeMoneyJavaDelegation"</span><span class="tok-o">)</span> 15405<span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"Creates a new account"</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-s">"Creates a new account using the account number specified"</span><span class="tok-o">)</span> 15406<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">AcmeMoneyTask</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractCustomServiceTask</span> <span class="tok-o">{</span> 15407 15408 <span class="tok-kd">private</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-n">String</span> <span class="tok-n">HELP_ACCOUNT_NUMBER_LONG</span> <span class="tok-o">=</span> <span class="tok-s">"Provide a number that is suitable as an account number."</span><span class="tok-o">;</span> 15409 15410 <span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">TEXT</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Account Number"</span><span class="tok-o">,</span> <span class="tok-n">required</span> <span class="tok-o">=</span> <span class="tok-kc">true</span><span class="tok-o">)</span> 15411 <span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"Provide an account number"</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-n">HELP_ACCOUNT_NUMBER_LONG</span><span class="tok-o">)</span> 15412 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">accountNumber</span><span class="tok-o">;</span> 15413 15414 <span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">MULTILINE_TEXT</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Comments"</span><span class="tok-o">)</span> 15415 <span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"Provide comments"</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-s">"You can add comments to the node to provide a brief description."</span><span class="tok-o">)</span> 15416 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">comments</span><span class="tok-o">;</span> 15417 15418 <span class="tok-cm">/*</span> 15419<span class="tok-cm"> * (non-Javadoc)</span> 15420<span class="tok-cm"> *</span> 15421<span class="tok-cm"> * @see org.activiti.designer.integration.servicetask.AbstractCustomServiceTask #contributeToPaletteDrawer()</span> 15422<span class="tok-cm"> */</span> 15423 <span class="tok-nd">
15423@Override</span> 15424 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">contributeToPaletteDrawer</span><span class="tok-o">()</span> <span class="tok-o">{</span> 15425 <span class="tok-k">return</span> <span class="tok-s">"Acme Corporation"</span><span class="tok-o">;</span> 15426 <span class="tok-o">}</span> 15427 15428 <span class="tok-nd">@Override</span> 15429 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getName</span><span class="tok-o">()</span> <span class="tok-o">{</span> 15430 <span class="tok-k">return</span> <span class="tok-s">"Money node"</span><span class="tok-o">;</span> 15431 <span class="tok-o">}</span> 15432 15433 <span class="tok-cm">/*</span> 15434<span class="tok-cm"> * (non-Javadoc)</span> 15435<span class="tok-cm"> *</span> 15436<span class="tok-cm"> * @see org.activiti.designer.integration.servicetask.AbstractCustomServiceTask #getSmallIconPath()</span> 15437<span class="tok-cm"> */</span> 15438 <span class="tok-nd">@Override</span> 15439 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getSmallIconPath</span><span class="tok-o">()</span> <span class="tok-o">{</span> 15440 <span class="tok-k">return</span> <span class="tok-s">"icons/coins.png"</span><span class="tok-o">;</span> 15441 <span class="tok-o">}</span> 15442<span class="tok-o">}</span> 15443</td></tr></table></code></pre> 15444</div> 15445</div> 15446<div class="paragraph"> 15447<p>If you extend Activiti Designer with this shape, The palette and corresponding node will look like this:</p> 15448</div> 15449<div class="imageblock" style="text-align: center"> 15450<div class="content"> 15451<img src="images/designer.palette.add.money.png" alt="designer.palette.add.money"> 15452</div> 15453</div> 15454<div class="paragraph"> 15455<p>The properties screen for the money task is shown below. Note the required message for the <code>accountNumber</code> field.</p> 15456</div> 15457<div class="imageblock" style="text-align: center"> 15458<div class="content"> 15459<img src="images/designer.palette.add.money.properties.required.png" alt="designer.palette.add.money.properties.required"> 15460</div> 15461</div> 15462<div class="paragraph"> 15463<p>Users can enter static text or use expressions that use process variables in the property fields when creating diagrams (e.g. "This little piggy went to ${piggyLocation}"). Generally, this applies to text fields where users are free to enter any text. If you expect users to want to use expressions and you apply runtime behavior to your <code>CustomServiceTask</code> (using <code>@Runtime</code>), make sure to use <code>Expression</code> fields in the delegate class so the expressions are correctly resolved at runtime. More information on runtime behavior can be found in <a href="#eclipseDesignerConfiguringRuntime">this section</a>.</p> 15464</div> 15465<div class="paragraph"> 15466<p>The help for fields is offered by the buttons to the right of each property. Clicking on the button shows a popup as displayed below.</p> 15467</div> 15468<div class="imageblock" style="text-align: center"> 15469<div class="content"> 15470<img src="images/designer.palette.add.money.help.png" alt="designer.palette.add.money.help"> 15471</div> 15472</div> 15473<div class="sect5"> 15474<h6 id="eclipseDesignerConfiguringRuntime">Configuring runtime execution of Custom Service Tasks</h6> 15475<div class="paragraph"> 15476<p>With your fields setup and your extension applied to Designer, users can configure the properties of the service task when modelling a process. In most cases, you will want to use these user-configured properties when the process is executed by Activiti. To do this, you must instruct Activiti which class to instantiate when the process reaches your <code>CustomServiceTask</code>.</p> 15477</div> 15478<div class="paragraph"> 15479<p>There is a special annotation for specifying the runtime characteristics of your <code>CustomServiceTask</code>, the <code>@Runtime</code> annotation. Here’s an example of how to use it:</p> 15480</div> 15481<div class="listingblock"> 15482<div class="content"> 15483<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nd">
15483@Runtime</span><span class="tok-o">(</span><span class="tok-n">javaDelegateClass</span> <span class="tok-o">=</span> <span class="tok-s">"org.acme.runtime.AcmeMoneyJavaDelegation"</span><span class="tok-o">)</span> 15484</td></tr></table></code></pre> 15485</div> 15486</div> 15487<div class="paragraph"> 15488<p>Your <code>CustomServiceTask</code> will result in a normal <code>ServiceTask</code> in the BPMN output of processes modelled with it. Activiti enables <a href="#bpmnJavaServiceTask">several ways</a> to define the runtime characteristics of <code>ServiceTask</code>s. Therefore, the <code>@Runtime</code> annotation can take one of three attributes, which match directly to the options Activiti provides, like this:</p> 15489</div> 15490<div class="ulist"> 15491<ul> 15492<li> 15493<p><code>javaDelegateClass</code> maps to <code>activiti:class</code> in the BPMN output. Specify the fully qualified classname of a class that implements <code>JavaDelegate</code>.</p> 15494</li> 15495<li> 15496<p><code>expression</code> maps to <code>activiti:expression</code> in the BPMN output. Specify an expression to a method to be executed, such as a method in a Spring Bean. You should <em>not</em> specify any <code>@Property</code> annotations on fields when using this option. For more information, see below.</p> 15497</li> 15498<li> 15499<p><code>javaDelegateExpression</code> maps to <code>activiti:delegateExpression</code> in the BPMN output. Specify an expression to a class that implements <code>JavaDelegate</code>.</p> 15500</li> 15501</ul> 15502</div> 15503<div class="paragraph"> 15504<p>The user’s property values will be injected into the runtime class if you provide members in the class for Activiti to inject into. The names should match the names of the members in your <code>CustomServiceTask</code>. For more information, consult <a href="#serviceTaskFieldInjection">this part</a> of the userguide. Note that since version 5.11.0 of the Designer you can use the <code>Expression</code> interface for dynamic field values. This means that the value of the property in the Activiti Designer must contain an expression and this expression will then be injected into an <code>Expression</code> property in the <code>JavaDelegate</code> implementation class.</p> 15505</div> 15506<div class="admonitionblock note"> 15507<table> 15508<tr> 15509<td class="icon"> 15510<i class="fa icon-note" title="Note"></i> 15511</td> 15512<td class="content"> 15513<div class="paragraph"> 15514<p>You can use <code>@Property</code> annotations on members of your <code>CustomServiceTask</code>, but this will not work if you use <code>@Runtime</code><em>s <code>expression</code> attribute. The reason for this is that the expression you specify will be attempted to be resolved to a <em>method</em> by Activiti, not to a class. Therefore, no injection into a class will be performed. Any members marked with <code>@Property</code> will be ignored by Designer if you use <code>expression</code> in your <code>@Runtime</code> annotation. Designer will not render them as editable fields in the node’s property pane and will produce no output for the properties in the process</em> BPMN.</p> 15515</div> 15516</td> 15517</tr> 15518</table> 15519</div> 15520<div class="admonitionblock note"> 15521<table> 15522<tr> 15523<td class="icon"> 15524<i class="fa icon-note" title="Note"></i> 15525</td> 15526<td class="content"> 15527<div class="paragraph"> 15528<p>Note that the runtime class shouldn’t be in your extension JAR, as it’s dependent on the Activiti libraries. Activiti needs to be able to find it at runtime, so it needs to be on the Activiti engine’s classpath.</p> 15529</div> 15530</td> 15531</tr> 15532</table> 15533</div> 15534<div class="paragraph"> 15535<p>The examples project in Designer’s source tree contains examples of the different options for configuring <code>@Runtime</code>. Take a look in the money-tasks project for some starting points. The examples refer to delegate class examples that are in the money-delegates project.</p> 15536</div> 15537</div> 15538</div> 15539<div class="sect4"> 15540<h5 id="eclipseDesignerPropertyTypes">Property types</h5> 15541<div class="paragraph"> 15542<p>This section describes the property types you can use for a <code>CustomServiceTask</code> by setting its type to a <code>PropertyType</code> value.</p> 15543</div> 15544<div class="sect5"> 15545<h6 id="_propertytype_text">PropertyType.TEXT</h6> 15546<div class="paragraph"> 15547<p>Creates a single line text field as shown below. Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the field to a light red color.</p> 15548</div> 15549<div class="imageblock" style="text-align: center"> 15550<div class="content">
15551<img src="images/designer.property.text.invalid.png" alt="designer.property.text.invalid"> 15552</div> 15553</div> 15554</div> 15555<div class="sect5"> 15556<h6 id="_propertytype_multiline_text">PropertyType.MULTILINE_TEXT</h6> 15557<div class="paragraph"> 15558<p>Creates a multiline text field as shown below (height is fixed at 80 pixels). Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the field to a light red color.</p> 15559</div> 15560<div class="imageblock" style="text-align: center"> 15561<div class="content"> 15562<img src="images/designer.property.multiline.text.invalid.png" alt="designer.property.multiline.text.invalid"> 15563</div> 15564</div> 15565</div> 15566<div class="sect5"> 15567<h6 id="_propertytype_period">PropertyType.PERIOD</h6> 15568<div class="paragraph"> 15569<p>Creates a structured editor for specifying a period of time by editing amounts of each unit with a spinner control. The result is shown below. Can be a required field (which is interpreted such that not all values may be 0, so at least 1 part of the period must have a non-zero value) and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the entire field to a light red color. The value of the field is stored as a string of the form 1y 2mo 3w 4d 5h 6m 7s, which represents 1 year, 2 months, 3 weeks, 4 days, 6 minutes and 7 seconds. The entire string is always stored, even if parts are 0.</p> 15570</div> 15571<div class="imageblock" style="text-align: center"> 15572<div class="content"> 15573<img src="images/designer.property.period.png" alt="designer.property.period"> 15574</div> 15575</div> 15576</div> 15577<div class="sect5"> 15578<h6 id="_propertytype_boolean_choice">PropertyType.BOOLEAN_CHOICE</h6> 15579<div class="paragraph"> 15580<p>Creates a single checkbox control for boolean or toggle choices. Note that you can specify the <code>required</code> attribute on the <code>Property</code> annotation, but it will not be evaluated because that would leave the user without a choice whether to check the box or not. The value stored in the diagram is java.lang.Boolean.toString(boolean), which results in "true" or "false".</p> 15581</div> 15582<div class="imageblock" style="text-align: center"> 15583<div class="content"> 15584<img src="images/designer.property.boolean.choice.png" alt="designer.property.boolean.choice"> 15585</div> 15586</div> 15587</div> 15588<div class="sect5"> 15589<h6 id="_propertytype_radio_choice">PropertyType.RADIO_CHOICE</h6> 15590<div class="paragraph"> 15591<p>Creates a group of radio buttons as shown below. Selection of any of the radio buttons is mutually exclusive with selection of any of the others (i.e., only one selection allowed). Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the group to a light red color.</p> 15592</div> 15593<div class="paragraph"> 15594<p>This property type expects the class member you have annotated to also have an accompanying <code>@PropertyItems</code> annotation (for an example, see below). Using this additional annotation, you can specify the list of items that should be offered in an array of Strings. Specify the items by adding two array entries for each item: first, the label to be shown; second, the value to be stored.</p> 15595</div> 15596<div class="listingblock"> 15597<div class="content"> 15598<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 155992 156003 156014</div></td><td class="code"><span></span><span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">RADIO_CHOICE</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Withdrawl limit"</span><span class="tok-o">,</span> <span class="tok-n">required</span> <span class="tok-o">=</span> <span class="tok-kc">true</span><span class="tok-o">)</span> 15602<span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"The maximum daily withdrawl amount "</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-s">"Choose the maximum daily amount that can be withdrawn from the account."</span><span class="tok-o">)</span> 15603<span class="tok-nd">@PropertyItems</span><span class="tok-o">({</span> <span class="tok-n">LIMIT_LOW_LABEL</span><span class="tok-o">,</span> <span class="tok-n">LIMIT_LOW_VALUE</span><span class="tok-o">,</span> <span class="tok-n">LIMIT_MEDIUM_LABEL</span><span class="tok-o">,</span> <span class="tok-n">LIMIT_MEDIUM_VALUE</span><span class="tok-o">,</span> <span class="tok-n">LIMIT_HIGH_LABEL</span><span class="tok-o">,</span> <span class="tok-n">LIMIT_HIGH_VALUE</span> <span class="tok-o">})</span> 15604<span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">withdrawlLimit</span><span class="tok-o">;</span> 15605</td></tr></table></code></pre> 15606</div> 15607</div> 15608<div class="imageblock" style="text-align: center"> 15609<div class="content"> 15610<img src="images/designer.property.radio.choice.png" alt="designer.property.radio.choice"> 15611</div> 15612</div> 15613<div class="imageblock" style="text-align: center"> 15614<div class="content"> 15615<img src="images/designer.property.radio.choice.invalid.png" alt="designer.property.radio.choice.invalid"> 15616</div> 15617</div> 15618</div> 15619<div class="sect5"> 15620<h6 id="_propertytype_combobox_choice">PropertyType.COMBOBOX_CHOICE</h6> 15621<div class="paragraph"> 15622<p>Creates a combobox with fixed options as shown below. Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the combobox to a light red color.</p> 15623</div> 15624<div class="paragraph"> 15625<p>This property type expects the class member you have annotated to al
15625so have an accompanying <code>@PropertyItems</code> annotation (for an example, see below). Using this additional annotation, you can specify the list of items that should be offered in an array of Strings. Specify the items by adding two array entries for each item: first, the label to be shown; second, the value to be stored.</p> 15626</div> 15627<div class="listingblock"> 15628<div class="content"> 15629<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 156302 156313 156324 156335 156346</div></td><td class="code"><span></span><span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">COMBOBOX_CHOICE</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Account type"</span><span class="tok-o">,</span> <span class="tok-n">required</span> <span class="tok-o">=</span> <span class="tok-kc">true</span><span class="tok-o">)</span> 15635<span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"The type of account"</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-s">"Choose a type of account from the list of options"</span><span class="tok-o">)</span> 15636<span class="tok-nd">@PropertyItems</span><span class="tok-o">({</span> <span class="tok-n">ACCOUNT_TYPE_SAVINGS_LABEL</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_SAVINGS_VALUE</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_JUNIOR_LABEL</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_JUNIOR_VALUE</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_JOINT_LABEL</span><span class="tok-o">,</span> 15637 <span class="tok-n">ACCOUNT_TYPE_JOINT_VALUE</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_TRANSACTIONAL_LABEL</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_TRANSACTIONAL_VALUE</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_STUDENT_LABEL</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_STUDENT_VALUE</span><span class="tok-o">,</span> 15638 <span class="tok-n">ACCOUNT_TYPE_SENIOR_LABEL</span><span class="tok-o">,</span> <span class="tok-n">ACCOUNT_TYPE_SENIOR_VALUE</span> <span class="tok-o">})</span> 15639<span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">accountType</span><span class="tok-o">;</span> 15640</td></tr></table></code></pre> 15641</div> 15642</div> 15643<div class="imageblock" style="text-align: center"> 15644<div class="content"> 15645<img src="images/designer.property.combobox.choice.png" alt="designer.property.combobox.choice"> 15646</div> 15647</div> 15648<div class="imageblock" style="text-align: center"> 15649<div class="content"> 15650<img src="images/designer.property.combobox.choice.invalid.png" alt="designer.property.combobox.choice.invalid"> 15651</div> 15652</div> 15653</div> 15654<div class="sect5"> 15655<h6 id="_propertytype_date_picker">PropertyType.DATE_PICKER</h6> 15656<div class="paragraph"> 15657<p>Creates a date selection control as shown below. Can be a required field and shows validation messages as a tooltip (note, that the control used will auto-set the selection to the date on the system, so the value is seldom empty). Validation failures are displayed by changing the background of the control to a light red color.</p> 15658</div> 15659<div class="paragraph"> 15660<p>This property type expects the class member you have annotated to also have an accompanying <code>@DatePickerProperty</code> annotation (for an example, see below). Using this additional annotation, you can specify the date time pattern to be used to store dates in the diagram and the type of datepicker you would like to be shown. Both attributes are optional and have default values that will be used if you don’t specify them (these are static variables in the <code>DatePickerProperty</code> annotation). The <code>dateTimePattern</code> attribute should be used to supply a pattern to the <code>SimpleDateFormat</code> class. When using the <code>swtStyle</code> attribute, you should specify an integer value that is supported by <code>SWT</code>'s <code>DateTime</code> control, because this is the control that is used to render this type of property.</p> 15661</div> 15662<div class="listingblock"> 15663<div class="content"> 15664<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 156652 156663 156674</div></td><td class="code"><span></span><span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">DATE_PICKER</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Expiry date"</span><span class="tok-o">,</span> <span class="tok-n">required</span> <span class="tok-o">=</span> <span class="tok-kc">true</span><span class="tok-o">)</span> 15668<span class="tok-nd">@Help</span><span class="tok-o">(</span><span class="tok-n">displayHelpShort</span> <span class="tok-o">=</span> <span class="tok-s">"The date the account expires "</span><span class="tok-o">,</span> <span class="tok-n">displayHelpLong</span> <span class="tok-o">=</span> <span class="tok-s">"Choose the date when the account will expire if no extended before the date."</span><span class="tok-o">)</span> 15669<span class="tok-nd">@DatePickerProperty</span><span class="tok-o">(</span><span class="tok-n">dateTimePattern</span> <span class="tok-o">=</span> <span class="tok-s">"MM-dd-yyyy"</span><span class="tok-o">,</span> <span class="tok-n">swtStyle</span> <span class="tok-o">=</span> <span class="tok-mi">32</span><span class="tok-o">)</span> 15670<span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">expiryDate</span><span class="tok-o">;</span> 15671</td></tr></table></code></pre> 15672</div> 15673</div> 15674<div class="imageblock" style="text-align: center"> 15675<div class="content"> 15676<img src="images/designer.property.date.picker.png" alt="designer.property.date.picker"> 15677</div> 15678</div> 15679</div> 15680<div class="sect5"> 15681<h6 id="_propertytype_data_grid">PropertyType.DATA_GRID</h6> 15682<div class="paragraph"> 15683<p>Creates a data grid control as shown below. A data grid can be used to allow the user to enter an arbitrary amount of rows of data and enter values for a fixed set of columns in each of those rows (each individual combination of row and column is referred to as a cell). Rows can be added and removed as the user sees fit.</p> 15684</div> 15685<div class="paragraph"> 15686<p>This property type expects the class member you have annotated to al
15686so have an accompanying <code>@DataGridProperty</code> annotation (for an example, see below). Using this additional annotation, you can specify some specific attributes of the data grid. You are required to reference a different class to determine which columns go into the grid with the <code>itemClass</code> attribute. Activiti Designer expects the member type to be a <code>List</code>. By convention, you can use the class of the <code>itemClass</code> attribute as its generic type. If, for example, you have a grocery list that you edit in the grid, you would define the columns of the grid in the <code>GroceryListItem</code> class. From your <code>CustomServiceTask</code>, you would refer to it like this:</p> 15687</div> 15688<div class="listingblock"> 15689<div class="content"> 15690<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 156912 156923</div></td><td class="code"><span></span><span class="tok-nd">@Property</span><span class="tok-o">(</span><span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">PropertyType</span><span class="tok-o">.</span><span class="tok-na">DATA_GRID</span><span class="tok-o">,</span> <span class="tok-n">displayName</span> <span class="tok-o">=</span> <span class="tok-s">"Grocery List"</span><span class="tok-o">)</span> 15693<span class="tok-nd">@DataGridProperty</span><span class="tok-o">(</span><span class="tok-n">itemClass</span> <span class="tok-o">=</span> <span class="tok-n">GroceryListItem</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">)</span> 15694<span class="tok-kd">private</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">GroceryListItem</span><span class="tok-o">></span> <span class="tok-n">groceryList</span><span class="tok-o">;</span> 15695</td></tr></table></code></pre> 15696</div> 15697</div> 15698<div class="paragraph"> 15699<p>The "itemClass" class uses the same annotations you would otherwise use to specify fields of a <code>CustomServiceTask</code>, with the exception of using a data grid. Specifically, <code>TEXT</code>, <code>MULTILINE_TEXT</code> and <code>PERIOD</code> are currently supported. You’ll notice the grid will create single line text controls for each field, regardless of the <code>PropertyType</code>. This is done on purpose to keep the grid graphically appealing and readable. If you consider the regular display mode for a <code>PERIOD</code> <code>PropertyType</code> for instance, you can imagine it would never properly fit in a grid cell without cluttering the screen. For <code>MULTILINE_TEXT</code> and <code>PERIOD</code>, a double-click mechanism is added to each field which pops up a larger editor for the <code>PropertyType</code>. The value is stored to the field after the user clicks OK and is therefore readable within the grid.</p> 15700</div> 15701<div class="paragraph"> 15702<p>Required attributes are handled in a similar manner to regular fields of type <code>TEXT</code> and the entire grid is validated as soon as any field loses focus. The background color of the text control in a specific cell of the data grid is changed to light red if there are validation failures.</p> 15703</div> 15704<div class="paragraph"> 15705<p>By default, the component allows the user to add rows, but not to determine the order of those rows. If you wish to allow this, you should set the <code>orderable</code> attribute to true, which enables buttons at the end of each row to move it up or down in the grid.</p> 15706</div> 15707<div class="admonitionblock note"> 15708<table> 15709<tr> 15710<td class="icon"> 15711<i class="fa icon-note" title="Note"></i> 15712</td> 15713<td class="content"> 15714<div class="paragraph"> 15715<p>At the moment, this property type is not correctly injected into your runtime class.</p> 15716</div> 15717</td> 15718</tr> 15719</table> 15720</div> 15721<div class="imageblock" style="text-align: center"> 15722<div class="content"> 15723<img src="images/designer.property.datagrid.png" alt="designer.property.datagrid"> 15724</div> 15725</div> 15726</div> 15727</div> 15728<div class="sect4"> 15729<h5 id="_disabling_default_shapes_in_the_palette">Disabling default shapes in the palette</h5> 15730<div class="paragraph"> 15731<p>This customization requires you to include a class in your extension that implements the <code>DefaultPaletteCustomizer</code> interface. You should not implement this interface directly, but subclass the <code>AbstractDefaultPaletteCustomizer</code> base class. Currently, this class provides no functionality, but future versions of the <code>DefaultPaletteCustomizer</code> interface will offer more capabilities for which this base class will provide some sensible defaults so it’s best to subclass so your extension will be compatible with future releases.</p> 15732</div> 15733<div class="paragraph"> 15734<p>Extending the <code>AbstractDefaultPaletteCustomizer</code> class requires you to implement one method, <code>disablePaletteEntries()</code>, from which you must return a list of <code>PaletteEntry</code> values. For each of the default shapes, you can disable it by adding its corresponding <code>PaletteEntry</code> value to your list. Note that if you remove shapes from the default set and there are no remaining shapes in a particular drawer, that drawer will be removed from the palette in its entirety. If you wish to disable all of the default shapes, you only need to add <code>PaletteEntry.ALL</code> to your result. As an example, the code below disables the Manual task and Script task shapes in the palette.</p> 15735</div> 15736<div class="listingblock"> 15737<div class="content"> 15738<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 15739 2 15740 3 15741 4 15742 5 15743 6 15744 7 15745 8 15746 9 1574710 1574811 1574912 1575013 1575114 1575215 1575316</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyPaletteCustomizer</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractDefaultPaletteCustomizer</span> <span class="tok-o">{</span> 15754 15755 <span class="tok-cm">/*</span> 15756<span class="tok-cm"> * (non-Javadoc)</span> 15757<span class="tok-cm"> *</span> 15758<span class="tok-cm"> * @see org.activiti.designer.integration.palette.DefaultPaletteCustomizer#disablePaletteEntries()</span> 15759<span class="tok-cm"> */</span> 15760 <span class="tok-nd">
15760@Override</span> 15761 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">PaletteEntry</span><span class="tok-o">></span> <span class="tok-nf">disablePaletteEntries</span><span class="tok-o">()</span> <span class="tok-o">{</span> 15762 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">PaletteEntry</span><span class="tok-o">></span> <span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ArrayList</span><span class="tok-o"><</span><span class="tok-n">PaletteEntry</span><span class="tok-o">>();</span> 15763 <span class="tok-n">result</span><span class="tok-o">.</span><span class="tok-na">add</span><span class="tok-o">(</span><span class="tok-n">PaletteEntry</span><span class="tok-o">.</span><span class="tok-na">MANUAL_TASK</span><span class="tok-o">);</span> 15764 <span class="tok-n">result</span><span class="tok-o">.</span><span class="tok-na">add</span><span class="tok-o">(</span><span class="tok-n">PaletteEntry</span><span class="tok-o">.</span><span class="tok-na">SCRIPT_TASK</span><span class="tok-o">);</span> 15765 <span class="tok-k">return</span> <span class="tok-n">result</span><span class="tok-o">;</span> 15766 <span class="tok-o">}</span> 15767 15768<span class="tok-o">}</span> 15769</td></tr></table></code></pre> 15770</div> 15771</div> 15772<div class="paragraph"> 15773<p>The result of applying this extension is shown in the picture below. As you can see, the manual task and script task shapes are no longer available in the <code>Tasks</code> drawer.</p> 15774</div> 15775<div class="imageblock" style="text-align: center"> 15776<div class="content"> 15777<img src="images/designer.palette.disable.manual.and.script.png" alt="designer.palette.disable.manual.and.script"> 15778</div> 15779</div> 15780<div class="paragraph"> 15781<p>To disable all of the default shapes, you could use something similar to the code below.</p> 15782</div> 15783<div class="listingblock"> 15784<div class="content"> 15785<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 15786 2 15787 3 15788 4 15789 5 15790 6 15791 7 15792 8 15793 9 1579410 1579511 1579612 1579713 1579814 1579915</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyPaletteCustomizer</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractDefaultPaletteCustomizer</span> <span class="tok-o">{</span> 15800 15801 <span class="tok-cm">/*</span> 15802<span class="tok-cm"> * (non-Javadoc)</span> 15803<span class="tok-cm"> *</span> 15804<span class="tok-cm"> * @see org.activiti.designer.integration.palette.DefaultPaletteCustomizer#disablePaletteEntries()</span> 15805<span class="tok-cm"> */</span> 15806 <span class="tok-nd">@Override</span> 15807 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">PaletteEntry</span><span class="tok-o">></span> <span class="tok-nf">disablePaletteEntries</span><span class="tok-o">()</span> <span class="tok-o">{</span> 15808 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">PaletteEntry</span><span class="tok-o">></span> <span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ArrayList</span><span class="tok-o"><</span><span class="tok-n">PaletteEntry</span><span class="tok-o">>();</span> 15809 <span class="tok-n">result</span><span class="tok-o">.</span><span class="tok-na">add</span><span class="tok-o">(</span><span class="tok-n">PaletteEntry</span><span class="tok-o">.</span><span class="tok-na">ALL</span><span class="tok-o">);</span> 15810 <span class="tok-k">return</span> <span class="tok-n">result</span><span class="tok-o">;</span> 15811 <span class="tok-o">}</span> 15812 15813<span class="tok-o">}</span> 15814</td></tr></table></code></pre> 15815</div> 15816</div> 15817<div class="paragraph"> 15818<p>The result will look like this (notice that the drawers the default shapes were in are no longer in the palette):</p> 15819</div> 15820<div class="imageblock" style="text-align: center"> 15821<div class="content"> 15822<img src="images/designer.palette.disable.all.png" alt="designer.palette.disable.all"> 15823</div> 15824</div> 15825</div> 15826</div> 15827<div class="sect3"> 15828<h4 id="_validating_diagrams_and_exporting_to_custom_output_formats">12.5.2. Validating diagrams and exporting to custom output formats</h4> 15829<div class="paragraph"> 15830<p>Besides customizing the palette, you can also create extensions to Activiti Designer that can perform validations and save information from the diagram to custom resources in the Eclipse workspace. There are built-in extension points for doing this and this section explains how to use them.</p> 15831</div> 15832<div class="admonitionblock note"> 15833<table> 15834<tr> 15835<td class="icon"> 15836<i class="fa icon-note" title="Note"></i> 15837</td> 15838<td class="content"> 15839<div class="paragraph"> 15840<p>The ExportMarshaller functions were reintroduced recently. We are still working on the validation functionality. The documentation below details the old situation and will be updated when the new functionality is available.</p> 15841</div> 15842</td> 15843</tr> 15844</table> 15845</div> 15846<div class="paragraph"> 15847<p>Activiti Designer allows you to write extensions that validate diagrams. There are already validations of BPMN constructs in the tool by default, but you can add your own if you want to validate additional items such as modeling conventions or the values in properties of <code>CustomServiceTask</code>s. These extensions are known as <code>Process Validators</code>.</p> 15848</div> 15849<div class="paragraph"> 15850<p>You can also Activiti Designer to publish to additional formats when saving diagrams. These extensions are called <code>Export Marshallers</code> and are invoked automatically by Activiti Designer on each save action by the user. This behavior can be enabled or disabled by setting a preference in Eclipse’s preferences dialog for each format for which there is an extension detected. Designer will make sure your <code>ExportMarshaller</code> is invoked when saving the diagram, depending on the user’s preference.</p> 15851</div> 15852<div class="paragraph"> 15853<p>Often, you will want to combine a <code>ProcessValidator</code> and an <code>ExportMarshaller</code>. Let’s say you have a number of <code>CustomServiceTask</code>s in use that have properties you would like to use in the process that gets generated. However, before the process is generated, you want to validate some of those values first. Combining a <code>ProcessValidator</code> and <code>ExportMarshaller</code> is the best way to accomplish this and Activiti Designer enables you to plug your extensions into the tool seamlessly.</p> 15854</div> 15855<div class="paragraph"> 15856<p>To create a <code>ProcessValidator</code> or an <code>ExportMarshaller</code>, you need to create a different kind of extension than for extending the palette. The reason for this is simple: from your co
15856de you will need access to more APIs than those that are offered by the integration library. In particular, you will need classes that are available in Eclipse itself. So to get started, you should create an Eclipse plugin (which you can do by using Eclipse’s PDE support) and package it in a custom Eclipse product or feature. It’s beyond the scope of this user guide to explain all the details involved in developing Eclipse plugins, so the instructions below are limited to the functionality for extending Activiti Designer.</p> 15857</div> 15858<div class="paragraph"> 15859<p>Your bundle should be dependent on the following libraries:</p> 15860</div> 15861<div class="ulist"> 15862<ul> 15863<li> 15864<p>org.eclipse.core.runtime</p> 15865</li> 15866<li> 15867<p>org.eclipse.core.resources</p> 15868</li> 15869<li> 15870<p>org.activiti.designer.eclipse</p> 15871</li> 15872<li> 15873<p>org.activiti.designer.libs</p> 15874</li> 15875<li> 15876<p>org.activiti.designer.util</p> 15877</li> 15878</ul> 15879</div> 15880<div class="paragraph"> 15881<p>Optionally, the org.apache.commons.lang bundle is available through Designer if you’d like to use that in your extension.</p> 15882</div> 15883<div class="paragraph"> 15884<p>Both <code>ProcessValidator</code>s and <code>ExportMarshaller</code>s are created by extending a base class. These base classes inherit some useful methods from their superclass, the <code>AbstractDiagramWorker</code> class. Using these methods you can create information, warning and error markers that show up in Eclipse’s problems view for the user to figure out what’s wrong or important. You can get to information about the diagram in the form of <code>Resources</code> and <code>InputStreams</code>. This information is provided from the <code>DiagramWorkerContext</code>, which is available from the <code>AbstractDiagramWorker</code> class.</p> 15885</div> 15886<div class="paragraph"> 15887<p>It’s probably a good idea to invoke <code>clearMarkers()</code> as one of the first things you do in either a <code>ProcessValidator</code> or an <code>ExportMarshaller</code>; this will clear any previous markers for your worker (markers are automatically linked to the worker and clearing markers for one worker leaves other markers untouched). For example:</p> 15888</div> 15889<div class="listingblock"> 15890<div class="content"> 15891<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 158922</div></td><td class="code"><span></span><span class="tok-c1">// Clear markers for this diagram first</span> 15893<span class="tok-n">clearMarkersForDiagram</span><span class="tok-o">();</span> 15894</td></tr></table></code></pre> 15895</div> 15896</div> 15897<div class="paragraph"> 15898<p>You should also use the progress monitor provided (in the <code>DiagramWorkerContext</code>) to report your progress back to the user because validations and/or marshalling actions can take up some time during which the user is forced to wait. Reporting progress requires some knowledge of how you should use Eclipse’s features. Take a look at <a href="http://www.eclipse.org/articles/Article-Progress-Monitors/article.html">this article</a> for a thorough explanation of the concepts and usage.</p> 15899</div> 15900<div class="sect4"> 15901<h5 id="_creating_a_processvalidator_extension">Creating a ProcessValidator extension</h5> 15902<div class="admonitionblock note"> 15903<table> 15904<tr> 15905<td class="icon"> 15906<i class="fa icon-note" title="Note"></i> 15907</td> 15908<td class="content"> 15909<div class="paragraph"> 15910<p>Under review!</p> 15911</div> 15912</td> 15913</tr> 15914</table> 15915</div> 15916<div class="paragraph"> 15917<p>Create an extension to the <code>org.activiti.designer.eclipse.extension.validation.ProcessValidator</code> extension point in your <code>plugin.xml</code> file. For this extension point, you are required to subclass the <code>AbstractProcessValidator</code> class.</p> 15918</div> 15919<div class="listingblock"> 15920<div class="content"> 15921<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 159222 159233 159244 159255 159266 159277 159288 159299</div></td><td class="code"><span></span><span class="tok-cp"><?eclipse version="3.6"?></span> 15930<span class="tok-nt"><plugin></span> 15931 <span class="tok-nt"><extension</span> 15932 <span class="tok-na">point=</span><span class="tok-s">"org.activiti.designer.eclipse.extension.validation.ProcessValidator"</span><span class="tok-nt">></span> 15933 <span class="tok-nt"><ProcessValidator</span>
15934 <span class="tok-na">class=</span><span class="tok-s">"org.acme.validation.AcmeProcessValidator"</span><span class="tok-nt">></span> 15935 <span class="tok-nt"></ProcessValidator></span> 15936 <span class="tok-nt"></extension></span> 15937<span class="tok-nt"></plugin></span> 15938</td></tr></table></code></pre> 15939</div> 15940</div> 15941<div class="listingblock"> 15942<div class="content"> 15943<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 159442</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">AcmeProcessValidator</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractProcessValidator</span> <span class="tok-o">{</span> 15945<span class="tok-o">}</span> 15946</td></tr></table></code></pre> 15947</div> 15948</div> 15949<div class="paragraph"> 15950<p>You have to implement a number of methods. Most importantly, implement <code>getValidatorId()</code> so you return a globally unique ID for your validator. This will enable you to invoke it from and <code>ExportMarshaller</code>, or event let someone <em>else</em> invoke your validator from their <code>ExportMarshaller</code>. Implement <code>getValidatorName()</code> and return a logical name for your validator. This name is shown to the user in dialogs. In <code>getFormatName()</code>, you can return the type of diagram the validator typically validates.</p> 15951</div> 15952<div class="paragraph"> 15953<p>The validation work itself is done in the <code>validateDiagram()</code> method. From this point on, it’s up to your specific functionality what you code here. Typically, however, you will want to start by getting hold of the nodes in the diagram’s process, so you can iterate through them, collect, compare and validate data. This snippet shows you how to do this:</p> 15954</div> 15955<div class="listingblock"> 15956<div class="content"> 15957<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 159582 159593 159604 159615 159626 159637</div></td><td class="code"><span></span><span class="tok-kd">final</span> <span class="tok-n">EList</span><span class="tok-o"><</span><span class="tok-n">EObject</span><span class="tok-o">></span> <span class="tok-n">contents</span> <span class="tok-o">=</span> <span class="tok-n">getResourceForDiagram</span><span class="tok-o">(</span><span class="tok-n">diagram</span><span class="tok-o">).</span><span class="tok-na">getContents</span><span class="tok-o">();</span> 15964<span class="tok-k">for</span> <span class="tok-o">(</span><span class="tok-kd">final</span> <span class="tok-n">EObject</span> <span class="tok-n">object</span> <span class="tok-o">:</span> <span class="tok-n">contents</span><span class="tok-o">)</span> <span class="tok-o">{</span> 15965 <span class="tok-k">if</span> <span class="tok-o">(</span><span class="tok-n">object</span> <span class="tok-k">instanceof</span> <span class="tok-n">StartEvent</span> <span class="tok-o">)</span> <span class="tok-o">{</span> 15966 <span class="tok-c1">// Perform some validations for StartEvents</span> 15967 <span class="tok-o">}</span> 15968 <span class="tok-c1">// Other node types and validations</span> 15969<span class="tok-o">}</span> 15970</td></tr></table></code></pre> 15971</div> 15972</div> 15973<div class="paragraph"> 15974<p>Don’t forget to invoke <code>addProblemToDiagram()</code> and/or <code>addWarningToDiagram()</code>, etc as you go through your validations. Make sure you return a correct boolean result at the end to indicate whether you consider the validation as succeeded or failed. This can be used by and invoking <code>ExportMarshaller</code> to determine the next course of action.</p> 15975</div> 15976</div> 15977<div class="sect4"> 15978<h5 id="_creating_an_exportmarshaller_extension">Creating an ExportMarshaller extension</h5> 15979<div class="paragraph"> 15980<p>Create an extension to the <code>org.activiti.designer.eclipse.extension.ExportMarshaller</code> extension point in your <code>plugin.xml</code> file. For this extension point, you are required to subclass the <code>AbstractExportMarshaller</code> class. This abstract base class provides you with a number of useful methods when marshalling to your own format, but most importantly it allows you to save resources to the workspace and to invoke validators.</p> 15981</div> 15982<div class="paragraph"> 15983<p>An example implementation is available in Designer’s examples folder. This example shows how to use the methods in the base class to get the basics done, such as accessing the diagram’s <code>InputStream</code>, using its <code>BpmnModel</code> and saving resources to the workspace.</p> 15984</div> 15985<div class="listingblock"> 15986<div class="content"> 15987<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 159882 159893 159904 159915 159926 159937 159948 159959</div></td><td class="code"><span></span><span class="tok-cp"><?eclipse version="3.6"?></span> 15996<span class="tok-nt"><plugin></span> 15997 <span class="tok-nt"><extension</span> 15998 <span class="tok-na">point=</span><span class="tok-s">"org.activiti.designer.eclipse.extension.ExportMarshaller"</span><span class="tok-nt">></span> 15999 <span class="tok-nt"><ExportMarshaller</span>
16000 <span class="tok-na">class=</span><span class="tok-s">"org.acme.export.AcmeExportMarshaller"</span><span class="tok-nt">></span> 16001 <span class="tok-nt"></ExportMarshaller></span> 16002 <span class="tok-nt"></extension></span> 16003 <span class="tok-nt"></plugin></span> 16004</td></tr></table></code></pre> 16005</div> 16006</div> 16007<div class="listingblock"> 16008<div class="content"> 16009<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 160102</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">AcmeExportMarshaller</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractExportMarshaller</span> <span class="tok-o">{</span> 16011<span class="tok-o">}</span> 16012</td></tr></table></code></pre> 16013</div> 16014</div> 16015<div class="paragraph"> 16016<p>You are required to implement some methods, such as <code>getMarshallerName()</code> and <code>getFormatName()</code>. These methods are used to display options to the user and to show information in progress dialogs, so make sure the descriptions you return reflect the functionality you are implementing.</p> 16017</div> 16018<div class="paragraph"> 16019<p>The bulk of your work is performed in the <code>doMarshallDiagram()</code> method.</p> 16020</div> 16021<div class="paragraph"> 16022<p>If you want to perform a certain validation first, you can invoke the validator directly from your marshaller. You receive a boolean result from the validator, so you know whether validation succeeded. In most cases you won’t want to proceed with marshalling the diagram if it’s not valid, but you might choose to go ahead anyway or even create a different resource if validation fails.</p> 16023</div> 16024<div class="paragraph"> 16025<p>Once you have all the data you need, you should invoke the <code>saveResource()</code> method to create a file containing your data. You can invoke <code>saveResource()</code> as many times as you wish from a single ExportMarshaller; a marshaller can therefore be used to create more than one output file.</p> 16026</div> 16027<div class="paragraph"> 16028<p>You can construct a filename for your output resource(s) by using the <code>saveResource()</code> method in the <code>AbstractDiagramWorker</code> class. There are a couple of useful variables you can have parsed, allowing you to create filenames such as _original-filename__my-format-name.xml. These variables are described in the Javadocs and defined by the <code>ExportMarshaller</code> interface. You can also use <code>resolvePlaceholders()</code> on a string (e.g. a path) if you want to parse the placeholders yourself. <code>getURIRelativeToDiagram()</code> will invoke this for you.</p> 16029</div> 16030<div class="paragraph"> 16031<p>You should use the progress monitor provided to report your progress back to the user. How to do this is described in <a href="http://www.eclipse.org/articles/Article-Progress-Monitors/article.html">this article</a>.</p> 16032</div> 16033</div> 16034</div> 16035</div> 16036</div> 16037</div> 16038<div class="sect1"> 16039<h2 id="_rest_api">13. REST API</h2> 16040<div class="sectionbody"> 16041<div class="sect2"> 16042<h3 id="_general_activiti_rest_principles">13.1. General Activiti REST principles</h3> 16043<div class="sect3"> 16044<h4 id="_installation_and_authentication">13.1.1. Installation and Authentication</h4> 16045<div class="paragraph"> 16046<p>Activiti includes a REST API to the Activiti Engine that can be installed by deploying the activiti-rest.war file to a servlet container like Apache Tomcat. However, it can also be used in another web-application by including the servlet and it’s mapping in your application and add all activiti-rest dependencies to the classpath.</p> 16047</div> 16048<div class="paragraph"> 16049<p>By default the Activiti Engine will connect to an in-memory H2 database. You can change the database settings in the db.properties file in the WEB-INF/classes folder. The REST API uses JSON format (<a href="http://www.json.org" class="bare">http://www.json.org</a>) and is built upon the Spring MVC (<a href="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html" class="bare">http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html</a>).</p> 16050</div> 16051<div class="paragraph"> 16052<p>All REST-resources require a valid Activiti-user to be authenticated by default. Basic HTTP access authentication is used, so you should always include a <code>Authorization: Basic …​==</code> HTTP-header when performing requests or include the username and password in the request-url (e.g. <code><a href="http://username:password@localhost…​" class="bare">http://username:password@localhost…​</a>;</code>).</p> 16053</div> 16054<div class="paragraph"> 16055<p><strong>It’s recommended to use Basic Authentication in combination with HTTPS.</strong></p> 16056</div> 16057</div> 16058<div class="sect3"> 16059<h4 id="_configuration_2">13.1.2. Configuration</h4> 16060<div class="paragraph"> 16061<p>The Activiti REST web application is using Spring Java Configuration for starting the Activiti Engine, defining the basic authentication security using Spring security and to define the variable converters for specific variable handling. 16062A small amount of properties can be defined by changing the engine.properties file you can find in the WEB-INF/classes folder. 16063If you need more advanced configuration options there’s the possibility to override the default Spring beans in XML in the activiti-custom-context.xml file you can also find in the WEB-INF/classes folder. 16064An example configuration is already in comments in this file. This is also the place to override the default RestResponseFactory by defining a new Spring bean with the name restResponsefactory and use your custom implementation class for it.</p> 16065</div> 16066</div> 16067<div class="sect3"> 16068<h4 id="restUsageInTomcat">13.1.3. Usage in Tomcat</h4> 16069<div class="paragraph"> 16070<p>Due to <a href="http://tomcat.apache.org/tomcat-7.0-doc/security-howto.html"> default security properties on Tomcat</a>, <strong>escaped forward slashes (<code>%2F</code> and <code>%5C</code>) are not allowed by default (400-result is returned).</strong> This may have an impact on the deployment resources and their data-URL, as the URL can potentially contain escaped forward slashes.</p> 16071</div> 16072<div class="paragraph"> 16073<p><strong>When issues are experienced with unexpected 400-results, set the following system-property: <code>-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true.</code></strong></p> 16074</div> 16075<div class="paragraph"> 16076<p>It’s a best practice to always set the <strong>Accept</strong> and <strong>Content-Type</strong> (in case of posting/putting JSON) headers to <strong>application/json</strong> on the HTTP requests described below.</p> 16077</div> 16078</div> 16079<div class="sect3"> 16080<h4 id="_methods_and_return_codes">13.1.4. Methods and return-codes</h4> 16081<table class="tableblock frame-all grid-all spread"> 16082<caption class="title">Table 2. HTTP-methods and corresponding operations</caption> 16083<colgroup> 16084<col style="width: 50%;"> 16085<col style="width: 50%;"> 16086</colgroup> 16087<thead> 16088<tr> 16089<th class="tableblock halign-left valign-top">Method</th> 16090<th class="tableblock halign-left valign-top">Operations</th> 16091</tr> 16092</thead> 16093<tbody> 16094<tr> 16095<td class="tableblock halign-left valign-top"><p class="tableblock"><code>GET</code></p></td> 16096<td class="tableblock halign-left valign-top"><p class="tableblock">Get a single resource or get a collection of resources.</p></td> 16097</tr> 16098<tr> 16099<td class="tableblock halign-left valign-top"><p class="tableblock"><code>POST</code></p></td> 16100<td class="tableblock halign-left valign-top"><p class="tableblock">Create a new resource. Also used for executing resource-queries which have a too complex request-structure to fit in the query-URL of a GET-request.</p></td> 16101</tr> 16102<tr> 16103<td class="tableblock halign-left valign-top"><p class="tableblock"><code>PUT</code></p></td> 16104<td class="tableblock halign-left valign-top"><p class="tableblock">Update properties of an existing resource. Also used for invoking actions on an existing resource.</p></td> 16105</tr> 16106<tr> 16107<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DELETE</code></p></td> 16108<td class="tableblock halign-left valign-top"><p class="tableblock">Delete an existing resource.</p></td> 16109</tr> 16110</tbody> 16111</table> 16112<table class="tableblock frame-all grid-all spread"> 16113<caption class="title">Table 3. HTTP-methods response codes</caption> 16114<colgroup> 16115<col style="width: 50%;"> 16116<col style="width: 50%;"> 16117</colgroup> 16118<thead> 16119<tr> 16120<th class="tableblock halign-left valign-top">Response</th> 16121<th class="tableblock halign-left valign-top">Description</th> 16122</tr> 16123</thead> 16124<tbody> 16125<tr> 16126<td class="tableblock halign-left valign-top"><p class="tableblock"><code>200 - Ok</code></p></td> 16127<td class="tableblock halign-left valign-top"><p class="tableblock">The operation was successful and a response has been returned (<code>GET</code> and <code>PUT</code> requests).</p></td> 16128</tr> 16129<tr> 16130<td class="tableblock halign-left valign-top"><p class="tableblock"><code>201 - Created</code></p></td> 16131<td class="tableblock halign-left valign-top"><p class="tableblock">The operation was successful and the entity has been created and is returned in the response-body (<code>POST</code> request).</p></td> 16132</tr> 16133<tr> 16134<td class="tableblock halign-left valign-top"><p class="tableblock"><code>204 - No content</code></p></td> 16135<td class="tableblock halign-left valign-top"><p class="tableblock">The operation was successful and entity has been deleted and therefore there is no response-body returned (<code>DELETE</code> request).</p></td> 16136</tr> 16137<tr> 16138<td class="tableblock halign-left valign-top"><p class="tableblock"><code>401 - Unauthorized</code></p></td> 16139<td class="tableblock halign-left valign-top"><p class="tableblock">The operation failed. The operation requires an Authentication header to be set. If this was present in the request, the supplied credentials are not valid or the user is not authorized to perform this operation.</p></td> 16140</tr> 16141<tr> 16142<td class="tableblock halign-left valign-top"><p class="tableblock"><code>403 - Forbidden</code></p></td> 16143<td class="tableblock halign-left valign-top"><p class="tableblock">The operation is forbidden and should not be re-attempted. This does not imply an issue with authentication not authorization, it’s an operation that is not allowed. Example: deleting a task that is part of a running process is not allowed and will never be allowed, regardless of the user or process/task state.</p></td> 16144</tr> 16145<tr> 16146<td class="tableblock halign-left valign-top"><p class="tableblock"><code>404 - Not found</code></p></td> 16147<td class="tableblock halign-left valign-top"><p class="tableblock">The operation failed.The requested resource was not found.</p></td> 16148</tr> 16149<tr> 16150<td class="tableblock halign-left valign-top"><p class="tableblock"><code>405 - Method not allowed</code></p></td> 16151<td class="tableblock halign-left valign-top"><p class="tableblock">The operation failed. The used method is not allowed for this resource. E.g. trying to update (PUT) a deployment-resource will result in a <code>405</code> status.</p></td> 16152</tr> 16153<tr> 16154<td class="tableblock halign-left valign-top"><p class="tableblock"><code>409 - Conflict</code></p></td> 16155<td class="tableblock halign-left valign-top"><p class="tableblock">The operation failed. The operation causes an update of a resource that has been updated by another operation, which makes the update no longer valid. Can also indicate a resource that is being created in a collection where a resource with that identifier already exists.</p></td> 16156</tr> 16157<tr> 16158<td class="tableblock halign-left valign-top"><p class="tableblock"><code>415 - Unsupported Media Type</code></p></td> 16159<td class="tableblock halign-left valign-top"><p class="tableblock">The operation failed. The request body contains an unsupported media type. Also occurs when the request-body JSON contains an unknown attribute or value that doesn’t have the right format/type to be accepted.</p></td> 16160</tr> 16161<tr> 16162<td class="tableblock halign-left valign-top"><p class="tableblock"><code>500 - Internal server error</code></p></td> 16163<td class="tableblock halign-left valign-top"><p class="tableblock">The operation failed. An unexpected exception occurred while executing the operation. The response-body contains details about the error.</p></td> 16164</tr> 16165</tbody> 16166</table> 16167<div class="paragraph"> 16168<p>The media-type of the HTTP-responses is always <code>application/json</code> unless binary content is requested (e.g. deployment resource data), the media-type of the content is used.</p> 16169</div> 16170</div> 16171<div class="sect3"> 16172<h4 id="_error_response_body">13.1.5. Error response body</h4> 16173<div class="paragraph"> 16174<p>When an error occurs (both client and server, 4XX and 5XX status-codes) the response body contains an object describing the error that occurred. An example for a 404-status when a task is not found:</p> 16175</div> 16176<div class="listingblock"> 16177<div class="content"> 16178<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 161792 161803 161814</div></td><td class="code"><span></span><span class="tok-p">{</span> 16182 <span class="tok-nt">"statusCode"</span> <span class="tok-p">:</span> <span class="tok-mi">404</span><span class="tok-p">,</span> 16183 <span class="tok-nt">"errorMessage"</span> <span class="tok-p">:</span> <span class="tok-s2">"Could not find a task with id '444'."</span> 16184<span class="tok-p">}</span> 16185</td></tr></table></code></pre> 16186</div> 16187</div> 16188</div> 16189<div class="sect3"> 16190<h4 id="_request_parameters">13.1.6. Request parameters</h4> 16191<div class="sect4"> 16192<h5 id="_url_fragments">URL fragments</h5> 16193<div class="paragraph"> 16194<p>Parameters that are part of the url (e.g. the deploymentId parameter in <code><a href="http://host/actviti-rest/service/repository/deployments/{deploymentId}" class="bare">http://host/actviti-rest/service/repository/deployments/{deploymentId}</a></code>) 16195 need to be properly escaped (see <a href="https://en.wikipedia.org/wiki/Percent-encoding">URL-encoding or Percent-encoding</a>) in case the segment contains special characters. Most frameworks have this functionality built in, but it should be taken into account. Especially for segments that can contains forward-slashes (e.g. deployment resource), this is required.</p> 16196</div> 16197</div> 16198<div class="sect4"> 16199<h5 id="_rest_url_query_parameters">Rest URL query parameters</h5> 16200<div class="paragraph"> 16201<p>Parameters added as query-string in the URL (e.g. the name parameter used in <code><a href="http://host/activiti-rest/service/deployments?name=Deployment" class="bare">http://host/activiti-rest/service/deployments?name=Deployment</a></code>) can have the following types and are mentioned in the corresponding REST-API documentation:</p> 16202</div> 16203<table class="tableblock frame-all grid-all spread"> 16204<caption class="title">Table 4. URL query parameter types</caption> 16205<colgroup> 16206<col style="width: 50%;"> 16207<col style="width: 50%;"> 16208</colgroup> 16209<thead> 16210<tr> 16211<th class="tableblock halign-left valign-top">Type</th> 16212<th class="tableblock halign-left valign-top">Format</th> 16213</tr> 16214</thead> 16215<tbody> 16216<tr> 16217<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16218<td class="tableblock halign-left valign-top"><p class="tableblock">Plain text parameters. Can contain any valid characters that are allowed in URL’s. In case of a <code>XXXLike</code> parameter, the string should contain the wildcard character <code>%</code> (properly url-encoded). This allows to specify the intent of the like-search. E.g. <em><code>Tas%</code></em> matches all values, starting with <em>Tas</em>.</p></td> 16219</tr> 16220<tr> 16221<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 16222<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647.</p></td> 16223</tr> 16224<tr> 16225<td class="tableblock halign-left valign-top"><p class="tableblock">Long</p></td> 16226<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing a long value. Can only contain numeric non-decimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807.
16226</p></td> 16227</tr> 16228<tr> 16229<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 16230<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing a boolean value. Can be either <code>true</code> or <code>false</code>. All other values other than these two, will cause a <em><code>405 - Bad request</code></em> response.</p></td> 16231</tr> 16232<tr> 16233<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 16234<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing a date value. Use the ISO-8601 date-format (see <a href="http://en.wikipedia.org/wiki/ISO_8601">ISO-8601 on wikipedia</a>) using both time and date-components (e.g. <code>2013-04-03T23:45Z</code>).</p></td> 16235</tr> 16236</tbody> 16237</table> 16238</div> 16239<div class="sect4"> 16240<h5 id="restJsonBody">JSON body parameters</h5> 16241<table class="tableblock frame-all grid-all spread"> 16242<caption class="title">Table 5. JSON parameter types</caption> 16243<colgroup> 16244<col style="width: 50%;"> 16245<col style="width: 50%;"> 16246</colgroup> 16247<thead> 16248<tr> 16249<th class="tableblock halign-left valign-top">Type</th> 16250<th class="tableblock halign-left valign-top">Format</th> 16251</tr> 16252</thead> 16253<tbody> 16254<tr> 16255<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16256<td class="tableblock halign-left valign-top"><p class="tableblock">Plain text parameters. In case of a <code>XXXLike</code> parameter, the string should contain the wildcard character <code>%</code>. This allows to specify the intent of the like-search. E.g. <em><code>Tas%</code></em> matches all values, starting with <em>Tas</em>.</p></td> 16257</tr> 16258<tr> 16259<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 16260<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing an integer value, using a JSON number. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647.</p></td> 16261</tr> 16262<tr> 16263<td class="tableblock halign-left valign-top"><p class="tableblock">Long</p></td> 16264<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing a long value, using a JSON number. Can only contain numeric non-decimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807.</p></td> 16265</tr> 16266<tr> 16267<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 16268<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter representing a date value, using a JSON text. Use the ISO-8601 date-format (see <a href="http://en.wikipedia.org/wiki/ISO_8601">ISO-8601 on wikipedia</a>) using both time and date-components (e.g. <code>2013-04-03T23:45Z</code>).</p></td> 16269</tr> 16270</tbody> 16271</table> 16272</div> 16273<div class="sect4"> 16274<h5 id="restPagingAndSort">Paging and sorting</h5> 16275<div class="paragraph"> 16276<p>Paging and order parameters can be added as query-string in the URL (e.g. the name parameter used in <code><a href="http://host/activiti-rest/service/deployments?sort=name" class="bare">http://host/activiti-rest/service/deployments?sort=name</a></code>).</p> 16277</div> 16278<table class="tableblock frame-all grid-all spread"> 16279<caption class="title">Table 6. Variable query JSON parameters</caption> 16280<colgroup> 16281<col style="width: 33.3333%;"> 16282<col style="width: 33.3333%;"> 16283<col style="width: 33.3334%;"> 16284</colgroup> 16285<thead> 16286<tr> 16287<th class="tableblock halign-left valign-top">Parameter</th> 16288<th class="tableblock halign-left valign-top">Default value</th> 16289<th class="tableblock halign-left valign-top">Description</th> 16290</tr> 16291</thead> 16292<tbody> 16293<tr> 16294<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 16295<td class="tableblock halign-left valign-top"><p class="tableblock">different per query implementation</p></td> 16296<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the sort key, for which the default value and the allowed values are different per query implementation.</p></td> 16297</tr> 16298<tr> 16299<td class="tableblock halign-left valign-top"><p class="tableblock">order</p></td> 16300<td class="tableblock halign-left valign-top"><p class="tableblock">asc</p></td> 16301<td class="tableblock halign-left valign-top"><p class="tableblock">Sorting order which can be <em>asc</em> or <em>desc</em>.</p></td> 16302</tr> 16303<tr> 16304<td class="tableblock halign-left valign-top"><p class="tableblock">start</p></td> 16305<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> 16306<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter to allow for paging of the result. By default the result will start at 0.</p></td> 16307</tr> 16308<tr> 16309<td class="tableblock halign-left valign-top"><p class="tableblock">size</p></td> 16310<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td> 16311<td class="tableblock halign-left valign-top"><p class="tableblock">Parameter to allow for paging of the result. By default the size will be 10.</p></td> 16312</tr> 16313</tbody> 16314</table> 16315</div> 16316<div class="sect4"> 16317<h5 id="restQueryVariable">JSON query variable format</h5> 16318<div class="listingblock"> 16319<div class="content"> 16320<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 163212 163223 163234 163245 163256</div></td><td class="code"><span></span><span class="tok-p">{</span> 16326 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"variableName"</span><span class="tok-p">,</span> 16327 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"variableValue"</span><span class="tok-p">,</span> 16328 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 16329 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"
16329string"</span> 16330<span class="tok-p">}</span> 16331</td></tr></table></code></pre> 16332</div> 16333</div> 16334<table class="tableblock frame-all grid-all spread"> 16335<caption class="title">Table 7. Variable query JSON parameters</caption> 16336<colgroup> 16337<col style="width: 33.3333%;"> 16338<col style="width: 33.3333%;"> 16339<col style="width: 33.3334%;"> 16340</colgroup> 16341<thead> 16342<tr> 16343<th class="tableblock halign-left valign-top">Parameter</th> 16344<th class="tableblock halign-left valign-top">Required</th> 16345<th class="tableblock halign-left valign-top">Description</th> 16346</tr> 16347</thead> 16348<tbody> 16349<tr> 16350<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 16351<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16352<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the variable to include in a query. Can be empty in case <em><code>equals</code></em> is used in some queries to query for resources that have <strong>any variable name</strong> with the given value.</p></td> 16353</tr> 16354<tr> 16355<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td> 16356<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 16357<td class="tableblock halign-left valign-top"><p class="tableblock">Value of the variable included in the query, should include a correct format for the given type.</p></td> 16358</tr> 16359<tr> 16360<td class="tableblock halign-left valign-top"><p class="tableblock">operator</p></td> 16361<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 16362<td class="tableblock halign-left valign-top"><p class="tableblock">Operator to use in query, can have the following values: <code>equals, notEquals, equalsIgnoreCase, notEqualsIgnoreCase, lessThan, greaterThan, lessThanOrEquals, greaterThanOrEquals</code> and <code>like</code>.</p></td> 16363</tr> 16364<tr> 16365<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td> 16366<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16367<td class="tableblock halign-left valign-top"><p class="tableblock">Type of variable to use. When omitted, the type will be deducted from the <code>value</code> parameter. Any JSON text-values will be considered of type <code>string</code>, JSON booleans of type <code>boolean</code>, JSON numbers of type <code>long</code> or <code>integer</code> depending on the size of the number. It’s recommended to include an explicit type when in doubt. Types supported out of the box are listed below.</p></td> 16368</tr> 16369</tbody> 16370</table> 16371<table class="tableblock frame-all grid-all spread"> 16372<caption class="title">Table 8. Default query JSON types</caption> 16373<colgroup> 16374<col style="width: 50%;"> 16375<col style="width: 50%;"> 16376</colgroup> 16377<thead> 16378<tr> 16379<th class="tableblock halign-left valign-top">Type name</th> 16380<th class="tableblock halign-left valign-top">Description</th> 16381</tr> 16382</thead> 16383<tbody> 16384<tr> 16385<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 16386<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as and converted to a <code>java.lang.String</code>.</p></td> 16387</tr> 16388<tr> 16389<td class="tableblock halign-left valign-top"><p class="tableblock">short</p></td> 16390<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as and converted to a <code>java.lang.Integer</code>.</p></td> 16391</tr> 16392<tr> 16393<td class="tableblock halign-left valign-top"><p class="tableblock">integer</p></td> 16394<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as and converted to a <code>java.lang.Integer</code>.</p></td> 16395</tr> 16396<tr> 16397<td class="tableblock halign-left valign-top"><p class="tableblock">long</p></td> 16398<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as and converted to a <code>java.lang.Long</code>.</p></td> 16399</tr> 16400<tr> 16401<td class="tableblock halign-left valign-top"><p class="tableblock">double</p></td> 16402<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as and converted to a <code>java.lang.Double</code>.</p></td> 16403</tr> 16404<tr> 16405<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td> 16406<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as and converted to a <code>java.lang.Boolean</code>.</p></td> 16407</tr> 16408<tr> 16409<td class="tableblock halign-left valign-top"><p class="tableblock">date</p></td> 16410<td class="tableblock halign-left valign-top"><p class="tableblock">Value is treated as and converted to a <code>java.util.Date</code>. The JSON string will be converted using ISO-8601 date format.</p></td> 16411</tr> 16412</tbody> 16413</table> 16414</div> 16415<div class="sect4"> 16416<h5 id="restVariables">Variable representation</h5> 16417<div class="paragraph"> 16418<p>When working with variables (execution/process and task), the REST-api uses some common principles and JSON-format for both reading and writing. The JSON representation of a variable looks like this:</p> 16419</div> 16420<div class="listingblock"> 16421<div class="content"> 16422<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 164232 164243 164254 164265 164276 164287</div></td><td class="code"><span></span><span class="tok-p">{</span> 16429 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"variableName"</span><span class="tok-p">,</span> 16430 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"variableValue"</span><span class="tok-p">,</span> 16431 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://..."</span><span class="tok-p">,</span> 16432 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 16433 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"
16433string"</span> 16434<span class="tok-p">}</span> 16435</td></tr></table></code></pre> 16436</div> 16437</div> 16438<table class="tableblock frame-all grid-all spread"> 16439<caption class="title">Table 9. Variable JSON attributes</caption> 16440<colgroup> 16441<col style="width: 33.3333%;"> 16442<col style="width: 33.3333%;"> 16443<col style="width: 33.3334%;"> 16444</colgroup> 16445<thead> 16446<tr> 16447<th class="tableblock halign-left valign-top">Parameter</th> 16448<th class="tableblock halign-left valign-top">Required</th> 16449<th class="tableblock halign-left valign-top">Description</th> 16450</tr> 16451</thead> 16452<tbody> 16453<tr> 16454<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 16455<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 16456<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the variable.</p></td> 16457</tr> 16458<tr> 16459<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td> 16460<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16461<td class="tableblock halign-left valign-top"><p class="tableblock">Value of the variable. When writing a variable and <code>value</code> is omitted, <code>null</code> will be used as value.</p></td> 16462</tr> 16463<tr> 16464<td class="tableblock halign-left valign-top"><p class="tableblock">valueUrl</p></td> 16465<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16466<td class="tableblock halign-left valign-top"><p class="tableblock">When reading a variable of type <code>binary</code> or <code>serializable</code>, this attribute will point to the URL where the raw binary data can be fetched from.</p></td> 16467</tr> 16468<tr> 16469<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 16470<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16471<td class="tableblock halign-left valign-top"><p class="tableblock">Scope of the variable. If <em><code>local</code></em>, the variable is explicitly defined on the resource it’s requested from. When <em><code>global</code></em>, the variable is defined on the parent (or any parent in the parent-tree) of the resource it’s requested from. When writing a variable and the scope is omitted, <code>global</code> is assumed.</p></td> 16472</tr> 16473<tr> 16474<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td> 16475<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16476<td class="tableblock halign-left valign-top"><p class="tableblock">Type of the variable. See table below for additional information on types. When writing a variable and this value is omitted, the type will be deducted from the raw JSON-attribute request type and is limited to either <code>string</code>, <code>double</code>, <code>integer</code> and <code>boolean</code>. It’s advised to always include a type to make sure no wrong assumption about the type can be done.</p></td> 16477</tr> 16478</tbody> 16479</table> 16480<table class="tableblock frame-all grid-all spread"> 16481<caption class="title">Table 10. Variable Types</caption> 16482<colgroup> 16483<col style="width: 50%;"> 16484<col style="width: 50%;"> 16485</colgroup> 16486<thead> 16487<tr> 16488<th class="tableblock halign-left valign-top">Type name</th> 16489<th class="tableblock halign-left valign-top">Description</th> 16490</tr> 16491</thead> 16492<tbody> 16493<tr> 16494<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 16495<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as a <code>java.lang.String</code>. Raw JSON-text value is used when writing a variable.</p></td> 16496</tr> 16497<tr> 16498<td class="tableblock halign-left valign-top"><p class="tableblock">integer</p></td> 16499<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as a <code>java.lang.Integer</code>. When writing, JSON number value is used as base for conversion, falls back to JSON text.</p></td> 16500</tr> 16501<tr> 16502<td class="tableblock halign-left valign-top"><p class="tableblock">short</p></td> 16503<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as a <code>java.lang.Short</code>. When writing, JSON number value is used as base for conversion, falls back to JSON text.</p></td> 16504</tr> 16505<tr> 16506<td class="tableblock halign-left valign-top"><p class="tableblock">long</p></td> 16507<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as a <code>java.lang.Long</code>. When writing, JSON number value is used as base for conversion, falls back to JSON text.</p></td> 16508</tr> 16509<tr> 16510<td class="tableblock halign-left valign-top"><p class="tableblock">double</p></td> 16511<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as a <code>java.lang.Double</code>. When writing, JSON number value is used as base for conversion, falls back to JSON text.</p></td> 16512</tr> 16513<tr> 16514<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td> 16515<td class="tableblock halign-left valign-top"><p class="tableblock">Value is threaded as a <code>java.lang.Boolean</code>
16515. When writing, JSON boolean value is used for conversion.</p></td> 16516</tr> 16517<tr> 16518<td class="tableblock halign-left valign-top"><p class="tableblock">date</p></td> 16519<td class="tableblock halign-left valign-top"><p class="tableblock">Value is treated as a <code>java.util.Date</code>. When writing, the JSON text will be converted using ISO-8601 date format.</p></td> 16520</tr> 16521<tr> 16522<td class="tableblock halign-left valign-top"><p class="tableblock">binary</p></td> 16523<td class="tableblock halign-left valign-top"><p class="tableblock">Binary variable, treated as an array of bytes. The <code>value</code> attribute is null, the <code>valueUrl</code> contains an URL pointing to the raw binary stream.</p></td> 16524</tr> 16525<tr> 16526<td class="tableblock halign-left valign-top"><p class="tableblock">serializable</p></td> 16527<td class="tableblock halign-left valign-top"><p class="tableblock">Serialized representation of a Serializable Java-object. As with the <code>binary</code> type, the <code>value</code> attribute is null, the <code>valueUrl</code> contains an URL pointing to the raw binary stream. All serializable variables (which are not of any of the above types) will be exposed as a variable of this type.</p></td> 16528</tr> 16529</tbody> 16530</table> 16531<div class="paragraph"> 16532<p>It’s possible to support additional variable-types with a custom JSON representation (either simple value or complex/nested JSON object). By extending the <code>initializeVariableConverters()</code> method on <code>org.activiti.rest.service.api.RestResponseFactory</code>, you can add additional <code>org.activiti.rest.service.api.engine.variable.RestVariableConverter</code> classes to support converting your POJO’s to a format suitable for transferring through REST and converting the REST-value back to your POJO. The actual transformation to JSON is done by Jackson.</p> 16533</div> 16534</div> 16535</div> 16536</div> 16537<div class="sect2"> 16538<h3 id="_deployment">13.2. Deployment</h3> 16539<div class="paragraph"> 16540<p><strong>When using tomcat, please read <a href="#restUsageInTomcat">Usage in Tomcat</a>.</strong></p> 16541</div> 16542<div class="sect3"> 16543<h4 id="_list_of_deployments">13.2.1. List of Deployments</h4> 16544<div class="listingblock"> 16545<div class="content"> 16546<pre>GET repository/deployments</pre> 16547</div> 16548</div> 16549<table class="tableblock frame-all grid-all spread"> 16550<caption class="title">Table 11. URL query parameters</caption> 16551<colgroup> 16552<col style="width: 25%;"> 16553<col style="width: 25%;"> 16554<col style="width: 25%;"> 16555<col style="width: 25%;"> 16556</colgroup> 16557<thead> 16558<tr> 16559<th class="tableblock halign-left valign-top">Parameter</th> 16560<th class="tableblock halign-left valign-top">Required</th> 16561<th class="tableblock halign-left valign-top">Value</th> 16562<th class="tableblock halign-left valign-top">Description</th> 16563</tr> 16564</thead> 16565<tbody> 16566<tr> 16567<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 16568<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16569<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16570<td class="tableblock halign-left valign-top"><p class="tableblock">Only return deployments with the given name.</p></td> 16571</tr> 16572<tr> 16573<td class="tableblock halign-left valign-top"><p class="tableblock">nameLike</p></td> 16574<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16575<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16576<td class="tableblock halign-left valign-top"><p class="tableblock">Only return deployments with a name like the given name.</p></td> 16577</tr> 16578<tr> 16579<td class="tableblock halign-left valign-top"><p class="tableblock">category</p></td> 16580<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16581<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16582<td class="tableblock halign-left valign-top"><p class="tableblock">Only return deployments with the given category.</p></td> 16583</tr> 16584<tr> 16585<td class="tableblock halign-left valign-top"><p class="tableblock">categoryNotEquals</p></td> 16586<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16587<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16588<td class="tableblock halign-left valign-top"><p class="tableblock">Only return deployments which don’t have the given category.</p></td> 16589</tr> 16590<tr> 16591<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 16592<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16593<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16594<td class="tableblock halign-left valign-top"><p class="tableblock">Only return deployments with the given tenantId.</p></td> 16595</tr> 16596<tr> 16597<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 16598<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16599<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16600<td class="tableblock halign-left valign-top"><p class="tableblock">Only return deployments with a tenantId like the given value.</p></td> 16601</tr> 16602<tr> 16603<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 16604<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16605<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 16606<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns deployments without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 16607</tr> 16608<tr> 16609<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 16610<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 16611<td class="tableblock halign-left valign-top"><p class="tableblock"><em>id</em> (default), <em>
16611name</em>, <em>deploytime</em> or <em>tenantId</em></p></td> 16612<td class="tableblock halign-left valign-top"><p class="tableblock">Property to sort on, to be used together with the <em>order</em>.</p></td> 16613</tr> 16614</tbody> 16615</table> 16616<table class="tableblock frame-all grid-all spread"> 16617<caption class="title">Table 12. REST Response codes</caption> 16618<colgroup> 16619<col style="width: 50%;"> 16620<col style="width: 50%;"> 16621</colgroup> 16622<thead> 16623<tr> 16624<th class="tableblock halign-left valign-top">Response code</th> 16625<th class="tableblock halign-left valign-top">Description</th> 16626</tr> 16627</thead> 16628<tbody> 16629<tr> 16630<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 16631<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the request was successful.</p></td> 16632</tr> 16633</tbody> 16634</table> 16635<div class="paragraph"> 16636<p><strong>Success response body:</strong></p> 16637</div> 16638<div class="listingblock"> 16639<div class="content"> 16640<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 16641 2 16642 3 16643 4 16644 5 16645 6 16646 7 16647 8 16648 9 1664910 1665011 1665112 1665213 1665314 1665415 1665516 1665617</div></td><td class="code"><span></span><span class="tok-p">{</span> 16657 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 16658 <span class="tok-p">{</span> 16659 <span class="tok-nt">"id"</span><span class="tok-p">:</span> <span class="tok-s2">"10"</span><span class="tok-p">,</span> 16660 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"activiti-examples.bar"</span><span class="tok-p">,</span> 16661 <span class="tok-nt">"deploymentTime"</span><span class="tok-p">:</span> <span class="tok-s2">"2010-10-13T14:54:26.750+02:00"</span><span class="tok-p">,</span> 16662 <span class="tok-nt">"category"</span><span class="tok-p">:</span> <span class="tok-s2">"examples"</span><span class="tok-p">,</span> 16663 <span class="tok-nt">"url"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/service/repository/deployments/10"</span><span class="tok-p">,</span> 16664 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span> <span class="tok-kc">null</span> 16665 <span class="tok-p">}</span> 16666 <span class="tok-p">],</span> 16667 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 16668 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 16669 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"id"</span><span class="tok-p">,</span> 16670 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 16671 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 16672<span class="tok-p">}</span> 16673</td></tr></table></code></pre> 16674</div> 16675</div> 16676</div> 16677<div class="sect3"> 16678<h4 id="_get_a_deployment">13.2.2. Get a deployment</h4> 16679<div class="listingblock"> 16680<div class="content"> 16681<pre>GET repository/deployments/{deploymentId}</pre> 16682</div> 16683</div> 16684<table class="tableblock frame-all grid-all spread"> 16685<caption class="title">Table 13. Get a deployment - URL parameters</caption> 16686<colgroup> 16687<col style="width: 25%;"> 16688<col style="width: 25%;"> 16689<col style="width: 25%;"> 16690<col style="width: 25%;"> 16691</colgroup> 16692<thead> 16693<tr> 16694<th class="tableblock halign-left valign-top">Parameter</th> 16695<th class="tableblock halign-left valign-top">Required</th> 16696<th class="tableblock halign-left valign-top">Value</th> 16697<th class="tableblock halign-left valign-top">Description</th> 16698</tr> 16699</thead> 16700<tbody> 16701<tr> 16702<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 16703<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 16704<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16705<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the deployment to get.</p></td> 16706</tr> 16707</tbody> 16708</table> 16709<table class="tableblock frame-all grid-all spread"> 16710<caption class="title">Table 14. Get a deployment - Response codes</caption> 16711<colgroup> 16712<col style="width: 50%;"> 16713<col style="width: 50%;"> 16714</colgroup> 16715<thead> 16716<tr> 16717<th class="tableblock halign-left valign-top">Response code</th> 16718<th class="tableblock halign-left valign-top">Description</th> 16719</tr> 16720</thead> 16721<tbody> 16722<tr> 16723<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 16724<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the deployment was found and returned.</p></td> 16725</tr> 16726<tr> 16727<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 16728<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested deployment was not found.</p></td> 16729</tr> 16730</tbody> 16731</table> 16732<div class="paragraph"> 16733<p><strong>Success response body:</strong></p> 16734</div> 16735<div class="listingblock"> 16736<div class="content"> 16737<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 167382 167393 167404 167415 167426 167437 167448</div></td><td class="code"><span></span><span class="tok-p">{</span> 16745 <span class="tok-nt">"id"</span><span class="tok-p">:</span> <span class="tok-s2">"10"</span><span class="tok-p">,</span> 16746 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"activiti-examples.bar"</span><span class="tok-p">,</span> 16747 <span class="tok-nt">"deploymentTime"</span><span class="tok-p">:</span> <span class="tok-s2">"2010-10-13T14:54:26.750+02:00"</span><span class="tok-p">,</span> 16748 <span class="tok-nt">"category"</span><span class="tok-p">:</span> <span class="tok-s2">"examples"</span><span class="tok-p">,</span> 16749 <span class="tok-nt">"url"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/service/repository/deployments/10"</span><span class="tok-p">,</span> 16750 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 16751<span class="tok-p">}</span> 16752</td></tr></table></code></pre> 16753</div> 16754</div> 16755</div> 16756<div class="sect3"> 16757<h4 id="_create_a_new_deployment">13.2.3. Create a new deployment</h4> 16758<div class="listingblock"> 16759<div class="content"> 16760<pre>POST repository/deployments</pre> 16761</div> 16762</div> 16763<div class="paragraph"> 16764<p><strong>Request body:</strong></p> 16765</div> 16766<div class="paragraph"> 16767<p>The request body should contain data of type <em>multipart/form-data</em>. There should be exactly one file in the request, any additional files will be ignored. The deployment name is the name of the file-field passed in. If multiple resources need to be deployed in a single deployment, compress the resources in a zip and make sure the file-name ends with <code>.bar</code> or <code>.zip</code>.</p> 16768</div> 16769<div class="paragraph"> 16770<p>An additional parameter (form-field) can be passed in the request body with name <code>tenantId</code>. The value of this field will be used as the id of the tenant this deployment is done in.</p> 16771</div> 16772<table class="tableblock frame-all grid-all spread"> 16773<caption class="title">Table 15. Create a new deployment - Response codes</caption> 16774<colgroup> 16775<col style="width: 50%;"> 16776<col style="width: 50%;"> 16777</colgroup> 16778<thead> 16779<tr> 16780<th class="tableblock halign-left valign-top">Response code</th> 16781<th class="tableblock halign-left valign-top">Description</th> 16782</tr> 16783</thead> 16784<tbody> 16785<tr> 16786<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 16787<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the deployment was created.</p></td> 16788</tr> 16789<tr> 16790<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 16791<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates there was no content present in the request body or the content mime-type is not supported for deployment. The status-description contains additional information.</p></td> 16792</tr> 16793</tbody> 16794</table> 16795<div class="paragraph"> 16796<p><strong>Success response body:</strong></p> 16797</div> 16798<div class="listingblock"> 16799<div class="content"> 16800<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 168012 168023 168034 168045 168056 168067 168078</div></td><td class="code"><span></span><span class="tok-p">{</span> 16808 <span class="tok-nt">"id"</span><span class="tok-p">:</span> <span class="tok-s2">"10"</span><span class="tok-p">,</span> 16809 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"activiti-examples.bar"</span><span class="tok-p">,</span> 16810 <span class="tok-nt">"deploymentTime"</span><span class="tok-p">:</span> <span class="tok-s2">"2010-10-13T14:54:26.750+02:00"</span><span class="tok-p">,</span> 16811 <span class="tok-nt">"category"</span><span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 16812 <span class="tok-nt">"url"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/service/repository/deployments/10"</span><span class="tok-p">,</span> 16813 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTenant"</span> 16814<span class="tok-p">}</span> 16815</td></tr></table></code></pre> 16816</div> 16817</div> 16818</div> 16819<div class="sect3"> 16820<h4 id="_delete_a_deployment">13.2.4. Delete a deployment</h4> 16821<div class="listingblock"> 16822<div class="content"> 16823<pre>DELETE repository/deployments/{deploymentId}</pre> 16824</div> 16825</div> 16826<table class="tableblock frame-all grid-all spread"> 16827<caption class="title">Table 16. Delete a deployment - URL parameters</caption> 16828<colgroup> 16829<col style="width: 25%;"> 16830<col style="width: 25%;"> 16831<col style="width: 25%;"> 16832<col style="width: 25%;"> 16833</colgroup> 16834<thead> 16835<tr> 16836<th class="tableblock halign-left valign-top">Parameter</th> 16837<th class="tableblock halign-left valign-top">Required</th> 16838<th class="tableblock halign-left valign-top">Value</th> 16839<th class="tableblock halign-left valign-top">Description</th> 16840</tr> 16841</thead> 16842<tbody> 16843<tr> 16844<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 16845<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 16846<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16847<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the deployment to delete.</p></td> 16848</tr> 16849</tbody> 16850</table> 16851<table class="tableblock frame-all grid-all spread"> 16852<caption class="title">Table 17. Delete a deployment - Response codes</caption> 16853<colgroup> 16854<col style="width: 50%;"> 16855<col style="width: 50%;"> 16856</colgroup> 16857<thead> 16858<tr> 16859<th class="tableblock halign-left valign-top">Response code</th> 16860<th class="tableblock halign-left valign-top">Description</th> 16861</tr> 16862</thead> 16863<tbody> 16864<tr> 16865<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 16866<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the deployment was found and has been deleted. Response-body is intentionally empty.</p></td> 16867</tr> 16868<tr> 16869<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 16870<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested deployment was not found.</p></td> 16871</tr> 16872</tbody> 16873</table> 16874</div> 16875<div class="sect3"> 16876<h4 id="_list_resources_in_a_deployment">13.2.5. List resources in a deployment</h4> 16877<div class="listingblock"> 16878<div class="content"> 16879<pre>GET repository/deployments/{deploymentId}/resources</pre> 16880</div> 16881</div> 16882<table class="tableblock frame-all grid-all spread"> 16883<caption class="title">Table 18. List resources in a deployment - URL parameters</caption> 16884<colgroup> 16885<col style="width: 25%;"> 16886<col style="width: 25%;"> 16887<col style="width: 25%;"> 16888<col style="width: 25%;"> 16889</colgroup> 16890<thead> 16891<tr> 16892<th class="tableblock halign-left valign-top">Parameter</th> 16893<th class="tableblock halign-left valign-top">Required</th> 16894<th class="tableblock halign-left valign-top">Value</th> 16895<th class="tableblock halign-left valign-top">Description</th> 16896</tr> 16897</thead> 16898<tbody> 16899<tr> 16900<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 16901<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 16902<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 16903<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the deployment to get the resources for.</p></td> 16904</tr> 16905</tbody> 16906</table> 16907<table class="tableblock frame-all grid-all spread"> 16908<caption class="title">Table 19. List resources in a deployment - Response codes</caption> 16909<colgroup> 16910<col style="width: 50%;"> 16911<col style="width: 50%;"> 16912</colgroup> 16913<thead> 16914<tr> 16915<th class="tableblock halign-left valign-top">Response code</th> 16916<th class="tableblock halign-left valign-top">Description</th> 16917</tr> 16918</thead> 16919<tbody> 16920<tr> 16921<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 16922<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the deployment was found and the resource list has been returned.</p></td> 16923</tr> 16924<tr> 16925<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 16926<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested deployment was not found.</p></td> 16927</tr> 16928</tbody> 16929</table> 16930<div class="paragraph"> 16931<p><strong>Success response body:</strong></p> 16932</div> 16933<div class="listingblock"> 16934<div class="content"> 16935<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 16936 2 16937 3 16938 4 16939 5 16940 6 16941 7 16942 8 16943 9 1694410 1694511 1694612 1694713 1694814 1694915 1695016</div></td><td class="code"><span></span><span class="tok-p">[</span> 16951 <span class="tok-p">{</span> 16952 <span class="tok-nt">"id"</span><span class="tok-p">:</span> <span class="tok-s2">"diagrams/my-process.bpmn20.xml"</span><span class="tok-p">,</span> 16953 <span class="tok-nt">"url"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/repository/deployments/10/resources/diagrams%2Fmy-process.bpmn20.xml"</span><span class="tok-p">,</span> 16954 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/repository/deployments/10/resourcedata/diagrams%2Fmy-process.bpmn20.xml"</span><span class="tok-p">,</span> 16955 <span class="tok-nt">"mediaType"</span><span class="tok-p">:</span> <span class="tok-s2">"text/xml"</span><span class="tok-p">,</span> 16956 <span class="tok-nt">"type"</span><span class="tok-p">:</span> <span class="tok-s2">"processDefinition"</span> 16957 <span class="tok-p">},</span> 16958 <span class="tok-p">{</span> 16959 <span class="tok-nt">"id"</span><span class="tok-p">:</span> <span class="tok-s2">"image.png"</span><span class="tok-p">,</span> 16960 <span class="tok-nt">"url"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/repository/deployments/10/resources/image.png"</span><span class="tok-p">,</span> 16961 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/repository/deployments/10/resourcedata/image.png"</span><span class="tok-p">,</span> 16962 <span class="tok-nt">"mediaType"</span><span class="tok-p">:</span> <span class="tok-s2">"image/png"</span><span class="tok-p">,</span> 16963 <span class="tok-nt">"type"</span><span class="tok-p">:</span> <span class="tok-s2">"resource"</span> 16964 <span class="tok-p">}</span> 16965<span class="tok-p">]</span> 16966</td></tr></table></code></pre> 16967</div> 16968</div> 16969<div class="ulist"> 16970<ul> 16971<li> 16972<p><code>mediaType</code>: Contains the media-type the resource has. This is resolved using a (pluggable) <co
16972de>MediaTypeResolver</code> and contains, by default, a limited number of mime-type mappings.</p> 16973</li> 16974<li> 16975<p><code>type</code>: Type of resource, possible values:</p> 16976</li> 16977<li> 16978<p><code>resource</code>: Plain old resource.</p> 16979</li> 16980<li> 16981<p><code>processDefinition</code>: Resource that contains one or more process-definitions. This resource is picked up by the deployer.</p> 16982</li> 16983<li> 16984<p><code>processImage</code>: Resource that represents a deployed process definition’s graphical layout.</p> 16985</li> 16986</ul> 16987</div> 16988<div class="paragraph"> 16989<p><em>The contentUrl property in the resulting JSON for a single resource contains the actual URL to use for retrieving the binary resource.</em></p> 16990</div> 16991</div> 16992<div class="sect3"> 16993<h4 id="_get_a_deployment_resource">13.2.6. Get a deployment resource</h4> 16994<div class="listingblock"> 16995<div class="content"> 16996<pre>GET repository/deployments/{deploymentId}/resources/{resourceId}</pre> 16997</div> 16998</div> 16999<table class="tableblock frame-all grid-all spread"> 17000<caption class="title">Table 20. Get a deployment resource - URL parameters</caption> 17001<colgroup> 17002<col style="width: 25%;"> 17003<col style="width: 25%;"> 17004<col style="width: 25%;"> 17005<col style="width: 25%;"> 17006</colgroup> 17007<thead> 17008<tr> 17009<th class="tableblock halign-left valign-top">Parameter</th> 17010<th class="tableblock halign-left valign-top">Required</th> 17011<th class="tableblock halign-left valign-top">Value</th> 17012<th class="tableblock halign-left valign-top">Description</th> 17013</tr> 17014</thead> 17015<tbody> 17016<tr> 17017<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 17018<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17019<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17020<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the deployment the requested resource is part of.</p></td> 17021</tr> 17022<tr> 17023<td class="tableblock halign-left valign-top"><p class="tableblock">resourceId</p></td> 17024<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17025<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17026<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the resource to get. <strong>Make sure you URL-encode the resourceId in case it contains forward slashes. Eg: use <em>diagrams%2Fmy-process.bpmn20.xml</em> instead of <em>diagrams/Fmy-process.bpmn20.xml</em>.</strong></p></td> 17027</tr> 17028</tbody> 17029</table> 17030<table class="tableblock frame-all grid-all spread"> 17031<caption class="title">Table 21. Get a deployment resource - Response codes</caption> 17032<colgroup> 17033<col style="width: 50%;"> 17034<col style="width: 50%;"> 17035</colgroup> 17036<thead> 17037<tr> 17038<th class="tableblock halign-left valign-top">Response code</th> 17039<th class="tableblock halign-left valign-top">Description</th> 17040</tr> 17041</thead> 17042<tbody> 17043<tr> 17044<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17045<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates both deployment and resource have been found and the resource has been returned.</p></td> 17046</tr> 17047<tr> 17048<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17049<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested deployment was not found or there is no resource with the given id present in the deployment. The status-description contains additional information.</p></td> 17050</tr> 17051</tbody> 17052</table> 17053<div class="paragraph"> 17054<p><strong>Success response body:</strong></p> 17055</div> 17056<div class="listingblock"> 17057<div class="content"> 17058<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 170592 170603 170614 170625 170636 170647</div></td><td class="code"><span></span><span class="tok-p">{</span> 17065 <span class="tok-nt">"id"</span><span class="tok-p">:</span> <span class="tok-s2">"diagrams/my-process.bpmn20.xml"</span><span class="tok-p">,</span> 17066 <span class="tok-nt">"url"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/repository/deployments/10/resources/diagrams%2Fmy-process.bpmn20.xml"</span><span class="tok-p">,</span> 17067 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/repository/deployments/10/resourcedata/diagrams%2Fmy-process.bpmn20.xml"</span><span class="tok-p">,</span> 17068 <span class="tok-nt">"mediaType"</span><span class="tok-p">:</span> <span class="tok-s2">"text/xml"</span><span class="tok-p">,</span> 17069 <span class="tok-nt">"type"</span><span class="tok-p">:</span> <span class="tok-s2">"processDefinition"</span> 17070<span class="tok-p">}</span> 17071</td></tr></table></code></pre> 17072</div> 17073</div> 17074<div class="ulist"> 17075<ul> 17076<li> 17077<p><code>mediaType</code>: Contains the media-type the resource has. This is resolved using a (pluggable) <code>MediaTypeResolver</code> and contains, by default, a limited number of mime-type mappings.</p> 17078</li> 17079<li> 17080<p><code>type</code>: Type of resource, possible values:</p> 17081</li> 17082<li> 17083<p><code>resource</code>: Plain old resource.</p> 17084</li> 17085<li> 17086<p><code>processDefinition</code>
17086: Resource that contains one or more process-definitions. This resource is picked up by the deployer.</p> 17087</li> 17088<li> 17089<p><code>processImage</code>: Resource that represents a deployed process definition’s graphical layout.</p> 17090</li> 17091</ul> 17092</div> 17093</div> 17094<div class="sect3"> 17095<h4 id="_get_a_deployment_resource_content">13.2.7. Get a deployment resource content</h4> 17096<div class="listingblock"> 17097<div class="content"> 17098<pre>GET repository/deployments/{deploymentId}/resourcedata/{resourceId}</pre> 17099</div> 17100</div> 17101<table class="tableblock frame-all grid-all spread"> 17102<caption class="title">Table 22. Get a deployment resource content - URL parameters</caption> 17103<colgroup> 17104<col style="width: 25%;"> 17105<col style="width: 25%;"> 17106<col style="width: 25%;"> 17107<col style="width: 25%;"> 17108</colgroup> 17109<thead> 17110<tr> 17111<th class="tableblock halign-left valign-top">Parameter</th> 17112<th class="tableblock halign-left valign-top">Required</th> 17113<th class="tableblock halign-left valign-top">Value</th> 17114<th class="tableblock halign-left valign-top">Description</th> 17115</tr> 17116</thead> 17117<tbody> 17118<tr> 17119<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 17120<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17121<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17122<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the deployment the requested resource is part of.</p></td> 17123</tr> 17124<tr> 17125<td class="tableblock halign-left valign-top"><p class="tableblock">resourceId</p></td> 17126<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17127<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17128<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the resource to get the data for. <strong>Make sure you URL-encode the resourceId in case it contains forward slashes. Eg: use <em>diagrams%2Fmy-process.bpmn20.xml</em> instead of <em>diagrams/Fmy-process.bpmn20.xml</em>.</strong></p></td> 17129</tr> 17130</tbody> 17131</table> 17132<div class="literalblock"> 17133<div class="content"> 17134<pre>.Get a deployment resource content - Response codes</pre> 17135</div> 17136</div> 17137<table class="tableblock frame-all grid-all spread"> 17138<colgroup> 17139<col style="width: 50%;"> 17140<col style="width: 50%;"> 17141</colgroup> 17142<thead> 17143<tr> 17144<th class="tableblock halign-left valign-top">Response code</th> 17145<th class="tableblock halign-left valign-top">Description</th> 17146</tr> 17147</thead> 17148<tbody> 17149<tr> 17150<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17151<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates both deployment and resource have been found and the resource data has been returned.</p></td> 17152</tr> 17153<tr> 17154<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17155<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested deployment was not found or there is no resource with the given id present in the deployment. The status-description contains additional information.</p></td> 17156</tr> 17157</tbody> 17158</table> 17159<div class="paragraph"> 17160<p><strong>Success response body:</strong></p> 17161</div> 17162<div class="paragraph"> 17163<p>The response body will contain the binary resource-content for the requested resource. The response content-type will be the same as the type returned in the resources <em>mimeType</em> property. Also, a content-disposition header is set, allowing browsers to download the file instead of displaying it.</p> 17164</div> 17165</div> 17166</div> 17167<div class="sect2"> 17168<h3 id="_process_definitions">13.3. Process Definitions</h3> 17169<div class="sect3"> 17170<h4 id="_list_of_process_definitions">13.3.1. List of process definitions</h4> 17171<div class="listingblock"> 17172<div class="content"> 17173<pre>GET repository/process-definitions</pre> 17174</div> 17175</div> 17176<table class="tableblock frame-all grid-all spread"> 17177<caption class="title">Table 23. List of process definitions - URL parameters</caption> 17178<colgroup> 17179<col style="width: 25%;"> 17180<col style="width: 25%;"> 17181<col style="width: 25%;"> 17182<col style="width: 25%;"> 17183</colgroup> 17184<thead> 17185<tr> 17186<th class="tableblock halign-left valign-top">Parameter</th> 17187<th class="tableblock halign-left valign-top">Required</th> 17188<th class="tableblock halign-left valign-top">Value</th> 17189<th class="tableblock halign-left valign-top">Description</th> 17190</tr> 17191</thead> 17192<tbody> 17193<tr> 17194<td class="tableblock halign-left valign-top"><p class="tableblock">version</p></td> 17195<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17196<td class="tableblock halign-left valign-top"><p class="tableblock">integer</p></td> 17197<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with the given version.</p></td> 17198</tr> 17199<tr> 17200<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 17201<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17202<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17203<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with the given name.</p></td> 17204</tr> 17205<tr> 17206<td class="tableblock halign-left valign-top"><p class="tableblock">nameLike</p></td> 17207<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17208<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17209<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with a name like the given name.</p></td> 17210</tr> 17211<tr> 17212<td class="tableblock halign-left valign-top"><p class="tableblock">key</p></td> 17213<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17214<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17215<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with the given key.</p></td> 17216</tr> 17217<tr> 17218<td class="tableblock halign-left valign-top"><p class="tableblock">keyLike</p></td> 17219<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17220<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17221<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with a name like the given key.</p></td> 17222</tr> 17223<tr> 17224<td class="tableblock halign-left valign-top"><p class="tableblock">resourceName</p></td> 17225<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17226<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17227<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with the given resource name.</p></td> 17228</tr> 17229<tr> 17230<td class="tableblock halign-left valign-top"><p class="tableblock">resourceNameLike</p></td> 17231<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17232<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17233<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with a name like the given resource name.</p></td> 17234</tr> 17235<tr> 17236<td class="tableblock halign-left valign-top"><p class="tableblock">category</p></td> 17237<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17238<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17239<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with the given category.</p></td> 17240</tr> 17241<tr> 17242<td class="tableblock halign-left valign-top"><p class="tableblock">categoryLike</p></td> 17243<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17244<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17245<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions with a category like the given name.</p></td> 17246</tr> 17247<tr> 17248<td class="tableblock halign-left valign-top"><p class="tableblock">categoryNotEquals</p></td> 17249<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17250<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17251<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions which don’t have the given category.</p></td> 17252</tr> 17253<tr> 17254<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 17255<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17256<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17257<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions which are part of a deployment with the given id.</p></td> 17258</tr> 17259<tr> 17260<td class="tableblock halign-left valign-top"><p class="tableblock">startableByUser</p></td> 17261<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17262<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17263<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process definitions which can be started by the given user.</p></td> 17264</tr> 17265<tr> 17266<td class="tableblock halign-left valign-top"><p class="tableblock">latest</p></td> 17267<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17268<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 17269<td class="tableblock halign-left valign-top"><p class="tableblock">Only return the latest process definition versions. Can only be used together with <em>key</em> and <em>keyLike</em> parameters, using any other parameter will result in a 400-response.</p></td> 17270</tr> 17271<tr> 17272<td class="tableblock halign-left valign-top"><p class="tableblock">suspended</p></td> 17273<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17274<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 17275<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns process definitions which are suspended. If <code>false</code>, only active process definitions (which are not suspended) are returned.</p></td> 17276</tr> 17277<tr> 17278<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 17279<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17280<td class="tableblock halign-left valign-top"><p class="tableblock"><em>name</em> (default), <em>id</em>, <em>key</em>, <em>category</em>, <em>deploymentId</em> and <em>version</em></p></td> 17281<td class="tableblock halign-left valign-top"><p class="tableblock">Property to sort on, to be used together with the <em>order</em>.</p></td> 17282</tr> 17283</tbody> 17284</table> 17285<table class="tableblock frame-all grid-all spread"> 17286<caption class="title">Table 24. List of process definitions - Response codes</caption> 17287<colgroup> 17288<col style="width: 50%;"> 17289<col style="width: 50%;"> 17290</colgroup> 17291<thead> 17292<tr> 17293<th class="tableblock halign-left valign-top">Response code</th> 17294<th class="tableblock halign-left valign-top">Description</th> 17295</tr> 17296</thead> 17297<tbody> 17298<tr> 17299<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17300<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the process-definitions are returned</p></td> 17301</tr> 17302<tr> 17303<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 17304<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format or that <em>latest</em> is used with other parameters other than <em>key</em> and <em>keyLike</em>. The status-message contains additional information.</p></td> 17305</tr> 17306</tbody> 17307</table> 17308<div class="paragraph"> 17309<p><strong>Success response body:</strong></p> 17310</div> 17311<div class="listingblock"> 17312<div class="content"> 17313<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 17314 2 17315 3 17316 4 17317 5 17318 6 17319 7 17320 8 17321 9 1732210 1732311 1732412 1732513 1732614 1732715 1732816 1732917 1733018 1733119 1733220 1733321 1733422 1733523 1733624 1733725</div></td><td class="code"><span></span><span class="tok-p">{</span> 17338 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 17339 <span class="tok-p">{</span>
17340 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess:1:4"</span><span class="tok-p">,</span> 17341 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 17342 <span class="tok-nt">"version"</span> <span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 17343 <span class="tok-nt">"key"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess"</span><span class="tok-p">,</span> 17344 <span class="tok-nt">"category"</span> <span class="tok-p">:</span> <span class="tok-s2">"Examples"</span><span class="tok-p">,</span> 17345 <span class="tok-nt">"suspended"</span> <span class="tok-p">:</span> <span class="tok-kc">false</span><span class="tok-p">,</span> 17346 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"The One Task Process"</span><span class="tok-p">,</span> 17347 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a process for testing purposes"</span><span class="tok-p">,</span> 17348 <span class="tok-nt">"deploymentId"</span> <span class="tok-p">:</span> <span class="tok-s2">"2"</span><span class="tok-p">,</span> 17349 <span class="tok-nt">"deploymentUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/repository/deployments/2"</span><span class="tok-p">,</span> 17350 <span class="tok-nt">"graphicalNotationDefined"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span><span class="tok-p">,</span> 17351 <span class="tok-nt">"resource"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/deployments/2/resources/testProcess.xml"</span><span class="tok-p">,</span> 17352 <span class="tok-nt">"diagramResource"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/deployments/2/resources/testProcess.png"</span><span class="tok-p">,</span> 17353 <span class="tok-nt">"startFormDefined"</span> <span class="tok-p">:</span> <span class="tok-kc">false</span> 17354 <span class="tok-p">}</span> 17355 <span class="tok-p">],</span> 17356 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 17357 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 17358 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 17359 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 17360 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 17361<span class="tok-p">}</span> 17362</td></tr></table></code></pre> 17363</div> 17364</div> 17365<div class="ulist"> 17366<ul> 17367<li> 17368<p><code>graphicalNotationDefined</code>: Indicates the process definition contains graphical information (BPMN DI).</p> 17369</li> 17370<li> 17371<p><code>resource</code>: Contains the actual deployed BPMN 2.0 xml.</p> 17372</li> 17373<li> 17374<p><code>diagramResource</code>: Contains a graphical representation of the process, null when no diagram is available.</p> 17375</li> 17376</ul> 17377</div> 17378</div> 17379<div class="sect3"> 17380<h4 id="_get_a_process_definition">13.3.2. Get a process definition</h4> 17381<div class="listingblock"> 17382<div class="content"> 17383<pre>GET repository/process-definitions/{processDefinitionId}</pre> 17384</div> 17385</div> 17386<table class="tableblock frame-all grid-all spread"> 17387<caption class="title">Table 25. Get a process definition - URL parameters</caption> 17388<colgroup> 17389<col style="width: 25%;"> 17390<col style="width: 25%;"> 17391<col style="width: 25%;"> 17392<col style="width: 25%;"> 17393</colgroup> 17394<thead> 17395<tr> 17396<th class="tableblock halign-left valign-top">Parameter</th> 17397<th class="tableblock halign-left valign-top">Required</th> 17398<th class="tableblock halign-left valign-top">Value</th> 17399<th class="tableblock halign-left valign-top">Description</th> 17400</tr> 17401</thead> 17402<tbody> 17403<tr> 17404<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 17405<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17406<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17407<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition to get.</p></td> 17408</tr> 17409</tbody> 17410</table> 17411<table class="tableblock frame-all grid-all spread"> 17412<caption class="title">Table 26. Get a process definition - Response codes</caption> 17413<colgroup> 17414<col style="width: 50%;"> 17415<col style="width: 50%;"> 17416</colgroup> 17417<thead> 17418<tr> 17419<th class="tableblock halign-left valign-top">Response code</th> 17420<th class="tableblock halign-left valign-top">Description</th> 17421</tr> 17422</thead> 17423<tbody> 17424<tr> 17425<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17426<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process definition was found and returned.</p></td> 17427</tr> 17428<tr> 17429<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17430<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17431</tr> 17432</tbody> 17433</table> 17434<div class="paragraph"> 17435<p><strong>Success response body:</strong></p> 17436</div> 17437<div class="listingblock"> 17438<div class="content"> 17439<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 17440 2 17441 3 17442 4 17443 5 17444 6 17445 7 17446 8 17447 9 1744810 1744911 1745012 1745113 1745214 1745315 1745416</div></td><td class="code"><span></span><span class="tok-p">{</span> 17455 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess:1:4"</span><span class="tok-p">,</span> 17456 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 17457 <span class="tok-nt">"version"</span> <span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 17458 <span class="tok-nt">"key"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess"</span><span class="tok-p">,</span> 17459 <span class="tok-nt">"category"</span> <span class="tok-p">:</span> <span class="tok-s2">"Examples"</span><span class="tok-p">,</span> 17460 <span class="tok-nt">"suspended"</span> <span class="tok-p">:</span> <span class="tok-kc">
17460false</span><span class="tok-p">,</span> 17461 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"The One Task Process"</span><span class="tok-p">,</span> 17462 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a process for testing purposes"</span><span class="tok-p">,</span> 17463 <span class="tok-nt">"deploymentId"</span> <span class="tok-p">:</span> <span class="tok-s2">"2"</span><span class="tok-p">,</span> 17464 <span class="tok-nt">"deploymentUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/repository/deployments/2"</span><span class="tok-p">,</span> 17465 <span class="tok-nt">"graphicalNotationDefined"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span><span class="tok-p">,</span> 17466 <span class="tok-nt">"resource"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/deployments/2/resources/testProcess.xml"</span><span class="tok-p">,</span> 17467 <span class="tok-nt">"diagramResource"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/deployments/2/resources/testProcess.png"</span><span class="tok-p">,</span> 17468 <span class="tok-nt">"startFormDefined"</span> <span class="tok-p">:</span> <span class="tok-kc">false</span> 17469<span class="tok-p">}</span> 17470</td></tr></table></code></pre> 17471</div> 17472</div> 17473<div class="ulist"> 17474<ul> 17475<li> 17476<p><code>graphicalNotationDefined</code>: Indicates the process definition contains graphical information (BPMN DI).</p> 17477</li> 17478<li> 17479<p><code>resource</code>: Contains the actual deployed BPMN 2.0 xml.</p> 17480</li> 17481<li> 17482<p><code>diagramResource</code>: Contains a graphical representation of the process, null when no diagram is available.</p> 17483</li> 17484</ul> 17485</div> 17486</div> 17487<div class="sect3"> 17488<h4 id="_update_category_for_a_process_definition">13.3.3. Update category for a process definition</h4> 17489<div class="listingblock"> 17490<div class="content"> 17491<pre>PUT repository/process-definitions/{processDefinitionId}</pre> 17492</div> 17493</div> 17494<div class="paragraph"> 17495<p><strong>Body JSON:</strong></p> 17496</div> 17497<div class="listingblock"> 17498<div class="content"> 17499<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 175002 175013</div></td><td class="code"><span></span><span class="tok-p">{</span> 17502 <span class="tok-nt">"category"</span> <span class="tok-p">:</span> <span class="tok-s2">"updatedcategory"</span> 17503<span class="tok-p">}</span> 17504</td></tr></table></code></pre> 17505</div> 17506</div> 17507<table class="tableblock frame-all grid-all spread"> 17508<caption class="title">Table 27. Update category for a process definition - Response codes</caption> 17509<colgroup> 17510<col style="width: 50%;"> 17511<col style="width: 50%;"> 17512</colgroup> 17513<thead> 17514<tr> 17515<th class="tableblock halign-left valign-top">Response code</th> 17516<th class="tableblock halign-left valign-top">Description</th> 17517</tr> 17518</thead> 17519<tbody> 17520<tr> 17521<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17522<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process was category was altered.</p></td> 17523</tr> 17524<tr> 17525<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 17526<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates no category was defined in the request body.</p></td> 17527</tr> 17528<tr> 17529<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17530<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17531</tr> 17532</tbody> 17533</table> 17534<div class="paragraph"> 17535<p><strong>Success response body:</strong> see response for <code>repository/process-definitions/{processDefinitionId}</code>.</p> 17536</div> 17537</div> 17538<div class="sect3"> 17539<h4 id="_get_a_process_definition_resource_content">13.3.4. Get a process definition resource content</h4> 17540<div class="listingblock"> 17541<div class="content"> 17542<pre>GET repository/process-definitions/{processDefinitionId}/resourcedata</pre> 17543</div> 17544</div> 17545<table class="tableblock frame-all grid-all spread"> 17546<caption class="title">
17546Table 28. Get a process definition resource content - URL parameters</caption> 17547<colgroup> 17548<col style="width: 25%;"> 17549<col style="width: 25%;"> 17550<col style="width: 25%;"> 17551<col style="width: 25%;"> 17552</colgroup> 17553<thead> 17554<tr> 17555<th class="tableblock halign-left valign-top">Parameter</th> 17556<th class="tableblock halign-left valign-top">Required</th> 17557<th class="tableblock halign-left valign-top">Value</th> 17558<th class="tableblock halign-left valign-top">Description</th> 17559</tr> 17560</thead> 17561<tbody> 17562<tr> 17563<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 17564<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17565<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17566<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition to get the resource data for.</p></td> 17567</tr> 17568</tbody> 17569</table> 17570<div class="paragraph"> 17571<p><strong>Response:</strong></p> 17572</div> 17573<div class="paragraph"> 17574<p>Exactly the same response codes/boy as <code>GET repository/deployment/{deploymentId}/resourcedata/{resourceId}</code>.</p> 17575</div> 17576</div> 17577<div class="sect3"> 17578<h4 id="_get_a_process_definition_bpmn_model">13.3.5. Get a process definition BPMN model</h4> 17579<div class="listingblock"> 17580<div class="content"> 17581<pre>GET repository/process-definitions/{processDefinitionId}/model</pre> 17582</div> 17583</div> 17584<table class="tableblock frame-all grid-all spread"> 17585<caption class="title">Table 29. Get a process definition BPMN model - URL parameters</caption> 17586<colgroup> 17587<col style="width: 25%;"> 17588<col style="width: 25%;"> 17589<col style="width: 25%;"> 17590<col style="width: 25%;"> 17591</colgroup> 17592<thead> 17593<tr> 17594<th class="tableblock halign-left valign-top">Parameter</th> 17595<th class="tableblock halign-left valign-top">Required</th> 17596<th class="tableblock halign-left valign-top">Value</th> 17597<th class="tableblock halign-left valign-top">Description</th> 17598</tr> 17599</thead> 17600<tbody> 17601<tr> 17602<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 17603<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17604<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17605<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition to get the model for.</p></td> 17606</tr> 17607</tbody> 17608</table> 17609<table class="tableblock frame-all grid-all spread"> 17610<caption class="title">Table 30. Get a process definition BPMN model - Response codes</caption> 17611<colgroup> 17612<col style="width: 50%;"> 17613<col style="width: 50%;"> 17614</colgroup> 17615<thead> 17616<tr> 17617<th class="tableblock halign-left valign-top">Response code</th> 17618<th class="tableblock halign-left valign-top">Description</th> 17619</tr> 17620</thead> 17621<tbody> 17622<tr> 17623<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17624<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process definition was found and the model is returned.</p></td> 17625</tr> 17626<tr> 17627<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17628<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17629</tr> 17630</tbody> 17631</table> 17632<div class="paragraph"> 17633<p><strong>Response body:</strong> 17634The response body is a JSON representation of the <code>org.activiti.bpmn.model.BpmnModel</code> and contains the full process definition model.</p> 17635</div> 17636<div class="listingblock"> 17637<div class="content"> 17638<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 17639 2 17640 3 17641 4 17642 5 17643 6 17644 7 17645 8 17646 9 1764710 1764811 1764912 1765013 1765114 1765215</div></td><td class="code"><span></span><span class="tok-p">{</span> 17653 <span class="tok-nt">"processes"</span><span class="tok-p">:[</span> 17654 <span class="tok-p">{</span> 17655 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"oneTaskProcess"</span><span class="tok-p">,</span> 17656 <span class="tok-nt">"xmlRowNumber"</span><span class="tok-p">:</span><span class="tok-mi">7</span><span class="tok-p">,</span>
17657 <span class="tok-nt">"xmlColumnNumber"</span><span class="tok-p">:</span><span class="tok-mi">60</span><span class="tok-p">,</span> 17658 <span class="tok-nt">"extensionElements"</span><span class="tok-p">:{</span> 17659 17660 <span class="tok-p">},</span> 17661 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"The One Task Process"</span><span class="tok-p">,</span> 17662 <span class="tok-nt">"executable"</span><span class="tok-p">:</span><span class="tok-kc">true</span><span class="tok-p">,</span> 17663 <span class="tok-nt">"documentation"</span><span class="tok-p">:</span><span class="tok-s2">"One task process description"</span><span class="tok-p">,</span> 17664 17665 <span class="tok-err">]</span> 17666<span class="tok-p">}</span> 17667</td></tr></table></code></pre> 17668</div> 17669</div> 17670</div> 17671<div class="sect3"> 17672<h4 id="_suspend_a_process_definition">13.3.6. Suspend a process definition</h4> 17673<div class="listingblock"> 17674<div class="content"> 17675<pre>PUT repository/process-definitions/{processDefinitionId}</pre> 17676</div> 17677</div> 17678<div class="paragraph"> 17679<p><strong>Body JSON:</strong></p> 17680</div> 17681<div class="listingblock"> 17682<div class="content"> 17683<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 176842 176853 176864 176875</div></td><td class="code"><span></span><span class="tok-p">{</span> 17688 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"suspend"</span><span class="tok-p">,</span> 17689 <span class="tok-nt">"includeProcessInstances"</span> <span class="tok-p">:</span> <span class="tok-s2">"false"</span><span class="tok-p">,</span> 17690 <span class="tok-nt">"date"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-15T00:42:12Z"</span> 17691<span class="tok-p">}</span> 17692</td></tr></table></code></pre> 17693</div> 17694</div> 17695<table id="processDefinitionActionBodyParameters" class="tableblock frame-all grid-all spread"> 17696<caption class="title">Table 31. Suspend a process definition - JSON Body parameters</caption> 17697<colgroup> 17698<col style="width: 33.3333%;"> 17699<col style="width: 33.3333%;"> 17700<col style="width: 33.3334%;"> 17701</colgroup> 17702<thead> 17703<tr> 17704<th class="tableblock halign-left valign-top">Parameter</th> 17705<th class="tableblock halign-left valign-top">Description</th> 17706<th class="tableblock halign-left valign-top">Required</th> 17707</tr> 17708</thead> 17709<tbody> 17710<tr> 17711<td class="tableblock halign-left valign-top"><p class="tableblock">action</p></td> 17712<td class="tableblock halign-left valign-top"><p class="tableblock">Action to perform. Either <code>activate</code> or <code>suspend</code>.</p></td> 17713<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17714</tr> 17715<tr> 17716<td class="tableblock halign-left valign-top"><p class="tableblock">includeProcessInstances</p></td> 17717<td class="tableblock halign-left valign-top"><p class="tableblock">Whether or not to suspend/activate running process-instances for this process-definition. If omitted, the process-instances are left in the state they are.</p></td> 17718<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17719</tr> 17720<tr> 17721<td class="tableblock halign-left valign-top"><p class="tableblock">date</p></td> 17722<td class="tableblock halign-left valign-top"><p class="tableblock">Date (ISO-8601) when the suspension/activation should be executed. If omitted, the suspend/activation is effective immediately.</p></td> 17723<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 17724</tr> 17725</tbody> 17726</table> 17727<table class="tableblock frame-all grid-all spread"> 17728<caption class="title">Table 32. Suspend a process definition - Response codes</caption> 17729<colgroup> 17730<col style="width: 50%;"> 17731<col style="width: 50%;"> 17732</colgroup> 17733<thead> 17734<tr> 17735<th class="tableblock halign-left valign-top">Response code</th> 17736<th class="tableblock halign-left valign-top">Description</th> 17737</tr> 17738</thead> 17739<tbody> 17740<tr> 17741<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17742<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process was suspended.</p></td> 17743</tr> 17744<tr> 17745<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17746<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17747</tr> 17748<tr> 17749<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 17750<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition is already suspended.</p></td> 17751</tr> 17752</tbody> 17753</table> 17754<div class="paragraph"> 17755<p><strong>Success response body:</strong> see response for <code>repository/process-definitions/{processDefinitionId}</code>.</p> 17756</div> 17757</div> 17758<div class="sect3"> 17759<h4 id="_activate_a_process_definition">13.3.7. Activate a process definition</h4> 17760<div class="listingblock"> 17761<div class="content"> 17762<pre>PUT repository/process-definitions/{processDefinitionId}</pre> 17763</div> 17764</div> 17765<div class="paragraph"> 17766<p><strong>Body JSON:</strong></p> 17767</div> 17768<div class="listingblock"> 17769<div class="content"> 17770<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 177712 177723 177734 177745</div></td><td class="code"><span></span><span class="tok-p">{</span> 17775 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"activate"</span><span class="tok-p">,</span> 17776 <span class="tok-nt">"includeProcessInstances"</span> <span class="tok-p">:</span> <span class="tok-s2">"true"</span><span class="tok-p">,</span> 17777 <span class="tok-nt">"date"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-15T00:42:12Z"</span> 17778<span class="tok-p">}</span> 17779</td></tr></table></code></pre> 17780</div> 17781</div> 17782<div class="paragraph"> 17783<p>See suspend process definition <a href="#processDefinitionActionBodyParameters">JSON Body parameters</a>.</p> 17784</div> 17785<table class="tableblock frame-all grid-all spread"> 17786<caption class="title">Table 33. Activate a process definition - Response codes</caption> 17787<colgroup> 17788<col style="width: 50%;"> 17789<col style="width: 50%;"> 17790</colgroup> 17791<thead> 17792<tr> 17793<th class="tableblock halign-left valign-top">Response code</th> 17794<th class="tableblock halign-left valign-top">Description</th> 17795</tr> 17796</thead> 17797<tbody> 17798<tr> 17799<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17800<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process was activated.</p></td> 17801</tr> 17802<tr> 17803<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17804<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17805</tr> 17806<tr> 17807<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 17808<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition is already active.</p></td> 17809</tr> 17810</tbody> 17811</table> 17812<div class="paragraph"> 17813<p><strong>Success response body:</strong> see response for <code>repository/process-definitions/{processDefinitionId}</code>.</p> 17814</div> 17815</div> 17816<div class="sect3"> 17817<h4 id="_get_all_candidate_starters_for_a_process_definition">13.3.8. Get all candidate starters for a process-definition</h4> 17818<div class="listingblock"> 17819<div class="content"> 17820<pre>GET repository/process-definitions/{processDefinitionId}/identitylinks</pre> 17821</div> 17822</div> 17823<table class="tableblock frame-all grid-all spread"> 17824<caption class="title">Table 34. Get all candidate starters for a process-definition - URL parameters</caption> 17825<colgroup> 17826<col style="width: 25%;"> 17827<col style="width: 25%;"> 17828<col style="width: 25%;"> 17829<col style="width: 25%;"> 17830</colgroup> 17831<thead> 17832<tr> 17833<th class="tableblock halign-left valign-top">Parameter</th> 17834<th class="tableblock halign-left valign-top">Required</th> 17835<th class="tableblock halign-left valign-top">Value</th> 17836<th class="tableblock halign-left valign-top">Description</th> 17837</tr> 17838</thead> 17839<tbody> 17840<tr> 17841<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 17842<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17843<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17844<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition to get the identity links for.</p></td> 17845</tr> 17846</tbody> 17847</table> 17848<table class="tableblock frame-all grid-all spread"> 17849<caption class="title">Table 35. Get all candidate starters for a process-definition - Response codes</caption> 17850<colgroup> 17851<col style="width: 50%;"> 17852<col style="width: 50%;"> 17853</colgroup> 17854<thead> 17855<tr> 17856<th class="tableblock halign-left valign-top">Response code</th> 17857<th class="tableblock halign-left valign-top">Description</th> 17858</tr> 17859</thead> 17860<tbody> 17861<tr> 17862<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 17863<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process definition was found and the requested identity links are returned.</p></td> 17864</tr> 17865<tr> 17866<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17867<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17868</tr> 17869</tbody> 17870</table> 17871<div class="paragraph"> 17872<p><strong>Success response body:</strong></p> 17873</div> 17874<div class="listingblock"> 17875<div class="content"> 17876<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 17877 2 17878 3 17879 4 17880 5 17881 6 17882 7 17883 8 17884 9 1788510 1788611 1788712 1788813 1788914</div></td><td class="code"><span></span><span class="tok-p">[</span> 17890 <span class="tok-p">{</span>
17891 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/groups/admin"</span><span class="tok-p">,</span> 17892 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 17893 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-s2">"admin"</span><span class="tok-p">,</span> 17894 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"candidate"</span> 17895 <span class="tok-p">},</span> 17896 <span class="tok-p">{</span> 17897 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit"</span><span class="tok-p">,</span> 17898 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 17899 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 17900 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"candidate"</span> 17901 <span class="tok-p">}</span> 17902<span class="tok-p">]</span> 17903</td></tr></table></code></pre> 17904</div> 17905</div> 17906</div> 17907<div class="sect3"> 17908<h4 id="_add_a_candidate_starter_to_a_process_definition">13.3.9. Add a candidate starter to a process definition</h4> 17909<div class="listingblock"> 17910<div class="content"> 17911<pre>POST repository/process-definitions/{processDefinitionId}/identitylinks</pre> 17912</div> 17913</div> 17914<table class="tableblock frame-all grid-all spread"> 17915<caption class="title">Table 36. Add a candidate starter to a process definition - URL parameters</caption> 17916<colgroup> 17917<col style="width: 25%;"> 17918<col style="width: 25%;"> 17919<col style="width: 25%;"> 17920<col style="width: 25%;"> 17921</colgroup> 17922<thead> 17923<tr> 17924<th class="tableblock halign-left valign-top">Parameter</th> 17925<th class="tableblock halign-left valign-top">Required</th> 17926<th class="tableblock halign-left valign-top">Value</th> 17927<th class="tableblock halign-left valign-top">Description</th> 17928</tr> 17929</thead> 17930<tbody> 17931<tr> 17932<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 17933<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 17934<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 17935<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition.</p></td> 17936</tr> 17937</tbody> 17938</table> 17939<div class="paragraph"> 17940<p><strong>Request body (user):</strong></p> 17941</div> 17942<div class="listingblock"> 17943<div class="content"> 17944<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 179452 179463</div></td><td class="code"><span></span><span class="tok-p">{</span> 17947 <span class="tok-nt">"user"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span> 17948<span class="tok-p">}</span> 17949</td></tr></table></code></pre> 17950</div> 17951</div> 17952<div class="paragraph"> 17953<p><strong>Request body (group):</strong></p> 17954</div> 17955<div class="listingblock"> 17956<div class="content"> 17957<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 179582 179593</div></td><td class="code"><span></span><span class="tok-p">{</span> 17960 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-s2">"sales"</span> 17961<span class="tok-p">}</span> 17962</td></tr></table></code></pre> 17963</div> 17964</div> 17965<table class="tableblock frame-all grid-all spread"> 17966<caption class="title">Table 37. Add a candidate starter to a process definition - Response codes</caption> 17967<colgroup> 17968<col style="width: 50%;"> 17969<col style="width: 50%;"> 17970</colgroup> 17971<thead> 17972<tr> 17973<th class="tableblock halign-left valign-top">Response code</th> 17974<th class="tableblock halign-left valign-top">Description</th> 17975</tr> 17976</thead> 17977<tbody> 17978<tr> 17979<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 17980<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process definition was found and the identity link was created.</p></td> 17981</tr> 17982<tr> 17983<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 17984<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found.</p></td> 17985</tr> 17986</tbody> 17987</table> 17988<div class="paragraph"> 17989<p><strong>Success response body:</strong></p> 17990</div> 17991<div class="listingblock"> 17992<div class="content"> 17993<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 179942 179953 179964 179975 179986</div></td><td class="code"><span></span><span class="tok-p">{</span> 17999 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit"</span><span class="tok-p">,</span> 18000 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 18001 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 18002 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"candidate"</span> 18003<span class="tok-p">}</span> 18004</td></tr></table></code></pre> 18005</div> 18006</div> 18007</div> 18008<div class="sect3"> 18009<h4 id="_delete_a_candidate_starter_from_a_process_definition">13.3.10. Delete a candidate starter from a process definition</h4> 18010<div class="listingblock"> 18011<div class="content"> 18012<pre>DELETE repository/process-definitions/{processDefinitionId}/identitylinks/{family}/{identityId}</pre> 18013</div> 18014</div> 18015<table class="tableblock frame-all grid-all spread"> 18016<caption class="title">Table 38. Delete a candidate starter from a process definition - URL parameters</caption> 18017<colgroup> 18018<col style="width: 25%;"> 18019<col style="width: 25%;"> 18020<col style="width: 25%;"> 18021<col style="width: 25%;"> 18022</colgroup> 18023<thead> 18024<tr> 18025<th class="tableblock halign-left valign-top">Parameter</th> 18026<th class="tableblock halign-left valign-top">Required</th> 18027<th class="tableblock halign-left valign-top">Value</th> 18028<th class="tableblock halign-left valign-top">Description</th> 18029</tr> 18030</thead> 18031<tbody> 18032<tr> 18033<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 18034<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18035<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18036<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition.</p></td> 18037</tr> 18038<tr> 18039<td class="tableblock halign-left valign-top"><p class="tableblock">family</p></td> 18040<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18041<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18042<td class="tableblock halign-left valign-top"><p class="tableblock">Either <code>users</code> or <code>groups</code>, depending on the type of identity link.</p></td> 18043</tr> 18044<tr> 18045<td class="tableblock halign-left valign-top"><p class="tableblock">identityId</p></td> 18046<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18047<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18048<td class="tableblock halign-left valign-top"><p class="tableblock">Either the userId or groupId of the identity to remove as candidate starter.</p></td> 18049</tr> 18050</tbody> 18051</table> 18052<table class="tableblock frame-all grid-all spread"> 18053<caption class="title">Table 39. Delete a candidate starter from a process definition - Response codes</caption> 18054<colgroup> 18055<col style="width: 50%;"> 18056<col style="width: 50%;"> 18057</colgroup> 18058<thead> 18059<tr> 18060<th class="tableblock halign-left valign-top">Response code</th> 18061<th class="tableblock halign-left valign-top">Description</th> 18062</tr> 18063</thead> 18064<tbody> 18065<tr> 18066<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 18067<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process definition was found and the identity link was removed. The response body is intentionally empty.</p></td> 18068</tr> 18069<tr> 18070<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18071<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found or the process definition doesn’t have an identity-link that matches the url.</p></td> 18072</tr> 18073</tbody> 18074</table> 18075<div class="paragraph"> 18076<p><strong>Success response body:</strong></p> 18077</div> 18078<div class="listingblock"> 18079<div class="content"> 18080<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 180812 180823 180834 180845 180856</div></td><td class="code"><span></span><span class="tok-p">{</span> 18086 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit"</span><span class="tok-p">,</span> 18087 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 18088 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 18089 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"candidate"</span> 18090<span class="tok-p">}</span> 18091</td></tr></table></code></pre> 18092</div> 18093</div> 18094</div> 18095<div class="sect3"> 18096<h4 id="_get_a_candidate_starter_from_a_process_definition">13.3.11. Get a candidate starter from a process definition</h4> 18097<div class="listingblock"> 18098<div class="content"> 18099<pre>GET repository/process-definitions/{processDefinitionId}/identitylinks/{family}/{identityId}</pre> 18100</div> 18101</div> 18102<table class="tableblock frame-all grid-all spread"> 18103<caption class="title">Table 40. Get a candidate starter from a process definition - URL parameters</caption> 18104<colgroup> 18105<col style="width: 25%;"> 18106<col style="width: 25%;"> 18107<col style="width: 25%;"> 18108<col style="width: 25%;"> 18109</colgroup> 18110<thead> 18111<tr> 18112<th class="tableblock halign-left valign-top">Parameter</th> 18113<th class="tableblock halign-left valign-top">Required</th> 18114<th class="tableblock halign-left valign-top">Value</th> 18115<th class="tableblock halign-left valign-top">Description</th> 18116</tr> 18117</thead> 18118<tbody> 18119<tr> 18120<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 18121<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18122<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18123<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process definition.</p></td> 18124</tr> 18125<tr> 18126<td class="tableblock halign-left valign-top"><p class="tableblock">family</p></td> 18127<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18128<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18129<td class="tableblock halign-left valign-top"><p class="tableblock">Either <code>users</code> or <code>groups</code>, depending on the type of identity link.</p></td> 18130</tr> 18131<tr> 18132<td class="tableblock halign-left valign-top"><p class="tableblock">identityId</p></td> 18133<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18134<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18135<td class="tableblock halign-left valign-top"><p class="tableblock">Either the userId or groupId of the identity to get as candidate starter.</p></td> 18136</tr> 18137</tbody> 18138</table> 18139<table class="tableblock frame-all grid-all spread"> 18140<caption class="title">Table 41. Get a candidate starter from a process definition - Response codes</caption> 18141<colgroup> 18142<col style="width: 50%;"> 18143<col style="width: 50%;"> 18144</colgroup> 18145<thead> 18146<tr> 18147<th class="tableblock halign-left valign-top">Response code</th> 18148<th class="tableblock halign-left valign-top">Description</th> 18149</tr> 18150</thead> 18151<tbody> 18152<tr> 18153<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18154<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process definition was found and the identity link was returned.</p></td> 18155</tr> 18156<tr> 18157<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18158<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process definition was not found or the process definition doesn’t have an identity-link that matches the url.</p></td> 18159</tr> 18160</tbody> 18161</table> 18162<div class="paragraph"> 18163<p><strong>Success response body:</strong></p> 18164</div> 18165<div class="listingblock"> 18166<div class="content"> 18167<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 181682 181693 181704 181715 181726</div></td><td class="code"><span></span><span class="tok-p">{</span> 18173 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit"</span><span class="tok-p">,</span> 18174 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 18175 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 18176 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"candidate"</span> 18177<span class="tok-p">}</span> 18178</td></tr></table></code></pre> 18179</div> 18180</div> 18181</div> 18182</div> 18183<div class="sect2"> 18184<h3 id="_models">13.4. Models</h3> 18185<div class="sect3"> 18186<h4 id="_get_a_list_of_models">13.4.1. Get a list of models</h4> 18187<div class="listingblock"> 18188<div class="content"> 18189<pre>GET repository/models</pre> 18190</div> 18191</div> 18192<table class="tableblock frame-all grid-all spread"> 18193<caption class="title">Table 42. Get a list of models - URL query parameters</caption> 18194<colgroup> 18195<col style="width: 25%;"> 18196<col style="width: 25%;"> 18197<col style="width: 25%;"> 18198<col style="width: 25%;"> 18199</colgroup> 18200<thead> 18201<tr> 18202<th class="tableblock halign-left valign-top">Parameter</th> 18203<th class="tableblock halign-left valign-top">Required</th> 18204<th class="tableblock halign-left valign-top">Value</th> 18205<th class="tableblock halign-left valign-top">Description</th> 18206</tr> 18207</thead> 18208<tbody> 18209<tr> 18210<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 18211<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18212<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18213<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with the given id.</p></td> 18214</tr> 18215<tr> 18216<td class="tableblock halign-left valign-top"><p class="tableblock">category</p></td> 18217<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18218<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18219<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with the given category.</p></td> 18220</tr> 18221<tr> 18222<td class="tableblock halign-left valign-top"><p class="tableblock">categoryLike</p></td> 18223<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18224<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18225<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with a category like the given value. Use the <code>%</code> character as wildcard.</p></td> 18226</tr> 18227<tr> 18228<td class="tableblock halign-left valign-top"><p class="tableblock">categoryNotEquals</p></td> 18229<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18230<td class="tableblock halign-left vali
18230gn-top"><p class="tableblock">String</p></td> 18231<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models without the given category.</p></td> 18232</tr> 18233<tr> 18234<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 18235<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18236<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18237<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with the given name.</p></td> 18238</tr> 18239<tr> 18240<td class="tableblock halign-left valign-top"><p class="tableblock">nameLike</p></td> 18241<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18242<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18243<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with a name like the given value. Use the <code>%</code> character as wildcard.</p></td> 18244</tr> 18245<tr> 18246<td class="tableblock halign-left valign-top"><p class="tableblock">key</p></td> 18247<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18248<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18249<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with the given key.</p></td> 18250</tr> 18251<tr> 18252<td class="tableblock halign-left valign-top"><p class="tableblock">deploymentId</p></td> 18253<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18254<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18255<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models which are deployed in the given deployment.</p></td> 18256</tr> 18257<tr> 18258<td class="tableblock halign-left valign-top"><p class="tableblock">version</p></td> 18259<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18260<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 18261<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with the given version.</p></td> 18262</tr> 18263<tr> 18264<td class="tableblock halign-left valign-top"><p class="tableblock">latestVersion</p></td> 18265<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18266<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 18267<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return models which are the latest version. Best used in combination with <code>key</code>. If <code>false</code> is passed in as value, this is ignored and all versions are returned.</p></td> 18268</tr> 18269<tr> 18270<td class="tableblock halign-left valign-top"><p class="tableblock">deployed</p></td> 18271<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18272<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 18273<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only deployed models are returned. If <code>false</code>, only undeployed models are returned (deploymentId is null).</p></td> 18274</tr> 18275<tr> 18276<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 18277<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18278<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18279<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with the given tenantId.</p></td> 18280</tr> 18281<tr> 18282<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 18283<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18284<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18285<td class="tableblock halign-left valign-top"><p class="tableblock">Only return models with a tenantId like the given value.</p></td> 18286</tr> 18287<tr> 18288<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 18289<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18290<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 18291<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns models without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 18292</tr> 18293<tr> 18294<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 18295<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 18296<td class="tableblock halign-left valign-top"><p class="tableblock"><em>id</em> (default), <em>category</em>, <em>createTime</em>, <em>key</em>, <em>lastUpdateTime</em>, <em>
18296name</em>, <em>version</em> or <em>tenantId</em></p></td> 18297<td class="tableblock halign-left valign-top"><p class="tableblock">Property to sort on, to be used together with the <em>order</em>.</p></td> 18298</tr> 18299</tbody> 18300</table> 18301<table class="tableblock frame-all grid-all spread"> 18302<caption class="title">Table 43. Get a list of models - Response codes</caption> 18303<colgroup> 18304<col style="width: 50%;"> 18305<col style="width: 50%;"> 18306</colgroup> 18307<thead> 18308<tr> 18309<th class="tableblock halign-left valign-top">Response code</th> 18310<th class="tableblock halign-left valign-top">Description</th> 18311</tr> 18312</thead> 18313<tbody> 18314<tr> 18315<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18316<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the models are returned</p></td> 18317</tr> 18318<tr> 18319<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 18320<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format. The status-message contains additional information.</p></td> 18321</tr> 18322</tbody> 18323</table> 18324<div class="paragraph"> 18325<p><strong>Success response body:</strong></p> 18326</div> 18327<div class="listingblock"> 18328<div class="content"> 18329<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 18330 2 18331 3 18332 4 18333 5 18334 6 18335 7 18336 8 18337 9 1833810 1833911 1834012 1834113 1834214 1834315 1834416 1834517 1834618 1834719 1834820 1834921 1835022 1835123 1835224 1835325 1835426</div></td><td class="code"><span></span><span class="tok-p">{</span> 18355 <span class="tok-nt">"data"</span><span class="tok-p">:[</span> 18356 <span class="tok-p">{</span> 18357 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Model name"</span><span class="tok-p">,</span> 18358 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"Model key"</span><span class="tok-p">,</span> 18359 <span class="tok-nt">"category"</span><span class="tok-p">:</span><span class="tok-s2">"Model category"</span><span class="tok-p">,</span> 18360 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 18361 <span class="tok-nt">"metaInfo"</span><span class="tok-p">:</span><span class="tok-s2">"Model metainfo"</span><span class="tok-p">,</span> 18362 <span class="tok-nt">"deploymentId"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 18363 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"10"</span><span class="tok-p">,</span> 18364 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/models/10"</span><span class="tok-p">,</span> 18365 <span class="tok-nt">"createTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T14:31:08.612+0000"</span><span class="tok-p">,</span> 18366 <span class="tok-nt">"lastUpdateTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T14:31:08.612+0000"</span><span class="tok-p">,</span> 18367 <span class="tok-nt">"deploymentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/deployments/7"</span><span class="tok-p">,</span> 18368 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 18369 <span class="tok-p">},</span> 18370 18371 <span class="tok-err">...</span> 18372 18373 <span class="tok-p">],</span> 18374 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 18375 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 18376 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"id"</span><span class="tok-p">,</span> 18377 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 18378 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">2</span> 18379<span class="tok-p">}</span> 18380</td></tr></table></code></pre> 18381</div> 18382</div> 18383</div> 18384<div class="sect3"> 18385<h4 id="_get_a_model">13.4.2. Get a model</h4> 18386<div class="listingblock"> 18387<div class="content"> 18388<pre>GET repository/models/{modelId}</pre> 18389</div> 18390</div> 18391<table class="tableblock frame-all grid-all spread"> 18392<caption class="title">Table 44. Get a model - URL parameters</caption> 18393<colgroup> 18394<col style="width: 25%;"> 18395<col style="width: 25%;"> 18396<col style="width: 25%;"> 18397<col style="width: 25%;"> 18398</colgroup> 18399<thead> 18400<tr> 18401<th class="tableblock halign-left valign-top">Parameter</th> 18402<th class="tableblock halign-left valign-top">Required</th> 18403<th class="tableblock halign-left valign-top">Value</th> 18404<th class="tableblock halign-left valign-top">Description</th> 18405</tr> 18406</thead> 18407<tbody> 18408<tr> 18409<td class="tableblock halign-left valign-top"><p class="tableblock">modelId</p></td> 18410<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18411<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18412<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the model to get.</p></td> 18413</tr> 18414</tbody> 18415</table> 18416<table class="tableblock frame-all grid-all spread"> 18417<caption class="title">Table 45. Get a model - Response codes</caption> 18418<colgroup> 18419<col style="width: 50%;"> 18420<col style="width: 50%;"> 18421</colgroup> 18422<thead> 18423<tr> 18424<th class="tableblock halign-left valign-top">Response code</th> 18425<th class="tableblock halign-left valign-top">Description</th> 18426</tr> 18427</thead> 18428<tbody> 18429<tr> 18430<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18431<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and returned.</p></td> 18432</tr> 18433<tr> 18434<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18435<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18436</tr> 18437</tbody> 18438</table> 18439<div class="paragraph"> 18440<p><strong>Success response body:</strong></p> 18441</div> 18442<div class="listingblock"> 18443<div class="content"> 18444<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 18445 2 18446 3 18447 4 18448 5 18449 6 18450 7 18451 8 18452 9 1845310 1845411 1845512 1845613 1845714</div></td><td class="code"><span></span><span class="tok-p">{</span> 18458 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 18459 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/models/5"</span><span class="tok-p">,</span> 18460 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Model name"</span><span class="tok-p">,</span> 18461 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"Model key"</span><span class="tok-p">,</span> 18462 <span class="tok-nt">"category"</span><span class="tok-p">:</span><span class="tok-s2">"Model category"</span><span class="tok-p">,</span> 18463 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 18464 <span class="tok-nt">"metaInfo"</span><span class="tok-p">:</span><span class="tok-s2">"Model metainfo"</span><span class="tok-p">,</span> 18465 <span class="tok-nt">"deploymentId"</span><span class="tok-p">:</span><span class="tok-s2">"2"</span><span class="tok-p">,</span> 18466 <span class="tok-nt">"deploymentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/deployments/2"</span><span class="tok-p">,</span> 18467 <span class="tok-nt">"createTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T12:31:19.861+0000"</span><span class="tok-p">,</span> 18468 <span class="tok-nt">"lastUpdateTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T12:31:19.861+0000"</span><span class="tok-p">,</span> 18469 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 18470<span class="tok-p">}</span> 18471</td></tr></table></code></pre> 18472</div> 18473</div> 18474</div> 18475<div class="sect3"> 18476<h4 id="_update_a_model">13.4.3. Update a model</h4> 18477<div class="listingblock"> 18478<div class="content"> 18479<pre>PUT repository/models/{modelId}</pre> 18480</div> 18481</div> 18482<div class="paragraph"> 18483<p><strong>Request body:</strong></p> 18484</div> 18485<div class="listingblock"> 18486<div class="content"> 18487<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 184882 184893 184904 184915 184926 184937 184948 184959</div></td><td class="code"><span></span><span class="tok-p">{</span> 18496 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Model name"</span><span class="tok-p">,</span> 18497 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"Model key"</span><span class="tok-p">,</span> 18498 <span class="tok-nt">"category"</span><span class="tok-p">:</span><span class="tok-s2">"Model category"</span><span class="tok-p">,</span> 18499 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 18500 <span class="tok-nt">"metaInfo"</span><span class="tok-p">:</span><span class="tok-s2">"Model metainfo"</span><span class="tok-p">,</span> 18501 <span class="tok-nt">"deploymentId"</span><span class="tok-p">:</span><span class="tok-s2">"2"</span><span class="tok-p">,</span> 18502 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-s2">"updatedTenant"</span> 18503<span class="tok-p">}</span> 18504</td></tr></table></code></pre> 18505</div> 18506</div> 18507<div class="paragraph"> 18508<p>All request values are optional. For example, you can only include the <em>
18508name</em> attribute in the request body JSON-object, only updating the name of the model, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the model-value will be updated to null. Example: <code>{"metaInfo" : null}</code> will clear the metaInfo of the model).</p> 18509</div> 18510<table class="tableblock frame-all grid-all spread"> 18511<caption class="title">Table 46. Update a model - Response codes</caption> 18512<colgroup> 18513<col style="width: 50%;"> 18514<col style="width: 50%;"> 18515</colgroup> 18516<thead> 18517<tr> 18518<th class="tableblock halign-left valign-top">Response code</th> 18519<th class="tableblock halign-left valign-top">Description</th> 18520</tr> 18521</thead> 18522<tbody> 18523<tr> 18524<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18525<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and updated.</p></td> 18526</tr> 18527<tr> 18528<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18529<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18530</tr> 18531</tbody> 18532</table> 18533<div class="paragraph"> 18534<p><strong>Success response body:</strong></p> 18535</div> 18536<div class="listingblock"> 18537<div class="content"> 18538<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 18539 2 18540 3 18541 4 18542 5 18543 6 18544 7 18545 8 18546 9 1854710 1854811 1854912 1855013 1855114</div></td><td class="code"><span></span><span class="tok-p">{</span> 18552 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 18553 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/models/5"</span><span class="tok-p">,</span> 18554 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Model name"</span><span class="tok-p">,</span> 18555 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"Model key"</span><span class="tok-p">,</span> 18556 <span class="tok-nt">"category"</span><span class="tok-p">:</span><span class="tok-s2">"Model category"</span><span class="tok-p">,</span> 18557 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 18558 <span class="tok-nt">"metaInfo"</span><span class="tok-p">:</span><span class="tok-s2">"Model metainfo"</span><span class="tok-p">,</span> 18559 <span class="tok-nt">"deploymentId"</span><span class="tok-p">:</span><span class="tok-s2">"2"</span><span class="tok-p">,</span> 18560 <span class="tok-nt">"deploymentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/deployments/2"</span><span class="tok-p">,</span> 18561 <span class="tok-nt">"createTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T12:31:19.861+0000"</span><span class="tok-p">,</span> 18562 <span class="tok-nt">"lastUpdateTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T12:31:19.861+0000"</span><span class="tok-p">,</span> 18563 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-s2">""</span><span class="tok-err">updatedTenant"</span> 18564<span class="tok-p">}</span> 18565</td></tr></table></code></pre> 18566</div> 18567</div> 18568</div> 18569<div class="sect3"> 18570<h4 id="_create_a_model">13.4.4. Create a model</h4> 18571<div class="listingblock"> 18572<div class="content"> 18573<pre>POST repository/models</pre> 18574</div> 18575</div> 18576<div class="paragraph"> 18577<p><strong>Request body:</strong></p> 18578</div> 18579<div class="listingblock"> 18580<div class="content"> 18581<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 185822 185833 185844 185855 185866 185877 185888 185899</div></td><td class="code"><span></span><span class="tok-p">{</span> 18590 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Model name"</span><span class="tok-p">,</span> 18591 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"Model key"</span><span class="tok-p">,</span> 18592 <span class="tok-nt">"category"</span><span class="tok-p">:</span><span class="tok-s2">"Model category"</span><span class="tok-p">,</span> 18593 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-mi">1</span><span class="tok-p">,</span> 18594 <span class="tok-nt">"metaInfo"</span><span class="tok-p">:</span><span class="tok-s2">"Model metainfo"</span><span class="tok-p">,</span> 18595 <span class="tok-nt">"deploymentId"</span><span class="tok-p">:</span><span class="tok-s2">"2"</span><span class="tok-p">,</span> 18596 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-s2">"tenant"</span> 18597<span class="tok-p">}</span> 18598</td></tr></table></code></pre> 18599</div> 18600</div> 18601<div class="paragraph"> 18602<p>All request values are optional. For example, you can only include the <em>
18602name</em> attribute in the request body JSON-object, only setting the name of the model, leaving all other fields null.</p> 18603</div> 18604<table class="tableblock frame-all grid-all spread"> 18605<caption class="title">Table 47. Create a model - Response codes</caption> 18606<colgroup> 18607<col style="width: 50%;"> 18608<col style="width: 50%;"> 18609</colgroup> 18610<thead> 18611<tr> 18612<th class="tableblock halign-left valign-top">Response code</th> 18613<th class="tableblock halign-left valign-top">Description</th> 18614</tr> 18615</thead> 18616<tbody> 18617<tr> 18618<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 18619<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was created.</p></td> 18620</tr> 18621</tbody> 18622</table> 18623<div class="paragraph"> 18624<p><strong>Success response body:</strong></p> 18625</div> 18626<div class="listingblock"> 18627<div class="content"> 18628<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 18629 2 18630 3 18631 4 18632 5 18633 6 18634 7 18635 8 18636 9 1863710 1863811 1863912 1864013 1864114</div></td><td class="code"><span></span><span class="tok-p">{</span> 18642 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 18643 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/models/5"</span><span class="tok-p">,</span> 18644 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Model name"</span><span class="tok-p">,</span> 18645 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"Model key"</span><span class="tok-p">,</span> 18646 <span class="tok-nt">"category"</span><span class="tok-p">:</span><span class="tok-s2">"Model category"</span><span class="tok-p">,</span> 18647 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-mi">1</span><span class="tok-p">,</span> 18648 <span class="tok-nt">"metaInfo"</span><span class="tok-p">:</span><span class="tok-s2">"Model metainfo"</span><span class="tok-p">,</span> 18649 <span class="tok-nt">"deploymentId"</span><span class="tok-p">:</span><span class="tok-s2">"2"</span><span class="tok-p">,</span> 18650 <span class="tok-nt">"deploymentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/deployments/2"</span><span class="tok-p">,</span> 18651 <span class="tok-nt">"createTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T12:31:19.861+0000"</span><span class="tok-p">,</span> 18652 <span class="tok-nt">"lastUpdateTime"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-12T12:31:19.861+0000"</span><span class="tok-p">,</span> 18653 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-s2">"tenant"</span> 18654<span class="tok-p">}</span> 18655</td></tr></table></code></pre> 18656</div> 18657</div> 18658</div> 18659<div class="sect3"> 18660<h4 id="_delete_a_model">13.4.5. Delete a model</h4> 18661<div class="listingblock"> 18662<div class="content"> 18663<pre>DELETE repository/models/{modelId}</pre> 18664</div> 18665</div> 18666<table class="tableblock frame-all grid-all spread"> 18667<caption class="title">Table 48. Delete a model - URL parameters</caption> 18668<colgroup> 18669<col style="width: 25%;"> 18670<col style="width: 25%;"> 18671<col style="width: 25%;"> 18672<col style="width: 25%;"> 18673</colgroup> 18674<thead> 18675<tr> 18676<th class="tableblock halign-left valign-top">Parameter</th> 18677<th class="tableblock halign-left valign-top">Required</th> 18678<th class="tableblock halign-left valign-top">Value</th> 18679<th class="tableblock halign-left valign-top">Description</th> 18680</tr> 18681</thead> 18682<tbody> 18683<tr> 18684<td class="tableblock halign-left valign-top"><p class="tableblock">modelId</p></td> 18685<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18686<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18687<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the model to delete.</p></td> 18688</tr> 18689</tbody> 18690</table> 18691<table class="tableblock frame-all grid-all spread"> 18692<caption class="title">Table 49. Delete a model - Response codes</caption> 18693<colgroup> 18694<col style="width: 50%;"> 18695<col style="width: 50%;"> 18696</colgroup> 18697<thead> 18698<tr> 18699<th class="tableblock halign-left valign-top">Response code</th> 18700<th class="tableblock halign-left valign-top">Description</th> 18701</tr> 18702</thead> 18703<tbody> 18704<tr> 18705<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 18706<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and has been deleted. Response-body is intentionally empty.</p></td> 18707</tr> 18708<tr> 18709<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18710<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18711</tr> 18712</tbody> 18713</table> 18714</div> 18715<div class="sect3"> 18716<h4 id="_get_the_editor_source_for_a_model">13.4.6. Get the editor source for a model</h4> 18717<div class="listingblock"> 18718<div class="content"> 18719<pre>GET repository/models/{modelId}/source</pre> 18720</div> 18721</div> 18722<table class="tableblock frame-all grid-all spread"> 18723<caption class="title">Table 50. Get the editor source for a model - URL parameters</caption> 18724<colgroup> 18725<col style="width: 25%;"> 18726<col style="width: 25%;"> 18727<col style="width: 25%;"> 18728<col style="width: 25%;"> 18729</colgroup> 18730<thead> 18731<tr> 18732<th class="tableblock halign-left valign-top">Parameter</th> 18733<th class="tableblock halign-left valign-top">Required</th> 18734<th class="tableblock halign-left valign-top">Value</th> 18735<th class="tableblock halign-left valign-top">Description</th> 18736</tr> 18737</thead> 18738<tbody> 18739<tr> 18740<td class="tableblock halign-left valign-top"><p class="tableblock">modelId</p></td> 18741<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18742<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18743<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the model.</p></td> 18744</tr> 18745</tbody> 18746</table> 18747<table class="tableblock frame-all grid-all spread"> 18748<caption class="title">Table 51. Get the editor source for a model - Response codes</caption> 18749<colgroup> 18750<col style="width: 50%;"> 18751<col style="width: 50%;"> 18752</colgroup> 18753<thead> 18754<tr> 18755<th class="tableblock halign-left valign-top">Response code</th> 18756<th class="tableblock halign-left valign-top">Description</th> 18757</tr> 18758</thead> 18759<tbody> 18760<tr> 18761<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18762<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and source is returned.</p></td> 18763</tr> 18764<tr> 18765<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18766<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18767</tr> 18768</tbody> 18769</table> 18770<div class="paragraph"> 18771<p><strong>Success response body:</strong></p> 18772</div> 18773<div class="paragraph"> 18774<p>Response body contains the model’s raw editor source. The response’s content-type is set to <code>application/octet-stream</code>, regardless of the content of the source.</p> 18775</div> 18776</div> 18777<div class="sect3"> 18778<h4 id="_set_the_editor_source_for_a_model">13.4.7. Set the editor source for a model</h4> 18779<div class="listingblock"> 18780<div class="content"> 18781<pre>PUT repository/models/{modelId}/source</pre> 18782</div> 18783</div> 18784<table class="tableblock frame-all grid-all spread"> 18785<caption class="title">Table 52. Set the editor source for a model - URL parameters</caption> 18786<colgroup> 18787<col style="width: 25%;"> 18788<col style="width: 25%;"> 18789<col style="width: 25%;"> 18790<col style="width: 25%;"> 18791</colgroup> 18792<thead> 18793<tr> 18794<th class="tableblock halign-left valign-top">Parameter</th> 18795<th class="tableblock halign-left valign-top">Required</th> 18796<th class="tableblock halign-left valign-top">Value</th> 18797<th class="tableblock halign-left valign-top">Description</th> 18798</tr> 18799</thead> 18800<tbody> 18801<tr> 18802<td class="tableblock halign-left valign-top"><p class="tableblock">modelId</p></td> 18803<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18804<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18805<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the model.</p></td> 18806</tr> 18807</tbody> 18808</table> 18809<div class="paragraph"> 18810<p><strong>Request body:</strong></p> 18811</div> 18812<div class="paragraph"> 18813<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the source.</p> 18814</div> 18815<table class="tableblock frame-all grid-all spread"> 18816<caption class="title">Table 53. Set the editor source for a model - Response codes</caption> 18817<colgroup> 18818<col style="width: 50%;"> 18819<col style="width: 50%;"> 18820</colgroup> 18821<thead> 18822<tr> 18823<th class="tableblock halign-left valign-top">Response code</th> 18824<th class="tableblock halign-left valign-top">Description</th> 18825</tr> 18826</thead> 18827<tbody> 18828<tr> 18829<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18830<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and the source has been updated.</p></td> 18831</tr> 18832<tr> 18833<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18834<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18835</tr> 18836</tbody> 18837</table> 18838<div class="paragraph"> 18839<p><strong>Success response body:</strong></p> 18840</div> 18841<div class="paragraph"> 18842<p>Response body contains the model’s raw editor source. The response’s content-type is set to <code>application/octet-stream</code>, regardless of the content of the source.</p> 18843</div> 18844</div> 18845<div class="sect3"> 18846<h4 id="_get_the_extra_editor_source_for_a_model">13.4.8. Get the extra editor source for a model</h4> 18847<div class="listingblock"> 18848<div class="content"> 18849<pre>GET repository/models/{modelId}/source-extra</pre> 18850</div> 18851</div> 18852<table class="tableblock frame-all grid-all spread"> 18853<caption class="title">Table 54. Get the extra editor source for a model - URL parameters</caption> 18854<colgroup> 18855<col style="width: 25%;"> 18856<col style="width: 25%;"> 18857<col style="width: 25%;"> 18858<col style="width: 25%;"> 18859</colgroup> 18860<thead> 18861<tr> 18862<th class="tableblock halign-left valign-top">Parameter</th> 18863<th class="tableblock halign-left valign-top">Required</th> 18864<th class="tableblock halign-left valign-top">Value</th> 18865<th class="tableblock halign-left valign-top">Description</th> 18866</tr> 18867</thead> 18868<tbody> 18869<tr> 18870<td class="tableblock halign-left valign-top"><p class="tableblock">modelId</p></td> 18871<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18872<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18873<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the model.</p></td> 18874</tr> 18875</tbody> 18876</table> 18877<table class="tableblock frame-all grid-all spread"> 18878<caption class="title">Table 55. Get the extra editor source for a model - Response codes</caption> 18879<colgroup> 18880<col style="width: 50%;"> 18881<col style="width: 50%;"> 18882</colgroup> 18883<thead> 18884<tr> 18885<th class="tableblock halign-left valign-top">Response code</th> 18886<th class="tableblock halign-left valign-top">Description</th> 18887</tr> 18888</thead> 18889<tbody> 18890<tr> 18891<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18892<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and source is returned.</p></td> 18893</tr> 18894<tr> 18895<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18896<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18897</tr> 18898</tbody> 18899</table> 18900<div class="paragraph"> 18901<p><strong>Success response body:</strong></p> 18902</div> 18903<div class="paragraph"> 18904<p>Response body contains the model’s raw extra editor source. The response’s content-type is set to <code>application/octet-stream</code>, regardless of the content of the extra source.</p> 18905</div> 18906</div> 18907<div class="sect3"> 18908<h4 id="_set_the_extra_editor_source_for_a_model">13.4.9. Set the extra editor source for a model</h4> 18909<div class="listingblock"> 18910<div class="content"> 18911<pre>PUT repository/models/{modelId}/source-extra</pre> 18912</div> 18913</div> 18914<table class="tableblock frame-all grid-all spread"> 18915<caption class="title">Table 56. Set the extra editor source for a model - URL parameters</caption> 18916<colgroup> 18917<col style="width: 25%;"> 18918<col style="width: 25%;"> 18919<col style="width: 25%;"> 18920<col style="width: 25%;"> 18921</colgroup> 18922<thead> 18923<tr> 18924<th class="tableblock halign-left valign-top">Parameter</th> 18925<th class="tableblock halign-left valign-top">Required</th> 18926<th class="tableblock halign-left valign-top">Value</th> 18927<th class="tableblock halign-left valign-top">Description</th> 18928</tr> 18929</thead> 18930<tbody> 18931<tr> 18932<td class="tableblock halign-left valign-top"><p class="tableblock">modelId</p></td> 18933<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 18934<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 18935<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the model.</p></td> 18936</tr> 18937</tbody> 18938</table> 18939<div class="paragraph"> 18940<p><strong>Request body:</strong></p> 18941</div> 18942<div class="paragraph"> 18943<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the extra source.</p> 18944</div> 18945<table class="tableblock frame-all grid-all spread"> 18946<caption class="title">Table 57. Set the extra editor source for a model - Response codes</caption> 18947<colgroup> 18948<col style="width: 50%;"> 18949<col style="width: 50%;"> 18950</colgroup> 18951<thead> 18952<tr> 18953<th class="tableblock halign-left valign-top">Response code</th> 18954<th class="tableblock halign-left valign-top">Description</th> 18955</tr> 18956</thead> 18957<tbody> 18958<tr> 18959<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 18960<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the model was found and the extra source has been updated.</p></td> 18961</tr> 18962<tr> 18963<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 18964<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested model was not found.</p></td> 18965</tr> 18966</tbody> 18967</table> 18968<div class="paragraph"> 18969<p><strong>Success response body:</strong></p> 18970</div> 18971<div class="paragraph"> 18972<p>Response body contains the model’s raw editor source. The response’s content-type is set to <code>application/octet-stream</code>, regardless of the content of the source.</p> 18973</div> 18974</div> 18975</div> 18976<div class="sect2"> 18977<h3 id="_process_instances">13.5. Process Instances</h3> 18978<div class="sect3"> 18979<h4 id="_get_a_process_instance">13.5.1. Get a process instance</h4> 18980<div class="listingblock"> 18981<div class="content"> 18982<pre>GET runtime/process-instances/{processInstanceId}</pre> 18983</div> 18984</div> 18985<table class="tableblock frame-all grid-all spread"> 18986<caption class="title">Table 58. Get a process instance - URL parameters</caption> 18987<colgroup> 18988<col style="width: 25%;"> 18989<col style="width: 25%;"> 18990<col style="width: 25%;"> 18991<col style="width: 25%;"> 18992</colgroup> 18993<thead> 18994<tr> 18995<th class="tableblock halign-left valign-top">Parameter</th> 18996<th class="tableblock halign-left valign-top">Required</th> 18997<th class="tableblock halign-left valign-top">Value</th> 18998<th class="tableblock halign-left valign-top">Description</th> 18999</tr> 19000</thead> 19001<tbody> 19002<tr> 19003<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19004<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19005<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19006<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to get.</p></td> 19007</tr> 19008</tbody> 19009</table> 19010<table class="tableblock frame-all grid-all spread"> 19011<caption class="title">Table 59. Get a process instance - Response codes</caption> 19012<colgroup> 19013<col style="width: 50%;"> 19014<col style="width: 50%;"> 19015</colgroup> 19016<thead> 19017<tr> 19018<th class="tableblock halign-left valign-top">Resp
19018onse code</th> 19019<th class="tableblock halign-left valign-top">Description</th> 19020</tr> 19021</thead> 19022<tbody> 19023<tr> 19024<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 19025<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and returned.</p></td> 19026</tr> 19027<tr> 19028<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19029<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 19030</tr> 19031</tbody> 19032</table> 19033<div class="paragraph"> 19034<p><strong>Success response body:</strong></p> 19035</div> 19036<div class="listingblock"> 19037<div class="content"> 19038<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 190392 190403 190414 190425 190436 190447 190458 190469</div></td><td class="code"><span></span><span class="tok-p">{</span> 19047 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 19048 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/7"</span><span class="tok-p">,</span> 19049 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19050 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 19051 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4"</span><span class="tok-p">,</span> 19052 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span><span class="tok-p">,</span> 19053 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span> <span class="tok-kc">null</span> 19054<span class="tok-p">}</span> 19055</td></tr></table></code></pre> 19056</div> 19057</div> 19058</div> 19059<div class="sect3"> 19060<h4 id="_delete_a_process_instance">13.5.2. Delete a process instance</h4> 19061<div class="listingblock"> 19062<div class="content"> 19063<pre>DELETE runtime/process-instances/{processInstanceId}</pre> 19064</div> 19065</div> 19066<table class="tableblock frame-all grid-all spread"> 19067<caption class="title">Table 60. Delete a process instance - URL parameters</caption> 19068<colgroup> 19069<col style="width: 25%;"> 19070<col style="width: 25%;"> 19071<col style="width: 25%;"> 19072<col style="width: 25%;"> 19073</colgroup> 19074<thead> 19075<tr> 19076<th class="tableblock halign-left valign-top">Parameter</th> 19077<th class="tableblock halign-left valign-top">Required</th> 19078<th class="tableblock halign-left valign-top">Value</th> 19079<th class="tableblock halign-left valign-top">Description</th> 19080</tr> 19081</thead> 19082<tbody> 19083<tr> 19084<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19085<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19086<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19087<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to delete.</p></td> 19088</tr> 19089</tbody> 19090</table> 19091<table class="tableblock frame-all grid-all spread"> 19092<caption class="title">Table 61. Delete a process instance - Response codes</caption> 19093<colgroup> 19094<col style="width: 50%;"> 19095<col style="width: 50%;"> 19096</colgroup> 19097<thead> 19098<tr> 19099<th class="tableblock halign-left valign-top">Response code</th> 19100<th class="tableblock halign-left valign-top">Description</th> 19101</tr> 19102</thead> 19103<tbody> 19104<tr> 19105<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 19106<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and deleted. Response body is left empty intentionally.</p></td> 19107</tr> 19108<tr> 19109<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19110<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 19111</tr> 19112</tbody> 19113</table> 19114</div> 19115<div class="sect3"> 19116<h4 id="_activate_or_suspend_a_process_instance">13.5.3. Activate or suspend a process instance</h4> 19117<div class="listingblock"> 19118<div class="content"> 19119<pre>PUT runtime/process-instances/{processInstanceId}</pre> 19120</div> 19121</div> 19122<table class="tableblock frame-all grid-all spread"> 19123<caption class="title">Table 62. Activate or suspend a process instance - URL parameters</caption> 19124<colgroup> 19125<col style="width: 25%;"> 19126<col style="width: 25%;"> 19127<col style="width: 25%;"> 19128<col style="width: 25%;"> 19129</colgroup> 19130<thead> 19131<tr> 19132<th class="tableblock halign-left valign-top">Parameter</th> 19133<th class="tableblock halign-left valign-top">Required</th> 19134<th class="tableblock halign-left valign-top">Value</th> 19135<th class="tableblock halign-left valign-top">Description</th> 19136</tr> 19137</thead> 19138<tbody> 19139<tr> 19140<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19141<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19142<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19143<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to activate/suspend.</p></td> 19144</tr> 19145</tbody> 19146</table> 19147<div class="paragraph"> 19148<p><strong>Request response body (suspend):</strong></p> 19149</div> 19150<div class="listingblock"> 19151<div class="content"> 19152<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 191532 191543</div></td><td class="code"><span></span><span class="tok-p">{</span> 19155 <span class="tok-nt">"action"</span><span class="tok-p">:</span><span class="tok-s2">"suspend"</span> 19156<span class="tok-p">}</span> 19157</td></tr></table></code></pre> 19158</div> 19159</div> 19160<div class="paragraph"> 19161<p><strong>Request response body (activate):</strong></p> 19162</div> 19163<div class="listingblock"> 19164<div class="content"> 19165<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 191662 191673</div></td><td class="code"><span></span><span class="tok-p">{</span> 19168 <span class="tok-nt">"action"</span><span class="tok-p">:</span><span class="tok-s2">"activate"</span> 19169<span class="tok-p">}</span> 19170</td></tr></table></code></pre> 19171</div> 19172</div> 19173<table class="tableblock frame-all grid-all spread"> 19174<caption class="title">Table 63. Activate or suspend a process instance - Response codes</caption> 19175<colgroup> 19176<col style="width: 50%;"> 19177<col style="width: 50%;"> 19178</colgroup> 19179<thead> 19180<tr> 19181<th class="tableblock halign-left valign-top">Response code</th> 19182<th class="tableblock halign-left valign-top">Description</th> 19183</tr> 19184</thead> 19185<tbody> 19186<tr> 19187<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 19188<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and action was executed.</p></td> 19189</tr> 19190<tr> 19191<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 19192<td class="tableblock halign-left valign-top"><p class="tableblock">
19192Indicates an invalid action was supplied.</p></td> 19193</tr> 19194<tr> 19195<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19196<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 19197</tr> 19198<tr> 19199<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 19200<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance action cannot be executed since the process-instance is already activated/suspended.</p></td> 19201</tr> 19202</tbody> 19203</table> 19204</div> 19205<div class="sect3"> 19206<h4 id="_start_a_process_instance">13.5.4. Start a process instance</h4> 19207<div class="listingblock"> 19208<div class="content"> 19209<pre>POST runtime/process-instances</pre> 19210</div> 19211</div> 19212<div class="paragraph"> 19213<p><strong>Request body (start by process definition id):</strong></p> 19214</div> 19215<div class="listingblock"> 19216<div class="content"> 19217<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19218 2 19219 3 19220 4 19221 5 19222 6 19223 7 19224 8 19225 9 1922610</div></td><td class="code"><span></span><span class="tok-p">{</span> 19227 <span class="tok-nt">"processDefinitionId"</span><span class="tok-p">:</span><span class="tok-s2">"oneTaskProcess:1:158"</span><span class="tok-p">,</span> 19228 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19229 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 19230 <span class="tok-p">{</span> 19231 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"myVar"</span><span class="tok-p">,</span> 19232 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"This is a variable"</span><span class="tok-p">,</span> 19233 <span class="tok-p">}</span> 19234 <span class="tok-p">]</span> 19235<span class="tok-p">}</span> 19236</td></tr></table></code></pre> 19237</div> 19238</div> 19239<div class="paragraph"> 19240<p><strong>Request body (start by process definition key):</strong></p> 19241</div> 19242<div class="listingblock"> 19243<div class="content"> 19244<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19245 2 19246 3 19247 4 19248 5 19249 6 19250 7 19251 8 19252 9 1925310 1925411</div></td><td class="code"><span></span><span class="tok-p">{</span> 19255 <span class="tok-nt">"processDefinitionKey"</span><span class="tok-p">:</span><span class="tok-s2">"oneTaskProcess"</span><span class="tok-p">,</span> 19256 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19257 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span> <span class="tok-s2">"tenant1"</span><span class="tok-p">,</span> 19258 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 19259 <span class="tok-p">{</span> 19260 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"myVar"</span><span class="tok-p">,</span> 19261 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"This is a variable"</span><span class="tok-p">,</span> 19262 <span class="tok-p">}</span> 19263 <span class="tok-p">]</span> 19264<span class="tok-p">}</span> 19265</td></tr></table></code></pre> 19266</div> 19267</div> 19268<div class="paragraph"> 19269<p><strong>Request body (start by message):</strong></p> 19270</div> 19271<div class="listingblock"> 19272<div class="content"> 19273<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19274 2 19275 3 19276 4 19277 5 19278 6 19279 7 19280 8 19281 9 1928210 1928311</div></td><td class="code"><span></span><span class="tok-p">{</span> 19284 <span class="tok-nt">"message"</span><span class="tok-p">:</span><span class="tok-s2">"newOrderMessage"</span><span class="tok-p">,</span> 19285 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19286 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span> <span class="tok-s2">"tenant1"</span><span class="tok-p">,</span> 19287 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span>
19288 <span class="tok-p">{</span> 19289 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"myVar"</span><span class="tok-p">,</span> 19290 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"This is a variable"</span><span class="tok-p">,</span> 19291 <span class="tok-p">}</span> 19292 <span class="tok-p">]</span> 19293<span class="tok-p">}</span> 19294</td></tr></table></code></pre> 19295</div> 19296</div> 19297<div class="paragraph"> 19298<p>Note that also a <em>transientVariables</em> property is accepted as part of this json, that follows the same structure as the <em>variables</em> property.</p> 19299</div> 19300<div class="paragraph"> 19301<p>Only one of <code>processDefinitionId</code>, <code>processDefinitionKey</code> or <code>message</code> can be used in the request body. Parameters <code>businessKey</code>, <code>variables</code> and <code>tenantId</code> are optional. If <code>tenantId</code> is omitted, the default tenant will be used. More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>. Note that the variable-scope that is supplied is ignored, process-variables are always <code>local</code>.</p> 19302</div> 19303<table class="tableblock frame-all grid-all spread"> 19304<caption class="title">Table 64. Start a process instance - Response codes</caption> 19305<colgroup> 19306<col style="width: 50%;"> 19307<col style="width: 50%;"> 19308</colgroup> 19309<thead> 19310<tr> 19311<th class="tableblock halign-left valign-top">Response code</th> 19312<th class="tableblock halign-left valign-top">Description</th> 19313</tr> 19314</thead> 19315<tbody> 19316<tr> 19317<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 19318<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was created.</p></td> 19319</tr> 19320<tr> 19321<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 19322<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates either the process-definition was not found (based on id or key), no process is started by sending the given message or an invalid variable has been passed. Status description contains additional information about the error.</p></td> 19323</tr> 19324</tbody> 19325</table> 19326<div class="paragraph"> 19327<p><strong>Success response body:</strong></p> 19328</div> 19329<div class="listingblock"> 19330<div class="content"> 19331<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 193322 193333 193344 193355 193366 193377 193388 193399</div></td><td class="code"><span></span><span class="tok-p">{</span> 19340 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 19341 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/7"</span><span class="tok-p">,</span> 19342 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19343 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 19344 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4"</span><span class="tok-p">,</span> 19345 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span><span class="tok-p">,</span> 19346 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 19347<span class="tok-p">}</span> 19348</td></tr></table></code></pre> 19349</div> 19350</div> 19351</div> 19352<div class="sect3"> 19353<h4 id="restProcessInstancesGet">13.5.5. List of process instances</h4> 19354<div class="listingblock"> 19355<div class="content"> 19356<pre>GET runtime/process-instances</pre> 19357</div> 19358</div> 19359<table class="tableblock frame-all grid-all spread"> 19360<caption class="title">
19360Table 65. List of process instances - URL query parameters</caption> 19361<colgroup> 19362<col style="width: 25%;"> 19363<col style="width: 25%;"> 19364<col style="width: 25%;"> 19365<col style="width: 25%;"> 19366</colgroup> 19367<thead> 19368<tr> 19369<th class="tableblock halign-left valign-top">Parameter</th> 19370<th class="tableblock halign-left valign-top">Required</th> 19371<th class="tableblock halign-left valign-top">Value</th> 19372<th class="tableblock halign-left valign-top">Description</th> 19373</tr> 19374</thead> 19375<tbody> 19376<tr> 19377<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 19378<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19379<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19380<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instance with the given id.</p></td> 19381</tr> 19382<tr> 19383<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKey</p></td> 19384<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19385<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19386<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances with the given process definition key.</p></td> 19387</tr> 19388<tr> 19389<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 19390<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19391<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19392<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances with the given process definition id.</p></td> 19393</tr> 19394<tr> 19395<td class="tableblock halign-left valign-top"><p class="tableblock">businessKey</p></td> 19396<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19397<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19398<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances with the given businessKey.</p></td> 19399</tr> 19400<tr> 19401<td class="tableblock halign-left valign-top"><p class="tableblock">involvedUser</p></td> 19402<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19403<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19404<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances in which the given user is involved.</p></td> 19405</tr> 19406<tr> 19407<td class="tableblock halign-left valign-top"><p class="tableblock">suspended</p></td> 19408<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19409<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 19410<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return process instance which are suspended. If <code>false</code>, only return process instances which are not suspended (active).</p></td> 19411</tr> 19412<tr> 19413<td class="tableblock halign-left valign-top"><p class="tableblock">superProcessInstanceId</p></td> 19414<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19415<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19416<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances which have the given super process-instance id (for processes that have a call-activities).</p></td> 19417</tr> 19418<tr> 19419<td class="tableblock halign-left valign-top"><p class="tableblock">subProcessInstanceId</p></td> 19420<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19421<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19422<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances which have the given sub process-instance id (for processes started as a call-activity).</p></td> 19423</tr> 19424<tr> 19425<td class="tableblock halign-left valign-top"><p class="tableblock">excludeSubprocesses</p></td> 19426<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19427<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 19428<td class="tableblock halign-left valign-top"><p class="tableblock">Return only process instances which aren’t sub processes.</p></td> 19429</tr> 19430<tr> 19431<td class="tableblock halign-left valign-top"><p class="tableblock">includeProcessVariables</p></td> 19432<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19433<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 19434<td class="tableblock halign-left valign-top"><p class="tableblock">Indication to include process variables in the result.</p></td> 19435</tr> 19436<tr> 19437<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 19438<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19439<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19440<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances with the given tenantId.</p></td> 19441</tr> 19442<tr> 19443<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 19444<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19445<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19446<td class="tableblock halign-left valign-top"><p class="tableblock">Only return process instances with a tenantId like the given value.</p></td> 19447</tr> 19448<tr> 19449<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 19450<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19451<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 19452<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns process instances without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 19453</tr> 19454<tr> 19455<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 19456<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 19457<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19458<td class="tableblock halign-left valign-top"><p class="tableblock">Sort field, should be either one of <code>id</code> (default), <code>processDefinitionId</code>, <code>tenantId</code> or <code>processDefinitionKey</code>.</p></td> 19459</tr> 19460</tbody> 19461</table> 19462<table class="tableblock frame-all grid-all spread"> 19463<caption class="title">Table 66. List of process instances - Response codes</caption> 19464<colgroup> 19465<col style="width: 50%;"> 19466<col style="width: 50%;"> 19467</colgroup> 19468<thead> 19469<tr> 19470<th class="tableblock halign-left valign-top">Response code</th> 19471<th class="tableblock halign-left valign-top">Description</th> 19472</tr> 19473</thead> 19474<tbody> 19475<tr> 19476<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 19477<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the process-instances are returned</p></td> 19478</tr> 19479<tr> 19480<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 19481<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format . The status-message contains additional information.</p></td> 19482</tr> 19483</tbody> 19484</table> 19485<div class="paragraph"> 19486<p><strong>Success response body:</strong></p> 19487</div> 19488<div class="listingblock"> 19489<div class="content"> 19490<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19491 2 19492 3 19493 4 19494 5 19495 6 19496 7 19497 8 19498 9 1949910 1950011 1950112 1950213 1950314 1950415 1950516 1950617 1950718 1950819 1950920</div></td><td class="code"><span></span><span class="tok-p">{</span> 19510 <span class="tok-nt">"data"</span><span class="tok-p">:[</span>
19511 <span class="tok-p">{</span> 19512 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 19513 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/7"</span><span class="tok-p">,</span> 19514 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19515 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 19516 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4"</span><span class="tok-p">,</span> 19517 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span><span class="tok-p">,</span> 19518 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 19519 <span class="tok-p">}</span> 19520 19521 19522 <span class="tok-p">],</span> 19523 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 19524 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 19525 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"id"</span><span class="tok-p">,</span> 19526 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 19527 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">2</span> 19528<span class="tok-p">}</span> 19529</td></tr></table></code></pre> 19530</div> 19531</div> 19532</div> 19533<div class="sect3"> 19534<h4 id="_query_process_instances">13.5.6. Query process instances</h4> 19535<div class="listingblock"> 19536<div class="content"> 19537<pre>POST query/process-instances</pre> 19538</div> 19539</div> 19540<div class="paragraph"> 19541<p><strong>Request body:</strong></p> 19542</div> 19543<div class="listingblock"> 19544<div class="content"> 19545<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19546 2 19547 3 19548 4 19549 5 19550 6 19551 7 19552 8 19553 9 1955410 1955511 1955612</div></td><td class="code"><span></span><span class="tok-p">{</span> 19557 <span class="tok-nt">"processDefinitionKey"</span><span class="tok-p">:</span><span class="tok-s2">"oneTaskProcess"</span><span class="tok-p">,</span> 19558 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> 19559 <span class="tok-p">[</span> 19560 <span class="tok-p">{</span> 19561 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 19562 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mi">1234</span><span class="tok-p">,</span> 19563 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 19564 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"long"</span> 19565 <span class="tok-p">}</span> 19566 <span class="tok-p">]</span> 19567<span class="tok-p">}</span> 19568</td></tr></table></code></pre> 19569</div> 19570</div> 19571<div class="paragraph"> 19572<p>The request body can contain all possible filters that can be used in the <a href="#restProcessInstancesGet">List process instances</a> URL query. On top of these, it’s possible to provide an array of variables 19573to include in the query, with their format <a href="#restQueryVariable">described here</a>.</p> 19574</div> 19575<div class="paragraph"> 19576<p>The general <a href="#restPagingAndSort">paging and sorting query-parameters</a> can be used for this URL.</p> 19577</div> 19578<table class="tableblock frame-all grid-all spread"> 19579<caption class="title">Table 67. Query process instances - Response codes</caption> 19580<colgroup> 19581<col style="width: 50%;"> 19582<col style="width: 50%;"> 19583</colgroup> 19584<thead> 19585<tr> 19586<th class="tableblock halign-left valign-top">Response code</th> 19587<th class="tableblock halign-left valign-top">Description</th> 19588</tr> 19589</thead> 19590<tbody> 19591<tr> 19592<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 19593<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the process-instances are returned</p></td> 19594</tr> 19595<tr> 19596<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 19597<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format . The status-message contains additional information.</p></td> 19598</tr> 19599</tbody> 19600</table> 19601<div class="paragraph"> 19602<p><strong>Success response body:</strong></p> 19603</div> 19604<div class="listingblock"> 19605<div class="content"> 19606<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19607 2 19608 3 19609 4 19610 5 19611 6 19612 7 19613 8 19614 9 1961510 1961611 1961712 1961813 1961914 1962015 1962116 1962217 1962318 1962419 1962520</div></td><td class="code"><span></span><span class="tok-p">{</span> 19626 <span class="tok-nt">"data"</span><span class="tok-p">:[</span>
19627 <span class="tok-p">{</span> 19628 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 19629 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/7"</span><span class="tok-p">,</span> 19630 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19631 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 19632 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4"</span><span class="tok-p">,</span> 19633 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span><span class="tok-p">,</span> 19634 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 19635 <span class="tok-p">}</span> 19636 19637 19638 <span class="tok-p">],</span> 19639 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 19640 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 19641 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"id"</span><span class="tok-p">,</span> 19642 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 19643 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">2</span> 19644<span class="tok-p">}</span> 19645</td></tr></table></code></pre> 19646</div> 19647</div> 19648</div> 19649<div class="sect3"> 19650<h4 id="_get_diagram_for_a_process_instance">13.5.7. Get diagram for a process instance</h4> 19651<div class="listingblock"> 19652<div class="content"> 19653<pre>GET runtime/process-instances/{processInstanceId}/diagram</pre> 19654</div> 19655</div> 19656<table class="tableblock frame-all grid-all spread"> 19657<caption class="title">Table 68. Get diagram for a process instance - URL parameters</caption> 19658<colgroup> 19659<col style="width: 25%;"> 19660<col style="width: 25%;"> 19661<col style="width: 25%;"> 19662<col style="width: 25%;"> 19663</colgroup> 19664<thead> 19665<tr> 19666<th class="tableblock halign-left valign-top">Parameter</th> 19667<th class="tableblock halign-left valign-top">Required</th> 19668<th class="tableblock halign-left valign-top">Value</th> 19669<th class="tableblock halign-left valign-top">Description</th> 19670</tr> 19671</thead> 19672<tbody> 19673<tr> 19674<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19675<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19676<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19677<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to get the diagram for.</p></td> 19678</tr> 19679</tbody> 19680</table> 19681<table class="tableblock frame-all grid-all spread"> 19682<caption class="title">Table 69. Get diagram for a process instance - Response codes</caption> 19683<colgroup> 19684<col style="width: 50%;"> 19685<col style="width: 50%;"> 19686</colgroup> 19687<thead> 19688<tr> 19689<th class="tableblock halign-left valign-top">Response code</th> 19690<th class="tableblock halign-left valign-top">Description</th> 19691</tr> 19692</thead> 19693<tbody> 19694<tr> 19695<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 19696<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and the diagram was returned.</p></td> 19697</tr> 19698<tr> 19699<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 19700<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found but the process doesn’t contain any graphical information (BPMN:DI) and no diagram can be created.</p></td> 19701</tr> 19702<tr> 19703<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19704<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 19705</tr> 19706</tbody> 19707</table> 19708<div class="paragraph"> 19709<p><strong>Success response body:</strong></p> 19710</div> 19711<div class="listingblock"> 19712<div class="content"> 19713<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 197142 197153 197164 197175 197186 197197 197208</div></td><td class="code"><span></span><span class="tok-p">{</span> 19721 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 19722 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/7"</span><span class="tok-p">,</span> 19723 <span class="tok-nt">"businessKey"</span><span class="tok-p">:</span><span class="tok-s2">"myBusinessKey"</span><span class="tok-p">,</span> 19724 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">
19724false</span><span class="tok-p">,</span> 19725 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4"</span><span class="tok-p">,</span> 19726 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span> 19727<span class="tok-p">}</span> 19728</td></tr></table></code></pre> 19729</div> 19730</div> 19731</div> 19732<div class="sect3"> 19733<h4 id="_get_involved_people_for_process_instance">13.5.8. Get involved people for process instance</h4> 19734<div class="listingblock"> 19735<div class="content"> 19736<pre>GET runtime/process-instances/{processInstanceId}/identitylinks</pre> 19737</div> 19738</div> 19739<table class="tableblock frame-all grid-all spread"> 19740<caption class="title">Table 70. Get involved people for process instance - URL parameters</caption> 19741<colgroup> 19742<col style="width: 25%;"> 19743<col style="width: 25%;"> 19744<col style="width: 25%;"> 19745<col style="width: 25%;"> 19746</colgroup> 19747<thead> 19748<tr> 19749<th class="tableblock halign-left valign-top">Parameter</th> 19750<th class="tableblock halign-left valign-top">Required</th> 19751<th class="tableblock halign-left valign-top">Value</th> 19752<th class="tableblock halign-left valign-top">Description</th> 19753</tr> 19754</thead> 19755<tbody> 19756<tr> 19757<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19758<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19759<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19760<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to the links for.</p></td> 19761</tr> 19762</tbody> 19763</table> 19764<table class="tableblock frame-all grid-all spread"> 19765<caption class="title">Table 71. Get involved people for process instance - Response codes</caption> 19766<colgroup> 19767<col style="width: 50%;"> 19768<col style="width: 50%;"> 19769</colgroup> 19770<thead> 19771<tr> 19772<th class="tableblock halign-left valign-top">Response code</th> 19773<th class="tableblock halign-left valign-top">Description</th> 19774</tr> 19775</thead> 19776<tbody> 19777<tr> 19778<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 19779<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and links are returned.</p></td> 19780</tr> 19781<tr> 19782<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19783<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 19784</tr> 19785</tbody> 19786</table> 19787<div class="paragraph"> 19788<p><strong>Success response body:</strong></p> 19789</div> 19790<div class="listingblock"> 19791<div class="content"> 19792<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 19793 2 19794 3 19795 4 19796 5 19797 6 19798 7 19799 8 19800 9 1980110 1980211 1980312 1980413 1980514</div></td><td class="code"><span></span><span class="tok-p">[</span> 19806 <span class="tok-p">{</span> 19807 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType"</span><span class="tok-p">,</span> 19808 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"john"</span><span class="tok-p">,</span> 19809 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 19810 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"customType"</span> 19811 <span class="tok-p">},</span> 19812 <span class="tok-p">{</span> 19813 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5/identitylinks/users/paul/candidate"</span><span class="tok-p">,</span> 19814 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"paul"</span><span class="tok-p">,</span>
19815 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 19816 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"candidate"</span> 19817 <span class="tok-p">}</span> 19818<span class="tok-p">]</span> 19819</td></tr></table></code></pre> 19820</div> 19821</div> 19822<div class="paragraph"> 19823<p>Note that the <code>groupId</code> will always be null, as it’s only possible to involve users with a process-instance.</p> 19824</div> 19825</div> 19826<div class="sect3"> 19827<h4 id="_add_an_involved_user_to_a_process_instance">13.5.9. Add an involved user to a process instance</h4> 19828<div class="listingblock"> 19829<div class="content"> 19830<pre>POST runtime/process-instances/{processInstanceId}/identitylinks</pre> 19831</div> 19832</div> 19833<table class="tableblock frame-all grid-all spread"> 19834<caption class="title">Table 72. Add an involved user to a process instance - URL parameters</caption> 19835<colgroup> 19836<col style="width: 25%;"> 19837<col style="width: 25%;"> 19838<col style="width: 25%;"> 19839<col style="width: 25%;"> 19840</colgroup> 19841<thead> 19842<tr> 19843<th class="tableblock halign-left valign-top">Parameter</th> 19844<th class="tableblock halign-left valign-top">Required</th> 19845<th class="tableblock halign-left valign-top">Value</th> 19846<th class="tableblock halign-left valign-top">Description</th> 19847</tr> 19848</thead> 19849<tbody> 19850<tr> 19851<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19852<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19853<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19854<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to the links for.</p></td> 19855</tr> 19856</tbody> 19857</table> 19858<div class="paragraph"> 19859<p><strong>Request body:</strong></p> 19860</div> 19861<div class="listingblock"> 19862<div class="content"> 19863<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 198642 198653 198664</div></td><td class="code"><span></span><span class="tok-p">{</span> 19867 <span class="tok-nt">"userId"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 19868 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"participant"</span> 19869<span class="tok-p">}</span> 19870</td></tr></table></code></pre> 19871</div> 19872</div> 19873<div class="paragraph"> 19874<p>Both <code>userId</code> and <code>type</code> are required.</p> 19875</div> 19876<table class="tableblock frame-all grid-all spread"> 19877<caption class="title">Table 73. Add an involved user to a process instance - Response codes</caption> 19878<colgroup> 19879<col style="width: 50%;"> 19880<col style="width: 50%;"> 19881</colgroup> 19882<thead> 19883<tr> 19884<th class="tableblock halign-left valign-top">Response code</th> 19885<th class="tableblock halign-left valign-top">Description</th> 19886</tr> 19887</thead> 19888<tbody> 19889<tr> 19890<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 19891<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and the link is created.</p></td> 19892</tr> 19893<tr> 19894<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 19895<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested body did not contain a userId or a type.</p></td> 19896</tr> 19897<tr> 19898<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19899<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 19900</tr> 19901</tbody> 19902</table> 19903<div class="paragraph"> 19904<p><strong>Success response body:</strong></p> 19905</div> 19906<div class="listingblock"> 19907<div class="content"> 19908<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 199092 199103 199114 199125 199136</div></td><td class="code"><span></span><span class="tok-p">{</span> 19914 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType"</span><span class="tok-p">,</span> 19915 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"john"</span><span class="tok-p">,</span> 19916 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 19917 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"customType"</span> 19918<span class="tok-p">}</span> 19919</td></tr></table></code></pre> 19920</div> 19921</div> 19922<div class="paragraph"> 19923<p>Note that the <code>groupId</code> will always be null, as it’s only possible to involve users with a process-instance.</p> 19924</div> 19925</div> 19926<div class="sect3"> 19927<h4 id="_remove_an_involved_user_to_from_process_instance">13.5.10. Remove an involved user to from process instance</h4> 19928<div class="listingblock"> 19929<div class="content"> 19930<pre>DELETE runtime/process-instances/{processInstanceId}/identitylinks/users/{userId}/{type}</pre> 19931</div> 19932</div> 19933<table class="tableblock frame-all grid-all spread"> 19934<caption class="title">Table 74. Remove an involved user to from process instance - URL parameters</caption> 19935<colgroup> 19936<col style="width: 25%;"> 19937<col style="width: 25%;"> 19938<col style="width: 25%;"> 19939<col style="width: 25%;"> 19940</colgroup> 19941<thead> 19942<tr> 19943<th class="tableblock halign-left valign-top">Parameter</th> 19944<th class="tableblock halign-left valign-top">Required</th> 19945<th class="tableblock halign-left valign-top">Value</th> 19946<th class="tableblock halign-left valign-top">Description</th> 19947</tr> 19948</thead> 19949<tbody> 19950<tr> 19951<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 19952<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19953<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19954<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance.</p></td> 19955</tr> 19956<tr> 19957<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 19958<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19959<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19960<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to delete link for.</p></td> 19961</tr> 19962<tr> 19963<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td> 19964<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 19965<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 19966<td class="tableblock halign-left valign-top"><p class="tableblock">Type of link to delete.</p></td> 19967</tr> 19968</tbody> 19969</table> 19970<table class="tableblock frame-all grid-all spread"> 19971<caption class="title">Table 75. Remove an involved user to from process instance - Response codes</caption> 19972<colgroup> 19973<col style="width: 50%;"> 19974<col style="width: 50%;"> 19975</colgroup> 19976<thead> 19977<tr> 19978<th class="tableblock halign-left valign-top">Response code</th> 19979<th class="tableblock halign-left valign-top">Description</th> 19980</tr> 19981</thead> 19982<tbody> 19983<tr> 19984<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 19985<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and the link has been deleted. Response body is left empty intentionally.</p></td> 19986</tr> 19987<tr> 19988<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 19989<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found or the link to delete doesn’t exist. The response status contains additional information about the error.</p></td> 19990</tr> 19991</tbody> 19992</table> 19993<div class="paragraph"> 19994<p><strong>Success response body:</strong></p> 19995</div> 19996<div class="listingblock"> 19997<div class="content"> 19998<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 199992 200003 200014 200025 200036</div></td><td class="code"><span></span><span class="tok-p">{</span> 20004 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType"</span><span class="tok-p">,</span> 20005 <span class="tok-nt">"user"</span><span class="tok-p">:</span><span class="tok-s2">"john"</span><span class="tok-p">,</span> 20006 <span class="tok-nt">"group"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20007 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"customType"</span> 20008<span class="tok-p">}</span> 20009</td></tr></table></code></pre> 20010</div> 20011</div> 20012<div class="paragraph"> 20013<p>Note that the <code>groupId</code> will always be null, as it’s only possible to involve users with a process-instance.</p> 20014</div> 20015</div> 20016<div class="sect3"> 20017<h4 id="_list_of_variables_for_a_process_instance">13.5.11. List of variables for a process instance</h4> 20018<div class="listingblock"> 20019<div class="content"> 20020<pre>GET runtime/process-instances/{processInstanceId}/variables</pre> 20021</div> 20022</div> 20023<table class="tableblock frame-all grid-all spread"> 20024<caption class="title">Table 76. List of variables for a process instance - URL parameters</caption> 20025<colgroup> 20026<col style="width: 25%;"> 20027<col style="width: 25%;"> 20028<col style="width: 25%;"> 20029<col style="width: 25%;"> 20030</colgroup> 20031<thead> 20032<tr> 20033<th class="tableblock halign-left valign-top">Parameter</th> 20034<th class="tableblock halign-left valign-top">Required</th> 20035<th class="tableblock halign-left valign-top">Value</th> 20036<th class="tableblock halign-left valign-top">Description</th> 20037</tr> 20038</thead> 20039<tbody> 20040<tr> 20041<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 20042<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20043<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20044<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to the variables for.</p></td> 20045</tr> 20046</tbody> 20047</table> 20048<table class="tableblock frame-all grid-all spread"> 20049<caption class="title">Table 77. List of variables for a process instance - Response codes</caption> 20050<colgroup> 20051<col style="width: 50%;"> 20052<col style="width: 50%;"> 20053</colgroup> 20054<thead> 20055<tr> 20056<th class="tableblock halign-left valign-top">Response code</th> 20057<th class="tableblock halign-left valign-top">Description</th> 20058</tr> 20059</thead> 20060<tbody> 20061<tr> 20062<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20063<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and variables are returned.</p></td> 20064</tr> 20065<tr> 20066<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20067<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 20068</tr> 20069</tbody> 20070</table> 20071<div class="paragraph"> 20072<p><strong>Success response body:</strong></p> 20073</div> 20074<div class="listingblock"> 20075<div class="content"> 20076<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 20077 2 20078 3 20079 4 20080 5 20081 6 20082 7 20083 8 20084 9 2008510 2008611 2008712 2008813 2008914 2009015</div></td><td class="code"><span></span><span class="tok-p">[</span> 20091 <span class="tok-p">{</span>
20092 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 20093 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 20094 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 20095 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 20096 <span class="tok-p">},</span> 20097 <span class="tok-p">{</span> 20098 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"byteArrayProcVar"</span><span class="tok-p">,</span> 20099 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"binary"</span><span class="tok-p">,</span> 20100 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20101 <span class="tok-nt">"valueUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5/variables/byteArrayProcVar/data"</span><span class="tok-p">,</span> 20102 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 20103 <span class="tok-p">}</span> 20104<span class="tok-p">]</span> 20105</td></tr></table></code></pre> 20106</div> 20107</div> 20108<div class="paragraph"> 20109<p>In case the variable is a binary variable or serializable, the <code>valueUrl</code> points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response. 20110Note that only <code>local</code> scoped variables are returned, as there is no <code>global</code> scope for process-instance variables.</p> 20111</div> 20112</div> 20113<div class="sect3"> 20114<h4 id="_get_a_variable_for_a_process_instance">13.5.12. Get a variable for a process instance</h4> 20115<div class="listingblock"> 20116<div class="content"> 20117<pre>GET runtime/process-instances/{processInstanceId}/variables/{variableName}</pre> 20118</div> 20119</div> 20120<table class="tableblock frame-all grid-all spread"> 20121<caption class="title">Table 78. Get a variable for a process instance - URL parameters</caption> 20122<colgroup> 20123<col style="width: 25%;"> 20124<col style="width: 25%;"> 20125<col style="width: 25%;"> 20126<col style="width: 25%;"> 20127</colgroup> 20128<thead> 20129<tr> 20130<th class="tableblock halign-left valign-top">Parameter</th> 20131<th class="tableblock halign-left valign-top">Required</th> 20132<th class="tableblock halign-left valign-top">Value</th> 20133<th class="tableblock halign-left valign-top">Description</th> 20134</tr> 20135</thead> 20136<tbody> 20137<tr> 20138<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 20139<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20140<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20141<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to the variables for.</p></td> 20142</tr> 20143<tr> 20144<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 20145<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20146<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20147<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the variable to get.</p></td> 20148</tr> 20149</tbody> 20150</table> 20151<table class="tableblock frame-all grid-all spread"> 20152<caption class="title">Table 79. Get a variable for a process instance - Response codes</caption> 20153<colgroup> 20154<col style="width: 50%;"> 20155<col style="width: 50%;"> 20156</colgroup> 20157<thead> 20158<tr> 20159<th class="tableblock halign-left valign-top">Response code</th> 20160<th class="tableblock halign-left valign-top">Description</th> 20161</tr> 20162</thead> 20163<tbody> 20164<tr> 20165<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20166<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates both the process instance and variable were found and variable is returned.</p></td> 20167</tr> 20168<tr> 20169<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 20170<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.</p></td> 20171</tr> 20172<tr> 20173<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20174<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.</p></td> 20175</tr> 20176</tbody> 20177</table> 20178<div class="paragraph"> 20179<p><strong>Success response body:</strong></p> 20180</div> 20181<div class="listingblock"> 20182<div class="content"> 20183<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 201842 201853 201864 201875 201886</div></td><td class="code"><span></span> <span class="tok-p">{</span>
20189 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 20190 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 20191 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 20192 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 20193 <span class="tok-p">}</span> 20194</td></tr></table></code></pre> 20195</div> 20196</div> 20197<div class="paragraph"> 20198<p>In case the variable is a binary variable or serializable, the <code>valueUrl</code> points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response. Note that only <code>local</code> scoped variables are returned, as there is no <code>global</code> scope for process-instance variables.</p> 20199</div> 20200</div> 20201<div class="sect3"> 20202<h4 id="_create_or_update_variables_on_a_process_instance">13.5.13. Create (or update) variables on a process instance</h4> 20203<div class="listingblock"> 20204<div class="content"> 20205<pre>POST runtime/process-instances/{processInstanceId}/variables</pre> 20206</div> 20207</div> 20208<div class="listingblock"> 20209<div class="content"> 20210<pre>PUT runtime/process-instances/{processInstanceId}/variables</pre> 20211</div> 20212</div> 20213<div class="paragraph"> 20214<p>When using <code>POST</code>, all variables that are passed are created. In case one of the variables already exists on the process instance, the request results in an error (409 - CONFLICT). When <code>PUT</code> is used, nonexistent variables are created on the process-instance and existing ones are overridden without any error.</p> 20215</div> 20216<table class="tableblock frame-all grid-all spread"> 20217<caption class="title">Table 80. Create (or update) variables on a process instance - URL parameters</caption> 20218<colgroup> 20219<col style="width: 25%;"> 20220<col style="width: 25%;"> 20221<col style="width: 25%;"> 20222<col style="width: 25%;"> 20223</colgroup> 20224<thead> 20225<tr> 20226<th class="tableblock halign-left valign-top">Parameter</th> 20227<th class="tableblock halign-left valign-top">Required</th> 20228<th class="tableblock halign-left valign-top">Value</th> 20229<th class="tableblock halign-left valign-top">Description</th> 20230</tr> 20231</thead> 20232<tbody> 20233<tr> 20234<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 20235<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20236<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20237<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to the variables for.</p></td> 20238</tr> 20239</tbody> 20240</table> 20241<div class="paragraph"> 20242<p><strong>Request body:</strong></p> 20243</div> 20244<div class="listingblock"> 20245<div class="content"> 20246<pre>[ 20247 { 20248 "name":"intProcVar" 20249 "type":"integer" 20250 "value":123 20251 }, 20252 20253 ... 20254]</pre> 20255</div> 20256</div> 20257<div class="paragraph"> 20258<p>Any number of variables can be passed into the request body array. More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>. Note that scope is ignored, only <code>local</code> variables can be set in a process instance.</p> 20259</div> 20260<table class="tableblock frame-all grid-all spread"> 20261<caption class="title">Table 81. Create (or update) variables on a process instance - Response codes</caption> 20262<colgroup> 20263<col style="width: 50%;"> 20264<col style="width: 50%;"> 20265</colgroup> 20266<thead> 20267<tr> 20268<th class="tableblock halign-left valign-top">Response code</th> 20269<th class="tableblock halign-left valign-top">Description</th> 20270</tr> 20271</thead> 20272<tbody> 20273<tr> 20274<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 20275<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and variable is created.</p></td> 20276</tr> 20277<tr> 20278<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 20279<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.</p></td> 20280</tr> 20281<tr> 20282<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20283<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 20284</tr> 20285<tr> 20286<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 20287<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found but already contains a variable with the given name (only thrown when POST method is used). Use the update-method instead.</p></td> 20288</tr> 20289</tbody> 20290</table> 20291<div class="paragraph"> 20292<p><strong>Success response body:</strong></p> 20293</div> 20294<div class="listingblock"> 20295<div class="content"> 20296<pre>[ 20297 { 20298 "name":"intProcVar", 20299 "type":"integer", 20300 "value":123, 20301 "scope":"local" 20302 }, 20303 20304 ... 20305 20306]</pre> 20307</div> 20308</div> 20309</div> 20310<div class="sect3"> 20311<h4 id="_update_a_single_variable_on_a_process_instance">13.5.14. Update a single variable on a process instance</h4> 20312<div class="listingblock"> 20313<div class="content"> 20314<pre>PUT runtime/process-instances/{processInstanceId}/variables/{variableName}</pre> 20315</div> 20316</div> 20317<table class="tableblock frame-all grid-all spread"> 20318<caption class="title">Table 82. Update a single variable on a process instance - URL parameters</caption> 20319<colgroup> 20320<col style="width: 25%;"> 20321<col style="width: 25%;"> 20322<col style="width: 25%;"> 20323<col style="width: 25%;"> 20324</colgroup> 20325<thead> 20326<tr> 20327<th class="tableblock halign-left valign-top">Parameter</th> 20328<th class="tableblock halign-left valign-top">Required</th> 20329<th class="tableblock halign-left valign-top">Value</th> 20330<th class="tableblock halign-left valign-top">Description</th> 20331</tr> 20332</thead> 20333<tbody> 20334<tr> 20335<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 20336<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20337<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20338<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to the variables for.</p></td> 20339</tr> 20340<tr> 20341<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 20342<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20343<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20344<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the variable to get.</p></td> 20345</tr> 20346</tbody> 20347</table> 20348<div class="paragraph"> 20349<p><strong>Request body:</strong></p> 20350</div> 20351<div class="listingblock"> 20352<div class="content"> 20353<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 203542 203553 203564 203575</div></td><td class="code"><span></span> <span class="tok-p">{</span> 20358 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span> 20359 <span class="tok-s2">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span> 20360 <span class="tok-s2">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span> 20361 <span class="tok-p">}</span> 20362</td></tr></table></code></pre> 20363</div> 20364</div> 20365<div class="paragraph"> 20366<p>More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>
20366. Note that scope is ignored, only <code>local</code> variables can be set in a process instance.</p> 20367</div> 20368<table class="tableblock frame-all grid-all spread"> 20369<caption class="title">Table 83. Update a single variable on a process instance - Response codes</caption> 20370<colgroup> 20371<col style="width: 50%;"> 20372<col style="width: 50%;"> 20373</colgroup> 20374<thead> 20375<tr> 20376<th class="tableblock halign-left valign-top">Response code</th> 20377<th class="tableblock halign-left valign-top">Description</th> 20378</tr> 20379</thead> 20380<tbody> 20381<tr> 20382<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20383<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates both the process instance and variable were found and variable is updated.</p></td> 20384</tr> 20385<tr> 20386<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20387<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.</p></td> 20388</tr> 20389</tbody> 20390</table> 20391<div class="paragraph"> 20392<p><strong>Success response body:</strong></p> 20393</div> 20394<div class="listingblock"> 20395<div class="content"> 20396<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 203972 203983 203994 204005 204016</div></td><td class="code"><span></span><span class="tok-p">{</span> 20402 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 20403 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 20404 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 20405 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 20406<span class="tok-p">}</span> 20407</td></tr></table></code></pre> 20408</div> 20409</div> 20410<div class="paragraph"> 20411<p>In case the variable is a binary variable or serializable, the <code>valueUrl</code> points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response. Note that only <code>local</code> scoped variables are returned, as there is no <code>global</code> scope for process-instance variables.</p> 20412</div> 20413</div> 20414<div class="sect3"> 20415<h4 id="_create_a_new_binary_variable_on_a_process_instance">13.5.15. Create a new binary variable on a process-instance</h4> 20416<div class="listingblock"> 20417<div class="content"> 20418<pre>POST runtime/process-instances/{processInstanceId}/variables</pre> 20419</div> 20420</div> 20421<table class="tableblock frame-all grid-all spread"> 20422<caption class="title">Table 84. Create a new binary variable on a process-instance - URL parameters</caption> 20423<colgroup> 20424<col style="width: 25%;"> 20425<col style="width: 25%;"> 20426<col style="width: 25%;"> 20427<col style="width: 25%;"> 20428</colgroup> 20429<thead> 20430<tr> 20431<th class="tableblock halign-left valign-top">Parameter</th> 20432<th class="tableblock halign-left valign-top">Required</th> 20433<th class="tableblock halign-left valign-top">Value</th> 20434<th class="tableblock halign-left valign-top">Description</th> 20435</tr> 20436</thead> 20437<tbody> 20438<tr> 20439<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 20440<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20441<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20442<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to create the new variable for.</p></td> 20443</tr> 20444</tbody> 20445</table> 20446<div class="paragraph"> 20447<p><strong>Request body:</strong></p> 20448</div> 20449<div class="paragraph"> 20450<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 20451</div> 20452<div class="ulist"> 20453<ul> 20454<li> 20455<p><code>name</code>: Required name of the variable.</p> 20456</li> 20457<li> 20458<p><code>type</code>: Type of variable that is created. If omitted, <code>binary</code> is assumed and the binary data in the request will be stored as an array of bytes.</p> 20459</li> 20460</ul> 20461</div> 20462<div class="paragraph"> 20463<p><strong>Success response body:</strong></p> 20464</div> 20465<div class="listingblock"> 20466<div class="content"> 20467<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 204682 204693 204704 204715 204726 204737</div></td><td class="code"><span></span><span class="tok-p">{</span> 20474 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"binaryVariable"</span><span class="tok-p">,</span> 20475 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 20476 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"binary"</span><span class="tok-p">,</span> 20477 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 20478 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://.../runtime/process-instances/123/variables/binaryVariable/data"</span> 20479<span class="tok-p">}</span> 20480</td></tr></table></code></pre> 20481</div> 20482</div> 20483<table class="tableblock frame-all grid-all spread"> 20484<caption class="title">Table 85. Create a new binary variable on a process-instance - Response codes</caption> 20485<colgroup> 20486<col style="width: 50%;"> 20487<col style="width: 50%;"> 20488</colgroup> 20489<thead> 20490<tr> 20491<th class="tableblock halign-left valign-top">Response code</th> 20492<th class="tableblock halign-left valign-top">Description</th> 20493</tr> 20494</thead> 20495<tbody> 20496<tr> 20497<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 20498<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable was created and the result is returned.</p></td> 20499</tr> 20500<tr> 20501<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 20502<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of the variable to create was missing. Status message provides additional information.</p></td> 20503</tr> 20504<tr> 20505<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20506<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found.</p></td> 20507</tr> 20508<tr> 20509<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 20510<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance already has a variable with the given name. Use the PUT method to update the task variable instead.</p></td> 20511</tr> 20512<tr> 20513<td class="tableblock halign-left valign-top"><p class="tableblock">415</p></td> 20514<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.</p></td> 20515</tr> 20516</tbody> 20517</table> 20518</div> 20519<div class="sect3"> 20520<h4 id="_update_an_existing_binary_variable_on_a_process_instance">13.5.16. Update an existing binary variable on a process-instance</h4> 20521<div class="listingblock"> 20522<div class="content"> 20523<pre>PUT runtime/process-instances/{processInstanceId}/variables</pre> 20524</div> 20525</div> 20526<table class="tableblock frame-all grid-all spread"> 20527<caption class="title">Table 86. Update an existing binary variable on a process-instance - URL parameters</caption> 20528<colgroup> 20529<col style="width: 25%;"> 20530<col style="width: 25%;"> 20531<col style="width: 25%;"> 20532<col style="width: 25%;"> 20533</colgroup> 20534<thead> 20535<tr> 20536<th class="tableblock halign-left valign-top">Parameter</th> 20537<th class="tableblock halign-left valign-top">Required</th> 20538<th class="tableblock halign-left valign-top">Value</th> 20539<th class="tableblock halign-left valign-top">Description</th> 20540</tr> 20541</thead> 20542<tbody> 20543<tr> 20544<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 20545<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20546<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20547<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to create the new variable for.</p></td> 20548</tr> 20549</tbody> 20550</table> 20551<div class="paragraph"> 20552<p><strong>Request body:</strong> 20553The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 20554</div> 20555<div class="ulist"> 20556<ul> 20557<li> 20558<p><code>name</code>: Required name of the variable.</p> 20559</li> 20560<li> 20561<p><code>type</code>: Type of variable that is created. If omitted, <code>binary</code> is assumed and the binary data in the request will be stored as an array of bytes.</p> 20562</li> 20563</ul> 20564</div> 20565<div class="paragraph"> 20566<p><strong>Success response body:</strong></p> 20567</div> 20568<div class="listingblock"> 20569<div class="content"> 20570<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 205712 205723 205734 205745 205756 205767</div></td><td class="code"><span></span><span class="tok-p">{</span> 20577 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"binaryVariable"</span><span class="tok-p">,</span> 20578 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 20579 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"binary"</span><span class="tok-p">,</span> 20580 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 20581 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://.../runtime/process-instances/123/variables/binaryVariable/data"</span> 20582<span class="tok-p">}</span> 20583</td></tr></table></code></pre> 20584</div> 20585</div> 20586<table class="tableblock frame-all grid-all spread"> 20587<caption class="title">Table 87. Update an existing binary variable on a process-instance - Response codes</caption> 20588<colgroup> 20589<col style="width: 50%;"> 20590<col style="width: 50%;"> 20591</colgroup> 20592<thead> 20593<tr> 20594<th class="tableblock halign-left valign-top">Response code</th> 20595<th class="tableblock halign-left valign-top">Description</th> 20596</tr> 20597</thead> 20598<tbody> 20599<tr> 20600<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20601<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable was updated and the result is returned.</p></td> 20602</tr> 20603<tr> 20604<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 20605<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of the variable to update was missing. Status message provides additional information.</p></td> 20606</tr> 20607<tr> 20608<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20609<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found or the process instance does not have a variable with the given name.</p></td> 20610</tr> 20611<tr> 20612<td class="tableblock halign-left valign-top"><p class="tableblock">415</p></td> 20613<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.</p></td> 20614</tr> 20615</tbody> 20616</table> 20617</div> 20618</div> 20619<div class="sect2"> 20620<h3 id="_executions">13.6. Executions</h3> 20621<div class="sect3"> 20622<h4 id="_get_an_execution">13.6.1. Get an execution</h4> 20623<div class="listingblock"> 20624<div class="content"> 20625<pre>GET runtime/executions/{executionId}</pre> 20626</div> 20627</div> 20628<table class="tableblock frame-all grid-all spread"> 20629<caption class="title">Table 88. Get an execution - URL parameters</caption> 20630<colgroup> 20631<col style="width: 25%;"> 20632<col style="width: 25%;"> 20633<col style="width: 25%;"> 20634<col style="width: 25%;"> 20635</colgroup> 20636<thead> 20637<tr> 20638<th class="tableblock halign-left valign-top">Parameter</th> 20639<th class="tableblock halign-left valign-top">Required</th> 20640<th class="tableblock halign-left valign-top">Value</th> 20641<th class="tableblock halign-left valign-top">Description</th> 20642</tr> 20643</thead> 20644<tbody> 20645<tr> 20646<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 20647<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20648<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20649<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to get.</p></td> 20650</tr> 20651</tbody> 20652</table> 20653<table class="tableblock frame-all grid-all spread"> 20654<caption class="title">Table 89. Get an execution - Response codes</caption> 20655<colgroup> 20656<col style="width: 50%;"> 20657<col style="width: 50%;"> 20658</colgroup> 20659<thead> 20660<tr> 20661<th class="tableblock halign-left valign-top">Response code</th> 20662<th class="tableblock halign-left valign-top">Description</th> 20663</tr> 20664</thead> 20665<tbody> 20666<tr> 20667<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20668<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found and returned.</p></td> 20669</tr> 20670<tr> 20671<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20672<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was not found.</p></td> 20673</tr> 20674</tbody> 20675</table> 20676<div class="paragraph"> 20677<p><strong>Success response body:</strong></p> 20678</div> 20679<div class="listingblock"> 20680<div class="content"> 20681<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 20682 2 20683 3 20684 4 20685 5 20686 6 20687 7 20688 8 20689 9 2069010 2069111</div></td><td class="code"><span></span><span class="tok-p">{</span> 20692 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 20693 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 20694 <span class="tok-nt">"parentId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20695 <span class="tok-nt">"parentUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20696 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 20697 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 20698 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">
20698false</span><span class="tok-p">,</span> 20699 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20700 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span> <span class="tok-kc">null</span> 20701<span class="tok-p">}</span> 20702</td></tr></table></code></pre> 20703</div> 20704</div> 20705</div> 20706<div class="sect3"> 20707<h4 id="_execute_an_action_on_an_execution">13.6.2. Execute an action on an execution</h4> 20708<div class="listingblock"> 20709<div class="content"> 20710<pre>PUT runtime/executions/{executionId}</pre> 20711</div> 20712</div> 20713<table class="tableblock frame-all grid-all spread"> 20714<caption class="title">Table 90. Execute an action on an execution - URL parameters</caption> 20715<colgroup> 20716<col style="width: 25%;"> 20717<col style="width: 25%;"> 20718<col style="width: 25%;"> 20719<col style="width: 25%;"> 20720</colgroup> 20721<thead> 20722<tr> 20723<th class="tableblock halign-left valign-top">Parameter</th> 20724<th class="tableblock halign-left valign-top">Required</th> 20725<th class="tableblock halign-left valign-top">Value</th> 20726<th class="tableblock halign-left valign-top">Description</th> 20727</tr> 20728</thead> 20729<tbody> 20730<tr> 20731<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 20732<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20733<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20734<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to execute action on.</p></td> 20735</tr> 20736</tbody> 20737</table> 20738<div class="paragraph"> 20739<p><strong>Request body (signal an execution):</strong></p> 20740</div> 20741<div class="listingblock"> 20742<div class="content"> 20743<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 207442 207453</div></td><td class="code"><span></span><span class="tok-p">{</span> 20746 <span class="tok-nt">"action"</span><span class="tok-p">:</span><span class="tok-s2">"signal"</span> 20747<span class="tok-p">}</span> 20748</td></tr></table></code></pre> 20749</div> 20750</div> 20751<div class="paragraph"> 20752<p>Both a <em>variables</em> and <em>transientVariables</em> property is accepted with following structure:</p> 20753</div> 20754<div class="listingblock"> 20755<div class="content"> 20756<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 207572 207583 207594 207605 207616 207627 207638 207649</div></td><td class="code"><span></span><span class="tok-p">{</span> 20765 <span class="tok-nt">"action"</span><span class="tok-p">:</span><span class="tok-s2">"signal"</span><span class="tok-p">,</span> 20766 <span class="tok-nt">"variables"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 20767 <span class="tok-p">{</span> 20768 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"myVar"</span><span class="tok-p">,</span> 20769 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"someValue"</span> 20770 <span class="tok-p">}</span> 20771 <span class="tok-p">]</span> 20772<span class="tok-p">}</span> 20773</td></tr></table></code></pre> 20774</div> 20775</div> 20776<div class="paragraph"> 20777<p><strong>Request body (signal event received for execution):</strong></p> 20778</div> 20779<div class="listingblock"> 20780<div class="content"> 20781<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 207822 207833 207844 207855</div></td><td class="code"><span></span><span class="tok-p">{</span> 20786 <span class="tok-nt">"action"</span><span class="tok-p">:</span><span class="tok-s2">"signalEventReceived"</span><span class="tok-p">,</span> 20787 <span class="tok-nt">"signalName"</span><span class="tok-p">:</span><span class="tok-s2">"mySignal"</span> 20788 <span class="tok-s2">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> <span class="tok-p">]</span> 20789<span class="tok-p">}</span> 20790</td></tr></table></code></pre> 20791</div> 20792</div> 20793<div class="paragraph"> 20794<p>Notifies the execution that a signal event has been received, requires a <code>signalName</code> parameter. Optional <code>variables</code> can be passed that are set on the execution before the action is executed.</p> 20795</div> 20796<div class="paragraph"> 20797<p><strong>Request body (signal event received for execution):</strong></p> 20798</div> 20799<div class="listingblock"> 20800<div class="content"> 20801<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 208022 208033 208044 208055</div></td><td class="code"><span></span><span class="tok-p">{</span> 20806 <span class="tok-nt">"action"</span><span class="tok-p">:</span><span class="tok-s2">"messageEventReceived"</span><span class="tok-p">,</span> 20807 <span class="tok-nt">"messageName"</span><span class="tok-p">:</span><span class="tok-s2">"myMessage"</span> 20808 <span class="tok-s2">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> <span class="tok-p">]</span> 20809<span class="tok-p">}</span> 20810</td></tr></table></code></pre> 20811</div> 20812</div> 20813<div class="paragraph"> 20814<p>Notifies the execution that a message event has been received, requires a <code>messageName</code> parameter. Optional <code>variables</code> can be passed that are set on the execution before the action is executed.</p> 20815</div> 20816<table class="tableblock frame-all grid-all spread"> 20817<caption class="title">Table 91. Execute an action on an execution - Response codes</caption> 20818<colgroup> 20819<col style="width: 50%;"> 20820<col style="width: 50%;"> 20821</colgroup> 20822<thead> 20823<tr> 20824<th class="tableblock halign-left valign-top">Response code</th> 20825<th class="tableblock halign-left valign-top">Description</th> 20826</tr> 20827</thead> 20828<tbody> 20829<tr> 20830<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20831<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found and the action is performed.</p></td> 20832</tr> 20833<tr> 20834<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 20835<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found, the action was performed and the action caused the execution to end.</p></td> 20836</tr> 20837<tr> 20838<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 20839<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an illegal action was requested, required parameters are missing in the request body or illegal variables are passed in. Status description contains additional information about the error.</p></td> 20840</tr> 20841<tr> 20842<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20843<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was not found.</p></td> 20844</tr> 20845</tbody> 20846</table> 20847<div class="paragraph"> 20848<p><strong>Success response body (in case execution is not ended due to action):</strong></p> 20849</div> 20850<div class="listingblock"> 20851<div class="content"> 20852<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 20853 2 20854 3 20855 4 20856 5 20857 6 20858 7 20859 8 20860 9 2086110 2086211</div></td><td class="code"><span></span><span class="tok-p">{</span> 20863 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 20864 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 20865 <span class="tok-nt">"parentId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20866 <span class="tok-nt">"parentUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20867 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 20868 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 20869 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">
20869false</span><span class="tok-p">,</span> 20870 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 20871 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 20872<span class="tok-p">}</span> 20873</td></tr></table></code></pre> 20874</div> 20875</div> 20876</div> 20877<div class="sect3"> 20878<h4 id="_get_active_activities_in_an_execution">13.6.3. Get active activities in an execution</h4> 20879<div class="listingblock"> 20880<div class="content"> 20881<pre>GET runtime/executions/{executionId}/activities</pre> 20882</div> 20883</div> 20884<div class="paragraph"> 20885<p>Returns all activities which are active in the execution and in all child-executions (and their children, recursively), if any.</p> 20886</div> 20887<table class="tableblock frame-all grid-all spread"> 20888<caption class="title">Table 92. Get active activities in an execution - URL parameters</caption> 20889<colgroup> 20890<col style="width: 25%;"> 20891<col style="width: 25%;"> 20892<col style="width: 25%;"> 20893<col style="width: 25%;"> 20894</colgroup> 20895<thead> 20896<tr> 20897<th class="tableblock halign-left valign-top">Parameter</th> 20898<th class="tableblock halign-left valign-top">Required</th> 20899<th class="tableblock halign-left valign-top">Value</th> 20900<th class="tableblock halign-left valign-top">Description</th> 20901</tr> 20902</thead> 20903<tbody> 20904<tr> 20905<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 20906<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 20907<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20908<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to get activities for.</p></td> 20909</tr> 20910</tbody> 20911</table> 20912<table class="tableblock frame-all grid-all spread"> 20913<caption class="title">Table 93. Get active activities in an execution - Response codes</caption> 20914<colgroup> 20915<col style="width: 50%;"> 20916<col style="width: 50%;"> 20917</colgroup> 20918<thead> 20919<tr> 20920<th class="tableblock halign-left valign-top">Response code</th> 20921<th class="tableblock halign-left valign-top">Description</th> 20922</tr> 20923</thead> 20924<tbody> 20925<tr> 20926<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 20927<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found and activities are returned.</p></td> 20928</tr> 20929<tr> 20930<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 20931<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was not found.</p></td> 20932</tr> 20933</tbody> 20934</table> 20935<div class="paragraph"> 20936<p><strong>Success response body:</strong></p> 20937</div> 20938<div class="listingblock"> 20939<div class="content"> 20940<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 209412 209423 209434</div></td><td class="code"><span></span><span class="tok-p">[</span> 20944 <span class="tok-s2">"userTaskForManager"</span><span class="tok-p">,</span> 20945 <span class="tok-s2">"receiveTask"</span> 20946<span class="tok-p">]</span> 20947</td></tr></table></code></pre> 20948</div> 20949</div> 20950</div> 20951<div class="sect3"> 20952<h4 id="restExecutionsGet">13.6.4. List of executions</h4> 20953<div class="listingblock"> 20954<div class="content"> 20955<pre>GET runtime/executions</pre> 20956</div> 20957</div> 20958<table class="tableblock frame-all grid-all spread"> 20959<caption class="title">Table 94. List of executions - URL query parameters</caption> 20960<colgroup> 20961<col style="width: 25%;"> 20962<col style="width: 25%;"> 20963<col style="width: 25%;"> 20964<col style="width: 25%;"> 20965</colgroup> 20966<thead> 20967<tr> 20968<th class="tableblock halign-left valign-top">Parameter</th> 20969<th class="tableblock halign-left valign-top">Required</th> 20970<th class="tableblock halign-left valign-top">Value</th> 20971<th class="tableblock halign-left valign-top">Description</th> 20972</tr> 20973</thead> 20974<tbody> 20975<tr> 20976<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 20977<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 20978<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20979<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions with the given id.</p></td> 20980</tr> 20981<tr> 20982<td class="tableblock halign-left valign-top"><p class="tableblock">activityId</p></td> 20983<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 20984<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20985<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions with the given activity id.</p></td> 20986</tr> 20987<tr> 20988<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKey</p></td> 20989<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 20990<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20991<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions with the given process definition key.</p></td> 20992</tr> 20993<tr> 20994<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 20995<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 20996<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 20997<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions with the given process definition id.</p></td> 20998</tr> 20999<tr> 21000<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 21001<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21002<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21003<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions which are part of the process instance with the given id.</p></td> 21004</tr> 21005<tr> 21006<td class="tableblock halign-left valign-top"><p class="tableblock">messageEventSubscriptionName</p></td> 21007<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21008<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21009<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions which are subscribed to a message with the given name.</p></td> 21010</tr> 21011<tr> 21012<td class="tableblock halign-left valign-top"><p class="tableblock">signalEventSubscriptionName</p></td> 21013<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21014<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21015<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions which are subscribed to a signal with the given name.</p></td> 21016</tr> 21017<tr> 21018<td class="tableblock halign-left valign-top"><p class="tableblock">parentId</p></td> 21019<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21020<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21021<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions which are a direct child of the given execution.</p></td> 21022</tr> 21023<tr> 21024<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 21025<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21026<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21027<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions with the given tenantId.</p></td> 21028</tr> 21029<tr> 21030<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 21031<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21032<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21033<td class="tableblock halign-left valign-top"><p class="tableblock">Only return executions with a tenantId like the given value.</p></td> 21034</tr> 21035<tr> 21036<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 21037<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21038<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 21039<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns executions without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 21040</tr> 21041<tr> 21042<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 21043<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21044<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21045<td class="tableblock halign-left valign-top"><p class="tableblock">Sort field, should be either one of <code>processInstanceId</code> (default), <code>processDefinitionId</code>, <code>processDefinitionKey</code> or <code>tenantId</code>.</p></td> 21046</tr> 21047</tbody> 21048</table> 21049<table class="tableblock frame-all grid-all spread"> 21050<caption class="title">Table 95. List of executions - Response codes</caption> 21051<colgroup> 21052<col style="width: 50%;"> 21053<col style="width: 50%;"> 21054</colgroup> 21055<thead> 21056<tr> 21057<th class="tableblock halign-left valign-top">Response code</th> 21058<th class="tableblock halign-left valign-top">Description</th> 21059</tr> 21060</thead> 21061<tbody> 21062<tr> 21063<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 21064<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the executions are returned</p></td> 21065</tr> 21066<tr> 21067<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 21068<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format . The status-message contains additional information.</p></td> 21069</tr> 21070</tbody> 21071</table> 21072<div class="paragraph"> 21073<p><strong>Success response body:</strong></p> 21074</div> 21075<div class="listingblock"> 21076<div class="content"> 21077<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 21078 2 21079 3 21080 4 21081 5 21082 6 21083 7 21084 8 21085 9 2108610 2108711 2108812 2108913 2109014 2109115 2109216 2109317 2109418 2109519 2109620 2109721 2109822 2109923 2110024 2110125 2110226 2110327 2110428 2110529 2110630 2110731</div></td><td class="code"><span></span><span class="tok-p">{</span> 21108 <span class="tok-nt">"data"</span><span class="tok-p">:[</span>
21109 <span class="tok-p">{</span> 21110 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21111 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 21112 <span class="tok-nt">"parentId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 21113 <span class="tok-nt">"parentUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 21114 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21115 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 21116 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 21117 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 21118 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 21119 <span class="tok-p">},</span> 21120 <span class="tok-p">{</span> 21121 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 21122 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/7"</span><span class="tok-p">,</span> 21123 <span class="tok-nt">"parentId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21124 <span class="tok-nt">"parentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 21125 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21126 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 21127 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 21128 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span><span class="tok-p">,</span> 21129 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 21130 <span class="tok-p">}</span> 21131 <span class="tok-p">],</span> 21132 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 21133 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 21134 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"processInstanceId"</span><span class="tok-p">,</span> 21135 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 21136 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">2</span> 21137<span class="tok-p">}</span> 21138</td></tr></table></code></pre> 21139</div> 21140</div> 21141</div> 21142<div class="sect3"> 21143<h4 id="_query_executions">13.6.5. Query executions</h4> 21144<div class="listingblock"> 21145<div class="content"> 21146<pre>POST query/executions</pre> 21147</div> 21148</div> 21149<div class="paragraph"> 21150<p><strong>Request body:</strong></p> 21151</div> 21152<div class="listingblock"> 21153<div class="content"> 21154<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 21155 2 21156 3 21157 4 21158 5 21159 6 21160 7 21161 8 21162 9 2116310 2116411 2116512 2116613 2116714 2116815 2116916 2117017 2117118 2117219 2117320 2117421</div></td><td class="code"><span></span><span class="tok-p">{</span> 21175 <span class="tok-nt">"processDefinitionKey"</span><span class="tok-p">:</span><span class="tok-s2">"oneTaskProcess"</span><span class="tok-p">,</span> 21176 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> 21177 <span class="tok-p">[</span> 21178 <span class="tok-p">{</span>
21179 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 21180 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mi">1234</span><span class="tok-p">,</span> 21181 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 21182 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"long"</span> 21183 <span class="tok-p">}</span> 21184 <span class="tok-p">],</span> 21185 <span class="tok-nt">"processInstanceVariables"</span><span class="tok-p">:</span> 21186 <span class="tok-p">[</span> 21187 <span class="tok-p">{</span> 21188 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"processVariable"</span><span class="tok-p">,</span> 21189 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"some string"</span><span class="tok-p">,</span> 21190 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 21191 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"string"</span> 21192 <span class="tok-p">}</span> 21193 <span class="tok-p">]</span> 21194<span class="tok-p">}</span> 21195</td></tr></table></code></pre> 21196</div> 21197</div> 21198<div class="paragraph"> 21199<p>The request body can contain all possible filters that can be used in the <a href="#restExecutionsGet">List executions</a> URL query. On top of these, it’s possible to provide an array of <code>variables</code> and <code>processInstanceVariables</code> 21200to include in the query, with their format <a href="#restQueryVariable">described here</a>.</p> 21201</div> 21202<div class="paragraph"> 21203<p>The general <a href="#restPagingAndSort">paging and sorting query-parameters</a> can be used for this URL.</p> 21204</div> 21205<table class="tableblock frame-all grid-all spread"> 21206<caption class="title">Table 96. Query executions - Response codes</caption> 21207<colgroup> 21208<col style="width: 50%;"> 21209<col style="width: 50%;"> 21210</colgroup> 21211<thead> 21212<tr> 21213<th class="tableblock halign-left valign-top">Response code</th> 21214<th class="tableblock halign-left valign-top">Description</th> 21215</tr> 21216</thead> 21217<tbody> 21218<tr> 21219<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 21220<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the executions are returned</p></td> 21221</tr> 21222<tr> 21223<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 21224<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format . The status-message contains additional information.</p></td> 21225</tr> 21226</tbody> 21227</table> 21228<div class="paragraph"> 21229<p><strong>Success response body:</strong></p> 21230</div> 21231<div class="listingblock"> 21232<div class="content"> 21233<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 21234 2 21235 3 21236 4 21237 5 21238 6 21239 7 21240 8 21241 9 2124210 2124311 2124412 2124513 2124614 2124715 2124816 2124917 2125018 2125119 2125220 2125321 2125422 2125523 2125624 2125725 2125826 2125927 2126028 2126129 2126230 2126331</div></td><td class="code"><span></span><span class="tok-p">{</span> 21264 <span class="tok-nt">"data"</span><span class="tok-p">:[</span> 21265 <span class="tok-p">{</span> 21266 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21267 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 21268 <span class="tok-nt">"parentId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 21269 <span class="tok-nt">"parentUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span>
21270 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21271 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 21272 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 21273 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 21274 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 21275 <span class="tok-p">},</span> 21276 <span class="tok-p">{</span> 21277 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 21278 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/7"</span><span class="tok-p">,</span> 21279 <span class="tok-nt">"parentId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21280 <span class="tok-nt">"parentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 21281 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 21282 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 21283 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span><span class="tok-kc">false</span><span class="tok-p">,</span> 21284 <span class="tok-nt">"activityId"</span><span class="tok-p">:</span><span class="tok-s2">"processTask"</span><span class="tok-p">,</span> 21285 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 21286 <span class="tok-p">}</span> 21287 <span class="tok-p">],</span> 21288 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 21289 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 21290 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"processInstanceId"</span><span class="tok-p">,</span> 21291 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 21292 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">2</span> 21293<span class="tok-p">}</span> 21294</td></tr></table></code></pre> 21295</div> 21296</div> 21297</div> 21298<div class="sect3"> 21299<h4 id="_list_of_variables_for_an_execution">13.6.6. List of variables for an execution</h4> 21300<div class="listingblock"> 21301<div class="content"> 21302<pre>GET runtime/executions/{executionId}/variables?scope={scope}</pre> 21303</div> 21304</div> 21305<table class="tableblock frame-all grid-all spread"> 21306<caption class="title">Table 97. List of variables for an execution - URL parameters</caption> 21307<colgroup> 21308<col style="width: 25%;"> 21309<col style="width: 25%;"> 21310<col style="width: 25%;"> 21311<col style="width: 25%;"> 21312</colgroup> 21313<thead> 21314<tr> 21315<th class="tableblock halign-left valign-top">Parameter</th> 21316<th class="tableblock halign-left valign-top">Required</th> 21317<th class="tableblock halign-left valign-top">Value</th> 21318<th class="tableblock halign-left valign-top">Description</th> 21319</tr> 21320</thead> 21321<tbody> 21322<tr> 21323<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 21324<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21325<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21326<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to the variables for.</p></td> 21327</tr> 21328<tr> 21329<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 21330<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21331<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21332<td class="tableblock halign-left valign-top"><p class="tableblock">Either <code>local</code> or <code>global</code>. If omitted, both local and global scoped variables are returned.</p></td> 21333</tr> 21334</tbody> 21335</table> 21336<table class="tableblock frame-all grid-all spread"> 21337<caption class="title">Table 98. List of variables for an execution - Response codes</caption> 21338<colgroup> 21339<col style="width: 50%;"> 21340<col style="width: 50%;"> 21341</colgroup> 21342<thead> 21343<tr> 21344<th class="tableblock halign-left valign-top">Response code</th> 21345<th class="tableblock halign-left valign-top">Description</th> 21346</tr> 21347</thead> 21348<tbody> 21349<tr> 21350<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 21351<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found and variables are returned.</p></td> 21352</tr> 21353<tr> 21354<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 21355<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested execution was not found.</p></td> 21356</tr> 21357</tbody> 21358</table> 21359<div class="paragraph"> 21360<p><strong>Success response body:</strong></p> 21361</div> 21362<div class="listingblock"> 21363<div class="content"> 21364<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 21365 2 21366 3 21367 4 21368 5 21369 6 21370 7 21371 8 21372 9 2137310 2137411 2137512 2137613 2137714 2137815 2137916 2138017</div></td><td class="code"><span></span><span class="tok-p">[</span> 21381 <span class="tok-p">{</span>
21382 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 21383 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 21384 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 21385 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"global"</span> 21386 <span class="tok-p">},</span> 21387 <span class="tok-p">{</span> 21388 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"byteArrayProcVar"</span><span class="tok-p">,</span> 21389 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"binary"</span><span class="tok-p">,</span> 21390 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 21391 <span class="tok-nt">"valueUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5/variables/byteArrayProcVar/data"</span><span class="tok-p">,</span> 21392 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 21393 <span class="tok-p">}</span> 21394 21395 21396<span class="tok-p">]</span> 21397</td></tr></table></code></pre> 21398</div> 21399</div> 21400<div class="paragraph"> 21401<p>In case the variable is a binary variable or serializable, the <code>valueUrl</code> points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response.</p> 21402</div> 21403</div> 21404<div class="sect3"> 21405<h4 id="_get_a_variable_for_an_execution">13.6.7. Get a variable for an execution</h4> 21406<div class="listingblock"> 21407<div class="content"> 21408<pre>GET runtime/executions/{executionId}/variables/{variableName}?scope={scope}</pre> 21409</div> 21410</div> 21411<table class="tableblock frame-all grid-all spread"> 21412<caption class="title">Table 99. Get a variable for an execution - URL parameters</caption> 21413<colgroup> 21414<col style="width: 25%;"> 21415<col style="width: 25%;"> 21416<col style="width: 25%;"> 21417<col style="width: 25%;"> 21418</colgroup> 21419<thead> 21420<tr> 21421<th class="tableblock halign-left valign-top">Parameter</th> 21422<th class="tableblock halign-left valign-top">Required</th> 21423<th class="tableblock halign-left valign-top">Value</th> 21424<th class="tableblock halign-left valign-top">Description</th> 21425</tr> 21426</thead> 21427<tbody> 21428<tr> 21429<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 21430<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21431<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21432<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to the variables for.</p></td> 21433</tr> 21434<tr> 21435<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 21436<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21437<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21438<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the variable to get.</p></td> 21439</tr> 21440<tr> 21441<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 21442<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 21443<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21444<td class="tableblock halign-left valign-top"><p class="tableblock">Either <code>local</code> or <code>global</code>. If omitted, local variable is returned (if exists). If not, a global variable is returned (if exists).</p></td> 21445</tr> 21446</tbody> 21447</table> 21448<table class="tableblock frame-all grid-all spread"> 21449<caption class="title">Table 100. Get a variable for an execution - Response codes</caption> 21450<colgroup> 21451<col style="width: 50%;"> 21452<col style="width: 50%;"> 21453</colgroup> 21454<thead> 21455<tr> 21456<th class="tableblock halign-left valign-top">Response code</th> 21457<th class="tableblock halign-left valign-top">Description</th> 21458</tr> 21459</thead> 21460<tbody> 21461<tr> 21462<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 21463<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates both the execution and variable were found and variable is returned.</p></td> 21464</tr> 21465<tr> 21466<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 21467<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.</p></td> 21468</tr> 21469<tr> 21470<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 21471<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested execution was not found or the execution does not have a variable with the given name in the requested scope (in case scope-query parameter was omitted, variable doesn’t exist in local and global scope). Status description contains additional information about the error.</p></td> 21472</tr> 21473</tbody> 21474</table> 21475<div class="paragraph"> 21476<p><strong>Success response body:</strong></p> 21477</div> 21478<div class="listingblock"> 21479<div class="content"> 21480<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 214812 214823 214834 214845 214856</div></td><td class="code"><span></span> <span class="tok-p">{</span>
21486 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 21487 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 21488 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 21489 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 21490 <span class="tok-p">}</span> 21491</td></tr></table></code></pre> 21492</div> 21493</div> 21494<div class="paragraph"> 21495<p>In case the variable is a binary variable or serializable, the <code>valueUrl</code> points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response.</p> 21496</div> 21497</div> 21498<div class="sect3"> 21499<h4 id="_create_or_update_variables_on_an_execution">13.6.8. Create (or update) variables on an execution</h4> 21500<div class="listingblock"> 21501<div class="content"> 21502<pre>POST runtime/executions/{executionId}/variables</pre> 21503</div> 21504</div> 21505<div class="listingblock"> 21506<div class="content"> 21507<pre>PUT runtime/executions/{executionId}/variables</pre> 21508</div> 21509</div> 21510<div class="paragraph"> 21511<p>When using <code>POST</code>, all variables that are passed are created. In case one of the variables already exists on the execution in the requested scope, the request results in an error (409 - CONFLICT). When <code>PUT</code> is used, nonexistent variables are created on the execution and existing ones are overridden without any error.</p> 21512</div> 21513<table class="tableblock frame-all grid-all spread"> 21514<caption class="title">Table 101. Create (or update) variables on an execution - URL parameters</caption> 21515<colgroup> 21516<col style="width: 25%;"> 21517<col style="width: 25%;"> 21518<col style="width: 25%;"> 21519<col style="width: 25%;"> 21520</colgroup> 21521<thead> 21522<tr> 21523<th class="tableblock halign-left valign-top">Parameter</th> 21524<th class="tableblock halign-left valign-top">Required</th> 21525<th class="tableblock halign-left valign-top">Value</th> 21526<th class="tableblock halign-left valign-top">Description</th> 21527</tr> 21528</thead> 21529<tbody> 21530<tr> 21531<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 21532<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21533<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21534<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to the variables for.</p></td> 21535</tr> 21536</tbody> 21537</table> 21538<div class="paragraph"> 21539<p><strong>Request body:</strong></p> 21540</div> 21541<div class="listingblock"> 21542<div class="content"> 21543<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 21544 2 21545 3 21546 4 21547 5 21548 6 21549 7 21550 8 21551 9 2155210 2155311</div></td><td class="code"><span></span><span class="tok-p">[</span> 21554 <span class="tok-p">{</span> 21555 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span> 21556 <span class="tok-s2">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span> 21557 <span class="tok-s2">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 21558 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 21559 <span class="tok-p">}</span> 21560 21561 21562 21563<span class="tok-p">]</span> 21564</td></tr></table></code></pre> 21565</div> 21566</div> 21567<div class="paragraph"> 21568<p>*Note that you can only provide variables that have the same scope. If the request-body array contains variables from mixed scopes, the request results in an error (400 - BAD REQUEST).*Any number of variables can be passed into the request body array. More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>. Note that scope is ignored, only <code>local</code> variables can be set in a process instance.</p> 21569</div> 21570<table class="tableblock frame-all grid-all spread"> 21571<caption class="title">Table 102. Create (or update) variables on an execution - Response codes</caption> 21572<colgroup> 21573<col style="width: 50%;"> 21574<col style="width: 50%;"> 21575</colgroup> 21576<thead> 21577<tr> 21578<th class="tableblock halign-left valign-top">Response code</th> 21579<th class="tableblock halign-left valign-top">Description</th> 21580</tr> 21581</thead> 21582<tbody> 21583<tr> 21584<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 21585<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found and variable is created.</p></td> 21586</tr> 21587<tr> 21588<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 21589<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.</p></td> 21590</tr> 21591<tr> 21592<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 21593<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested execution was not found.</p></td> 21594</tr> 21595<tr> 21596<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 21597<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution was found but already contains a variable with the given name (only thrown when POST method is used). Use the update-method instead.</p></td> 21598</tr> 21599</tbody> 21600</table> 21601<div class="paragraph"> 21602<p><strong>Success response body:</strong></p> 21603</div> 21604<div class="listingblock"> 21605<div class="content"> 21606<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 21607 2 21608 3 21609 4 21610 5 21611 6 21612 7 21613 8 21614 9 2161510 2161611</div></td><td class="code"><span></span><span class="tok-p">[</span> 21617 <span class="tok-p">{</span>
21618 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 21619 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 21620 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 21621 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"local"</span> 21622 <span class="tok-p">}</span> 21623 21624 21625 21626<span class="tok-p">]</span> 21627</td></tr></table></code></pre> 21628</div> 21629</div> 21630</div> 21631<div class="sect3"> 21632<h4 id="_update_a_variable_on_an_execution">13.6.9. Update a variable on an execution</h4> 21633<div class="listingblock"> 21634<div class="content"> 21635<pre>PUT runtime/executions/{executionId}/variables/{variableName}</pre> 21636</div> 21637</div> 21638<table class="tableblock frame-all grid-all spread"> 21639<caption class="title">Table 103. Update a variable on an execution - URL parameters</caption> 21640<colgroup> 21641<col style="width: 25%;"> 21642<col style="width: 25%;"> 21643<col style="width: 25%;"> 21644<col style="width: 25%;"> 21645</colgroup> 21646<thead> 21647<tr> 21648<th class="tableblock halign-left valign-top">Parameter</th> 21649<th class="tableblock halign-left valign-top">Required</th> 21650<th class="tableblock halign-left valign-top">Value</th> 21651<th class="tableblock halign-left valign-top">Description</th> 21652</tr> 21653</thead> 21654<tbody> 21655<tr> 21656<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 21657<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21658<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21659<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to update the variables for.</p></td> 21660</tr> 21661<tr> 21662<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 21663<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21664<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21665<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the variable to update.</p></td> 21666</tr> 21667</tbody> 21668</table> 21669<div class="paragraph"> 21670<p><strong>Request body:</strong></p> 21671</div> 21672<div class="listingblock"> 21673<div class="content"> 21674<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 216752 216763 216774 216785 216796</div></td><td class="code"><span></span> <span class="tok-p">{</span> 21680 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span> 21681 <span class="tok-s2">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span> 21682 <span class="tok-s2">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 21683 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"global"</span> 21684 <span class="tok-p">}</span> 21685</td></tr></table></code></pre> 21686</div> 21687</div> 21688<div class="paragraph"> 21689<p>More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>.</p> 21690</div> 21691<table class="tableblock frame-all grid-all spread"> 21692<caption class="title">Table 104. Update a variable on an execution - Response codes</caption> 21693<colgroup> 21694<col style="width: 50%;"> 21695<col style="width: 50%;"> 21696</colgroup> 21697<thead> 21698<tr> 21699<th class="tableblock halign-left valign-top">Response code</th> 21700<th class="tableblock halign-left valign-top">Description</th> 21701</tr> 21702</thead> 21703<tbody> 21704<tr> 21705<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 21706<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates both the process instance and variable were found and variable is updated.</p></td> 21707</tr> 21708<tr> 21709<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 21710<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.</p></td> 21711</tr> 21712</tbody> 21713</table> 21714<div class="paragraph"> 21715<p><strong>Success response body:</strong></p> 21716</div> 21717<div class="listingblock"> 21718<div class="content"> 21719<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 217202 217213 217224 217235 217246</div></td><td class="code"><span></span> <span class="tok-p">{</span>
21725 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"intProcVar"</span><span class="tok-p">,</span> 21726 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span><span class="tok-p">,</span> 21727 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 21728 <span class="tok-nt">"scope"</span><span class="tok-p">:</span><span class="tok-s2">"global"</span> 21729 <span class="tok-p">}</span> 21730</td></tr></table></code></pre> 21731</div> 21732</div> 21733<div class="paragraph"> 21734<p>In case the variable is a binary variable or serializable, the <code>valueUrl</code> points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response.</p> 21735</div> 21736</div> 21737<div class="sect3"> 21738<h4 id="_create_a_new_binary_variable_on_an_execution">13.6.10. Create a new binary variable on an execution</h4> 21739<div class="listingblock"> 21740<div class="content"> 21741<pre>POST runtime/executions/{executionId}/variables</pre> 21742</div> 21743</div> 21744<table class="tableblock frame-all grid-all spread"> 21745<caption class="title">Table 105. Create a new binary variable on an execution - URL parameters</caption> 21746<colgroup> 21747<col style="width: 25%;"> 21748<col style="width: 25%;"> 21749<col style="width: 25%;"> 21750<col style="width: 25%;"> 21751</colgroup> 21752<thead> 21753<tr> 21754<th class="tableblock halign-left valign-top">Parameter</th> 21755<th class="tableblock halign-left valign-top">Required</th> 21756<th class="tableblock halign-left valign-top">Value</th> 21757<th class="tableblock halign-left valign-top">Description</th> 21758</tr> 21759</thead> 21760<tbody> 21761<tr> 21762<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 21763<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21764<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21765<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to create the new variable for.</p></td> 21766</tr> 21767</tbody> 21768</table> 21769<div class="paragraph"> 21770<p><strong>Request body:</strong></p> 21771</div> 21772<div class="paragraph"> 21773<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 21774</div> 21775<div class="ulist"> 21776<ul> 21777<li> 21778<p><code>name</code>: Required name of the variable.</p> 21779</li> 21780<li> 21781<p><code>type</code>: Type of variable that is created. If omitted, <code>binary</code> is assumed and the binary data in the request will be stored as an array of bytes.</p> 21782</li> 21783<li> 21784<p><code>scope</code>: Scope of variable that is created. If omitted, <code>local</code> is assumed.</p> 21785</li> 21786</ul> 21787</div> 21788<div class="paragraph"> 21789<p><strong>Success response body:</strong></p> 21790</div> 21791<div class="listingblock"> 21792<div class="content"> 21793<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 217942 217953 217964 217975 217986 217997</div></td><td class="code"><span></span><span class="tok-p">{</span> 21800 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"binaryVariable"</span><span class="tok-p">,</span> 21801 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 21802 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"binary"</span><span class="tok-p">,</span> 21803 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 21804 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://.../runtime/executions/123/variables/binaryVariable/data"</span> 21805<span class="tok-p">}</span> 21806</td></tr></table></code></pre> 21807</div> 21808</div> 21809<table class="tableblock frame-all grid-all spread"> 21810<caption class="title">Table 106. Create a new binary variable on an execution - Response codes</caption> 21811<colgroup> 21812<col style="width: 50%;"> 21813<col style="width: 50%;"> 21814</colgroup> 21815<thead> 21816<tr> 21817<th class="tableblock halign-left valign-top">Response code</th> 21818<th class="tableblock halign-left valign-top">Description</th> 21819</tr> 21820</thead> 21821<tbody> 21822<tr> 21823<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 21824<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable was created and the result is returned.</p></td> 21825</tr> 21826<tr> 21827<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 21828<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of the variable to create was missing. Status message provides additional information.</p></td> 21829</tr> 21830<tr> 21831<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 21832<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested execution was not found.</p></td> 21833</tr> 21834<tr> 21835<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 21836<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the execution already has a variable with the given name. Use the PUT method to update the task variable instead.</p></td> 21837</tr> 21838<tr> 21839<td class="tableblock halign-left valign-top"><p class="tableblock">415</p></td> 21840<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.</p></td> 21841</tr> 21842</tbody> 21843</table> 21844</div> 21845<div class="sect3"> 21846<h4 id="_update_an_existing_binary_variable_on_a_process_instance_2">13.6.11. Update an existing binary variable on a process-instance</h4> 21847<div class="listingblock"> 21848<div class="content"> 21849<pre>PUT runtime/executions/{executionId}/variables/{variableName}</pre> 21850</div> 21851</div> 21852<table class="tableblock frame-all grid-all spread"> 21853<caption class="title">Table 107. Update an existing binary variable on a process-instance - URL parameters</caption> 21854<colgroup> 21855<col style="width: 25%;"> 21856<col style="width: 25%;"> 21857<col style="width: 25%;"> 21858<col style="width: 25%;"> 21859</colgroup> 21860<thead> 21861<tr> 21862<th class="tableblock halign-left valign-top">Parameter</th> 21863<th class="tableblock halign-left valign-top">Required</th> 21864<th class="tableblock halign-left valign-top">Value</th> 21865<th class="tableblock halign-left valign-top">Description</th> 21866</tr> 21867</thead> 21868<tbody> 21869<tr> 21870<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 21871<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21872<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21873<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the execution to create the new variable for.</p></td> 21874</tr> 21875<tr> 21876<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 21877<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21878<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21879<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable to update.</p></td> 21880</tr> 21881</tbody> 21882</table> 21883<div class="paragraph"> 21884<p><strong>Request body:</strong> 21885The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 21886</div> 21887<div class="ulist"> 21888<ul> 21889<li> 21890<p><code>name</code>: Required name of the variable.</p> 21891</li> 21892<li> 21893<p><code>type</code>: Type of variable that is created. If omitted, <code>binary</code> is assumed and the binary data in the request will be stored as an array of bytes.</p> 21894</li> 21895<li> 21896<p><code>scope</code>: Scope of variable that is created. If omitted, <code>local</code> is assumed.</p> 21897</li> 21898</ul> 21899</div> 21900<div class="paragraph"> 21901<p><strong>Success response body:</strong></p> 21902</div> 21903<div class="listingblock"> 21904<div class="content"> 21905<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 219062 219073 219084 219095 219106 219117</div></td><td class="code"><span></span><span class="tok-p">{</span> 21912 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"binaryVariable"</span><span class="tok-p">,</span> 21913 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 21914 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"binary"</span><span class="tok-p">,</span> 21915 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 21916 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://.../runtime/executions/123/variables/binaryVariable/data"</span> 21917<span class="tok-p">}</span> 21918</td></tr></table></code></pre> 21919</div> 21920</div> 21921<table class="tableblock frame-all grid-all spread"> 21922<caption class="title">Table 108. Update an existing binary variable on a process-instance - Response codes</caption> 21923<colgroup> 21924<col style="width: 50%;"> 21925<col style="width: 50%;"> 21926</colgroup> 21927<thead> 21928<tr> 21929<th class="tableblock halign-left valign-top">Response code</th> 21930<th class="tableblock halign-left valign-top">Description</th> 21931</tr> 21932</thead> 21933<tbody> 21934<tr> 21935<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 21936<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable was updated and the result is returned.</p></td> 21937</tr> 21938<tr> 21939<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 21940<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of the variable to update was missing. Status message provides additional information.</p></td> 21941</tr> 21942<tr> 21943<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 21944<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested execution was not found or the execution does not have a variable with the given name.</p></td> 21945</tr> 21946<tr> 21947<td class="tableblock halign-left valign-top"><p class="tableblock">415</p></td> 21948<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.</p></td> 21949</tr> 21950</tbody> 21951</table> 21952</div> 21953</div> 21954<div class="sect2"> 21955<h3 id="_tasks">13.7. Tasks</h3> 21956<div class="sect3"> 21957<h4 id="_get_a_task">13.7.1. Get a task</h4> 21958<div class="listingblock"> 21959<div class="content"> 21960<pre>GET runtime/tasks/{taskId}</pre> 21961</div> 21962</div> 21963<table class="tableblock frame-all grid-all spread"> 21964<caption class="title">Table 109. Get a task - URL parameters</caption> 21965<colgroup> 21966<col style="width: 25%;"> 21967<col style="width: 25%;"> 21968<col style="width: 25%;"> 21969<col style="width: 25%;"> 21970</colgroup> 21971<thead> 21972<tr> 21973<th class="tableblock halign-left valign-top">Parameter</th> 21974<th class="tableblock halign-left valign-top">Required</th> 21975<th class="tableblock halign-left valign-top">Value</th> 21976<th class="tableblock halign-left valign-top">Description</th> 21977</tr> 21978</thead> 21979<tbody> 21980<tr> 21981<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 21982<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 21983<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 21984<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get.</p></td> 21985</tr> 21986</tbody> 21987</table> 21988<table class="tableblock frame-all grid-all spread"> 21989<caption class="title">Table 110. Get a task - Response codes</caption> 21990<colgroup> 21991<col style="width: 50%;"> 21992<col style="width: 50%;"> 21993</colgroup> 21994<thead> 21995<tr> 21996<th class="tableblock halign-left valign-top">Response code</th> 21997<th class="tableblock halign-left valign-top">Description</th> 21998</tr> 21999</thead> 22000<tbody> 22001<tr> 22002<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 22003<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and returned.</p></td> 22004</tr> 22005<tr> 22006<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 22007<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 22008</tr> 22009</tbody> 22010</table> 22011<div class="paragraph"> 22012<p><strong>Success response body:</strong></p> 22013</div> 22014<div class="listingblock"> 22015<div class="content"> 22016<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 22017 2 22018 3 22019 4 22020 5 22021 6 22022 7 22023 8 22024 9 2202510 2202611 2202712 2202813 2202914 2203015 2203116 2203217 2203318 2203419</div></td><td class="code"><span></span><span class="tok-p">{</span> 22035 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 22036 <span class="tok-nt">"createTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 22037 <span class="tok-nt">"delegationState"</span> <span class="tok-p">:</span> <span class="tok-s2">"pending"</span><span class="tok-p">,</span> 22038 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"Task description"</span><span class="tok-p">,</span> 22039 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 22040 <span class="tok-nt">"execution"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 22041 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"8"</span><span class="tok-p">,</span> 22042 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task"</span><span class="tok-p">,</span> 22043 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"owner"</span><span class="tok-p">,</span> 22044 <span class="tok-nt">"parentTask"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/9"</span><span class="tok-p">,</span> 22045 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">50</span><span class="tok-p">,</span> 22046 <span class="tok-nt">"processDefinition"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 22047 <span class="tok-nt">"processInstance"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 22048 <span class="tok-nt">"suspended"</span> <span class="tok-p">:</span> <span class="tok-kc">
22048false</span><span class="tok-p">,</span> 22049 <span class="tok-nt">"taskDefinitionKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"theTask"</span><span class="tok-p">,</span> 22050 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/8"</span><span class="tok-p">,</span> 22051 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 22052<span class="tok-p">}</span> 22053</td></tr></table></code></pre> 22054</div> 22055</div> 22056<div class="ulist"> 22057<ul> 22058<li> 22059<p><code>delegationState</code>: Delegation-state of the task, can be <code>null</code>, <code>"pending"</code> or <code>"resolved".</code></p> 22060</li> 22061</ul> 22062</div> 22063</div> 22064<div class="sect3"> 22065<h4 id="restTasksGet">13.7.2. List of tasks</h4> 22066<div class="listingblock"> 22067<div class="content"> 22068<pre>GET runtime/tasks</pre> 22069</div> 22070</div> 22071<table class="tableblock frame-all grid-all spread"> 22072<caption class="title">Table 111. List of tasks - URL query parameters</caption> 22073<colgroup> 22074<col style="width: 25%;"> 22075<col style="width: 25%;"> 22076<col style="width: 25%;"> 22077<col style="width: 25%;"> 22078</colgroup> 22079<thead> 22080<tr> 22081<th class="tableblock halign-left valign-top">Parameter</th> 22082<th class="tableblock halign-left valign-top">Required</th> 22083<th class="tableblock halign-left valign-top">Value</th> 22084<th class="tableblock halign-left valign-top">Description</th> 22085</tr> 22086</thead> 22087<tbody> 22088<tr> 22089<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 22090<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22091<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22092<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with the given name.</p></td> 22093</tr> 22094<tr> 22095<td class="tableblock halign-left valign-top"><p class="tableblock">nameLike</p></td> 22096<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22097<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22098<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with a name like the given name.</p></td> 22099</tr> 22100<tr> 22101<td class="tableblock halign-left valign-top"><p class="tableblock">description</p></td> 22102<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22103<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22104<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with the given description.</p></td> 22105</tr> 22106<tr> 22107<td class="tableblock halign-left valign-top"><p class="tableblock">priority</p></td> 22108<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22109<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 22110<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with the given priority.</p></td> 22111</tr> 22112<tr> 22113<td class="tableblock halign-left valign-top"><p class="tableblock">minimumPriority</p></td> 22114<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22115<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 22116<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with a priority greater than the given value.</p></td> 22117</tr> 22118<tr> 22119<td class="tableblock halign-left valign-top"><p class="tableblock">maximumPriority</p></td> 22120<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22121<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 22122<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with a priority lower than the given value.</p></td> 22123</tr> 22124<tr> 22125<td class="tableblock halign-left valign-top"><p class="tableblock">assignee</p></td> 22126<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22127<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22128<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks assigned to the given user.</p></td> 22129</tr> 22130<tr> 22131<td class="tableblock halign-left valign-top"><p class="tableblock">assigneeLike</p></td> 22132<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22133<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22134<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks assigned with an assignee like the given value.</p></td> 22135</tr> 22136<tr> 22137<td class="tableblock halign-left valign-top"><p class="tableblock">owner</p></td> 22138<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22139<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22140<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks owned by the given user.</p></td> 22141</tr> 22142<tr> 22143<td class="tableblock halign-left valign-top"><p class="tableblock">ownerLike</p></td> 22144<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22145<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22146<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks assigned with an owner like the given value.</p></td> 22147</tr> 22148<tr> 22149<td class="tableblock halign-left valign-top"><p class="tableblock">unassigned</p></td> 22150<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22151<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22152<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks that are not assigned to anyone. If <code>false</code> is passed, the value is ignored.</p></td> 22153</tr> 22154<tr> 22155<td class="tableblock halign-left valign-top"><p class="tableblock">delegationState</p></td> 22156<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22157<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22158<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks that have the given delegation state. Possible values are <code>pending</code> and <code>resolved</code>.</p></td> 22159</tr> 22160<tr> 22161<td class="tableblock halign-left valign-top"><p class="tableblock">candidateUser</p></td> 22162<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22163<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22164<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks that can be claimed by the given user. This includes both tasks where the user is an explicit candidate for and task that are claimable by a group that the user is a member of.</p></td> 22165</tr> 22166<tr> 22167<td class="tableblock halign-left valign-top"><p class="tableblock">candidateGroup</p></td> 22168<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22169<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22170<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks that can be claimed by a user in the given group.</p></td> 22171</tr> 22172<tr> 22173<td class="tableblock halign-left valign-top"><p class="tableblock">candidateGroups</p></td> 22174<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22175<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22176<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks that can be claimed by a user in the given groups. Values split by comma.</p></td> 22177</tr> 22178<tr> 22179<td class="tableblock halign-left valign-top"><p class="tableblock">involvedUser</p></td> 22180<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22181<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22182<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks in which the given user is involved.</p></td> 22183</tr> 22184<tr> 22185<td class="tableblock halign-left valign-top"><p class="tableblock">taskDefinitionKey</p></td> 22186<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22187<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22188<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with the given task definition id.</p></td> 22189</tr> 22190<tr> 22191<td class="tableblock halign-left valign-top"><p class="tableblock">taskDefinitionKeyLike</p></td> 22192<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22193<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22194<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with a given task definition id like the given value.</p></td> 22195</tr> 22196<tr> 22197<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 22198<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22199<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22200<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of the process instance with the given id.</p></td> 22201</tr> 22202<tr> 22203<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceBusinessKey</p></td> 22204<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22205<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22206<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of the process instance with the given business key.</p></td> 22207</tr> 22208<tr> 22209<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceBusinessKeyLike</p></td> 22210<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22211<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22212<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of the process instance which has a business key like the given value.</p></td> 22213</tr> 22214<tr> 22215<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 22216<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22217<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22218<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of a process instance which has a process definition with the given id.</p></td> 22219</tr> 22220<tr> 22221<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKey</p></td> 22222<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22223<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22224<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of a process instance which has a process definition with the given key.</p></td> 22225</tr> 22226<tr> 22227<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKeyLike</p></td> 22228<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22229<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22230<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of a process instance which has a process definition with a key like the given value.</p></td> 22231</tr> 22232<tr> 22233<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionName</p></td> 22234<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22235<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22236<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of a process instance which has a process definition with the given name.</p></td> 22237</tr> 22238<tr> 22239<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionNameLike</p></td> 22240<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22241<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22242<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of a process instance which has a process definition with a name like the given value.</p></td> 22243</tr> 22244<tr> 22245<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 22246<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22247<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22248<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are part of the execution with the given id.</p></td> 22249</tr> 22250<tr> 22251<td class="tableblock halign-left valign-top"><p class="tableblock">createdOn</p></td> 22252<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22253<td class="tableblock halign-left valign-top"><p class="tableblock">ISO Date</p></td> 22254<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are created on the given date.</p></td> 22255</tr> 22256<tr> 22257<td class="tableblock halign-left valign-top"><p class="tableblock">createdBefore</p></td> 22258<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22259<td class="tableblock halign-left valign-top"><p class="tableblock">ISO Date</p></td> 22260<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are created before the given date.</p></td> 22261</tr> 22262<tr> 22263<td class="tableblock halign-left valign-top"><p class="tableblock">createdAfter</p></td> 22264<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22265<td class="tableblock halign-left valign-top"><p class="tableblock">ISO Date</p></td> 22266<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are created after the given date.</p></td> 22267</tr> 22268<tr> 22269<td class="tableblock halign-left valign-top"><p class="tableblock">dueOn</p></td> 22270<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22271<td class="tableblock halign-left valign-top"><p class="tableblock">ISO Date</p></td> 22272<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are due on the given date.</p></td> 22273</tr> 22274<tr> 22275<td class="tableblock halign-left valign-top"><p class="tableblock">dueBefore</p></td> 22276<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22277<td class="tableblock halign-left valign-top"><p class="tableblock">ISO Date</p></td> 22278<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are due before the given date.</p></td> 22279</tr> 22280<tr> 22281<td class="tableblock halign-left valign-top"><p class="tableblock">dueAfter</p></td> 22282<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22283<td class="tableblock halign-left valign-top"><p class="tableblock">ISO Date</p></td> 22284<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which are due after the given date.</p></td> 22285</tr> 22286<tr> 22287<td class="tableblock halign-left valign-top"><p class="tableblock">withoutDueDate</p></td> 22288<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22289<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td> 22290<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which don’t have a due date. The property is ignored if the value is <code>false</code>.</p></td> 22291</tr> 22292<tr> 22293<td class="tableblock halign-left valign-top"><p class="tableblock">withoutDueDate</p></td> 22294<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22295<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td> 22296<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which don’t have a due date. The property is ignored if the value is <code>false</code>.</p></td> 22297</tr> 22298<tr> 22299<td class="tableblock halign-left valign-top"><p class="tableblock">withoutDueDate</p></td> 22300<td class="tablebl
22300ock halign-left valign-top"><p class="tableblock">No</p></td> 22301<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td> 22302<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks which don’t have a due date. The property is ignored if the value is <code>false</code>.</p></td> 22303</tr> 22304<tr> 22305<td class="tableblock halign-left valign-top"><p class="tableblock">excludeSubTasks</p></td> 22306<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22307<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22308<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks that are not a subtask of another task.</p></td> 22309</tr> 22310<tr> 22311<td class="tableblock halign-left valign-top"><p class="tableblock">active</p></td> 22312<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22313<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22314<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return tasks that are not suspended (either part of a process that is not suspended or not part of a process at all). If false, only tasks that are part of suspended process instances are returned.</p></td> 22315</tr> 22316<tr> 22317<td class="tableblock halign-left valign-top"><p class="tableblock">includeTaskLocalVariables</p></td> 22318<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22319<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22320<td class="tableblock halign-left valign-top"><p class="tableblock">Indication to include task local variables in the result.</p></td> 22321</tr> 22322<tr> 22323<td class="tableblock halign-left valign-top"><p class="tableblock">includeProcessVariables</p></td> 22324<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22325<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22326<td class="tableblock halign-left valign-top"><p class="tableblock">Indication to include process variables in the result.</p></td> 22327</tr> 22328<tr> 22329<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 22330<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22331<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22332<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with the given tenantId.</p></td> 22333</tr> 22334<tr> 22335<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 22336<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22337<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22338<td class="tableblock halign-left valign-top"><p class="tableblock">Only return tasks with a tenantId like the given value.</p></td> 22339</tr> 22340<tr> 22341<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 22342<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22343<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22344<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns tasks without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 22345</tr> 22346<tr> 22347<td class="tableblock halign-left valign-top"><p class="tableblock">candidateOrAssigned</p></td> 22348<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22349<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22350<td class="tableblock halign-left valign-top"><p class="tableblock">Select tasks that has been claimed or assigned to user or waiting to claim by user (candidate user or groups).</p></td> 22351</tr> 22352<tr> 22353<td class="tableblock halign-left valign-top"><p class="tableblock">category</p></td> 22354<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 22355<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 22356<td class="tableblock halign-left valign-top"><p class="tableblock">Select tasks with the given category. Note that this is the task category, not the category of the process definition (namespace within the BPMN Xml).</p></td> 22357</tr> 22358</tbody> 22359</table> 22360<table class="tableblock frame-all grid-all spread"> 22361<caption class="title">Table 112. List of tasks - Response codes</caption> 22362<colgroup> 22363<col style="width: 50%;"> 22364<col style="width: 50%;"> 22365</colgroup> 22366<thead> 22367<tr> 22368<th class="tableblock halign-left valign-top">Response code</th> 22369<th class="tableblock halign-left valign-top">Description</th> 22370</tr> 22371</thead> 22372<tbody> 22373<tr> 22374<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 22375<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the tasks are returned</p></td> 22376</tr> 22377<tr> 22378<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 22379<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format or that <em>delegationState</em>
22379 has an invalid value (other than <em>pending</em> and <em>resolved</em>). The status-message contains additional information.</p></td> 22380</tr> 22381</tbody> 22382</table> 22383<div class="paragraph"> 22384<p><strong>Success response body:</strong></p> 22385</div> 22386<div class="listingblock"> 22387<div class="content"> 22388<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 22389 2 22390 3 22391 4 22392 5 22393 6 22394 7 22395 8 22396 9 2239710 2239811 2239912 2240013 2240114 2240215 2240316 2240417 2240518 2240619 2240720 2240821 2240922 2241023 2241124 2241225 2241326 2241427 2241528</div></td><td class="code"><span></span><span class="tok-p">{</span> 22416 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 22417 <span class="tok-p">{</span> 22418 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 22419 <span class="tok-nt">"createTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 22420 <span class="tok-nt">"delegationState"</span> <span class="tok-p">:</span> <span class="tok-s2">"pending"</span><span class="tok-p">,</span> 22421 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"Task description"</span><span class="tok-p">,</span> 22422 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 22423 <span class="tok-nt">"execution"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 22424 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"8"</span><span class="tok-p">,</span> 22425 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task"</span><span class="tok-p">,</span> 22426 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"owner"</span><span class="tok-p">,</span> 22427 <span class="tok-nt">"parentTask"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/9"</span><span class="tok-p">,</span> 22428 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">50</span><span class="tok-p">,</span> 22429 <span class="tok-nt">"processDefinition"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 22430 <span class="tok-nt">"processInstance"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 22431 <span class="tok-nt">"suspended"</span> <span class="tok-p">:</span> <span class="tok-kc">false</span><span class="tok-p">,</span> 22432 <span class="tok-nt">"taskDefinitionKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"theTask"</span><span class="tok-p">,</span> 22433 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/8"</span><span class="tok-p">,</span> 22434 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 22435 <span class="tok-p">}</span> 22436 <span class="tok-p">],</span> 22437 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 22438 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 22439 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 22440 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 22441 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 22442<span class="tok-p">}</span> 22443</td></tr></table></code></pre> 22444</div> 22445</div> 22446</div> 22447<div class="sect3"> 22448<h4 id="_query_for_tasks">13.7.3. Query for tasks</h4> 22449<div class="listingblock"> 22450<div class="content"> 22451<pre>POST query/tasks</pre> 22452</div> 22453</div> 22454<div class="paragraph"> 22455<p><strong>Request body:</strong></p> 22456</div> 22457<div class="listingblock"> 22458<div class="content"> 22459<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 22460 2 22461 3 22462 4 22463 5 22464 6 22465 7 22466 8 22467 9 2246810 2246911 2247012 2247113 2247214 2247315 2247416 2247517 2247618 2247719 2247820 2247921 2248022</div></td><td class="code"><span></span><span class="tok-p">{</span> 22481 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task"</span><span class="tok-p">,</span> 22482 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"The task description"</span><span class="tok-p">,</span> 22483 22484 <span class="tok-err">...</span> 22485 22486 <span class="tok-nt">"taskVariables"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 22487 <span class="tok-p">{</span>
22488 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 22489 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mi">1234</span><span class="tok-p">,</span> 22490 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 22491 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"long"</span> 22492 <span class="tok-p">}</span> 22493 <span class="tok-p">],</span> 22494 22495 <span class="tok-nt">"processInstanceVariables"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 22496 <span class="tok-p">{</span> 22497 <span class="tok-err">...</span> 22498 <span class="tok-p">}</span> 22499 <span class="tok-p">]</span> 22500 <span class="tok-err">]</span> 22501<span class="tok-p">}</span> 22502</td></tr></table></code></pre> 22503</div> 22504</div> 22505<div class="paragraph"> 22506<p>All supported JSON parameter fields allowed are exactly the same as the parameters found for <a href="#restTasksGet">getting a collection of tasks</a> (except for candidateGroupIn which is only available in this POST task query REST service), but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri’s that are too long. On top of that, the query allows for filtering based on task and process variables. The <code>taskVariables</code> and <code>processInstanceVariables</code> are both JSON-arrays containing objects with the format <a href="#restQueryVariable">as described here.</a></p> 22507</div> 22508<table class="tableblock frame-all grid-all spread"> 22509<caption class="title">Table 113. Query for tasks - Response codes</caption> 22510<colgroup> 22511<col style="width: 50%;"> 22512<col style="width: 50%;"> 22513</colgroup> 22514<thead> 22515<tr> 22516<th class="tableblock halign-left valign-top">Response code</th> 22517<th class="tableblock halign-left valign-top">Description</th> 22518</tr> 22519</thead> 22520<tbody> 22521<tr> 22522<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 22523<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the tasks are returned</p></td> 22524</tr> 22525<tr> 22526<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 22527<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a parameter was passed in the wrong format or that <em>delegationState</em> has an invalid value (other than <em>pending</em> and <em>resolved</em>). The status-message contains additional information.</p></td> 22528</tr> 22529</tbody> 22530</table> 22531<div class="paragraph"> 22532<p><strong>Success response body:</strong></p> 22533</div> 22534<div class="listingblock"> 22535<div class="content"> 22536<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 22537 2 22538 3 22539 4 22540 5 22541 6 22542 7 22543 8 22544 9 2254510 2254611 2254712 2254813 2254914 2255015 2255116 2255217 2255318 2255419 2255520 2255621 2255722 2255823 2255924 2256025 2256126 2256227 2256328</div></td><td class="code"><span></span><span class="tok-p">{</span> 22564 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 22565 <span class="tok-p">{</span> 22566 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 22567 <span class="tok-nt">"createTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 22568 <span class="tok-nt">"delegationState"</span> <span class="tok-p">:</span> <span class="tok-s2">"pending"</span><span class="tok-p">,</span> 22569 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"Task description"</span><span class="tok-p">,</span> 22570 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span>
22571 <span class="tok-nt">"execution"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/executions/5"</span><span class="tok-p">,</span> 22572 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"8"</span><span class="tok-p">,</span> 22573 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task"</span><span class="tok-p">,</span> 22574 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"owner"</span><span class="tok-p">,</span> 22575 <span class="tok-nt">"parentTask"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/9"</span><span class="tok-p">,</span> 22576 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">50</span><span class="tok-p">,</span> 22577 <span class="tok-nt">"processDefinition"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 22578 <span class="tok-nt">"processInstance"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 22579 <span class="tok-nt">"suspended"</span> <span class="tok-p">:</span> <span class="tok-kc">false</span><span class="tok-p">,</span> 22580 <span class="tok-nt">"taskDefinitionKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"theTask"</span><span class="tok-p">,</span> 22581 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/8"</span><span class="tok-p">,</span> 22582 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 22583 <span class="tok-p">}</span> 22584 <span class="tok-p">],</span> 22585 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 22586 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 22587 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 22588 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 22589 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 22590<span class="tok-p">}</span> 22591</td></tr></table></code></pre> 22592</div> 22593</div> 22594</div> 22595<div class="sect3"> 22596<h4 id="_update_a_task">13.7.4. Update a task</h4> 22597<div class="listingblock"> 22598<div class="content"> 22599<pre>PUT runtime/tasks/{taskId}</pre> 22600</div> 22601</div> 22602<div class="paragraph"> 22603<p><strong>Body JSON:</strong></p> 22604</div> 22605<div class="listingblock"> 22606<div class="content"> 22607<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 22608 2 22609 3 22610 4 22611 5 22612 6 22613 7 22614 8 22615 9 2261610</div></td><td class="code"><span></span><span class="tok-p">{</span> 22617 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"assignee"</span><span class="tok-p">,</span> 22618 <span class="tok-nt">"delegationState"</span> <span class="tok-p">:</span> <span class="tok-s2">"resolved"</span><span class="tok-p">,</span> 22619 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"New task description"</span><span class="tok-p">,</span> 22620 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T13:06:02.438+02:00"</span><span class="tok-p">,</span> 22621 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"New task name"</span><span class="tok-p">,</span> 22622 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"owner"</span><span class="tok-p">,</span> 22623 <span class="tok-nt">"parentTaskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 22624 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">20</span> 22625<span class="tok-p">}</span> 22626</td></tr></table></code></pre> 22627</div> 22628</div> 22629<div class="paragraph"> 22630<p>All request values are optional. For example, you can only include the <em>assignee</em> attribute in the request body JSON-object, only updating the assignee of the task, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the task-value will be updated to null. Example: <code>{"dueDate" : null}</code> will clear the duedate of the task).</p> 22631</div> 22632<table class="tableblock frame-all grid-all spread"> 22633<caption class="title">Table 114. Update a task - Response codes</caption> 22634<colgroup> 22635<col style="width: 50%;"> 22636<col style="width: 50%;"> 22637</colgroup> 22638<thead> 22639<tr> 22640<th class="tableblock halign-left valign-top">Response code</th> 22641<th class="tableblock halign-left valign-top">Description</th> 22642</tr> 22643</thead> 22644<tbody> 22645<tr> 22646<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 22647<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was updated.</p></td> 22648</tr> 22649<tr> 22650<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 22651<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 22652</tr> 22653<tr> 22654<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 22655<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was updated simultaneously.</p></td> 22656</tr> 22657</tbody> 22658</table> 22659<div class="paragraph"> 22660<p><strong>Success response body:</strong> see response for <code>runtime/tasks/{taskId}</code>.</p> 22661</div> 22662</div> 22663<div class="sect3"> 22664<h4 id="_task_actions">13.7.5. Task actions</h4> 22665<div class="listingblock"> 22666<div class="content"> 22667<pre>POST runtime/tasks/{taskId}</pre> 22668</div> 22669</div> 22670<div class="paragraph"> 22671<p><strong>Complete a task - Body JSON:</strong></p> 22672</div> 22673<div class="listingblock"> 22674<div class="content"> 22675<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 226762 226773 226784</div></td><td class="code"><span></span><span class="tok-p">{</span> 22679 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"complete"</span><span class="tok-p">,</span> 22680 <span class="tok-nt">"variables"</span> <span class="tok-p">:</span> <span class="tok-p">[]</span> 22681<span class="tok-p">}</span> 22682</td></tr></table></code></pre> 22683</div> 22684</div> 22685<div class="paragraph"> 22686<p>Completes the task. Optional variable array can be passed in using the <code>variables</code> property. More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>. Note that the variable-scope that is supplied is ignored and the variables are set on the parent-scope unless a variable exists in a local scope, which is overridden in this case. This is the same behavior as the <code>TaskService.completeTask(taskId, variables)</code> invocation.</p> 22687</div> 22688<div class="paragraph"> 22689<p>Note that also a <em>transientVariables</em> property is accepted as part of this json, that follows the same structure as the <em>variables</em> property.</p> 22690</div> 22691<div class="paragraph"> 22692<p><strong>Claim a task - Body JSON:</strong></p> 22693</div> 22694<div class="listingblock"> 22695<div class="content"> 22696<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 226972 226983 226994</div></td><td class="code"><span></span><span class="tok-p">{</span> 22700 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"claim"</span><span class="tok-p">,</span> 22701 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"userWhoClaims"</span> 22702<span class="tok-p">}</span> 22703</td></tr></table></code></pre> 22704</div> 22705</div> 22706<div class="paragraph"> 22707<p>Claims the task by the given assignee. If the assignee is <code>null</code>, the task is assigned to no-one, claimable again.</p> 22708</div> 22709<div class="paragraph"> 22710<p><strong>Delegate a task - Body JSON:</strong></p> 22711</div> 22712<div class="listingblock"> 22713<div class="content"> 22714<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 227152 227163 227174</div></td><td class="code"><span></span><span class="tok-p">{</span> 22718 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"delegate"</span><span class="tok-p">,</span> 22719 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"userToDelegateTo"</span> 22720<span class="tok-p">}</span> 22721</td></tr></table></code></pre> 22722</div> 22723</div> 22724<div class="paragraph"> 22725<p>Delegates the task to the given assignee. The assignee is required.</p> 22726</div> 22727<div class="paragraph"> 22728<p><strong>Resolve a task - Body JSON:</strong></p> 22729</div> 22730<div class="listingblock"> 22731<div class="content"> 22732<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 227332 227343</div></td><td class="code"><span></span><span class="tok-p">{</span> 22735 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"resolve"</span> 22736<span class="tok-p">}</span> 22737</td></tr></table></code></pre> 22738</div> 22739</div> 22740<div class="paragraph"> 22741<p>Resolves the task delegation. The task is assigned back to the task owner (if any).</p> 22742</div> 22743<table class="tableblock frame-all grid-all spread"> 22744<caption class="title">Table 115. Task actions - Response codes</caption> 22745<colgroup> 22746<col style="width: 50%;"> 22747<col style="width: 50%;"> 22748</colgroup> 22749<thead> 22750<tr> 22751<th class="tableblock halign-left valign-top">Response code</th> 22752<th class="tableblock halign-left valign-top">Description</th> 22753</tr> 22754</thead> 22755<tbody> 22756<tr> 22757<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 22758<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the action was executed.</p></td> 22759</tr> 22760<tr> 22761<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 22762<td class="tableblock halign-left valign-top"><p class="tableblock">
22762When the body contains an invalid value or when the assignee is missing when the action requires it.</p></td> 22763</tr> 22764<tr> 22765<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 22766<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 22767</tr> 22768<tr> 22769<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 22770<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the action cannot be performed due to a conflict. Either the task was updates simultaneously or the task was claimed by another user, in case of the <em><code>claim</code></em> action.</p></td> 22771</tr> 22772</tbody> 22773</table> 22774<div class="paragraph"> 22775<p><strong>Success response body:</strong> see response for <code>runtime/tasks/{taskId}</code>.</p> 22776</div> 22777</div> 22778<div class="sect3"> 22779<h4 id="_delete_a_task">13.7.6. Delete a task</h4> 22780<div class="listingblock"> 22781<div class="content"> 22782<pre>DELETE runtime/tasks/{taskId}?cascadeHistory={cascadeHistory}&deleteReason={deleteReason}</pre> 22783</div> 22784</div> 22785<table class="tableblock frame-all grid-all spread"> 22786<caption class="title">Table 116. >Delete a task - URL parameters</caption> 22787<colgroup> 22788<col style="width: 25%;"> 22789<col style="width: 25%;"> 22790<col style="width: 25%;"> 22791<col style="width: 25%;"> 22792</colgroup> 22793<thead> 22794<tr> 22795<th class="tableblock halign-left valign-top">Parameter</th> 22796<th class="tableblock halign-left valign-top">Required</th> 22797<th class="tableblock halign-left valign-top">Value</th> 22798<th class="tableblock halign-left valign-top">Description</th> 22799</tr> 22800</thead> 22801<tbody> 22802<tr> 22803<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 22804<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 22805<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22806<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to delete.</p></td> 22807</tr> 22808<tr> 22809<td class="tableblock halign-left valign-top"><p class="tableblock">cascadeHistory</p></td> 22810<td class="tableblock halign-left valign-top"><p class="tableblock">False</p></td> 22811<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 22812<td class="tableblock halign-left valign-top"><p class="tableblock">Whether or not to delete the HistoricTask instance when deleting the task (if applicable). If not provided, this value defaults to false.</p></td> 22813</tr> 22814<tr> 22815<td class="tableblock halign-left valign-top"><p class="tableblock">deleteReason</p></td> 22816<td class="tableblock halign-left valign-top"><p class="tableblock">False</p></td> 22817<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22818<td class="tableblock halign-left valign-top"><p class="tableblock">Reason why the task is deleted. This value is ignored when <code>cascadeHistory</code> is true.</p></td> 22819</tr> 22820</tbody> 22821</table> 22822<table class="tableblock frame-all grid-all spread"> 22823<caption class="title">Table 117. >Delete a task - Response codes</caption> 22824<colgroup> 22825<col style="width: 50%;"> 22826<col style="width: 50%;"> 22827</colgroup> 22828<thead> 22829<tr> 22830<th class="tableblock halign-left valign-top">Response code</th> 22831<th class="tableblock halign-left valign-top">Description</th> 22832</tr> 22833</thead> 22834<tbody> 22835<tr> 22836<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 22837<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and has been deleted. Response-body is intentionally empty.</p></td> 22838</tr> 22839<tr> 22840<td class="tableblock halign-left valign-top"><p class="tableblock">403</p></td> 22841<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task cannot be deleted because it’s part of a workflow.</p></td> 22842</tr> 22843<tr> 22844<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 22845<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 22846</tr> 22847</tbody> 22848</table> 22849</div> 22850<div class="sect3"> 22851<h4 id="_get_all_variables_for_a_task">13.7.7. Get all variables for a task</h4> 22852<div class="listingblock"> 22853<div class="content"> 22854<pre>GET runtime/tasks/{taskId}/variables?scope={scope}</pre> 22855</div> 22856</div> 22857<table class="tableblock frame-all grid-all spread"> 22858<caption class="title">Table 118. Get all variables for a task - URL parameters</caption> 22859<colgroup> 22860<col style="width: 25%;"> 22861<col style="width: 25%;"> 22862<col style="width: 25%;"> 22863<col style="width: 25%;"> 22864</colgroup> 22865<thead> 22866<tr> 22867<th class="tableblock halign-left valign-top">Parameter</th> 22868<th class="tableblock halign-left valign-top">Required</th> 22869<th class="tableblock halign-left valign-top">Value</th> 22870<th class="tableblock halign-left valign-top">Description</th> 22871</tr> 22872</thead> 22873<tbody> 22874<tr> 22875<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 22876<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 22877<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22878<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get variables for.</p></td> 22879</tr> 22880<tr> 22881<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 22882<td class="tableblock halign-left valign-top"><p class="tableblock">False</p></td> 22883<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22884<td class="tableblock halign-left valign-top"><p class="tableblock">Scope of variables to be returned. When <em><code>local</code></em>, only task-local variables are returned. When <em><code>global</code></em>, only variables from the task’s parent execution-hierarchy are returned. When the parameter is omitted, both local and global variables are returned.</p></td> 22885</tr> 22886</tbody> 22887</table> 22888<table class="tableblock frame-all grid-all spread"> 22889<caption class="title">Table 119. Get all variables for a task - Response codes</caption> 22890<colgroup> 22891<col style="width: 50%;"> 22892<col style="width: 50%;"> 22893</colgroup> 22894<thead> 22895<tr> 22896<th class="tableblock halign-left valign-top">Response code</th> 22897<th class="tableblock halign-left valign-top">Description</th> 22898</tr> 22899</thead> 22900<tbody> 22901<tr> 22902<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 22903<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the requested variables are returned.</p></td> 22904</tr> 22905<tr> 22906<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 22907<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 22908</tr> 22909</tbody> 22910</table> 22911<div class="paragraph"> 22912<p><strong>Success response body:</strong></p> 22913</div> 22914<div class="listingblock"> 22915<div class="content"> 22916<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 22917 2 22918 3 22919 4 22920 5 22921 6 22922 7 22923 8 22924 9 2292510 2292611 2292712 2292813 2292914 2293015 2293116 2293217</div></td><td class="code"><span></span><span class="tok-p">[</span> 22933 <span class="tok-p">{</span> 22934 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"doubleTaskVar"</span><span class="tok-p">,</span> 22935 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 22936 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"double"</span><span class="tok-p">,</span> 22937 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mf">99.99</span> 22938 <span class="tok-p">},</span> 22939 <span class="tok-p">{</span> 22940 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"
22940stringProcVar"</span><span class="tok-p">,</span> 22941 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"global"</span><span class="tok-p">,</span> 22942 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"string"</span><span class="tok-p">,</span> 22943 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a ProcVariable"</span> 22944 <span class="tok-p">}</span> 22945 22946 22947 22948<span class="tok-p">]</span> 22949</td></tr></table></code></pre> 22950</div> 22951</div> 22952<div class="paragraph"> 22953<p>The variables are returned as a JSON array. Full response description can be found in the general <a href="#restVariables">REST-variables section</a>.</p> 22954</div> 22955</div> 22956<div class="sect3"> 22957<h4 id="_get_a_variable_from_a_task">13.7.8. Get a variable from a task</h4> 22958<div class="listingblock"> 22959<div class="content"> 22960<pre>GET runtime/tasks/{taskId}/variables/{variableName}?scope={scope}</pre> 22961</div> 22962</div> 22963<table class="tableblock frame-all grid-all spread"> 22964<caption class="title">Table 120. Get a variable from a task - URL parameters</caption> 22965<colgroup> 22966<col style="width: 25%;"> 22967<col style="width: 25%;"> 22968<col style="width: 25%;"> 22969<col style="width: 25%;"> 22970</colgroup> 22971<thead> 22972<tr> 22973<th class="tableblock halign-left valign-top">Parameter</th> 22974<th class="tableblock halign-left valign-top">Required</th> 22975<th class="tableblock halign-left valign-top">Value</th> 22976<th class="tableblock halign-left valign-top">Description</th> 22977</tr> 22978</thead> 22979<tbody> 22980<tr> 22981<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 22982<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 22983<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22984<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get a variable for.</p></td> 22985</tr> 22986<tr> 22987<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 22988<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 22989<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22990<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable to get.</p></td> 22991</tr> 22992<tr> 22993<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 22994<td class="tableblock halign-left valign-top"><p class="tableblock">False</p></td> 22995<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 22996<td class="tableblock halign-left valign-top"><p class="tableblock">Scope of variable to be returned. When <em><code>local</code></em>, only task-local variable value is returned. When <em><code>global</code></em>, only variable value from the task’s parent execution-hierarchy are returned. When the parameter is omitted, a local variable will be returned if it exists, otherwise a global variable.</p></td> 22997</tr> 22998</tbody> 22999</table> 23000<table class="tableblock frame-all grid-all spread"> 23001<caption class="title">Table 121. Get a variable from a task - Response codes</caption> 23002<colgroup> 23003<col style="width: 50%;"> 23004<col style="width: 50%;"> 23005</colgroup> 23006<thead> 23007<tr> 23008<th class="tableblock halign-left valign-top">Response code</th> 23009<th class="tableblock halign-left valign-top">Description</th> 23010</tr> 23011</thead> 23012<tbody> 23013<tr> 23014<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 23015<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the requested variables are returned.</p></td> 23016</tr> 23017<tr> 23018<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23019<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have a variable with the given name (in the given scope). Status message provides additional information.</p></td> 23020</tr> 23021</tbody> 23022</table> 23023<div class="paragraph"> 23024<p><strong>Success response body:</strong></p> 23025</div> 23026<div class="listingblock"> 23027<div class="content"> 23028<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 230292 230303 230314 230325 230336</div></td><td class="code"><span></span><span class="tok-p">{</span> 23034 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTaskVariable"</span><span class="tok-p">,</span> 23035 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23036 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"
23036string"</span><span class="tok-p">,</span> 23037 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"Hello my friend"</span> 23038<span class="tok-p">}</span> 23039</td></tr></table></code></pre> 23040</div> 23041</div> 23042<div class="paragraph"> 23043<p>Full response body description can be found in the general <a href="#restVariables">REST-variables section</a>.</p> 23044</div> 23045</div> 23046<div class="sect3"> 23047<h4 id="_get_the_binary_data_for_a_variable">13.7.9. Get the binary data for a variable</h4> 23048<div class="listingblock"> 23049<div class="content"> 23050<pre>GET runtime/tasks/{taskId}/variables/{variableName}/data?scope={scope}</pre> 23051</div> 23052</div> 23053<table class="tableblock frame-all grid-all spread"> 23054<caption class="title">Table 122. Get the binary data for a variable - URL parameters</caption> 23055<colgroup> 23056<col style="width: 25%;"> 23057<col style="width: 25%;"> 23058<col style="width: 25%;"> 23059<col style="width: 25%;"> 23060</colgroup> 23061<thead> 23062<tr> 23063<th class="tableblock halign-left valign-top">Parameter</th> 23064<th class="tableblock halign-left valign-top">Required</th> 23065<th class="tableblock halign-left valign-top">Value</th> 23066<th class="tableblock halign-left valign-top">Description</th> 23067</tr> 23068</thead> 23069<tbody> 23070<tr> 23071<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23072<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23073<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23074<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get a variable data for.</p></td> 23075</tr> 23076<tr> 23077<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 23078<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23079<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23080<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable to get data for. Only variables of type <code>binary</code> and <code>serializable</code> can be used. If any other type of variable is used, a <code>404</code> is returned.</p></td> 23081</tr> 23082<tr> 23083<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 23084<td class="tableblock halign-left valign-top"><p class="tableblock">False</p></td> 23085<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23086<td class="tableblock halign-left valign-top"><p class="tableblock">Scope of variable to be returned. When <em><code>local</code></em>, only task-local variable value is returned. When <em><code>global</code></em>, only variable value from the task’s parent execution-hierarchy are returned. When the parameter is omitted, a local variable will be returned if it exists, otherwise a global variable.</p></td> 23087</tr> 23088</tbody> 23089</table> 23090<table class="tableblock frame-all grid-all spread"> 23091<caption class="title">Table 123. Get the binary data for a variable - Response codes</caption> 23092<colgroup> 23093<col style="width: 50%;"> 23094<col style="width: 50%;"> 23095</colgroup> 23096<thead> 23097<tr> 23098<th class="tableblock halign-left valign-top">Response code</th> 23099<th class="tableblock halign-left valign-top">Description</th> 23100</tr> 23101</thead> 23102<tbody> 23103<tr> 23104<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 23105<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the requested variables are returned.</p></td> 23106</tr> 23107<tr> 23108<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23109<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have a variable with the given name (in the given scope) or the variable doesn’t have a binary stream available. Status message provides additional information.</p></td> 23110</tr> 23111</tbody> 23112</table> 23113<div class="paragraph"> 23114<p><strong>Success response body:</strong></p> 23115</div> 23116<div class="paragraph"> 23117<p>The response body contains the binary value of the variable. When the variable is of type <code>binary</code>, the content-type of the response is set to <code>application/octet-stream</code>, regardless of the content of the variable or the request accept-type header. In case of <code>serializable</code>, <code>application/x-java-serialized-object</code> is used as content-type.</p> 23118</div> 23119</div> 23120<div class="sect3"> 23121<h4 id="_create_new_variables_on_a_task">
2312113.7.10. Create new variables on a task</h4> 23122<div class="listingblock"> 23123<div class="content"> 23124<pre>POST runtime/tasks/{taskId}/variables</pre> 23125</div> 23126</div> 23127<table class="tableblock frame-all grid-all spread"> 23128<caption class="title">Table 124. Create new variables on a task - URL parameters</caption> 23129<colgroup> 23130<col style="width: 25%;"> 23131<col style="width: 25%;"> 23132<col style="width: 25%;"> 23133<col style="width: 25%;"> 23134</colgroup> 23135<thead> 23136<tr> 23137<th class="tableblock halign-left valign-top">Parameter</th> 23138<th class="tableblock halign-left valign-top">Required</th> 23139<th class="tableblock halign-left valign-top">Value</th> 23140<th class="tableblock halign-left valign-top">Description</th> 23141</tr> 23142</thead> 23143<tbody> 23144<tr> 23145<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23146<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23147<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23148<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to create the new variable for.</p></td> 23149</tr> 23150</tbody> 23151</table> 23152<div class="paragraph"> 23153<p><strong>Request body for creating simple (non-binary) variables:</strong></p> 23154</div> 23155<div class="listingblock"> 23156<div class="content"> 23157<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 23158 2 23159 3 23160 4 23161 5 23162 6 23163 7 23164 8 23165 9 2316610 2316711</div></td><td class="code"><span></span><span class="tok-p">[</span> 23168 <span class="tok-p">{</span> 23169 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTaskVariable"</span><span class="tok-p">,</span> 23170 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23171 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"string"</span><span class="tok-p">,</span> 23172 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"Hello my friend"</span> 23173 <span class="tok-p">},</span> 23174 <span class="tok-p">{</span> 23175 23176 <span class="tok-p">}</span> 23177<span class="tok-p">]</span> 23178</td></tr></table></code></pre> 23179</div> 23180</div> 23181<div class="paragraph"> 23182<p>The request body should be an array containing one or more JSON-objects representing the variables that should be created.</p> 23183</div> 23184<div class="ulist"> 23185<ul> 23186<li> 23187<p><code>name</code>: Required name of the variable</p> 23188</li> 23189<li> 23190<p><code>scope</code>: Scope of variable that is created. If omitted, <code>local</code> is assumed.</p> 23191</li> 23192<li> 23193<p><code>type</code>: Type of variable that is created. If omitted, reverts to raw JSON-value type (string, boolean, integer or double).</p> 23194</li> 23195<li> 23196<p><code>value</code>: Variable value.</p> 23197</li> 23198</ul> 23199</div> 23200<div class="paragraph"> 23201<p>More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>.</p> 23202</div> 23203<div class="paragraph"> 23204<p><strong>Success response body:</strong></p> 23205</div> 23206<div class="listingblock"> 23207<div class="content"> 23208<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 23209 2 23210 3 23211 4 23212 5 23213 6 23214 7 23215 8 23216 9 2321710 2321811</div></td><td class="code"><span></span><span class="tok-p">[</span> 23219 <span class="tok-p">{</span> 23220 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTaskVariable"</span><span class="tok-p">,</span> 23221 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23222 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"string"</span><span class="tok-p">,</span> 23223 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"Hello my friend"</span> 23224 <span class="tok-p">},</span> 23225 <span class="tok-p">{</span> 23226 23227 <span class="tok-p">}</span> 23228<span class="tok-p">]</span> 23229</td></tr></table></code></pre> 23230</div> 23231</div> 23232<table class="tableblock frame-all grid-all spread"> 23233<caption class="title">Table 125. Create new variables on a task - Response codes</caption> 23234<colgroup> 23235<col style="width: 50%;"> 23236<col style="width: 50%;"> 23237</colgroup> 23238<thead> 23239<tr> 23240<th class="tableblock halign-left valign-top">Response code</th> 23241<th class="tableblock halign-left valign-top">Description</th> 23242</tr> 23243</thead> 23244<tbody> 23245<tr> 23246<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 23247<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variables were created and the result is returned.</p></td> 23248</tr> 23249<tr> 23250<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 23251<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of a variable to create was missing or that an attempt is done to create a variable on a standalone task (without a process associated) with scope <code>global</code> or an empty array of variables was included in the request or request did not contain an array of variables. Status message provides additional information.</p></td> 23252</tr> 23253<tr> 23254<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23255<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 23256</tr> 23257<tr> 23258<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 23259<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task already has a variable with the given name. Use the PUT method to update the task variable instead.</p></td> 23260</tr> 23261</tbody> 23262</table> 23263</div> 23264<div class="sect3"> 23265<h4 id="_create_a_new_binary_variable_on_a_task">13.7.11. Create a new binary variable on a task</h4> 23266<div class="listingblock"> 23267<div class="content"> 23268<pre>POST runtime/tasks/{taskId}/variables</pre> 23269</div> 23270</div> 23271<table class="tableblock frame-all grid-all spread"> 23272<caption class="title">Table 126. Create a new binary variable on a task - URL parameters</caption> 23273<colgroup> 23274<col style="width: 25%;"> 23275<col style="width: 25%;"> 23276<col style="width: 25%;"> 23277<col style="width: 25%;"> 23278</colgroup> 23279<thead> 23280<tr> 23281<th class="tableblock halign-left valign-top">Parameter</th> 23282<th class="tableblock halign-left valign-top">Required</th> 23283<th class="tableblock halign-left valign-top">Value</th> 23284<th class="tableblock halign-left valign-top">Description</th> 23285</tr> 23286</thead> 23287<tbody> 23288<tr> 23289<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23290<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23291<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23292<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to create the new variable for.</p></td> 23293</tr> 23294</tbody> 23295</table> 23296<div class="paragraph"> 23297<p><strong>Request body:</strong></p> 23298</div> 23299<div class="paragraph"> 23300<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 23301</div> 23302<div class="ulist"> 23303<ul> 23304<li> 23305<p><code>name</code>: Required name of the variable.</p> 23306</li> 23307<li> 23308<p><code>scope</code>: Scope of variable that is created. If omitted, <code>local</code> is assumed.</p> 23309</li> 23310<li> 23311<p><code>type</code>: Type of variable that is created. If omitted, <code>binary</code> is assumed and the binary data in the request will be stored as an array of bytes.</p> 23312</li> 23313</ul> 23314</div> 23315<div class="paragraph"> 23316<p><strong>Success response body:</strong></p> 23317</div> 23318<div class="listingblock"> 23319<div class="content"> 23320<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 233212 233223 233234 233245 233256 233267</div></td><td class="code"><span></span><span class="tok-p">{</span> 23327 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"binaryVariable"</span><span class="tok-p">,</span> 23328 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23329 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"binary"</span><span class="tok-p">,</span> 23330 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 23331 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://.../runtime/tasks/123/variables/binaryVariable/data"</span> 23332<span class="tok-p">}</span> 23333</td></tr></table></code></pre> 23334</div> 23335</div> 23336<table class="tableblock frame-all grid-all spread"> 23337<caption class="title">Table 127. Create a new binary variable on a task - Response codes</caption> 23338<colgroup> 23339<col style="width: 50%;"> 23340<col style="width: 50%;"> 23341</colgroup> 23342<thead> 23343<tr> 23344<th class="tableblock halign-left valign-top">Response code</th> 23345<th class="tableblock halign-left valign-top">Description</th> 23346</tr> 23347</thead> 23348<tbody> 23349<tr> 23350<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 23351<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable was created and the result is returned.</p></td> 23352</tr> 23353<tr> 23354<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 23355<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of the variable to create was missing or that an attempt is done to create a variable on a standalone task (without a process associated) with scope <code>global</code>. Status message provides additional information.</p></td> 23356</tr> 23357<tr> 23358<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23359<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 23360</tr> 23361<tr> 23362<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 23363<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task already has a variable with the given name. Use the PUT method to update the task variable instead.</p></td> 23364</tr> 23365<tr> 23366<td class="tableblock halign-left valign-top"><p class="tableblock">415</p></td> 23367<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.</p></td> 23368</tr> 23369</tbody> 23370</table> 23371</div> 23372<div class="sect3"> 23373<h4 id="_update_an_existing_variable_on_a_task">13.7.12. Update an existing variable on a task</h4> 23374<div class="listingblock"> 23375<div class="content"> 23376<pre>PUT runtime/tasks/{taskId}/variables/{variableName}</pre> 23377</div> 23378</div> 23379<table class="tableblock frame-all grid-all spread"> 23380<caption class="title">Table 128. Update an existing variable on a task - URL parameters</caption> 23381<colgroup> 23382<col style="width: 25%;"> 23383<col style="width: 25%;"> 23384<col style="width: 25%;"> 23385<col style="width: 25%;"> 23386</colgroup> 23387<thead> 23388<tr> 23389<th class="tableblock halign-left valign-top">Parameter</th> 23390<th class="tableblock halign-left valign-top">Required</th> 23391<th class="tableblock halign-left valign-top">Value</th> 23392<th class="tableblock halign-left valign-top">Description</th> 23393</tr> 23394</thead> 23395<tbody> 23396<tr> 23397<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23398<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23399<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23400<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to update the variable for.</p></td> 23401</tr> 23402<tr> 23403<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 23404<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23405<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23406<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable to update.</p></td> 23407</tr> 23408</tbody> 23409</table> 23410<div class="paragraph"> 23411<p><strong>Request body for updating simple (non-binary) variables:</strong></p> 23412</div> 23413<div class="listingblock"> 23414<div class="content"> 23415<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 234162 234173 234184 234195 234206</div></td><td class="code"><span></span><span class="tok-p">{</span> 23421 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTaskVariable"</span><span class="tok-p">,</span> 23422 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23423 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"
23423string"</span><span class="tok-p">,</span> 23424 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"Hello my friend"</span> 23425<span class="tok-p">}</span> 23426</td></tr></table></code></pre> 23427</div> 23428</div> 23429<div class="ulist"> 23430<ul> 23431<li> 23432<p><code>name</code>: Required name of the variable</p> 23433</li> 23434<li> 23435<p><code>scope</code>: Scope of variable that is updated. If omitted, <code>local</code> is assumed.</p> 23436</li> 23437<li> 23438<p><code>type</code>: Type of variable that is updated. If omitted, reverts to raw JSON-value type (string, boolean, integer or double).</p> 23439</li> 23440<li> 23441<p><code>value</code>: Variable value.</p> 23442</li> 23443</ul> 23444</div> 23445<div class="paragraph"> 23446<p>More information about the variable format can be found in <a href="#restVariables">the REST variables section</a>.</p> 23447</div> 23448<div class="paragraph"> 23449<p><strong>Success response body:</strong></p> 23450</div> 23451<div class="listingblock"> 23452<div class="content"> 23453<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 234542 234553 234564 234575 234586</div></td><td class="code"><span></span><span class="tok-p">{</span> 23459 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTaskVariable"</span><span class="tok-p">,</span> 23460 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23461 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"string"</span><span class="tok-p">,</span> 23462 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"Hello my friend"</span> 23463<span class="tok-p">}</span> 23464</td></tr></table></code></pre> 23465</div> 23466</div> 23467<table class="tableblock frame-all grid-all spread"> 23468<caption class="title">Table 129. Update an existing variable on a task - Response codes</caption> 23469<colgroup> 23470<col style="width: 50%;"> 23471<col style="width: 50%;"> 23472</colgroup> 23473<thead> 23474<tr> 23475<th class="tableblock halign-left valign-top">Response code</th> 23476<th class="tableblock halign-left valign-top">Description</th> 23477</tr> 23478</thead> 23479<tbody> 23480<tr> 23481<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 23482<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variables was updated and the result is returned.</p></td> 23483</tr> 23484<tr> 23485<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 23486<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of a variable to update was missing or that an attempt is done to update a variable on a standalone task (without a process associated) with scope <code>global</code>. Status message provides additional information.</p></td> 23487</tr> 23488<tr> 23489<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23490<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have a variable with the given name in the given scope. Status message contains additional information about the error.</p></td> 23491</tr> 23492</tbody> 23493</table> 23494</div> 23495<div class="sect3"> 23496<h4 id="_updating_a_binary_variable_on_a_task">13.7.13. Updating a binary variable on a task</h4> 23497<div class="listingblock"> 23498<div class="content"> 23499<pre>PUT runtime/tasks/{taskId}/variables/{variableName}</pre> 23500</div> 23501</div> 23502<table class="tableblock frame-all grid-all spread"> 23503<caption class="title">Table 130. Updating a binary variable on a task - URL parameters</caption> 23504<colgroup> 23505<col style="width: 25%;"> 23506<col style="width: 25%;"> 23507<col style="width: 25%;"> 23508<col style="width: 25%;"> 23509</colgroup> 23510<thead> 23511<tr> 23512<th class="tableblock halign-left valign-top">Parameter</th> 23513<th class="tableblock halign-left valign-top">Required</th> 23514<th class="tableblock halign-left valign-top">Value</th> 23515<th class="tableblock halign-left valign-top">Description</th> 23516</tr> 23517</thead> 23518<tbody> 23519<tr> 23520<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23521<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23522<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23523<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to update the variable for.</p></td> 23524</tr> 23525<tr> 23526<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 23527<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23528<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23529<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable to update.</p></td> 23530</tr> 23531</tbody> 23532</table> 23533<div class="paragraph"> 23534<p><strong>Request body:</strong></p> 23535</div> 23536<div class="paragraph"> 23537<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 23538</div> 23539<div class="ulist"> 23540<ul> 23541<li> 23542<p><code>name</code>: Required name of the variable.</p> 23543</li> 23544<li> 23545<p><code>scope</code>: Scope of variable that is updated. If omitted, <code>local</code> is assumed.</p> 23546</li> 23547<li> 23548<p><code>type</code>: Type of variable that is updated. If omitted, <code>binary</code> is assumed and the binary data in the request will be stored as an array of bytes.</p> 23549</li> 23550</ul> 23551</div> 23552<div class="paragraph"> 23553<p><strong>Success response body:</strong></p> 23554</div> 23555<div class="listingblock"> 23556<div class="content"> 23557<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 235582 235593 235604 235615 235626 235637</div></td><td class="code"><span></span><span class="tok-p">{</span> 23564 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"binaryVariable"</span><span class="tok-p">,</span> 23565 <span class="tok-nt">"scope"</span> <span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 23566 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"binary"</span><span class="tok-p">,</span> 23567 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 23568 <span class="tok-nt">"valueUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://.../runtime/tasks/123/variables/binaryVariable/data"</span> 23569<span class="tok-p">}</span> 23570</td></tr></table></code></pre> 23571</div> 23572</div> 23573<table class="tableblock frame-all grid-all spread"> 23574<caption class="title">Table 131. Updating a binary variable on a task - Response codes</caption> 23575<colgroup> 23576<col style="width: 50%;"> 23577<col style="width: 50%;"> 23578</colgroup> 23579<thead> 23580<tr> 23581<th class="tableblock halign-left valign-top">Response code</th> 23582<th class="tableblock halign-left valign-top">Description</th> 23583</tr> 23584</thead> 23585<tbody> 23586<tr> 23587<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 23588<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable was updated and the result is returned.</p></td> 23589</tr> 23590<tr> 23591<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 23592<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the name of the variable to update was missing or that an attempt is done to update a variable on a standalone task (without a process associated) with scope <code>global</code>. Status message provides additional information.</p></td> 23593</tr> 23594<tr> 23595<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23596<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the variable to update doesn’t exist for the given task in the given scope.</p></td> 23597</tr> 23598<tr> 23599<td class="tableblock halign-left valign-top"><p class="tableblock">415</p></td> 23600<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.</p></td> 23601</tr> 23602</tbody> 23603</table> 23604</div> 23605<div class="sect3"> 23606<h4 id="_delete_a_variable_on_a_task">13.7.14. Delete a variable on a task</h4> 23607<div class="listingblock"> 23608<div class="content"> 23609<pre>DELETE runtime/tasks/{taskId}/variables/{variableName}?scope={scope}</pre> 23610</div> 23611</div> 23612<table class="tableblock frame-all grid-all spread"> 23613<caption class="title">Table 132. Delete a variable on a task - URL parameters</caption> 23614<colgroup> 23615<col style="width: 25%;"> 23616<col style="width: 25%;"> 23617<col style="width: 25%;"> 23618<col style="width: 25%;"> 23619</colgroup> 23620<thead> 23621<tr> 23622<th class="tableblock halign-left valign-top">Parameter</th> 23623<th class="tableblock halign-left valign-top">Required</th> 23624<th class="tableblock halign-left valign-top">Value</th> 23625<th class="tableblock halign-left valign-top">Description</th> 23626</tr> 23627</thead> 23628<tbody> 23629<tr> 23630<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23631<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23632<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23633<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task the variable to delete belongs to.</p></td> 23634</tr> 23635<tr> 23636<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 23637<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23638<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23639<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the variable to delete.</p></td> 23640</tr> 23641<tr> 23642<td class="tableblock halign-left valign-top"><p class="tableblock">scope</p></td> 23643<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 23644<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23645<td class="tableblock halign-left valign-top"><p class="tableblock">Scope of variable to delete in. Can be either <code>local</code> or <code>global</code>. If omitted, <code>local</code> is assumed.</p></td> 23646</tr> 23647</tbody> 23648</table> 23649<table class="tableblock frame-all grid-all spread"> 23650<caption class="title">Table 133. Delete a variable on a task - Response codes</caption> 23651<colgroup> 23652<col style="width: 50%;"> 23653<col style="width: 50%;"> 23654</colgroup> 23655<thead> 23656<tr> 23657<th class="tableblock halign-left valign-top">Response code</th> 23658<th class="tableblock halign-left valign-top">Description</th> 23659</tr> 23660</thead> 23661<tbody> 23662<tr> 23663<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 23664<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task variable was found and has been deleted. Response-body is intentionally empty.</p></td> 23665</tr> 23666<tr> 23667<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23668<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have a variable with the given name. Status message contains additional information about the error.</p></td> 23669</tr> 23670</tbody> 23671</table> 23672</div> 23673<div class="sect3"> 23674<h4 id="_delete_all_local_variables_on_a_task">13.7.15. Delete all local variables on a task</h4> 23675<div class="listingblock"> 23676<div class="content"> 23677<pre>DELETE runtime/tasks/{taskId}/variables</pre> 23678</div> 23679</div> 23680<table class="tableblock frame-all grid-all spread"> 23681<caption class="title">Table 134. Delete all local variables on a task - URL parameters</caption> 23682<colgroup> 23683<col style="width: 25%;"> 23684<col style="width: 25%;"> 23685<col style="width: 25%;"> 23686<col style="width: 25%;"> 23687</colgroup> 23688<thead> 23689<tr> 23690<th class="tableblock halign-left valign-top">Parameter</th> 23691<th class="tableblock halign-left valign-top">Required</th> 23692<th class="tableblock halign-left valign-top">Value</th> 23693<th class="tableblock halign-left valign-top">Description</th> 23694</tr> 23695</thead> 23696<tbody> 23697<tr> 23698<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23699<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23700<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23701<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task the variable to delete belongs to.</p></td> 23702</tr> 23703</tbody> 23704</table> 23705<table class="tableblock frame-all grid-all spread"> 23706<caption class="title">Table 135. Delete all local variables on a task - Response codes</caption> 23707<colgroup> 23708<col style="width: 50%;"> 23709<col style="width: 50%;"> 23710</colgroup> 23711<thead> 23712<tr> 23713<th class="tableblock halign-left valign-top">Response code</th> 23714<th class="tableblock halign-left valign-top">Description</th> 23715</tr> 23716</thead> 23717<tbody> 23718<tr> 23719<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 23720<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates all local task variables have been deleted. Response-body is intentionally empty.</p></td> 23721</tr> 23722<tr> 23723<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23724<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 23725</tr> 23726</tbody> 23727</table> 23728</div> 23729<div class="sect3"> 23730<h4 id="_get_all_identity_links_for_a_task">13.7.16. Get all identity links for a task</h4> 23731<div class="listingblock"> 23732<div class="content"> 23733<pre>GET runtime/tasks/{taskId}/identitylinks</pre> 23734</div> 23735</div> 23736<table class="tableblock frame-all grid-all spread"> 23737<caption class="title">Table 136. Get all identity links for a task - URL parameters</caption> 23738<colgroup> 23739<col style="width: 25%;"> 23740<col style="width: 25%;"> 23741<col style="width: 25%;"> 23742<col style="width: 25%;"> 23743</colgroup> 23744<thead> 23745<tr> 23746<th class="tableblock halign-left valign-top">Parameter</th> 23747<th class="tableblock halign-left valign-top">Required</th> 23748<th class="tableblock halign-left valign-top">Value</th> 23749<th class="tableblock halign-left valign-top">Description</th> 23750</tr> 23751</thead> 23752<tbody> 23753<tr> 23754<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23755<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23756<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23757<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the identity links for.</p></td> 23758</tr> 23759</tbody> 23760</table> 23761<table class="tableblock frame-all grid-all spread"> 23762<caption class="title">Table 137. Get all identity links for a task - Response codes</caption> 23763<colgroup> 23764<col style="width: 50%;"> 23765<col style="width: 50%;"> 23766</colgroup> 23767<thead> 23768<tr> 23769<th class="tableblock halign-left valign-top">Response code</th> 23770<th class="tableblock halign-left valign-top">Description</th> 23771</tr> 23772</thead> 23773<tbody> 23774<tr> 23775<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 23776<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the requested identity links are returned.</p></td> 23777</tr> 23778<tr> 23779<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23780<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 23781</tr> 23782</tbody> 23783</table> 23784<div class="paragraph"> 23785<p><strong>Success response body:</strong></p> 23786</div> 23787<div class="listingblock"> 23788<div class="content"> 23789<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 23790 2 23791 3 23792 4 23793 5 23794 6 23795 7 23796 8 23797 9 2379810 2379911 2380012 2380113 2380214 2380315 2380416</div></td><td class="code"><span></span><span class="tok-p">[</span> 23805 <span class="tok-p">{</span> 23806 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 23807 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 23808 <span class="tok-nt">"type"</span> <span class="tok-p
23808">:</span> <span class="tok-s2">"candidate"</span><span class="tok-p">,</span> 23809 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/users/kermit/candidate"</span> 23810 <span class="tok-p">},</span> 23811 <span class="tok-p">{</span> 23812 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 23813 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-s2">"sales"</span><span class="tok-p">,</span> 23814 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"candidate"</span><span class="tok-p">,</span> 23815 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/groups/sales/candidate"</span> 23816 <span class="tok-p">},</span> 23817 23818 <span class="tok-err">...</span> 23819<span class="tok-p">]</span> 23820</td></tr></table></code></pre> 23821</div> 23822</div> 23823</div> 23824<div class="sect3"> 23825<h4 id="_get_all_identitylinks_for_a_task_for_either_groups_or_users">13.7.17. Get all identitylinks for a task for either groups or users</h4> 23826<div class="listingblock"> 23827<div class="content"> 23828<pre>GET runtime/tasks/{taskId}/identitylinks/users 23829GET runtime/tasks/{taskId}/identitylinks/groups</pre> 23830</div> 23831</div> 23832<div class="paragraph"> 23833<p>Returns only identity links targetting either users or groups. Response body and status-codes are exactly the same as when getting the full list of identity links for a task.</p> 23834</div> 23835</div> 23836<div class="sect3"> 23837<h4 id="_get_a_single_identity_link_on_a_task">13.7.18. Get a single identity link on a task</h4> 23838<div class="listingblock"> 23839<div class="content"> 23840<pre>GET runtime/tasks/{taskId}/identitylinks/{family}/{identityId}/{type}</pre> 23841</div> 23842</div> 23843<table class="tableblock frame-all grid-all spread"> 23844<caption class="title">Table 138. Get all identitylinks for a task for either groups or users - URL parameters</caption> 23845<colgroup> 23846<col style="width: 25%;"> 23847<col style="width: 25%;"> 23848<col style="width: 25%;"> 23849<col style="width: 25%;"> 23850</colgroup> 23851<thead> 23852<tr> 23853<th class="tableblock halign-left valign-top">Parameter</th> 23854<th class="tableblock halign-left valign-top">Required</th> 23855<th class="tableblock halign-left valign-top">Value</th> 23856<th class="tableblock halign-left valign-top">Description</th> 23857</tr> 23858</thead> 23859<tbody> 23860<tr> 23861<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23862<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23863<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23864<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task .</p></td> 23865</tr> 23866<tr> 23867<td class="tableblock halign-left valign-top"><p class="tableblock">family</p></td> 23868<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23869<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23870<td class="tableblock halign-left valign-top"><p class="tableblock">Either <code>groups</code> or <code>users</code>, depending on what kind of identity is targeted.</p></td> 23871</tr> 23872<tr> 23873<td class="tableblock halign-left valign-top"><p class="tableblock">identityId</p></td> 23874<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23875<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23876<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the identity.</p></td> 23877</tr> 23878<tr> 23879<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td> 23880<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23881<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23882<td class="tableblock halign-left valign-top"><p class="tableblock">The type of identity link.</p></td> 23883</tr> 23884</tbody> 23885</table> 23886<table class="tableblock frame-all grid-all spread"> 23887<caption class="title">Table 139. Get all identitylinks for a task for either groups or users - Response codes</caption> 23888<colgroup> 23889<col style="width: 50%;"> 23890<col style="width: 50%;"> 23891</colgroup> 23892<thead> 23893<tr> 23894<th class="tableblock halign-left valign-top">Response code</th> 23895<th class="tableblock halign-left valign-top">Description</th> 23896</tr> 23897</thead> 23898<tbody> 23899<tr> 23900<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 23901<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and identity link was found and returned.</p></td> 23902</tr> 23903<tr> 23904<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 23905<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have the requested identityLink. The status contains additional information about this error.</p></td> 23906</tr> 23907</tbody> 23908</table> 23909<div class="paragraph"> 23910<p><strong>Success response body:</strong></p> 23911</div> 23912<div class="listingblock"> 23913<div class="content"> 23914<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 239152 239163 239174 239185 239196</div></td><td class="code"><span></span><span class="tok-p">{</span> 23920 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 23921 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-s2">"sales"</span><span class="tok-p">,</span> 23922 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"candidate"</span><span class="tok-p">,</span> 23923 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/groups/sales/candidate"</span> 23924<span class="tok-p">}</span> 23925</td></tr></table></code></pre> 23926</div> 23927</div> 23928</div> 23929<div class="sect3"> 23930<h4 id="_create_an_identity_link_on_a_task">13.7.19. Create an identity link on a task</h4> 23931<div class="listingblock"> 23932<div class="content"> 23933<pre>POST runtime/tasks/{taskId}/identitylinks</pre> 23934</div> 23935</div> 23936<table class="tableblock frame-all grid-all spread"> 23937<caption class="title">Table 140. Create an identity link on a task - URL parameters</caption> 23938<colgroup> 23939<col style="width: 25%;"> 23940<col style="width: 25%;"> 23941<col style="width: 25%;"> 23942<col style="width: 25%;"> 23943</colgroup> 23944<thead> 23945<tr> 23946<th class="tableblock halign-left valign-top">Parameter</th> 23947<th class="tableblock halign-left valign-top">Required</th> 23948<th class="tableblock halign-left valign-top">Value</th> 23949<th class="tableblock halign-left valign-top">Description</th> 23950</tr> 23951</thead> 23952<tbody> 23953<tr> 23954<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 23955<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 23956<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 23957<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task .</p></td> 23958</tr> 23959</tbody> 23960</table> 23961<div class="paragraph"> 23962<p><strong>Request body (user):</strong></p> 23963</div> 23964<div class="listingblock"> 23965<div class="content"> 23966<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 239672 239683 239694</div></td><td class="code"><span></span><span class="tok-p">{</span> 23970 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 23971 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"candidate"</span><span class="tok-p">,</span> 23972<span class="tok-p">}</span> 23973</td></tr></table></code></pre> 23974</div> 23975</div> 23976<div class="paragraph"> 23977<p><strong>Request body (group):</strong></p> 23978</div> 23979<div class="listingblock"> 23980<div class="content"> 23981<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 239822 239833 239844</div></td><td class="code"><span></span><span class="tok-p">{</span> 23985 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-s2">"sales"</span><span class="tok-p">,</span> 23986 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"candidate"</span><span class="tok-p">,</span> 23987<span class="tok-p">}</span> 23988</td></tr></table></code></pre> 23989</div> 23990</div> 23991<table class="tableblock frame-all grid-all spread"> 23992<caption class="title">Table 141. Create an identity link on a task - Response codes</caption> 23993<colgroup> 23994<col style="width: 50%;"> 23995<col style="width: 50%;"> 23996</colgroup> 23997<thead> 23998<tr> 23999<th class="tableblock halign-left valign-top">Response code</th> 24000<th class="tableblock halign-left valign-top">Description</th> 24001</tr> 24002</thead> 24003<tbody> 24004<tr> 24005<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 24006<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the identity link was created.</p></td> 24007</tr> 24008<tr> 24009<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24010<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have the requested identityLink. The status contains additional information about this error.</p></td> 24011</tr> 24012</tbody> 24013</table> 24014<div class="paragraph"> 24015<p><strong>Success response body:</strong></p> 24016</div> 24017<div class="listingblock"> 24018<div class="content"> 24019<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 240202 240213 240224 240235 240246</div></td><td class="code"><span></span><span class="tok-p">{</span> 24025 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 24026 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-s2">"sales"</span><span class="tok-p">,</span> 24027 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"candidate"</span><span class="tok-p">,</span> 24028 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/groups/sales/candidate"</span> 24029<span class="tok-p">}</span> 24030</td></tr></table></code></pre> 24031</div> 24032</div> 24033</div> 24034<div class="sect3"> 24035<h4 id="_delete_an_identity_link_on_a_task">13.7.20. Delete an identity link on a task</h4> 24036<div class="listingblock"> 24037<div class="content"> 24038<pre>DELETE runtime/tasks/{taskId}/identitylinks/{family}/{identityId}/{type}</pre> 24039</div> 24040</div> 24041<table class="tableblock frame-all grid-all spread"> 24042<caption class="title">Table 142. Delete an identity link on a task - URL parameters</caption> 24043<colgroup> 24044<col style="width: 25%;"> 24045<col style="width: 25%;"> 24046<col style="width: 25%;"> 24047<col style="width: 25%;"> 24048</colgroup> 24049<thead> 24050<tr> 24051<th class="tableblock halign-left valign-top">Parameter</th> 24052<th class="tableblock halign-left valign-top">Required</th> 24053<th class="tableblock halign-left valign-top">Value</th> 24054<th class="tableblock halign-left valign-top">Description</th> 24055</tr> 24056</thead> 24057<tbody> 24058<tr> 24059<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24060<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24061<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24062<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task.</p></td> 24063</tr> 24064<tr> 24065<td class="tableblock halign-left valign-top"><p class="tableblock">family</p></td> 24066<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24067<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24068<td class="tableblock halign-left valign-top"><p class="tableblock">Either <code>groups</code> or <code>users</code>, depending on what kind of identity is targeted.</p></td> 24069</tr> 24070<tr> 24071<td class="tableblock halign-left valign-top"><p class="tableblock">identityId</p></td> 24072<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24073<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24074<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the identity.</p></td> 24075</tr> 24076<tr> 24077<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td> 24078<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24079<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24080<td class="tableblock halign-left valign-top"><p class="tableblock">The type of identity link.</p></td> 24081</tr> 24082</tbody> 24083</table> 24084<table class="tableblock frame-all grid-all spread"> 24085<caption class="title">Table 143. Delete an identity link on a task - Response codes</caption> 24086<colgroup> 24087<col style="width: 50%;"> 24088<col style="width: 50%;"> 24089</colgroup> 24090<thead> 24091<tr> 24092<th class="tableblock halign-left valign-top">Response code</th> 24093<th class="tableblock halign-left valign-top">Description</th> 24094</tr> 24095</thead> 24096<tbody> 24097<tr> 24098<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 24099<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and identity link were found and the link has been deleted. Response-body is intentionally empty.</p></td> 24100</tr> 24101<tr> 24102<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24103<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have the requested identityLink. The status contains additional information about this error.</p></td> 24104</tr> 24105</tbody> 24106</table> 24107</div> 24108<div class="sect3"> 24109<h4 id="_create_a_new_comment_on_a_task">13.7.21. Create a new comment on a task</h4> 24110<div class="listingblock"> 24111<div class="content"> 24112<pre>POST runtime/tasks/{taskId}/comments</pre> 24113</div> 24114</div> 24115<table class="tableblock frame-all grid-all spread"> 24116<caption class="title">Table 144. Create a new comment on a task - URL parameters</caption> 24117<colgroup> 24118<col style="width: 25%;"> 24119<col style="width: 25%;"> 24120<col style="width: 25%;"> 24121<col style="width: 25%;"> 24122</colgroup> 24123<thead> 24124<tr> 24125<th class="tableblock halign-left valign-top">Parameter</th> 24126<th class="tableblock halign-left valign-top">Required</th> 24127<th class="tableblock halign-left valign-top">Value</th> 24128<th class="tableblock halign-left valign-top">Description</th> 24129</tr> 24130</thead> 24131<tbody> 24132<tr> 24133<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24134<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24135<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24136<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to create the comment for.</p></td> 24137</tr> 24138</tbody> 24139</table> 24140<div class="paragraph"> 24141<p><strong>Request body:</strong></p> 24142</div> 24143<div class="listingblock"> 24144<div class="content"> 24145<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 241462 241473 241484</div></td><td class="code"><span></span><span class="tok-p">{</span> 24149 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment on the task."</span><span class="tok-p">,</span> 24150 <span class="tok-nt">"saveProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span> 24151<span class="tok-p">}</span> 24152</td></tr></table></code></pre> 24153</div> 24154</div> 24155<div class="paragraph"> 24156<p>Parameter <code>saveProcessInstanceId</code> is optional, if <code>true</code> save process instance id of task with comment.</p> 24157</div> 24158<div class="paragraph"> 24159<p><strong>Success response body:</strong></p> 24160</div> 24161<div class="listingblock"> 24162<div class="content"> 24163<pre class="pygments highlight"><c
24163ode data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24164 2 24165 3 24166 4 24167 5 24168 6 24169 7 24170 8 24171 9 2417210</div></td><td class="code"><span></span><span class="tok-p">{</span> 24173 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"123"</span><span class="tok-p">,</span> 24174 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/101/comments/123"</span><span class="tok-p">,</span> 24175 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/123"</span><span class="tok-p">,</span> 24176 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment on the task."</span><span class="tok-p">,</span> 24177 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 24178 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-13T13:13:52.232+08:00"</span> 24179 <span class="tok-s2">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"101"</span><span class="tok-p">,</span> 24180 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 24181<span class="tok-p">}</span> 24182</td></tr></table></code></pre> 24183</div> 24184</div> 24185<table class="tableblock frame-all grid-all spread"> 24186<caption class="title">Table 145. Create a new comment on a task - Response codes</caption> 24187<colgroup> 24188<col style="width: 50%;"> 24189<col style="width: 50%;"> 24190</colgroup> 24191<thead> 24192<tr> 24193<th class="tableblock halign-left valign-top">Response code</th> 24194<th class="tableblock halign-left valign-top">Description</th> 24195</tr> 24196</thead> 24197<tbody> 24198<tr> 24199<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 24200<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the comment was created and the result is returned.</p></td> 24201</tr> 24202<tr> 24203<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 24204<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the comment is missing from the request.</p></td> 24205</tr> 24206<tr> 24207<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24208<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 24209</tr> 24210</tbody> 24211</table> 24212</div> 24213<div class="sect3"> 24214<h4 id="_get_all_comments_on_a_task">13.7.22. Get all comments on a task</h4> 24215<div class="listingblock"> 24216<div class="content"> 24217<pre>GET runtime/tasks/{taskId}/comments</pre> 24218</div> 24219</div> 24220<table class="tableblock frame-all grid-all spread"> 24221<caption class="title">Table 146. Get all comments on a task - URL parameters</caption> 24222<colgroup> 24223<col style="width: 25%;"> 24224<col style="width: 25%;"> 24225<col style="width: 25%;"> 24226<col style="width: 25%;"> 24227</colgroup> 24228<thead> 24229<tr> 24230<th class="tableblock halign-left valign-top">Parameter</th> 24231<th class="tableblock halign-left valign-top">Required</th> 24232<th class="tableblock halign-left valign-top">Value</th> 24233<th class="tableblock halign-left valign-top">Description</th> 24234</tr> 24235</thead> 24236<tbody> 24237<tr> 24238<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24239<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24240<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24241<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the comments for.</p></td> 24242</tr> 24243</tbody> 24244</table> 24245<div class="paragraph"> 24246<p><strong>Success response body:</strong></p> 24247</div> 24248<div class="listingblock"> 24249<div class="content"> 24250<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24251 2 24252 3 24253 4 24254 5 24255 6 24256 7 24257 8 24258 9 2425910 2426011 2426112 2426213 2426314 2426415 2426516 2426617 2426718 2426819 2426920 2427021 2427122</div></td><td class="code"><span></span><span class="tok-p">[</span> 24272 <span class="tok-p">{</span> 24273 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"123"</span><span class="tok-p">,</span> 24274 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/101/comments/123"</span><span class="tok-p">,</span> 24275 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/123"</span><span class="tok-p">,</span> 24276 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment on the task."</span><span class="tok-p">,</span> 24277 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span> 24278 <span class="tok-s2">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-13T13:13:52.232+08:00"</span> 24279 <span class="tok-s2">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"101"</span><span class="tok-p">,</span> 24280 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 24281 <span class="tok-p">},</span> 24282 <span class="tok-p">{</span> 24283 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"456"</span><span class="tok-p">,</span> 24284 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/101/comments/456"</span><span class="tok-p">,</span> 24285 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/456"</span><span class="tok-p">,</span> 24286 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is another comment on the task."</span><span class="tok-p">,</span> 24287 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"gonzo"</span><span class="tok-p">,</span> 24288 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-13T13:13:52.232+08:00"</span> 24289 <span class="tok-s2">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"101"</span><span class="tok-p">,</span> 24290 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 24291 <span class="tok-p">}</span> 24292<span class="tok-p">]</span> 24293</td></tr></table></code></pre> 24294</div> 24295</div> 24296<table class="tableblock frame-all grid-all spread"> 24297<caption class="title">Table 147. Get all comments on a task - Response codes</caption> 24298<colgroup> 24299<col style="width: 50%;"> 24300<col style="width: 50%;"> 24301</colgroup> 24302<thead> 24303<tr> 24304<th class="tableblock halign-left valign-top">Response code</th> 24305<th class="tableblock halign-left valign-top">Description</th> 24306</tr> 24307</thead> 24308<tbody> 24309<tr> 24310<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 24311<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the comments are returned.</p></td> 24312</tr> 24313<tr> 24314<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24315<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 24316</tr> 24317</tbody> 24318</table> 24319</div> 24320<div class="sect3"> 24321<h4 id="_get_a_comment_on_a_task">13.7.23. Get a comment on a task</h4> 24322<div class="listingblock"> 24323<div class="content"> 24324<pre>GET runtime/tasks/{taskId}/comments/{commentId}</pre> 24325</div> 24326</div> 24327<table class="tableblock frame-all grid-all spread"> 24328<caption class="title">Table 148. Get a comment on a task - URL parameters</caption> 24329<colgroup> 24330<col style="width: 25%;"> 24331<col style="width: 25%;"> 24332<col style="width: 25%;"> 24333<col style="width: 25%;"> 24334</colgroup> 24335<thead> 24336<tr> 24337<th class="tableblock halign-left valign-top">Parameter</th> 24338<th class="tableblock halign-left valign-top">Required</th> 24339<th class="tableblock halign-left valign-top">Value</th> 24340<th class="tableblock halign-left valign-top">Description</th> 24341</tr> 24342</thead> 24343<tbody> 24344<tr> 24345<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24346<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24347<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24348<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the comment for.</p></td> 24349</tr> 24350<tr> 24351<td class="tableblock halign-left valign-top"><p class="tableblock">commentId</p></td> 24352<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24353<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24354<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the comment.</p></td> 24355</tr> 24356</tbody> 24357</table> 24358<div class="paragraph"> 24359<p><strong>Success response body:</strong></p> 24360</div> 24361<div class="listingblock"> 24362<div class="content"> 24363<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24364 2 24365 3 24366 4 24367 5 24368 6 24369 7 24370 8 24371 9 2437210</div></td><td class="code"><span></span><span class="tok-p">{</span> 24373 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"123"</span><span class="tok-p">,</span> 24374 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/101/comments/123"</span><span class="tok-p">,</span> 24375 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/123"</span><span class="tok-p">,</span> 24376 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment on the task."</span><span class="tok-p">,</span> 24377 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 24378 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-13T13:13:52.232+08:00"</span> 24379 <span class="tok-s2">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"101"</span><span class="tok-p">,</span> 24380 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 24381<span class="tok-p">}</span> 24382</td></tr></table></code></pre> 24383</div> 24384</div> 24385<table class="tableblock frame-all grid-all spread"> 24386<caption class="title">Table 149. Get a comment on a task - Response codes</caption> 24387<colgroup> 24388<col style="width: 50%;"> 24389<col style="width: 50%;"> 24390</colgroup> 24391<thead> 24392<tr> 24393<th class="tableblock halign-left valign-top">Response code</th> 24394<th class="tableblock halign-left valign-top">Description</th> 24395</tr> 24396</thead> 24397<tbody> 24398<tr> 24399<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 24400<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and comment were found and the comment is returned.</p></td> 24401</tr> 24402<tr> 24403<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24404<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the tasks doesn’t have a comment with the given ID.</p></td> 24405</tr> 24406</tbody> 24407</table> 24408</div> 24409<div class="sect3"> 24410<h4 id="_delete_a_comment_on_a_task">13.7.24. Delete a comment on a task</h4> 24411<div class="listingblock"> 24412<div class="content"> 24413<pre>DELETE runtime/tasks/{taskId}/comments/{commentId}</pre> 24414</div> 24415</div> 24416<table class="tableblock frame-all grid-all spread"> 24417<caption class="title">Table 150. Delete a comment on a task - URL parameters</caption> 24418<colgroup> 24419<col style="width: 25%;"> 24420<col style="width: 25%;"> 24421<col style="width: 25%;"> 24422<col style="width: 25%;"> 24423</colgroup> 24424<thead> 24425<tr> 24426<th class="tableblock halign-left valign-top">Parameter</th> 24427<th class="tableblock halign-left valign-top">Required</th> 24428<th class="tableblock halign-left valign-top">Value</th> 24429<th class="tableblock halign-left valign-top">Description</th> 24430</tr> 24431</thead> 24432<tbody> 24433<tr> 24434<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24435<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24436<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24437<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to delete the comment for.</p></td> 24438</tr> 24439<tr> 24440<td class="tableblock halign-left valign-top"><p class="tableblock">commentId</p></td> 24441<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24442<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24443<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the comment.</p></td> 24444</tr> 24445</tbody> 24446</table> 24447<table class="tableblock frame-all grid-all spread"> 24448<caption class="title">Table 151. Delete a comment on a task - Response codes</caption> 24449<colgroup> 24450<col style="width: 50%;"> 24451<col style="width: 50%;"> 24452</colgroup> 24453<thead> 24454<tr> 24455<th class="tableblock halign-left valign-top">Response code</th> 24456<th class="tableblock halign-left valign-top">Description</th> 24457</tr> 24458</thead> 24459<tbody> 24460<tr> 24461<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 24462<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and comment were found and the comment is deleted. Response body is left empty intentionally.</p></td> 24463</tr> 24464<tr> 24465<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24466<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the tasks doesn’t have a comment with the given ID.</p></td> 24467</tr> 24468</tbody> 24469</table> 24470</div> 24471<div class="sect3"> 24472<h4 id="_get_all_events_for_a_task">13.7.25. Get all events for a task</h4> 24473<div class="listingblock"> 24474<div class="content"> 24475<pre>GET runtime/tasks/{taskId}/events</pre> 24476</div> 24477</div> 24478<table class="tableblock frame-all grid-all spread"> 24479<caption class="title">Table 152. Get all events for a task - URL parameters</caption> 24480<colgroup> 24481<col style="width: 25%;"> 24482<col style="width: 25%;"> 24483<col style="width: 25%;"> 24484<col style="width: 25%;"> 24485</colgroup> 24486<thead> 24487<tr> 24488<th class="tableblock halign-left valign-top">Parameter</th> 24489<th class="tableblock halign-left valign-top">Required</th> 24490<th class="tableblock halign-left valign-top">Value</th> 24491<th class="tableblock halign-left valign-top">Description</th> 24492</tr> 24493</thead> 24494<tbody> 24495<tr> 24496<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24497<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24498<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24499<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the events for.</p></td> 24500</tr> 24501</tbody> 24502</table> 24503<div class="paragraph"> 24504<p><strong>Success response body:</strong></p> 24505</div> 24506<div class="listingblock"> 24507<div class="content"> 24508<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24509 2 24510 3 24511 4 24512 5 24513 6 24514 7 24515 8 24516 9 2451710 2451811
2451912</div></td><td class="code"><span></span><span class="tok-p">[</span> 24520 <span class="tok-p">{</span> 24521 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"AddUserLink"</span><span class="tok-p">,</span> 24522 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 24523 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> <span class="tok-s2">"gonzo"</span><span class="tok-p">,</span> <span class="tok-s2">"contributor"</span> <span class="tok-p">],</span> 24524 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 24525 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-05-17T11:50:50.000+0000"</span><span class="tok-p">,</span> 24526 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/2/events/4"</span><span class="tok-p">,</span> 24527 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 24528 <span class="tok-p">}</span> 24529 24530<span class="tok-p">]</span> 24531</td></tr></table></code></pre> 24532</div> 24533</div> 24534<table class="tableblock frame-all grid-all spread"> 24535<caption class="title">Table 153. Get all events for a task - Response codes</caption> 24536<colgroup> 24537<col style="width: 50%;"> 24538<col style="width: 50%;"> 24539</colgroup> 24540<thead> 24541<tr> 24542<th class="tableblock halign-left valign-top">Response code</th> 24543<th class="tableblock halign-left valign-top">Description</th> 24544</tr> 24545</thead> 24546<tbody> 24547<tr> 24548<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 24549<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the events are returned.</p></td> 24550</tr> 24551<tr> 24552<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24553<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 24554</tr> 24555</tbody> 24556</table> 24557</div> 24558<div class="sect3"> 24559<h4 id="_get_an_event_on_a_task">13.7.26. Get an event on a task</h4> 24560<div class="listingblock"> 24561<div class="content"> 24562<pre>GET runtime/tasks/{taskId}/events/{eventId}</pre> 24563</div> 24564</div> 24565<table class="tableblock frame-all grid-all spread"> 24566<caption class="title">Table 154. Get an event on a task - URL parameters</caption> 24567<colgroup> 24568<col style="width: 25%;"> 24569<col style="width: 25%;"> 24570<col style="width: 25%;"> 24571<col style="width: 25%;"> 24572</colgroup> 24573<thead> 24574<tr> 24575<th class="tableblock halign-left valign-top">Parameter</th> 24576<th class="tableblock halign-left valign-top">Required</th> 24577<th class="tableblock halign-left valign-top">Value</th> 24578<th class="tableblock halign-left valign-top">Description</th> 24579</tr> 24580</thead> 24581<tbody> 24582<tr> 24583<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24584<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24585<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24586<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the event for.</p></td> 24587</tr> 24588<tr> 24589<td class="tableblock halign-left valign-top"><p class="tableblock">eventId</p></td> 24590<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24591<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24592<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the event.</p></td> 24593</tr> 24594</tbody> 24595</table> 24596<div class="paragraph"> 24597<p><strong>Success response body:</strong></p> 24598</div> 24599<div class="listingblock"> 24600<div class="content"> 24601<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 246022 246033 246044 246055 246066 246077 246088 246099</div></td><td class="code"><span></span><span class="tok-p">{</span> 24610 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"AddUserLink"</span><span class="tok-p">,</span> 24611 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 24612 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> <span class="tok-s2">"gonzo"</span><span class="tok-p">,</span> <span class="tok-s2">"contributor"</span> <span class="tok-p">],</span> 24613 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 24614 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-05-17T11:50:50.000+0000"</span><span class="tok-p">,</span> 24615 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/tasks/2/events/4"</span><span class="tok-p">,</span> 24616 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 24617<span class="tok-p">}</span> 24618</td></tr></table></code></pre> 24619</div> 24620</div> 24621<table class="tableblock frame-all grid-all spread"> 24622<caption class="title">Table 155. Get an event on a task - Response codes</caption> 24623<colgroup> 24624<col style="width: 50%;"> 24625<col style="width: 50%;"> 24626</colgroup> 24627<thead> 24628<tr> 24629<th class="tableblock halign-left valign-top">Response code</th> 24630<th class="tableblock halign-left valign-top">Description</th> 24631</tr> 24632</thead> 24633<tbody> 24634<tr> 24635<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 24636<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and event were found and the event is returned.</p></td> 24637</tr> 24638<tr> 24639<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24640<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the tasks doesn’t have an event with the given ID.</p></td> 24641</tr> 24642</tbody> 24643</table> 24644</div> 24645<div class="sect3"> 24646<h4 id="_create_a_new_attachment_on_a_task_containing_a_link_to_an_external_resource">13.7.27. Create a new attachment on a task, containing a link to an external resource</h4> 24647<div class="listingblock"> 24648<div class="content"> 24649<pre>POST runtime/tasks/{taskId}/attachments</pre> 24650</div> 24651</div> 24652<table class="tableblock frame-all grid-all spread"> 24653<caption class="title">Table 156. Create a new attachment on a task, containing a link to an external resource - URL parameters</caption> 24654<colgroup> 24655<col style="width: 25%;"> 24656<col style="width: 25%;"> 24657<col style="width: 25%;"> 24658<col style="width: 25%;"> 24659</colgroup> 24660<thead> 24661<tr> 24662<th class="tableblock halign-left valign-top">Parameter</th> 24663<th class="tableblock halign-left valign-top">Required</th> 24664<th class="tableblock halign-left valign-top">Value</th> 24665<th class="tableblock halign-left valign-top">Description</th> 24666</tr> 24667</thead> 24668<tbody> 24669<tr> 24670<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24671<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24672<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24673<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to create the attachment for.</p></td> 24674</tr> 24675</tbody> 24676</table> 24677<div class="paragraph"> 24678<p><strong>Request body:</strong></p> 24679</div> 24680<div class="listingblock"> 24681<div class="content"> 24682<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 246832 246843 246854 246865 246876</div></td><td class="code"><span></span><span class="tok-p">{</span> 24688 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Simple attachment"</span><span class="tok-p">,</span> 24689 <span class="tok-nt">"description"</span><span class="tok-p">:</span><span class="tok-s2">"Simple attachment description"</span><span class="tok-p">,</span> 24690 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"simpleType"</span><span class="tok-p">,</span> 24691 <span class="tok-nt">"externalUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://activiti.org"</span> 24692<span class="tok-p">}</span> 24693</td></tr></table></code></pre> 24694</div> 24695</div> 24696<div class="paragraph"> 24697<p>Only the attachment name is required to create a new attachment.</p> 24698</div> 24699<div class="paragraph"> 24700<p><strong>Success response body:</strong></p> 24701</div> 24702<div class="listingblock"> 24703<div class="content"> 24704<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24705 2 24706 3 24707 4 24708 5 24709 6 24710 7 24711 8 24712 9 2471310 2471411</div></td><td class="code"><span></span><span class="tok-p">{</span> 24715 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"3"</span><span class="tok-p">,</span> 24716 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/3"</span><span class="tok-p">,</span> 24717 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Simple attachment"</span><span class="tok-p">,</span> 24718 <span class="tok-nt">"description"</span><span class="tok-p">:</span><span class="tok-s2">"Simple attachment description"</span><span class="tok-p">,</span> 24719 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"simpleType"</span><span class="tok-p">,</span> 24720 <span class="tok-nt">"taskUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 24721 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 24722 <span class="tok-nt">"externalUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://activiti.org"</span><span class="tok-p">,</span> 24723 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 24724<span class="tok-p">}</span> 24725</td></tr></table></code></pre> 24726</div> 24727</div> 24728<table class="tableblock frame-all grid-all spread"> 24729<caption class="title">Table 157. Create a new attachment on a task, containing a link to an external resource - Response codes</caption> 24730<colgroup> 24731<col style="width: 50%;"> 24732<col style="width: 50%;"> 24733</colgroup> 24734<thead> 24735<tr> 24736<th class="tableblock halign-left valign-top">Response code</th> 24737<th class="tableblock halign-left valign-top">Description</th> 24738</tr> 24739</thead> 24740<tbody> 24741<tr> 24742<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 24743<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the attachment was created and the result is returned.</p></td> 24744</tr> 24745<tr> 24746<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 24747<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the attachment name is missing from the request.</p></td> 24748</tr> 24749<tr> 24750<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24751<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 24752</tr> 24753</tbody> 24754</table> 24755</div> 24756<div class="sect3"> 24757<h4 id="_create_a_new_attachment_on_a_task_with_an_attached_file">13.7.28. Create a new attachment on a task, with an attached file</h4> 24758<div class="listingblock"> 24759<div class="content"> 24760<pre>POST runtime/tasks/{taskId}/attachments</pre> 24761</div> 24762</div> 24763<table class="tableblock frame-all grid-all spread"> 24764<caption class="title">Table 158. Create a new attachment on a task, with an attached file - URL parameters</caption> 24765<colgroup> 24766<col style="width: 25%;"> 24767<col style="width: 25%;"> 24768<col style="width: 25%;"> 24769<col style="width: 25%;"> 24770</colgroup> 24771<thead> 24772<tr> 24773<th class="tableblock halign-left valign-top">Parameter</th> 24774<th class="tableblock halign-left valign-top">Required</th> 24775<th class="tableblock halign-left valign-top">Value</th> 24776<th class="tableblock halign-left valign-top">Description</th> 24777</tr> 24778</thead> 24779<tbody> 24780<tr> 24781<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24782<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24783<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24784<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to create the attachment for.</p></td> 24785</tr> 24786</tbody> 24787</table> 24788<div class="paragraph"> 24789<p><strong>Request body:</strong></p> 24790</div> 24791<div class="paragraph"> 24792<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:</p> 24793</div> 24794<div class="ulist"> 24795<ul> 24796<li> 24797<p><code>name</code>: Required name of the variable.</p> 24798</li> 24799<li> 24800<p><code>description</code>: Description of the attachment, optional.</p> 24801</li> 24802<li> 24803<p><code>type</code>: Type of attachment, optional. Supports any arbitrary string or a valid HTTP content-type.</p> 24804</li> 24805</ul> 24806</div> 24807<div class="paragraph"> 24808<p><strong>Success response body:</strong></p> 24809</div> 24810<div class="listingblock"> 24811<div class="content"> 24812<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24813 2 24814 3 24815 4 24816 5 24817 6 24818 7 24819 8 24820 9 2482110 2482211</div></td><td class="code"><span></span><span class="tok-p">{</span> 24823 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 24824 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/5"</span><span class="tok-p">,</span> 24825 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Binary attachment"</span><span class="tok-p">,</span> 24826 <span class="tok-nt">"description"</span><span class="tok-p">:</span><span class="tok-s2">"Binary attachment description"</span><span class="tok-p">,</span> 24827 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"binaryType"</span><span class="tok-p">,</span> 24828 <span class="tok-nt">"taskUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 24829 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 24830 <span class="tok-nt">"externalUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 24831 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/5/content"</span> 24832<span class="tok-p">}</span> 24833</td></tr></table></code></pre> 24834</div> 24835</div> 24836<table class="tableblock frame-all grid-all spread"> 24837<caption class="title">Table 159. Create a new attachment on a task, with an attached file - Response codes</caption> 24838<colgroup> 24839<col style="width: 50%;"> 24840<col style="width: 50%;"> 24841</colgroup> 24842<thead> 24843<tr> 24844<th class="tableblock halign-left valign-top">Response code</th> 24845<th class="tableblock halign-left valign-top">Description</th> 24846</tr> 24847</thead> 24848<tbody> 24849<tr> 24850<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 24851<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the attachment was created and the result is returned.</p></td> 24852</tr> 24853<tr> 24854<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 24855<td class="tableblock halign-left valign-to
24855p"><p class="tableblock">Indicates the attachment name is missing from the request or no file was present in the request. The error-message contains additional information.</p></td> 24856</tr> 24857<tr> 24858<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24859<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 24860</tr> 24861</tbody> 24862</table> 24863</div> 24864<div class="sect3"> 24865<h4 id="_get_all_attachments_on_a_task">13.7.29. Get all attachments on a task</h4> 24866<div class="listingblock"> 24867<div class="content"> 24868<pre>GET runtime/tasks/{taskId}/attachments</pre> 24869</div> 24870</div> 24871<table class="tableblock frame-all grid-all spread"> 24872<caption class="title">Table 160. Get all attachments on a task - URL parameters</caption> 24873<colgroup> 24874<col style="width: 25%;"> 24875<col style="width: 25%;"> 24876<col style="width: 25%;"> 24877<col style="width: 25%;"> 24878</colgroup> 24879<thead> 24880<tr> 24881<th class="tableblock halign-left valign-top">Parameter</th> 24882<th class="tableblock halign-left valign-top">Required</th> 24883<th class="tableblock halign-left valign-top">Value</th> 24884<th class="tableblock halign-left valign-top">Description</th> 24885</tr> 24886</thead> 24887<tbody> 24888<tr> 24889<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 24890<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 24891<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 24892<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the attachments for.</p></td> 24893</tr> 24894</tbody> 24895</table> 24896<div class="paragraph"> 24897<p><strong>Success response body:</strong></p> 24898</div> 24899<div class="listingblock"> 24900<div class="content"> 24901<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 24902 2 24903 3 24904 4 24905 5 24906 6 24907 7 24908 8 24909 9 2491010 2491111 2491212 2491313 2491414 2491515 2491616 2491717 2491818 2491919 2492020 2492121 2492222 2492323 2492424</div></td><td class="code"><span></span><span class="tok-p">[</span> 24925 <span class="tok-p">{</span> 24926 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"3"</span><span class="tok-p">,</span> 24927 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/3"</span><span class="tok-p">,</span> 24928 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Simple attachment"</span><span class="tok-p">,</span> 24929 <span class="tok-nt">"description"</span><span class="tok-p">:</span><span class="tok-s2">"Simple attachment description"</span><span class="tok-p">,</span> 24930 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"simpleType"</span><span class="tok-p">,</span> 24931 <span class="tok-nt">"taskUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 24932 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 24933 <span class="tok-nt">"externalUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://activiti.org"</span><span class="tok-p">,</span> 24934 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 24935 <span class="tok-p">},</span> 24936 <span class="tok-p">{</span> 24937 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 24938 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/5"</span><span class="tok-p">,</span> 24939 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Binary attachment"</span><span class="tok-p">,</span> 24940 <span class="tok-nt">"description"</span><span class="tok-p">:</span><span class="tok-s2">"Binary attachment description"</span><span class="tok-p">,</span> 24941 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"binaryType"</span><span class="tok-p">,</span> 24942 <span class="tok-nt">"taskUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 24943 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 24944 <span class="tok-nt">"externalUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 24945 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/5/content"</span> 24946 <span class="tok-p">}</span> 24947<span class="tok-p">]</span> 24948</td></tr></table></code></pre> 24949</div> 24950</div> 24951<table class="tableblock frame-all grid-all spread"> 24952<caption class="title">Table 161. Get all attachments on a task - Response codes</caption> 24953<colgroup> 24954<col style="width: 50%;"> 24955<col style="width: 50%;"> 24956</colgroup> 24957<thead> 24958<tr> 24959<th class="tableblock halign-left valign-top">Response code</th> 24960<th class="tableblock halign-left valign-top">Description</th> 24961</tr> 24962</thead> 24963<tbody> 24964<tr> 24965<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 24966<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task was found and the attachments are returned.</p></td> 24967</tr> 24968<tr> 24969<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 24970<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 24971</tr> 24972</tbody> 24973</table> 24974</div> 24975<div class="sect3"> 24976<h4 id="_get_an_attachment_on_a_task">13.7.30. Get an attachment on a task</h4> 24977<div class="listingblock"> 24978<div class="content"> 24979<pre>GET runtime/tasks/{taskId}/attachments/{attachmentId}</pre> 24980</div> 24981</div> 24982<table class="tableblock frame-all grid-all spread"> 24983<caption class="title">Table 162. Get an attachment on a task - URL parameters</caption> 24984<colgroup> 24985<col style="width: 25%;"> 24986<col style="width: 25%;"> 24987<col style="width: 25%;"> 24988<col style="width: 25%;"> 24989</colgroup> 24990<thead> 24991<tr> 24992<th class="tableblock halign-left valign-top">Parameter</th> 24993<th class="tableblock halign-left valign-top">Required</th> 24994<th class="tableblock halign-left valign-top">Value</th> 24995<th class="tableblock halign-left valign-top">Description</th> 24996</tr> 24997</thead> 24998<tbody> 24999<tr> 25000<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 25001<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25002<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25003<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get the attachment for.</p></td> 25004</tr> 25005<tr> 25006<td class="tableblock halign-left valign-top"><p class="tableblock">attachmentId</p></td> 25007<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25008<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25009<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the attachment.</p></td> 25010</tr> 25011</tbody> 25012</table> 25013<div class="paragraph"> 25014<p><strong>Success response body:</strong></p> 25015</div> 25016<div class="listingblock"> 25017<div class="content"> 25018<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25019 2 25020 3 25021 4 25022 5 25023 6 25024 7 25025 8 25026 9 2502710 2502811</div></td><td class="code"><span></span><span class="tok-p">{</span> 25029 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 25030 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/5"</span><span class="tok-p">,</span> 25031 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Binary attachment"</span><span class="tok-p">,</span> 25032 <span class="tok-nt">"description"</span><span class="tok-p">:</span><span class="tok-s2">"Binary attachment description"</span><span class="tok-p">,</span> 25033 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"binaryType"</span><span class="tok-p">,</span> 25034 <span class="tok-nt">"taskUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2"</span><span class="tok-p">,</span> 25035 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 25036 <span class="tok-nt">"externalUrl"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 25037 <span class="tok-nt">"contentUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/tasks/2/attachments/5/content"</span> 25038<span class="tok-p">}</span> 25039</td></tr></table></code></pre> 25040</div> 25041</div> 25042<div class="ulist"> 25043<ul> 25044<li> 25045<p><code>externalUrl - contentUrl:</code>In case the attachment is a link to an external resource, the <code>externalUrl</code>
25045 contains the URL to the external content. If the attachment content is present in the Activiti engine, the <code>contentUrl</code> will contain an URL where the binary content can be streamed from.</p> 25046</li> 25047<li> 25048<p><code>type:</code>Can be any arbitrary value. When a valid formatted media-type (e.g. application/xml, text/plain) is included, the binary content HTTP response content-type will be set the the given value.</p> 25049</li> 25050</ul> 25051</div> 25052<table class="tableblock frame-all grid-all spread"> 25053<caption class="title">Table 163. Get an attachment on a task - Response codes</caption> 25054<colgroup> 25055<col style="width: 50%;"> 25056<col style="width: 50%;"> 25057</colgroup> 25058<thead> 25059<tr> 25060<th class="tableblock halign-left valign-top">Response code</th> 25061<th class="tableblock halign-left valign-top">Description</th> 25062</tr> 25063</thead> 25064<tbody> 25065<tr> 25066<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25067<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and attachment were found and the attachment is returned.</p></td> 25068</tr> 25069<tr> 25070<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25071<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the tasks doesn’t have a attachment with the given ID.</p></td> 25072</tr> 25073</tbody> 25074</table> 25075</div> 25076<div class="sect3"> 25077<h4 id="_get_the_content_for_an_attachment">13.7.31. Get the content for an attachment</h4> 25078<div class="listingblock"> 25079<div class="content"> 25080<pre>GET runtime/tasks/{taskId}/attachment/{attachmentId}/content</pre> 25081</div> 25082</div> 25083<table class="tableblock frame-all grid-all spread"> 25084<caption class="title">Table 164. Get the content for an attachment - URL parameters</caption> 25085<colgroup> 25086<col style="width: 25%;"> 25087<col style="width: 25%;"> 25088<col style="width: 25%;"> 25089<col style="width: 25%;"> 25090</colgroup> 25091<thead> 25092<tr> 25093<th class="tableblock halign-left valign-top">Parameter</th> 25094<th class="tableblock halign-left valign-top">Required</th> 25095<th class="tableblock halign-left valign-top">Value</th> 25096<th class="tableblock halign-left valign-top">Description</th> 25097</tr> 25098</thead> 25099<tbody> 25100<tr> 25101<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 25102<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25103<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25104<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to get a variable data for.</p></td> 25105</tr> 25106<tr> 25107<td class="tableblock halign-left valign-top"><p class="tableblock">attachmentId</p></td> 25108<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25109<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25110<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the attachment, a <code>404</code> is returned when the attachment points to an external URL rather than content attached in Activiti.</p></td> 25111</tr> 25112</tbody> 25113</table> 25114<table class="tableblock frame-all grid-all spread"> 25115<caption class="title">Table 165. Get the content for an attachment - Response codes</caption> 25116<colgroup> 25117<col style="width: 50%;"> 25118<col style="width: 50%;"> 25119</colgroup> 25120<thead> 25121<tr> 25122<th class="tableblock halign-left valign-top">Response code</th> 25123<th class="tableblock halign-left valign-top">Description</th> 25124</tr> 25125</thead> 25126<tbody> 25127<tr> 25128<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25129<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and attachment was found and the requested content is returned.</p></td> 25130</tr> 25131<tr> 25132<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25133<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the task doesn’t have an attachment with the given id or the attachment doesn’t have a binary stream available. Status message provides additional information.</p></td> 25134</tr> 25135</tbody> 25136</table> 25137<div class="paragraph"> 25138<p><strong>Success response body:</strong></p> 25139</div> 25140<div class="paragraph"> 25141<p>The response body contains the binary content. By default, the content-type of the response is set to <code>application/octet-stream</code> unless the attachment type contains a valid Content-type.</p> 25142</div> 25143</div> 25144<div class="sect3"> 25145<h4 id="_delete_an_attachment_on_a_task">13.7.32. Delete an attachment on a task</h4> 25146<div class="listingblock"> 25147<div class="content"> 25148<pre>DELETE runtime/tasks/{taskId}/attachments/{attachmentId}</pre> 25149</div> 25150</div> 25151<table class="tableblock frame-all grid-all spread"> 25152<caption class="title">Table 166. Delete an attachment on a task - URL parameters</caption> 25153<colgroup> 25154<col style="width: 25%;"> 25155<col style="width: 25%;"> 25156<col style="width: 25%;"> 25157<col style="width: 25%;"> 25158</colgroup> 25159<thead> 25160<tr> 25161<th class="tableblock halign-left valign-top">Parameter</th> 25162<th class="tableblock halign-left valign-top">Required</th> 25163<th class="tableblock halign-left valign-top">Value</th> 25164<th class="tableblock halign-left valign-top">Description</th> 25165</tr> 25166</thead> 25167<tbody> 25168<tr> 25169<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 25170<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25171<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25172<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the task to delete the attachment for.</p></td> 25173</tr> 25174<tr> 25175<td class="tableblock halign-left valign-top"><p class="tableblock">attachmentId</p></td> 25176<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25177<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25178<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the attachment.</p></td> 25179</tr> 25180</tbody> 25181</table> 25182<table class="tableblock frame-all grid-all spread"> 25183<caption class="title">Table 167. Delete an attachment on a task - Response codes</caption> 25184<colgroup> 25185<col style="width: 50%;"> 25186<col style="width: 50%;"> 25187</colgroup> 25188<thead> 25189<tr> 25190<th class="tableblock halign-left valign-top">Response code</th> 25191<th class="tableblock halign-left valign-top">Description</th> 25192</tr> 25193</thead> 25194<tbody> 25195<tr> 25196<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 25197<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task and attachment were found and the attachment is deleted. Response body is left empty intentionally.</p></td> 25198</tr> 25199<tr> 25200<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25201<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the tasks doesn’t have a attachment with the given ID.</p></td> 25202</tr> 25203</tbody> 25204</table> 25205</div> 25206</div> 25207<div class="sect2"> 25208<h3 id="_history">13.8. History</h3> 25209<div class="sect3"> 25210<h4 id="_get_a_historic_process_instance">13.8.1. Get a historic process instance</h4> 25211<div class="listingblock"> 25212<div class="content"> 25213<pre>GET history/historic-process-instances/{processInstanceId}</pre> 25214</div> 25215</div> 25216<table class="tableblock frame-all grid-all spread"> 25217<caption class="title">Table 168. Get a historic process instance - Response codes</caption> 25218<colgroup> 25219<col style="width: 50%;"> 25220<col style="width: 50%;"> 25221</colgroup> 25222<thead> 25223<tr> 25224<th class="tableblock halign-left valign-top">Response code</th> 25225<th class="tableblock halign-left valign-top">Description</th> 25226</tr> 25227</thead> 25228<tbody> 25229<tr> 25230<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25231<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic process instances could be found.</p></td> 25232</tr> 25233<tr> 25234<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25235<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic process instances could not be found.</p></td> 25236</tr> 25237</tbody> 25238</table> 25239<div class="paragraph"> 25240<p><strong>Success response body:</strong></p> 25241</div> 25242<div class="listingblock"> 25243<div class="content"> 25244<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25245 2 25246 3 25247 4 25248 5 25249 6 25250 7 25251 8 25252 9 2525310 2525411 2525512 2525613 2525714 2525815 2525916 2526017 2526118 2526219 2526320 2526421 2526522 2526623 2526724 2526825 2526926</div></td><td class="code"><span></span><span class="tok-p">{</span> 25270 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 25271 <span class="tok-p">{</span>
25272 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 25273 <span class="tok-nt">"businessKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"myKey"</span><span class="tok-p">,</span> 25274 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25275 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25276 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 25277 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 25278 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 25279 <span class="tok-nt">"startUserId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 25280 <span class="tok-nt">"startActivityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"startEvent"</span><span class="tok-p">,</span> 25281 <span class="tok-nt">"endActivityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"endEvent"</span><span class="tok-p">,</span> 25282 <span class="tok-nt">"deleteReason"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25283 <span class="tok-nt">"superProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 25284 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 25285 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25286 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 25287 <span class="tok-p">}</span> 25288 <span class="tok-p">],</span> 25289 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 25290 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 25291 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 25292 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 25293 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 25294<span class="tok-p">}</span> 25295</td></tr></table></code></pre> 25296</div> 25297</div> 25298</div> 25299<div class="sect3"> 25300<h4 id="restHistoricProcessInstancesGet">13.8.2. List of historic process instances</h4> 25301<div class="listingblock"> 25302<div class="content"> 25303<pre>GET history/historic-process-instances</pre> 25304</div> 25305</div> 25306<table class="tableblock frame-all grid-all spread"> 25307<caption class="title">Table 169. List of historic process instances - URL parameters</caption> 25308<colgroup> 25309<col style="width: 25%;"> 25310<col style="width: 25%;"> 25311<col style="width: 25%;"> 25312<col style="width: 25%;"> 25313</colgroup> 25314<thead> 25315<tr> 25316<th class="tableblock halign-left valign-top">Parameter</th> 25317<th class="tableblock halign-left valign-top">Required</th> 25318<th class="tableblock halign-left valign-top">Value</th> 25319<th class="tableblock halign-left valign-top">Description</th> 25320</tr> 25321</thead> 25322<tbody> 25323<tr> 25324<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 25325<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25326<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25327<td class="tableblock halign-left valign-top"><p class="tableblock">An id of the historic process instance.</p></td> 25328</tr> 25329<tr> 25330<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKey</p></td> 25331<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25332<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25333<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition key of the historic process instance.</p></td> 25334</tr> 25335<tr> 25336<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 25337<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25338<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25339<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition id of the historic process instance.</p></td> 25340</tr> 25341<tr> 25342<td class="tableblock halign-left valign-top"><p class="tableblock">businessKey</p></td> 25343<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25344<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25345<td class="tableblock halign-left valign-top"><p class="tableblock">The business key of the historic process instance.</p></td> 25346</tr> 25347<tr> 25348<td class="tableblock halign-left valign-top"><p class="tableblock">involvedUser</p></td> 25349<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25350<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25351<td class="tableblock halign-left valign-top"><p class="tableblock">An involved user of the historic process instance.</p></td> 25352</tr> 25353<tr> 25354<td class="tableblock halign-left valign-top"><p class="tableblock">finished</p></td> 25355<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25356<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 25357<td class="tableblock halign-left valign-top"><p class="tableblock">
25357Indication if the historic process instance is finished.</p></td> 25358</tr> 25359<tr> 25360<td class="tableblock halign-left valign-top"><p class="tableblock">superProcessInstanceId</p></td> 25361<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25362<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25363<td class="tableblock halign-left valign-top"><p class="tableblock">An optional parent process id of the historic process instance.</p></td> 25364</tr> 25365<tr> 25366<td class="tableblock halign-left valign-top"><p class="tableblock">excludeSubprocesses</p></td> 25367<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25368<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 25369<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic process instances which aren’t sub processes.</p></td> 25370</tr> 25371<tr> 25372<td class="tableblock halign-left valign-top"><p class="tableblock">finishedAfter</p></td> 25373<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25374<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 25375<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic process instances that were finished after this date.</p></td> 25376</tr> 25377<tr> 25378<td class="tableblock halign-left valign-top"><p class="tableblock">finishedBefore</p></td> 25379<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25380<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 25381<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic process instances that were finished before this date.</p></td> 25382</tr> 25383<tr> 25384<td class="tableblock halign-left valign-top"><p class="tableblock">startedAfter</p></td> 25385<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25386<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 25387<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic process instances that were started after this date.</p></td> 25388</tr> 25389<tr> 25390<td class="tableblock halign-left valign-top"><p class="tableblock">startedBefore</p></td> 25391<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25392<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 25393<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic process instances that were started before this date.</p></td> 25394</tr> 25395<tr> 25396<td class="tableblock halign-left valign-top"><p class="tableblock">startedBy</p></td> 25397<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25398<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25399<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic process instances that were started by this user.</p></td> 25400</tr> 25401<tr> 25402<td class="tableblock halign-left valign-top"><p class="tableblock">includeProcessVariables</p></td> 25403<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25404<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 25405<td class="tableblock halign-left valign-top"><p class="tableblock">An indication if the historic process instance variables should be returned as well.</p></td> 25406</tr> 25407<tr> 25408<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 25409<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25410<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25411<td class="tableblock halign-left valign-top"><p class="tableblock">Only return instances with the given tenantId.</p></td> 25412</tr> 25413<tr> 25414<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 25415<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25416<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25417<td class="tableblock halign-left valign-top"><p class="tableblock">Only return instances with a tenantId like the given value.</p></td> 25418</tr> 25419<tr> 25420<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 25421<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 25422<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 25423<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns instances without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 25424</tr> 25425</tbody> 25426</table> 25427<table class="tableblock frame-all grid-all spread"> 25428<caption class="title">Table 170. List of historic process instances - Response codes</caption> 25429<colgroup> 25430<col style="width: 50%;"> 25431<col style="width: 50%;"> 25432</colgroup> 25433<thead> 25434<tr> 25435<th class="tableblock halign-left valign-top">Response code</th> 25436<th class="tableblock halign-left valign-top">Description</th> 25437</tr> 25438</thead> 25439<tbody> 25440<tr> 25441<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25442<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that historic process instances could be queried.</p></td> 25443</tr> 25444<tr> 25445<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 25446<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 25447</tr> 25448</tbody> 25449</table> 25450<div class="paragraph"> 25451<p><strong>Success response body:</strong></p> 25452</div> 25453<div class="listingblock"> 25454<div class="content"> 25455<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25456 2 25457 3 25458 4 25459 5 25460 6 25461 7 25462 8 25463 9 2546410 2546511 2546612 2546713 2546814 2546915 2547016 2547117 2547218 2547319 2547420 2547521 2547622 2547723 2547824 2547925 2548026 2548127 2548228 2548329 2548430 2548531 2548632</div></td><td class="code"><span></span><span class="tok-p">{</span> 25487 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 25488 <span class="tok-p">{</span>
25489 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 25490 <span class="tok-nt">"businessKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"myKey"</span><span class="tok-p">,</span> 25491 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25492 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25493 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 25494 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 25495 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 25496 <span class="tok-nt">"startUserId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 25497 <span class="tok-nt">"startActivityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"startEvent"</span><span class="tok-p">,</span> 25498 <span class="tok-nt">"endActivityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"endEvent"</span><span class="tok-p">,</span> 25499 <span class="tok-nt">"deleteReason"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25500 <span class="tok-nt">"superProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 25501 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 25502 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 25503 <span class="tok-p">{</span> 25504 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"test"</span><span class="tok-p">,</span> 25505 <span class="tok-nt">"variableScope"</span><span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 25506 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"myTest"</span> 25507 <span class="tok-p">}</span> 25508 <span class="tok-p">],</span> 25509 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 25510 <span class="tok-p">}</span> 25511 <span class="tok-p">],</span> 25512 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 25513 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 25514 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 25515 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 25516 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 25517<span class="tok-p">}</span> 25518</td></tr></table></code></pre> 25519</div> 25520</div> 25521</div> 25522<div class="sect3"> 25523<h4 id="_query_for_historic_process_instances">13.8.3. Query for historic process instances</h4> 25524<div class="listingblock"> 25525<div class="content"> 25526<pre>POST query/historic-process-instances</pre> 25527</div> 25528</div> 25529<div class="paragraph"> 25530<p><strong>Request body:</strong></p> 25531</div> 25532<div class="listingblock"> 25533<div class="content"> 25534<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25535 2 25536 3 25537 4 25538 5 25539 6 25540 7 25541 8 25542 9 2554310 2554411 2554512 2554613</div></td><td class="code"><span></span><span class="tok-p">{</span> 25547 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25548 25549 25550 <span class="tok-nt">"variables"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 25551 <span class="tok-p">{</span>
25552 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 25553 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mi">1234</span><span class="tok-p">,</span> 25554 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 25555 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"long"</span> 25556 <span class="tok-p">}</span> 25557 <span class="tok-p">]</span> 25558<span class="tok-p">}</span> 25559</td></tr></table></code></pre> 25560</div> 25561</div> 25562<div class="paragraph"> 25563<p>All supported JSON parameter fields allowed are exactly the same as the parameters found for <a href="#restHistoricProcessInstancesGet">getting a collection of historic process instances</a>, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri’s that are too long. On top of that, the query allows for filtering based on process variables. The <code>variables</code> property is a JSON-array containing objects with the format <a href="#restQueryVariable">as described here.</a></p> 25564</div> 25565<table class="tableblock frame-all grid-all spread"> 25566<caption class="title">Table 171. Query for historic process instances - Response codes</caption> 25567<colgroup> 25568<col style="width: 50%;"> 25569<col style="width: 50%;"> 25570</colgroup> 25571<thead> 25572<tr> 25573<th class="tableblock halign-left valign-top">Response code</th> 25574<th class="tableblock halign-left valign-top">Description</th> 25575</tr> 25576</thead> 25577<tbody> 25578<tr> 25579<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25580<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the tasks are returned</p></td> 25581</tr> 25582<tr> 25583<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 25584<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 25585</tr> 25586</tbody> 25587</table> 25588<div class="paragraph"> 25589<p><strong>Success response body:</strong></p> 25590</div> 25591<div class="listingblock"> 25592<div class="content"> 25593<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25594 2 25595 3 25596 4 25597 5 25598 6 25599 7 25600 8 25601 9 2560210 2560311 2560412 2560513 2560614 2560715 2560816 2560917 2561018 2561119 2561220 2561321 2561422 2561523 2561624 2561725 2561826 2561927 2562028 2562129 2562230 2562331 2562432</div></td><td class="code"><span></span><span class="tok-p">{</span> 25625 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 25626 <span class="tok-p">{</span> 25627 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 25628 <span class="tok-nt">"businessKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"myKey"</span><span class="tok-p">,</span> 25629 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25630 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 25631 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 25632 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 25633 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 25634 <span class="tok-nt">"startUserId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span>
25635 <span class="tok-nt">"startActivityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"startEvent"</span><span class="tok-p">,</span> 25636 <span class="tok-nt">"endActivityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"endEvent"</span><span class="tok-p">,</span> 25637 <span class="tok-nt">"deleteReason"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25638 <span class="tok-nt">"superProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 25639 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 25640 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 25641 <span class="tok-p">{</span> 25642 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"test"</span><span class="tok-p">,</span> 25643 <span class="tok-nt">"variableScope"</span><span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span> 25644 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"myTest"</span> 25645 <span class="tok-p">}</span> 25646 <span class="tok-p">],</span> 25647 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 25648 <span class="tok-p">}</span> 25649 <span class="tok-p">],</span> 25650 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 25651 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 25652 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 25653 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 25654 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 25655<span class="tok-p">}</span> 25656</td></tr></table></code></pre> 25657</div> 25658</div> 25659</div> 25660<div class="sect3"> 25661<h4 id="_delete_a_historic_process_instance">13.8.4. Delete a historic process instance</h4> 25662<div class="listingblock"> 25663<div class="content"> 25664<pre>DELETE history/historic-process-instances/{processInstanceId}</pre> 25665</div> 25666</div> 25667<table class="tableblock frame-all grid-all spread"> 25668<caption class="title">Table 172. Response codes</caption> 25669<colgroup> 25670<col style="width: 50%;"> 25671<col style="width: 50%;"> 25672</colgroup> 25673<thead> 25674<tr> 25675<th class="tableblock halign-left valign-top">Response code</th> 25676<th class="tableblock halign-left valign-top">Description</th> 25677</tr> 25678</thead> 25679<tbody> 25680<tr> 25681<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25682<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic process instance was deleted.</p></td> 25683</tr> 25684<tr> 25685<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25686<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic process instance could not be found.</p></td> 25687</tr> 25688</tbody> 25689</table> 25690</div> 25691<div class="sect3"> 25692<h4 id="_get_the_identity_links_of_a_historic_process_instance">13.8.5. Get the identity links of a historic process instance</h4> 25693<div class="listingblock"> 25694<div class="content"> 25695<pre>GET history/historic-process-instance/{processInstanceId}/identitylinks</pre> 25696</div> 25697</div> 25698<table class="tableblock frame-all grid-all spread"> 25699<caption class="title">Table 173. Response codes</caption> 25700<colgroup> 25701<col style="width: 50%;"> 25702<col style="width: 50%;"> 25703</colgroup> 25704<thead> 25705<tr> 25706<th class="tableblock halign-left valign-top">Response code</th> 25707<th class="tableblock halign-left valign-top">Description</th> 25708</tr> 25709</thead> 25710<tbody> 25711<tr> 25712<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25713<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the identity links are returned</p></td> 25714</tr> 25715<tr> 25716<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25717<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance could not be found.</p></td> 25718</tr> 25719</tbody> 25720</table> 25721<div class="paragraph"> 25722<p><strong>Success response body:</strong></p> 25723</div> 25724<div class="listingblock"> 25725<div class="content"> 25726<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25727 2 25728 3 25729 4 25730 5 25731 6 25732 7 25733 8 25734 9 2573510 2573611</div></td><td class="code"><span></span><span class="tok-p">[</span> 25737 <span class="tok-p">{</span> 25738 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"participant"</span><span class="tok-p">,</span> 25739 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 25740 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25741 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25742 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 25743 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 25744 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span> 25745 <span class="tok-p">}</span> 25746<span class="tok-p">]</span> 25747</td></tr></table></code></pre> 25748</div> 25749</div> 25750</div> 25751<div class="sect3"> 25752<h4 id="_get_the_binary_data_for_a_historic_process_instance_variable">13.8.6. Get the binary data for a historic process instance variable</h4> 25753<div class="listingblock"> 25754<div class="content"> 25755<pre>GET history/historic-process-instances/{processInstanceId}/variables/{variableName}/data</pre> 25756</div> 25757</div> 25758<table class="tableblock frame-all grid-all spread"> 25759<caption class="title">Table 174. Get the binary data for a historic process instance variable - Response codes</caption> 25760<colgroup> 25761<col style="width: 50%;"> 25762<col style="width: 50%;"> 25763</colgroup> 25764<thead> 25765<tr> 25766<th class="tableblock halign-left valign-top">Response code</th> 25767<th class="tableblock halign-left valign-top">Description</th> 25768</tr> 25769</thead> 25770<tbody> 25771<tr> 25772<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25773<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and the requested variable data is returned.</p></td> 25774</tr> 25775<tr> 25776<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25777<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested process instance was not found or the process instance doesn’t have a variable with the given name or the variable doesn’t have a binary stream available. Status message provides additional information.</p></td> 25778</tr> 25779</tbody> 25780</table> 25781<div class="paragraph"> 25782<p><strong>Success response body:</strong></p> 25783</div> 25784<div class="paragraph"> 25785<p>The response body contains the binary value of the variable. When the variable is of type <code>binary</code>, the content-type of the response is set to <code>application/octet-stream</code>, regardless of the content of the variable or the request accept-type header. In case of <code>serializable</code>, <code>application/x-java-serialized-object</code> is used as content-type.</p> 25786</div> 25787</div> 25788<div class="sect3"> 25789<h4 id="_create_a_new_comment_on_a_historic_process_instance">13.8.7. Create a new comment on a historic process instance</h4> 25790<div class="listingblock"> 25791<div class="content"> 25792<pre>POST history/historic-process-instances/{processInstanceId}/comments</pre> 25793</div> 25794</div> 25795<table class="tableblock frame-all grid-all spread"> 25796<caption class="title">Table 175. Create a new comment on a historic process instance - URL parameters</caption> 25797<colgroup> 25798<col style="width: 25%;"> 25799<col style="width: 25%;"> 25800<col style="width: 25%;"> 25801<col style="width: 25%;"> 25802</colgroup> 25803<thead> 25804<tr> 25805<th class="tableblock halign-left valign-top">Parameter</th> 25806<th class="tableblock halign-left valign-top">Required</th> 25807<th class="tableblock halign-left valign-top">Value</th> 25808<th class="tableblock halign-left valign-top">Description</th> 25809</tr> 25810</thead> 25811<tbody> 25812<tr> 25813<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 25814<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25815<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25816<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to create the comment for.</p></td> 25817</tr> 25818</tbody> 25819</table> 25820<div class="paragraph"> 25821<p><strong>Request body:</strong></p> 25822</div> 25823<div class="listingblock"> 25824<div class="content"> 25825<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 258262 258273 258284</div></td><td class="code"><span></span><span class="tok-p">{</span> 25829 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment."</span><span class="tok-p">,</span> 25830 <span class="tok-nt">"saveProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span> 25831<span class="tok-p">}</span> 25832</td></tr></table></code></pre> 25833</div> 25834</div> 25835<div class="paragraph"> 25836<p>Parameter <code>saveProcessInstanceId</code> is optional, if <code>true</code> save process instance id of task with comment.</p> 25837</div> 25838<div class="paragraph"> 25839<p><strong>Success response body:</strong></p> 25840</div> 25841<div class="listingblock"> 25842<div class="content"> 25843<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25844 2 25845 3 25846 4 25847 5 25848 6 25849 7 25850 8 25851 9 2585210</div></td><td class="code"><span></span><span class="tok-p">{</span> 25853 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"123"</span><span class="tok-p">,</span> 25854 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/runtime/tasks/101/comments/123"</span><span class="tok-p">,</span> 25855 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/123"</span><span class="tok-p">,</span> 25856 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment on the task."</span><span class="tok-p">,</span> 25857 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 25858 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-13T13:13:52.232+08:00"</span><span class="tok-p">,</span> 25859 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"101"</span><span class="tok-p">,</span> 25860 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 25861<span class="tok-p">}</span> 25862</td></tr></table></code></pre> 25863</div> 25864</div> 25865<table class="tableblock frame-all grid-all spread"> 25866<caption class="title">Table 176. Create a new comment on a historic process instance - Response codes</caption> 25867<colgroup> 25868<col style="width: 50%;"> 25869<col style="width: 50%;"> 25870</colgroup> 25871<thead> 25872<tr> 25873<th class="tableblock halign-left valign-top">Response code</th> 25874<th class="tableblock halign-left valign-top">Description</th> 25875</tr> 25876</thead> 25877<tbody> 25878<tr> 25879<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 25880<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the comment was created and the result is returned.</p></td> 25881</tr> 25882<tr> 25883<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 25884<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the comment is missing from the request.</p></td> 25885</tr> 25886<tr> 25887<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25888<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested historic process instance was not found.</p></td> 25889</tr> 25890</tbody> 25891</table> 25892</div> 25893<div class="sect3"> 25894<h4 id="_get_all_comments_on_a_historic_process_instance">13.8.8. Get all comments on a historic process instance</h4> 25895<div class="listingblock"> 25896<div class="content"> 25897<pre>GET history/historic-process-instances/{processInstanceId}/comments</pre> 25898</div> 25899</div> 25900<table class="tableblock frame-all grid-all spread"> 25901<caption class="title">Table 177. Get all comments on a process instance - URL parameters</caption> 25902<colgroup> 25903<col style="width: 25%;"> 25904<col style="width: 25%;"> 25905<col style="width: 25%;"> 25906<col style="width: 25%;"> 25907</colgroup> 25908<thead> 25909<tr> 25910<th class="tableblock halign-left valign-top">Parameter</th> 25911<th class="tableblock halign-left valign-top">Required</th> 25912<th class="tableblock halign-left valign-top">Value</th> 25913<th class="tableblock halign-left valign-top">Description</th> 25914</tr> 25915</thead> 25916<tbody> 25917<tr> 25918<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 25919<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 25920<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 25921<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the process instance to get the comments for.</p></td> 25922</tr> 25923</tbody> 25924</table> 25925<div class="paragraph"> 25926<p><strong>Success response body:</strong></p> 25927</div> 25928<div class="listingblock"> 25929<div class="content"> 25930<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 25931 2 25932 3 25933 4 25934 5 25935 6 25936 7 25937 8 25938 9 2593910 2594011 2594112 2594213 2594314 2594415 2594516 2594617 2594718</div></td><td class="code"><span></span><span class="tok-p">[</span> 25948 <span class="tok-p">{</span> 25949 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"123"</span><span class="tok-p">,</span> 25950 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/123"</span><span class="tok-p">,</span> 25951 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is a comment on the task."</span><span class="tok-p">,</span> 25952 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 25953 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-13T13:13:52.232+08:00"</span><span class="tok-p">,</span> 25954 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 25955 <span class="tok-p">},</span> 25956 <span class="tok-p">{</span> 25957 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"456"</span><span class="tok-p">,</span> 25958 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-proces
25958s-instances/100/comments/456"</span><span class="tok-p">,</span> 25959 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is another comment."</span><span class="tok-p">,</span> 25960 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"gonzo"</span><span class="tok-p">,</span> 25961 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-14T15:16:52.232+08:00"</span><span class="tok-p">,</span> 25962 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 25963 <span class="tok-p">}</span> 25964<span class="tok-p">]</span> 25965</td></tr></table></code></pre> 25966</div> 25967</div> 25968<table class="tableblock frame-all grid-all spread"> 25969<caption class="title">Table 178. Get all comments on a process instance - Response codes</caption> 25970<colgroup> 25971<col style="width: 50%;"> 25972<col style="width: 50%;"> 25973</colgroup> 25974<thead> 25975<tr> 25976<th class="tableblock halign-left valign-top">Response code</th> 25977<th class="tableblock halign-left valign-top">Description</th> 25978</tr> 25979</thead> 25980<tbody> 25981<tr> 25982<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 25983<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the process instance was found and the comments are returned.</p></td> 25984</tr> 25985<tr> 25986<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 25987<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found.</p></td> 25988</tr> 25989</tbody> 25990</table> 25991</div> 25992<div class="sect3"> 25993<h4 id="_get_a_comment_on_a_historic_process_instance">13.8.9. Get a comment on a historic process instance</h4> 25994<div class="listingblock"> 25995<div class="content"> 25996<pre>GET history/historic-process-instances/{processInstanceId}/comments/{commentId}</pre> 25997</div> 25998</div> 25999<table class="tableblock frame-all grid-all spread"> 26000<caption class="title">Table 179. Get a comment on a historic process instance - URL parameters</caption> 26001<colgroup> 26002<col style="width: 25%;"> 26003<col style="width: 25%;"> 26004<col style="width: 25%;"> 26005<col style="width: 25%;"> 26006</colgroup> 26007<thead> 26008<tr> 26009<th class="tableblock halign-left valign-top">Parameter</th> 26010<th class="tableblock halign-left valign-top">Required</th> 26011<th class="tableblock halign-left valign-top">Value</th> 26012<th class="tableblock halign-left valign-top">Description</th> 26013</tr> 26014</thead> 26015<tbody> 26016<tr> 26017<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 26018<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 26019<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26020<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the historic process instance to get the comment for.</p></td> 26021</tr> 26022<tr> 26023<td class="tableblock halign-left valign-top"><p class="tableblock">commentId</p></td> 26024<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 26025<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26026<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the comment.</p></td> 26027</tr> 26028</tbody> 26029</table> 26030<div class="paragraph"> 26031<p><strong>Success response body:</strong></p> 26032</div> 26033<div class="listingblock"> 26034<div class="content"> 26035<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 260362 260373 260384 260395 260406 260417 260428</div></td><td class="code"><span></span><span class="tok-p">{</span> 26043 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"123"</span><span class="tok-p">,</span> 26044 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/456"</span><span class="tok-p">,</span> 26045 <span class="tok-nt">"message"</span> <span class="tok-p">:</span> <span class="tok-s2">"This is another comment."</span><span class="tok-p">,</span> 26046 <span class="tok-nt">"author"</span> <span class="tok-p">:</span> <span class="tok-s2">"gonzo"</span><span class="tok-p">,</span> 26047 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2014-07-14T15:16:52.232+08:00"</span><span class="tok-p">,</span> 26048 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"100"</span> 26049<span class="tok-p">}</span> 26050</td></tr></table></code></pre> 26051</div> 26052</div> 26053<table class="tableblock frame-all grid-all spread"> 26054<caption class="title">Table 180. Get a comment on a historic process instance - Response codes</caption> 26055<colgroup> 26056<col style="width: 50%;"> 26057<col style="width: 50%;"> 26058</colgroup> 26059<thead> 26060<tr> 26061<th class="tableblock halign-left valign-top">Response code</th> 26062<th class="tableblock halign-left valign-top">Description</th> 26063</tr> 26064</thead> 26065<tbody> 26066<tr> 26067<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26068<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the historic process instance and comment were found and the comment is returned.</p></td> 26069</tr> 26070<tr> 26071<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 26072<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested historic process instance was not found or the historic process instance doesn’t have a comment with the given ID.</p></td> 26073</tr> 26074</tbody> 26075</table> 26076</div> 26077<div class="sect3"> 26078<h4 id="_delete_a_comment_on_a_historic_process_instance">13.8.10. Delete a comment on a historic process instance</h4> 26079<div class="listingblock"> 26080<div class="content"> 26081<pre>DELETE history/historic-process-instances/{processInstanceId}/comments/{commentId}</pre> 26082</div> 26083</div> 26084<table class="tableblock frame-all grid-all spread"> 26085<caption class="title">Table 181. Delete a comment on a historic process instance - URL parameters</caption> 26086<colgroup> 26087<col style="width: 25%;"> 26088<col style="width: 25%;"> 26089<col style="width: 25%;"> 26090<col style="width: 25%;"> 26091</colgroup> 26092<thead> 26093<tr> 26094<th class="tableblock halign-left valign-top">Parameter</th> 26095<th class="tableblock halign-left valign-top">Required</th> 26096<th class="tableblock halign-left valign-top">Value</th> 26097<th class="tableblock halign-left valign-top">Description</th> 26098</tr> 26099</thead> 26100<tbody> 26101<tr> 26102<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 26103<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 26104<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26105<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the historic process instance to delete the comment for.</p></td> 26106</tr> 26107<tr> 26108<td class="tableblock halign-left valign-top"><p class="tableblock">commentId</p></td> 26109<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 26110<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26111<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the comment.</p></td> 26112</tr> 26113</tbody> 26114</table> 26115<table class="tableblock frame-all grid-all spread"> 26116<caption class="title">Table 182. Delete a comment on a historic process instance - Response codes</caption> 26117<colgroup> 26118<col style="width: 50%;"> 26119<col style="width: 50%;"> 26120</colgroup> 26121<thead> 26122<tr> 26123<th class="tableblock halign-left valign-top">Response code</th> 26124<th class="tableblock halign-left valign-top">Description</th> 26125</tr> 26126</thead> 26127<tbody> 26128<tr> 26129<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 26130<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the historic process instance and comment were found and the comment is deleted. Response body is left empty intentionally.</p></td> 26131</tr> 26132<tr> 26133<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 26134<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task was not found or the historic process instance doesn’t have a comment with the given ID.</p></td> 26135</tr> 26136</tbody> 26137</table> 26138</div> 26139<div class="sect3"> 26140<h4 id="_get_a_single_historic_task_instance">13.8.11. Get a single historic task instance</h4> 26141<div class="listingblock"> 26142<div class="content"> 26143<pre>GET history/historic-task-instances/{taskId}</pre> 26144</div> 26145</div> 26146<table class="tableblock frame-all grid-all spread"> 26147<caption class="title">Table 183. Get a single historic task instance - Response codes</caption> 26148<colgroup> 26149<col style="width: 50%;"> 26150<col style="width: 50%;"> 26151</colgroup> 26152<thead> 26153<tr> 26154<th class="tableblock halign-left valign-top">Response code</th> 26155<th class="tableblock halign-left valign-top">Description</th> 26156</tr> 26157</thead> 26158<tbody> 26159<tr> 26160<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26161<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic task instances could be found.</p></td> 26162</tr> 26163<tr> 26164<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 26165<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic task instances could not be found.</p></td> 26166</tr> 26167</tbody> 26168</table> 26169<div class="paragraph"> 26170<p><strong>Success response body:</strong></p> 26171</div> 26172<div class="listingblock"> 26173<div class="content"> 26174<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 26175 2 26176 3 26177 4 26178 5 26179 6 26180 7 26181 8 26182 9 2618310 2618411 2618512 2618613 2618714 2618815 2618916 2619017 2619118 2619219 2619320 2619421 2619522 2619623 2619724 2619825 2619926</div></td><td class="code"><span></span><span class="tok-p">{</span> 26200 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 26201 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26202 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26203 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 26204 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/3"</span><span class="tok-p">,</span> 26205 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 26206 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task name"</span><span class="tok-p">,</span> 26207 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task description"</span><span class="tok-p">,</span> 26208 <span class="tok-nt">"deleteReason"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26209 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 26210 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"fozzie"</span><span class="tok-p">,</span> 26211 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 26212 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 26213 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 26214 <span class="tok-nt">"workTimeInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">234890</span><span class="tok-p">,</span> 26215 <span class="tok-nt">"claimTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T11:01:54.715+0000"</span><span class="tok-p">,</span> 26216 <span class="tok-nt">"taskDefinitionKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"taskKey"</span><span class="tok-p">,</span> 26217 <span class="tok-nt">"formKey"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26218 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">50</span><span class="tok-p">,</span> 26219 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-20T12:11:13.134+0000"</span><span class="tok-p">,</span> 26220 <span class="tok-nt">"parentTaskId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26221 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-task-instances/5"</span><span class="tok-p">,</span> 26222 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26223 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 26224<span class="tok-p">}</span> 26225</td></tr></table></code></pre> 26226</div> 26227</div> 26228</div> 26229<div class="sect3"> 26230<h4 id="restHistoricTaskInstancesGet">13.8.12. Get historic task instances</h4> 26231<div class="listingblock"> 26232<div class="content"> 26233<pre>GET history/historic-task-instances</pre> 26234</div> 26235</div> 26236<table class="tableblock frame-all grid-all spread"> 26237<caption class="title">
26237Table 184. Get historic task instances - URL parameters</caption> 26238<colgroup> 26239<col style="width: 25%;"> 26240<col style="width: 25%;"> 26241<col style="width: 25%;"> 26242<col style="width: 25%;"> 26243</colgroup> 26244<thead> 26245<tr> 26246<th class="tableblock halign-left valign-top">Parameter</th> 26247<th class="tableblock halign-left valign-top">Required</th> 26248<th class="tableblock halign-left valign-top">Value</th> 26249<th class="tableblock halign-left valign-top">Description</th> 26250</tr> 26251</thead> 26252<tbody> 26253<tr> 26254<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 26255<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26256<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26257<td class="tableblock halign-left valign-top"><p class="tableblock">An id of the historic task instance.</p></td> 26258</tr> 26259<tr> 26260<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 26261<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26262<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26263<td class="tableblock halign-left valign-top"><p class="tableblock">The process instance id of the historic task instance.</p></td> 26264</tr> 26265<tr> 26266<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKey</p></td> 26267<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26268<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26269<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition key of the historic task instance.</p></td> 26270</tr> 26271<tr> 26272<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionKeyLike</p></td> 26273<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26274<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26275<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition key of the historic task instance, which matches the given value.</p></td> 26276</tr> 26277<tr> 26278<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 26279<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26280<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26281<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition id of the historic task instance.</p></td> 26282</tr> 26283<tr> 26284<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionName</p></td> 26285<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26286<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26287<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition name of the historic task instance.</p></td> 26288</tr> 26289<tr> 26290<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionNameLike</p></td> 26291<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26292<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26293<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition name of the historic task instance, which matches the given value.</p></td> 26294</tr> 26295<tr> 26296<td class="tableblock halign-left valign-top"><p class="tableblock">processBusinessKey</p></td> 26297<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26298<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26299<td class="tableblock halign-left valign-top"><p class="tableblock">The process instance business key of the historic task instance.</p></td> 26300</tr> 26301<tr> 26302<td class="tableblock halign-left valign-top"><p class="tableblock">processBusinessKeyLike</p></td> 26303<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26304<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26305<td class="tableblock halign-left valign-top"><p class="tableblock">The process instance business key of the historic task instance that matches the given value.</p></td> 26306</tr> 26307<tr> 26308<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 26309<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26310<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26311<td class="tableblock halign-left valign-top"><p class="tableblock">The execution id of the historic task instance.</p></td> 26312</tr> 26313<tr> 26314<td class="tableblock halign-left valign-top"><p class="tableblock">taskDefinitionKey</p></td> 26315<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26316<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26317<td class="tableblock halign-left valign-top"><p class="tableblock">The task definition key for tasks part of a process</p></td> 26318</tr> 26319<tr> 26320<td class="tableblock halign-left valign-top"><p class="tableblock">taskName</p></td> 26321<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26322<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26323<td class="tableblock halign-left valign-top"><p class="tableblock">The task name of the historic task instance.</p></td> 26324</tr> 26325<tr> 26326<td class="tableblock halign-left valign-top"><p class="tableblock">taskNameLike</p></td> 26327<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26328<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26329<td class="tableblock halign-left valign-top"><p class="tableblock">The task name with <em>like</em> operator for the historic task instance.</p></td> 26330</tr> 26331<tr> 26332<td class="tableblock halign-left valign-top"><p class="tableblock">taskDescription</p></td> 26333<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26334<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26335<td class="tableblock halign-left valign-top"><p class="tableblock">The task description of the historic task instance.</p></td> 26336</tr> 26337<tr> 26338<td class="tableblock halign-left valign-top"><p class="tableblock">taskDescriptionLike</p></td> 26339<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26340<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26341<td class="tableblock halign-left valign-top"><p class="tableblock">The task description with <em>like</em> operator for the historic task instance.</p></td> 26342</tr> 26343<tr> 26344<td class="tableblock halign-left valign-top"><p class="tableblock">taskDefinitionKey</p></td> 26345<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26346<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26347<td class="tableblock halign-left valign-top"><p class="tableblock">The task identifier from the process definition for the historic task instance.</p></td> 26348</tr> 26349<tr> 26350<td class="tableblock halign-left valign-top"><p class="tableblock">taskCategory</p></td> 26351<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26352<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26353<td class="tableblock halign-left valign-top"><p class="tableblock">Select tasks with the given category. Note that this is the task category, not the category of the process definition (namespace within the BPMN Xml).</p></td> 26354</tr> 26355<tr> 26356<td class="tableblock halign-left valign-top"><p class="tableblock">taskDeleteReason</p></td> 26357<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26358<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26359<td class="tableblock halign-left valign-top"><p class="tableblock">The task delete reason of the historic task instance.</p></td> 26360</tr> 26361<tr> 26362<td class="tableblock halign-left valign-top"><p class="tableblock">taskDeleteReasonLike</p></td> 26363<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26364<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26365<td class="tableblock halign-left valign-top"><p class="tableblock">The task delete reason with <em>like</em> operator for the historic task instance.</p></td> 26366</tr> 26367<tr> 26368<td class="tableblock halign-left valign-top"><p class="tableblock">taskAssignee</p></td> 26369<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26370<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26371<td class="tableblock halign-left valign-top"><p class="tableblock">The assignee of the historic task instance.</p></td> 26372</tr> 26373<tr> 26374<td class="tableblock halign-left valign-top"><p class="tableblock">taskAssigneeLike</p></td> 26375<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26376<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26377<td class="tableblock halign-left valign-top"><p class="tableblock">The assignee with <em>like</em> operator for the historic task instance.</p></td> 26378</tr> 26379<tr> 26380<td class="tableblock halign-left valign-top"><p class="tableblock">taskOwner</p></td> 26381<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26382<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26383<td class="tableblock halign-left valign-top"><p class="tableblock">The owner of the historic task instance.</p></td> 26384</tr> 26385<tr> 26386<td class="tableblock halign-left valign-top"><p class="tableblock">taskOwnerLike</p></td> 26387<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26388<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26389<td class="tableblock halign-left valign-top"><p class="tableblock">The owner with <em>like</em> operator for the historic task instance.</p></td> 26390</tr> 26391<tr> 26392<td class="tableblock halign-left valign-top"><p class="tableblock">taskInvolvedUser</p></td> 26393<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26394<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26395<td class="tableblock halign-left valign-top"><p class="tableblock">An involved user of the historic task instance.</p></td> 26396</tr> 26397<tr> 26398<td class="tableblock halign-left valign-top"><p class="tableblock">taskPriority</p></td> 26399<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26400<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26401<td class="tableblock halign-left valign-top"><p class="tableblock">The priority of the historic task instance.</p></td> 26402</tr> 26403<tr> 26404<td class="tableblock halign-left valign-top"><p class="tableblock">finished</p></td> 26405<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26406<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26407<td class="tableblock halign-left valign-top"><p class="tableblock">
26407Indication if the historic task instance is finished.</p></td> 26408</tr> 26409<tr> 26410<td class="tableblock halign-left valign-top"><p class="tableblock">processFinished</p></td> 26411<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26412<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26413<td class="tableblock halign-left valign-top"><p class="tableblock">Indication if the process instance of the historic task instance is finished.</p></td> 26414</tr> 26415<tr> 26416<td class="tableblock halign-left valign-top"><p class="tableblock">parentTaskId</p></td> 26417<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26418<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26419<td class="tableblock halign-left valign-top"><p class="tableblock">An optional parent task id of the historic task instance.</p></td> 26420</tr> 26421<tr> 26422<td class="tableblock halign-left valign-top"><p class="tableblock">dueDate</p></td> 26423<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26424<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26425<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have a due date equal this date.</p></td> 26426</tr> 26427<tr> 26428<td class="tableblock halign-left valign-top"><p class="tableblock">dueDateAfter</p></td> 26429<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26430<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26431<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have a due date after this date.</p></td> 26432</tr> 26433<tr> 26434<td class="tableblock halign-left valign-top"><p class="tableblock">dueDateBefore</p></td> 26435<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26436<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26437<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have a due date before this date.</p></td> 26438</tr> 26439<tr> 26440<td class="tableblock halign-left valign-top"><p class="tableblock">withoutDueDate</p></td> 26441<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26442<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26443<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have no due-date. When <code>false</code> is provided as value, this parameter is ignored.</p></td> 26444</tr> 26445<tr> 26446<td class="tableblock halign-left valign-top"><p class="tableblock">taskCompletedOn</p></td> 26447<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26448<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26449<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have been completed on this date.</p></td> 26450</tr> 26451<tr> 26452<td class="tableblock halign-left valign-top"><p class="tableblock">taskCompletedAfter</p></td> 26453<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26454<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26455<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have been completed after this date.</p></td> 26456</tr> 26457<tr> 26458<td class="tableblock halign-left valign-top"><p class="tableblock">taskCompletedBefore</p></td> 26459<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26460<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26461<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that have been completed before this date.</p></td> 26462</tr> 26463<tr> 26464<td class="tableblock halign-left valign-top"><p class="tableblock">taskCreatedOn</p></td> 26465<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26466<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26467<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that were created on this date.</p></td> 26468</tr> 26469<tr> 26470<td class="tableblock halign-left valign-top"><p class="tableblock">taskCreatedBefore</p></td> 26471<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26472<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26473<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that were created before this date.</p></td> 26474</tr> 26475<tr> 26476<td class="tableblock halign-left valign-top"><p class="tableblock">taskCreatedAfter</p></td> 26477<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26478<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 26479<td class="tableblock halign-left valign-top"><p class="tableblock">Return only historic task instances that were created after this date.</p></td> 26480</tr> 26481<tr> 26482<td class="tableblock halign-left valign-top"><p class="tableblock">includeTaskLocalVariables</p></td> 26483<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26484<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26485<td class="tableblock halign-left valign-top"><p class="tableblock">An indication if the historic task instance local variables should be returned as well.</p></td> 26486</tr> 26487<tr> 26488<td class="tableblock halign-left valign-top"><p class="tableblock">includeProcessVariables</p></td> 26489<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26490<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26491<td class="tableblock halign-left valign-top"><p class="tableblock">An indication if the historic task instance global variables should be returned as well.</p></td> 26492</tr> 26493<tr> 26494<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 26495<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26496<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26497<td class="tableblock halign-left valign-top"><p class="tableblock">Only return historic task instances with the given tenantId.</p></td> 26498</tr> 26499<tr> 26500<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 26501<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26502<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26503<td class="tableblock halign-left valign-top"><p class="tableblock">Only return historic task instances with a tenantId like the given value.</p></td> 26504</tr> 26505<tr> 26506<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 26507<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26508<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26509<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns historic task instances without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 26510</tr> 26511</tbody> 26512</table> 26513<table class="tableblock frame-all grid-all spread"> 26514<caption class="title">Table 185. Get historic task instances - Response codes</caption> 26515<colgroup> 26516<col style="width: 50%;"> 26517<col style="width: 50%;"> 26518</colgroup> 26519<thead> 26520<tr> 26521<th class="tableblock halign-left valign-top">Response code</th> 26522<th class="tableblock halign-left valign-top">Description</th> 26523</tr> 26524</thead> 26525<tbody> 26526<tr> 26527<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26528<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that historic process instances could be queried.</p></td> 26529</tr> 26530<tr> 26531<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 26532<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 26533</tr> 26534</tbody> 26535</table> 26536<div class="paragraph"> 26537<p><strong>Success response body:</strong></p> 26538</div> 26539<div class="listingblock"> 26540<div class="content"> 26541<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 26542 2 26543 3 26544 4 26545 5 26546 6 26547 7 26548 8 26549 9 2655010 2655111 2655212 2655313 2655414 2655515 2655616 2655717 2655818 2655919 2656020 2656121 2656222 2656323 2656424 2656525 2656626 2656727 2656828 2656929 2657030 2657131 2657232 2657333 2657434 2657535 2657636 2657737 2657838 2657939 2658040 2658141 2658242 2658343 2658444 2658545 2658646 2658747 2658848</div></td><td class="code"><span></span><span class="tok-p">{</span> 26589 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 26590 <span class="tok-p">{</span>
26591 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 26592 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26593 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26594 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 26595 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/3"</span><span class="tok-p">,</span> 26596 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 26597 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task name"</span><span class="tok-p">,</span> 26598 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task description"</span><span class="tok-p">,</span> 26599 <span class="tok-nt">"deleteReason"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26600 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 26601 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"fozzie"</span><span class="tok-p">,</span> 26602 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 26603 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 26604 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 26605 <span class="tok-nt">"workTimeInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">234890</span><span class="tok-p">,</span> 26606 <span class="tok-nt">"claimTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T11:01:54.715+0000"</span><span class="tok-p">,</span> 26607 <span class="tok-nt">"taskDefinitionKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"taskKey"</span><span class="tok-p">,</span> 26608 <span class="tok-nt">"formKey"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26609 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">50</span><span class="tok-p">,</span> 26610 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-20T12:11:13.134+0000"</span><span class="tok-p">,</span> 26611 <span class="tok-nt">"parentTaskId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26612 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-task-instances/5"</span><span class="tok-p">,</span> 26613 <span class="tok-nt">"taskVariables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 26614 <span class="tok-p">{</span> 26615 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"test"</span><span class="tok-p">,</span> 26616 <span class="tok-nt">"variableScope"</span><span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span>
26617 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"myTest"</span> 26618 <span class="tok-p">}</span> 26619 <span class="tok-p">],</span> 26620 <span class="tok-nt">"processVariables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 26621 <span class="tok-p">{</span> 26622 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"processTest"</span><span class="tok-p">,</span> 26623 <span class="tok-nt">"variableScope"</span><span class="tok-p">:</span> <span class="tok-s2">"global"</span><span class="tok-p">,</span> 26624 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"myProcessTest"</span> 26625 <span class="tok-p">}</span> 26626 <span class="tok-p">],</span> 26627 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 26628 <span class="tok-p">}</span> 26629 <span class="tok-p">],</span> 26630 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 26631 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 26632 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 26633 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 26634 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 26635<span class="tok-p">}</span> 26636</td></tr></table></code></pre> 26637</div> 26638</div> 26639</div> 26640<div class="sect3"> 26641<h4 id="_query_for_historic_task_instances">13.8.13. Query for historic task instances</h4> 26642<div class="listingblock"> 26643<div class="content"> 26644<pre>POST query/historic-task-instances</pre> 26645</div> 26646</div> 26647<div class="paragraph"> 26648<p><strong>Query for historic task instances - Request body:</strong></p> 26649</div> 26650<div class="listingblock"> 26651<div class="content"> 26652<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 26653 2 26654 3 26655 4 26656 5 26657 6 26658 7 26659 8 26660 9 2666110 2666211 2666312 2666413</div></td><td class="code"><span></span><span class="tok-p">{</span> 26665 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26666 <span class="tok-err">...</span> 26667 26668 <span class="tok-nt">"variables"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 26669 <span class="tok-p">{</span> 26670 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 26671 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mi">1234</span><span class="tok-p">,</span> 26672 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 26673 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"long"</span> 26674 <span class="tok-p">}</span> 26675 <span class="tok-p">]</span> 26676<span class="tok-p">}</span> 26677</td></tr></table></code></pre> 26678</div> 26679</div> 26680<div class="paragraph"> 26681<p>All supported JSON parameter fields allowed are exactly the same as the parameters found for <a href="#restHistoricTaskInstancesGet">getting a collection of historic task instances</a>, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri’s that are too long. On top of that, the query allows for filtering based on process variables. The <code>taskVariables</code> and <code>processVariables</code> properties are JSON-arrays containing objects with the format <a href="#restQueryVariable">as described here.</a></p> 26682</div> 26683<table class="tableblock frame-all grid-all spread"> 26684<caption class="title">Table 186. Query for historic task instances - Response codes</caption> 26685<colgroup> 26686<col style="width: 50%;"> 26687<col style="width: 50%;"> 26688</colgroup> 26689<thead> 26690<tr> 26691<th class="tableblock halign-left valign-top">Response code</th> 26692<th class="tableblock halign-left valign-top">Description</th> 26693</tr> 26694</thead> 26695<tbody> 26696<tr> 26697<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26698<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the tasks are returned</p></td> 26699</tr> 26700<tr> 26701<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 26702<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 26703</tr> 26704</tbody> 26705</table> 26706<div class="paragraph"> 26707<p><strong>Success response body:</strong></p> 26708</div> 26709<div class="listingblock"> 26710<div class="content"> 26711<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 26712 2 26713 3 26714 4 26715 5 26716 6 26717 7 26718 8 26719 9 2672010 2672111 2672212 2672313 2672414 2672515 2672616 2672717 2672818 2672919 2673020 2673121 2673222 2673323 2673424 2673525 2673626 2673727 2673828 2673929 2674030 2674131 2674232 2674333 2674434 2674535 2674636 2674737 2674838 2674939 2675040 2675141 2675242 2675343 2675444 2675545 2675646 2675747 2675848</div></td><td class="code"><span></span><span class="tok-p">{</span> 26759 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 26760 <span class="tok-p">{</span>
26761 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 26762 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26763 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 26764 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 26765 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/3"</span><span class="tok-p">,</span> 26766 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 26767 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task name"</span><span class="tok-p">,</span> 26768 <span class="tok-nt">"description"</span> <span class="tok-p">:</span> <span class="tok-s2">"My task description"</span><span class="tok-p">,</span> 26769 <span class="tok-nt">"deleteReason"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26770 <span class="tok-nt">"owner"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 26771 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"fozzie"</span><span class="tok-p">,</span> 26772 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 26773 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 26774 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 26775 <span class="tok-nt">"workTimeInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">234890</span><span class="tok-p">,</span> 26776 <span class="tok-nt">"claimTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T11:01:54.715+0000"</span><span class="tok-p">,</span> 26777 <span class="tok-nt">"taskDefinitionKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"taskKey"</span><span class="tok-p">,</span> 26778 <span class="tok-nt">"formKey"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26779 <span class="tok-nt">"priority"</span> <span class="tok-p">:</span> <span class="tok-mi">50</span><span class="tok-p">,</span> 26780 <span class="tok-nt">"dueDate"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-20T12:11:13.134+0000"</span><span class="tok-p">,</span> 26781 <span class="tok-nt">"parentTaskId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26782 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-task-instances/5"</span><span class="tok-p">,</span> 26783 <span class="tok-nt">"taskVariables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 26784 <span class="tok-p">{</span> 26785 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"test"</span><span class="tok-p">,</span> 26786 <span class="tok-nt">"variableScope"</span><span class="tok-p">:</span> <span class="tok-s2">"local"</span><span class="tok-p">,</span>
26787 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"myTest"</span> 26788 <span class="tok-p">}</span> 26789 <span class="tok-p">],</span> 26790 <span class="tok-nt">"processVariables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 26791 <span class="tok-p">{</span> 26792 <span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"processTest"</span><span class="tok-p">,</span> 26793 <span class="tok-nt">"variableScope"</span><span class="tok-p">:</span> <span class="tok-s2">"global"</span><span class="tok-p">,</span> 26794 <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"myProcessTest"</span> 26795 <span class="tok-p">}</span> 26796 <span class="tok-p">],</span> 26797 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 26798 <span class="tok-p">}</span> 26799 <span class="tok-p">],</span> 26800 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 26801 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 26802 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 26803 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 26804 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 26805<span class="tok-p">}</span> 26806</td></tr></table></code></pre> 26807</div> 26808</div> 26809</div> 26810<div class="sect3"> 26811<h4 id="_delete_a_historic_task_instance">13.8.14. Delete a historic task instance</h4> 26812<div class="listingblock"> 26813<div class="content"> 26814<pre>DELETE history/historic-task-instances/{taskId}</pre> 26815</div> 26816</div> 26817<table class="tableblock frame-all grid-all spread"> 26818<caption class="title">Table 187. Response codes</caption> 26819<colgroup> 26820<col style="width: 50%;"> 26821<col style="width: 50%;"> 26822</colgroup> 26823<thead> 26824<tr> 26825<th class="tableblock halign-left valign-top">Response code</th> 26826<th class="tableblock halign-left valign-top">Description</th> 26827</tr> 26828</thead> 26829<tbody> 26830<tr> 26831<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26832<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic task instance was deleted.</p></td> 26833</tr> 26834<tr> 26835<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 26836<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that the historic task instance could not be found.</p></td> 26837</tr> 26838</tbody> 26839</table> 26840</div> 26841<div class="sect3"> 26842<h4 id="_get_the_identity_links_of_a_historic_task_instance">13.8.15. Get the identity links of a historic task instance</h4> 26843<div class="listingblock"> 26844<div class="content"> 26845<pre>GET history/historic-task-instance/{taskId}/identitylinks</pre> 26846</div> 26847</div> 26848<table class="tableblock frame-all grid-all spread"> 26849<caption class="title">Table 188. Response codes</caption> 26850<colgroup> 26851<col style="width: 50%;"> 26852<col style="width: 50%;"> 26853</colgroup> 26854<thead> 26855<tr> 26856<th class="tableblock halign-left valign-top">Response code</th> 26857<th class="tableblock halign-left valign-top">Description</th> 26858</tr> 26859</thead> 26860<tbody> 26861<tr> 26862<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26863<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the identity links are returned</p></td> 26864</tr> 26865<tr> 26866<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 26867<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task instance could not be found.</p></td> 26868</tr> 26869</tbody> 26870</table> 26871<div class="paragraph"> 26872<p><strong>Success response body:</strong></p> 26873</div> 26874<div class="listingblock"> 26875<div class="content"> 26876<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 26877 2 26878 3 26879 4 26880 5 26881 6 26882 7 26883 8 26884 9 2688510 2688611</div></td><td class="code"><span></span><span class="tok-p">[</span> 26887 <span class="tok-p">{</span> 26888 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"assignee"</span><span class="tok-p">,</span> 26889 <span class="tok-nt">"userId"</span> <span class="tok-p">:</span> <span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 26890 <span class="tok-nt">"groupId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26891 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 26892 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-task-instances/5"</span><span class="tok-p">,</span> 26893 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 26894 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 26895 <span class="tok-p">}</span> 26896<span class="tok-p">]</span> 26897</td></tr></table></code></pre> 26898</div> 26899</div> 26900</div> 26901<div class="sect3"> 26902<h4 id="_get_the_binary_data_for_a_historic_task_instance_variable">13.8.16. Get the binary data for a historic task instance variable</h4> 26903<div class="listingblock"> 26904<div class="content"> 26905<pre>GET history/historic-task-instances/{taskId}/variables/{variableName}/data</pre> 26906</div> 26907</div> 26908<table class="tableblock frame-all grid-all spread"> 26909<caption class="title">Table 189. Get the binary data for a historic task instance variable - Response codes</caption> 26910<colgroup> 26911<col style="width: 50%;"> 26912<col style="width: 50%;"> 26913</colgroup> 26914<thead> 26915<tr> 26916<th class="tableblock halign-left valign-top">Response code</th> 26917<th class="tableblock halign-left valign-top">Description</th> 26918</tr> 26919</thead> 26920<tbody> 26921<tr> 26922<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 26923<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the task instance was found and the requested variable data is returned.</p></td> 26924</tr> 26925<tr> 26926<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 26927<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested task instance was not found or the process instance doesn’t have a variable with the given name or the variable doesn’t have a binary stream available. Status message provides additional information.</p></td> 26928</tr> 26929</tbody> 26930</table> 26931<div class="paragraph"> 26932<p><strong>Success response body:</strong></p> 26933</div> 26934<div class="paragraph"> 26935<p>The response body contains the binary value of the variable. When the variable is of type <code>binary</code>, the content-type of the response is set to <code>application/octet-stream</code>, regardless of the content of the variable or the request accept-type header. In case of <code>serializable</code>, <code>application/x-java-serialized-object</code> is used as content-type.</p> 26936</div> 26937</div> 26938<div class="sect3"> 26939<h4 id="restHistoricActivityInstancesGet">13.8.17. Get historic activity instances</h4> 26940<div class="listingblock"> 26941<div class="content"> 26942<pre>GET history/historic-activity-instances</pre> 26943</div> 26944</div> 26945<table class="tableblock frame-all grid-all spread"> 26946<caption class="title">
26946Table 190. Get historic activity instances - URL parameters</caption> 26947<colgroup> 26948<col style="width: 25%;"> 26949<col style="width: 25%;"> 26950<col style="width: 25%;"> 26951<col style="width: 25%;"> 26952</colgroup> 26953<thead> 26954<tr> 26955<th class="tableblock halign-left valign-top">Parameter</th> 26956<th class="tableblock halign-left valign-top">Required</th> 26957<th class="tableblock halign-left valign-top">Value</th> 26958<th class="tableblock halign-left valign-top">Description</th> 26959</tr> 26960</thead> 26961<tbody> 26962<tr> 26963<td class="tableblock halign-left valign-top"><p class="tableblock">activityId</p></td> 26964<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26965<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26966<td class="tableblock halign-left valign-top"><p class="tableblock">An id of the activity instance.</p></td> 26967</tr> 26968<tr> 26969<td class="tableblock halign-left valign-top"><p class="tableblock">activityInstanceId</p></td> 26970<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26971<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26972<td class="tableblock halign-left valign-top"><p class="tableblock">An id of the historic activity instance.</p></td> 26973</tr> 26974<tr> 26975<td class="tableblock halign-left valign-top"><p class="tableblock">activityName</p></td> 26976<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26977<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26978<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the historic activity instance.</p></td> 26979</tr> 26980<tr> 26981<td class="tableblock halign-left valign-top"><p class="tableblock">activityType</p></td> 26982<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26983<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26984<td class="tableblock halign-left valign-top"><p class="tableblock">The element type of the historic activity instance.</p></td> 26985</tr> 26986<tr> 26987<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 26988<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26989<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 26990<td class="tableblock halign-left valign-top"><p class="tableblock">The execution id of the historic activity instance.</p></td> 26991</tr> 26992<tr> 26993<td class="tableblock halign-left valign-top"><p class="tableblock">finished</p></td> 26994<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 26995<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 26996<td class="tableblock halign-left valign-top"><p class="tableblock">Indication if the historic activity instance is finished.</p></td> 26997</tr> 26998<tr> 26999<td class="tableblock halign-left valign-top"><p class="tableblock">taskAssignee</p></td> 27000<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27001<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27002<td class="tableblock halign-left valign-top"><p class="tableblock">The assignee of the historic activity instance.</p></td> 27003</tr> 27004<tr> 27005<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 27006<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27007<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27008<td class="tableblock halign-left valign-top"><p class="tableblock">The process instance id of the historic activity instance.</p></td> 27009</tr> 27010<tr> 27011<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 27012<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27013<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27014<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition id of the historic activity instance.</p></td> 27015</tr> 27016<tr> 27017<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 27018<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27019<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27020<td class="tableblock halign-left valign-top"><p class="tableblock">Only return instances with the given tenantId.</p></td> 27021</tr> 27022<tr> 27023<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 27024<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27025<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27026<td class="tableblock halign-left valign-top"><p class="tableblock">Only return instances with a tenantId like the given value.</p></td> 27027</tr> 27028<tr> 27029<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 27030<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27031<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 27032<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns instances without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 27033</tr> 27034</tbody> 27035</table> 27036<table class="tableblock frame-all grid-all spread"> 27037<caption class="title">Table 191. Get historic activity instances - Response codes</caption> 27038<colgroup> 27039<col style="width: 50%;"> 27040<col style="width: 50%;"> 27041</colgroup> 27042<thead> 27043<tr> 27044<th class="tableblock halign-left valign-top">Response code</th> 27045<th class="tableblock halign-left valign-top">Description</th> 27046</tr> 27047</thead> 27048<tbody> 27049<tr> 27050<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27051<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that historic activity instances could be queried.</p></td> 27052</tr> 27053<tr> 27054<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 27055<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 27056</tr> 27057</tbody> 27058</table> 27059<div class="paragraph"> 27060<p><strong>Success response body:</strong></p> 27061</div> 27062<div class="listingblock"> 27063<div class="content"> 27064<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27065 2 27066 3 27067 4 27068 5 27069 6 27070 7 27071 8 27072 9 2707310 2707411 2707512 2707613 2707714 2707815 2707916 2708017 2708118 2708219 2708320 2708421 2708522 2708623 2708724 2708825 2708926 2709027</div></td><td class="code"><span></span><span class="tok-p">{</span> 27091 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27092 <span class="tok-p">{</span>
27093 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27094 <span class="tok-nt">"activityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 27095 <span class="tok-nt">"activityName"</span> <span class="tok-p">:</span> <span class="tok-s2">"My user task"</span><span class="tok-p">,</span> 27096 <span class="tok-nt">"activityType"</span> <span class="tok-p">:</span> <span class="tok-s2">"userTask"</span><span class="tok-p">,</span> 27097 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 27098 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 27099 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 27100 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/3"</span><span class="tok-p">,</span> 27101 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 27102 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 27103 <span class="tok-nt">"calledProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27104 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"fozzie"</span><span class="tok-p">,</span> 27105 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 27106 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 27107 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 27108 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 27109 <span class="tok-p">}</span> 27110 <span class="tok-p">],</span> 27111 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27112 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27113 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27114 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27115 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27116<span class="tok-p">}</span> 27117</td></tr></table></code></pre> 27118</div> 27119</div> 27120</div> 27121<div class="sect3"> 27122<h4 id="_query_for_historic_activity_instances">13.8.18. Query for historic activity instances</h4> 27123<div class="listingblock"> 27124<div class="content"> 27125<pre>POST query/historic-activity-instances</pre> 27126</div> 27127</div> 27128<div class="paragraph"> 27129<p><strong>Request body:</strong></p> 27130</div> 27131<div class="listingblock"> 27132<div class="content"> 27133<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 271342 271353</div></td><td class="code"><span></span><span class="tok-p">{</span> 27136 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span> 27137<span class="tok-p">}</span> 27138</td></tr></table></code></pre> 27139</div> 27140</div> 27141<div class="paragraph"> 27142<p>All supported JSON parameter fields allowed are exactly the same as the parameters found for <a href="#restHistoricTaskInstancesGet">getting a collection of historic task instances</a>, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri’s that are too long.</p> 27143</div> 27144<table class="tableblock frame-all grid-all spread"> 27145<caption class="title">Table 192. Query for historic activity instances - Response codes</caption> 27146<colgroup> 27147<col style="width: 50%;"> 27148<col style="width: 50%;"> 27149</colgroup> 27150<thead> 27151<tr> 27152<th class="tableblock halign-left valign-top">Response code</th> 27153<th class="tableblock halign-left valign-top">Description</th> 27154</tr> 27155</thead> 27156<tbody> 27157<tr> 27158<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27159<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the activities are returned</p></td> 27160</tr> 27161<tr> 27162<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 27163<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 27164</tr> 27165</tbody> 27166</table> 27167<div class="paragraph"> 27168<p><strong>Success response body:</strong></p> 27169</div> 27170<div class="listingblock"> 27171<div class="content"> 27172<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27173 2 27174 3 27175 4 27176 5 27177 6 27178 7 27179 8 27180 9 2718110 2718211 2718312 2718413 2718514 2718615 2718716 2718817 2718918 2719019 2719120 2719221 2719322 2719423 2719524 2719625 2719726 2719827</div></td><td class="code"><span></span><span class="tok-p">{</span> 27199 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27200 <span class="tok-p">{</span>
27201 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27202 <span class="tok-nt">"activityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 27203 <span class="tok-nt">"activityName"</span> <span class="tok-p">:</span> <span class="tok-s2">"My user task"</span><span class="tok-p">,</span> 27204 <span class="tok-nt">"activityType"</span> <span class="tok-p">:</span> <span class="tok-s2">"userTask"</span><span class="tok-p">,</span> 27205 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 27206 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 27207 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 27208 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/3"</span><span class="tok-p">,</span> 27209 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 27210 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"4"</span><span class="tok-p">,</span> 27211 <span class="tok-nt">"calledProcessInstanceId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27212 <span class="tok-nt">"assignee"</span> <span class="tok-p">:</span> <span class="tok-s2">"fozzie"</span><span class="tok-p">,</span> 27213 <span class="tok-nt">"startTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 27214 <span class="tok-nt">"endTime"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-18T14:06:32.715+0000"</span><span class="tok-p">,</span> 27215 <span class="tok-nt">"durationInMillis"</span> <span class="tok-p">:</span> <span class="tok-mi">86400056</span><span class="tok-p">,</span> 27216 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 27217 <span class="tok-p">}</span> 27218 <span class="tok-p">],</span> 27219 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27220 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27221 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27222 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27223 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27224<span class="tok-p">}</span> 27225</td></tr></table></code></pre> 27226</div> 27227</div> 27228</div> 27229<div class="sect3"> 27230<h4 id="restHistoricVariableInstancesGet">13.8.19. List of historic variable instances</h4> 27231<div class="listingblock"> 27232<div class="content"> 27233<pre>GET history/historic-variable-instances</pre> 27234</div> 27235</div> 27236<table class="tableblock frame-all grid-all spread"> 27237<caption class="title">Table 193. List of historic variable instances - URL parameters</caption> 27238<colgroup> 27239<col style="width: 25%;"> 27240<col style="width: 25%;"> 27241<col style="width: 25%;"> 27242<col style="width: 25%;"> 27243</colgroup> 27244<thead> 27245<tr> 27246<th class="tableblock halign-left valign-top">Parameter</th> 27247<th class="tableblock halign-left valign-top">Required</th> 27248<th class="tableblock halign-left valign-top">Value</th> 27249<th class="tableblock halign-left valign-top">Description</th> 27250</tr> 27251</thead> 27252<tbody> 27253<tr> 27254<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 27255<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27256<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27257<td class="tableblock halign-left valign-top"><p class="tableblock">The process instance id of the historic variable instance.</p></td> 27258</tr> 27259<tr> 27260<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 27261<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27262<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27263<td class="tableblock halign-left valign-top"><p class="tableblock">The task id of the historic variable instance.</p></td> 27264</tr> 27265<tr> 27266<td class="tableblock halign-left valign-top"><p class="tableblock">excludeTaskVariables</p></td> 27267<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27268<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 27269<td class="tableblock halign-left valign-top"><p class="tableblock">Indication to exclude the task variables from the result.</p></td> 27270</tr> 27271<tr> 27272<td class="tableblock halign-left valign-top"><p class="tableblock">variableName</p></td> 27273<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27274<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27275<td class="tableblock halign-left valign-top"><p class="tableblock">The variable name of the historic variable instance.</p></td> 27276</tr> 27277<tr> 27278<td class="tableblock halign-left valign-top"><p class="tableblock">variableNameLike</p></td> 27279<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27280<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27281<td class="tableblock halign-left valign-top"><p class="tableblock">The variable name using the <em>like</em> operator for the historic variable instance.</p></td> 27282</tr> 27283</tbody> 27284</table> 27285<table class="tableblock frame-all grid-all spread"> 27286<caption class="title">Table 194. List of historic variable instances - Response codes</caption> 27287<colgroup> 27288<col style="width: 50%;"> 27289<col style="width: 50%;"> 27290</colgroup> 27291<thead> 27292<tr> 27293<th class="tableblock halign-left valign-top">Response code</th> 27294<th class="tableblock halign-left valign-top">Description</th> 27295</tr> 27296</thead> 27297<tbody> 27298<tr> 27299<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27300<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that historic variable instances could be queried.</p></td> 27301</tr> 27302<tr> 27303<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 27304<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 27305</tr> 27306</tbody> 27307</table> 27308<div class="paragraph"> 27309<p><strong>Success response body:</strong></p> 27310</div> 27311<div class="listingblock"> 27312<div class="content"> 27313<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27314 2 27315 3 27316 4 27317 5 27318 6 27319 7 27320 8 27321 9 2732210 2732311 2732412 2732513 2732614 2732715 2732816 2732917 2733018 2733119 2733220</div></td><td class="code"><span></span><span class="tok-p">{</span> 27333 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27334 <span class="tok-p">{</span>
27335 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"14"</span><span class="tok-p">,</span> 27336 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27337 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 27338 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27339 <span class="tok-nt">"variable"</span> <span class="tok-p">:</span> <span class="tok-p">{</span> 27340 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 27341 <span class="tok-nt">"variableScope"</span><span class="tok-p">,</span> <span class="tok-nt">"global"</span><span class="tok-p">,</span> 27342 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"test"</span> 27343 <span class="tok-p">}</span> 27344 <span class="tok-p">}</span> 27345 <span class="tok-p">],</span> 27346 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27347 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27348 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27349 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27350 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27351<span class="tok-p">}</span> 27352</td></tr></table></code></pre> 27353</div> 27354</div> 27355</div> 27356<div class="sect3"> 27357<h4 id="_query_for_historic_variable_instances">13.8.20. Query for historic variable instances</h4> 27358<div class="listingblock"> 27359<div class="content"> 27360<pre>POST query/historic-variable-instances</pre> 27361</div> 27362</div> 27363<div class="paragraph"> 27364<p><strong>Request body:</strong></p> 27365</div> 27366<div class="listingblock"> 27367<div class="content"> 27368<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27369 2 27370 3 27371 4 27372 5 27373 6 27374 7 27375 8 27376 9 2737710 2737811 2737912 2738013</div></td><td class="code"><span></span><span class="tok-p">{</span> 27381 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"oneTaskProcess%3A1%3A4"</span><span class="tok-p">,</span> 27382 <span class="tok-err">...</span> 27383 27384 <span class="tok-nt">"variables"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 27385 <span class="tok-p">{</span> 27386 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 27387 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-mi">1234</span><span class="tok-p">,</span> 27388 <span class="tok-nt">"operation"</span> <span class="tok-p">:</span> <span class="tok-s2">"equals"</span><span class="tok-p">,</span> 27389 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"long"</span> 27390 <span class="tok-p">}</span> 27391 <span class="tok-p">]</span> 27392<span class="tok-p">}</span> 27393</td></tr></table></code></pre> 27394</div> 27395</div> 27396<div class="paragraph"> 27397<p>All supported JSON parameter fields allowed are exactly the same as the parameters found for <a href="#restHistoricVariableInstancesGet">getting a collection of historic process instances</a>, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri’s that are too long. On top of that, the query allows for filtering based on process variables. The <code>variables</code> property is a JSON-array containing objects with the format <a href="#restQueryVariable">as described here.</a></p> 27398</div> 27399<table class="tableblock frame-all grid-all spread"> 27400<caption class="title">Table 195. Query for historic variable instances - Response codes</caption> 27401<colgroup> 27402<col style="width: 50%;"> 27403<col style="width: 50%;"> 27404</colgroup> 27405<thead> 27406<tr> 27407<th class="tableblock halign-left valign-top">Response code</th> 27408<th class="tableblock halign-left valign-top">Description</th> 27409</tr> 27410</thead> 27411<tbody> 27412<tr> 27413<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27414<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the tasks are returned</p></td> 27415</tr> 27416<tr> 27417<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 27418<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 27419</tr> 27420</tbody> 27421</table> 27422<div class="paragraph"> 27423<p><strong>Success response body:</strong></p> 27424</div> 27425<div class="listingblock"> 27426<div class="content"> 27427<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27428 2 27429 3 27430 4 27431 5 27432 6 27433 7 27434 8 27435 9 2743610 2743711 2743812 2743913 2744014 2744115 2744216 2744317 2744418 2744519 2744620</div></td><td class="code"><span></span><span class="tok-p">{</span> 27447 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27448 <span class="tok-p">{</span>
27449 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"14"</span><span class="tok-p">,</span> 27450 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27451 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 27452 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27453 <span class="tok-nt">"variable"</span> <span class="tok-p">:</span> <span class="tok-p">{</span> 27454 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 27455 <span class="tok-nt">"variableScope"</span><span class="tok-p">,</span> <span class="tok-nt">"global"</span><span class="tok-p">,</span> 27456 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"test"</span> 27457 <span class="tok-p">}</span> 27458 <span class="tok-p">}</span> 27459 <span class="tok-p">],</span> 27460 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27461 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27462 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27463 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27464 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27465<span class="tok-p">}</span> 27466</td></tr></table></code></pre> 27467</div> 27468</div> 27469<div class="paragraph"> 27470<p>====Get the binary data for a historic task instance variable</p> 27471</div> 27472<div class="listingblock"> 27473<div class="content"> 27474<pre>GET history/historic-variable-instances/{varInstanceId}/data</pre> 27475</div> 27476</div> 27477<table class="tableblock frame-all grid-all spread"> 27478<caption class="title">Table 196. Get the binary data for a historic task instance variable - Response codes</caption> 27479<colgroup> 27480<col style="width: 50%;"> 27481<col style="width: 50%;"> 27482</colgroup> 27483<thead> 27484<tr> 27485<th class="tableblock halign-left valign-top">Response code</th> 27486<th class="tableblock halign-left valign-top">Description</th> 27487</tr> 27488</thead> 27489<tbody> 27490<tr> 27491<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27492<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the variable instance was found and the requested variable data is returned.</p></td> 27493</tr> 27494<tr> 27495<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 27496<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested variable instance was not found or the variable instance doesn’t have a variable with the given name or the variable doesn’t have a binary stream available. Status message provides additional information.</p></td> 27497</tr> 27498</tbody> 27499</table> 27500<div class="paragraph"> 27501<p><strong>Success response body:</strong></p> 27502</div> 27503<div class="paragraph"> 27504<p>The response body contains the binary value of the variable. When the variable is of type <code>binary</code>, the content-type of the response is set to <code>application/octet-stream</code>, regardless of the content of the variable or the request accept-type header. In case of <code>serializable</code>, <code>application/x-java-serialized-object</code> is used as content-type.</p> 27505</div> 27506</div> 27507<div class="sect3"> 27508<h4 id="restHistoricDetailGet">13.8.21. Get historic detail</h4> 27509<div class="listingblock"> 27510<div class="content"> 27511<pre>GET history/historic-detail</pre> 27512</div> 27513</div> 27514<table class="tableblock frame-all grid-all spread"> 27515<caption class="title">Table 197. Get historic detail - URL parameters</caption> 27516<colgroup> 27517<col style="width: 25%;"> 27518<col style="width: 25%;"> 27519<col style="width: 25%;"> 27520<col style="width: 25%;"> 27521</colgroup> 27522<thead> 27523<tr> 27524<th class="tableblock halign-left valign-top">Parameter</th> 27525<th class="tableblock halign-left valign-top">Required</th> 27526<th class="tableblock halign-left valign-top">Value</th> 27527<th class="tableblock halign-left valign-top">Description</th> 27528</tr> 27529</thead> 27530<tbody> 27531<tr> 27532<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 27533<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27534<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27535<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the historic detail.</p></td> 27536</tr> 27537<tr> 27538<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 27539<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27540<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27541<td class="tableblock halign-left valign-top"><p class="tableblock">The process instance id of the historic detail.</p></td> 27542</tr> 27543<tr> 27544<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 27545<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27546<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27547<td class="tableblock halign-left valign-top"><p class="tableblock">The execution id of the historic detail.</p></td> 27548</tr> 27549<tr> 27550<td class="tableblock halign-left valign-top"><p class="tableblock">activityInstanceId</p></td> 27551<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27552<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27553<td class="tableblock halign-left valign-top"><p class="tableblock">The activity instance id of the historic detail.</p></td> 27554</tr> 27555<tr> 27556<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 27557<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27558<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27559<td class="tableblock halign-left valign-top"><p class="tableblock">The task id of the historic detail.</p></td> 27560</tr> 27561<tr> 27562<td class="tableblock halign-left valign-top"><p class="tableblock">selectOnlyFormProperties</p></td> 27563<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27564<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 27565<td class="tableblock halign-left valign-top"><p class="tableblock">Indication to only return form properties in the result.</p></td> 27566</tr> 27567<tr> 27568<td class="tableblock halign-left valign-top"><p class="tableblock">selectOnlyVariableUpdates</p></td> 27569<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 27570<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 27571<td class="tableblock halign-left valign-top"><p class="tableblock">Indication to only return variable updates in the result.</p></td> 27572</tr> 27573</tbody> 27574</table> 27575<table class="tableblock frame-all grid-all spread"> 27576<caption class="title">Table 198. Get historic detail - Response codes</caption> 27577<colgroup> 27578<col style="width: 50%;"> 27579<col style="width: 50%;"> 27580</colgroup> 27581<thead> 27582<tr> 27583<th class="tableblock halign-left valign-top">Response code</th> 27584<th class="tableblock halign-left valign-top">Description</th> 27585</tr> 27586</thead> 27587<tbody> 27588<tr> 27589<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27590<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that historic detail could be queried.</p></td> 27591</tr> 27592<tr> 27593<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 27594<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 27595</tr> 27596</tbody> 27597</table> 27598<div class="paragraph"> 27599<p><strong>Success response body:</strong></p> 27600</div> 27601<div class="listingblock"> 27602<div class="content"> 27603<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27604 2 27605 3 27606 4 27607 5 27608 6 27609 7 27610 8 27611 9 2761210 2761311 2761412 2761513 2761614 2761715 2761816 2761917 2762018 2762119 2762220 2762321 2762422 2762523 2762624 2762725 2762826 2762927 2763028</div></td><td class="code"><span></span><span class="tok-p">{</span> 27631 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27632 <span class="tok-p">{</span>
27633 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"26"</span><span class="tok-p">,</span> 27634 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27635 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 27636 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27637 <span class="tok-nt">"activityInstanceId"</span><span class="tok-p">,</span> <span class="tok-nt">"10"</span><span class="tok-p">,</span> 27638 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27639 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-task-instances/6"</span><span class="tok-p">,</span> 27640 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 27641 <span class="tok-nt">"detailType"</span> <span class="tok-p">:</span> <span class="tok-s2">"variableUpdate"</span><span class="tok-p">,</span> 27642 <span class="tok-nt">"revision"</span> <span class="tok-p">:</span> <span class="tok-mi">2</span><span class="tok-p">,</span> 27643 <span class="tok-nt">"variable"</span> <span class="tok-p">:</span> <span class="tok-p">{</span> 27644 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 27645 <span class="tok-nt">"variableScope"</span><span class="tok-p">,</span> <span class="tok-nt">"global"</span><span class="tok-p">,</span> 27646 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"test"</span> 27647 <span class="tok-p">},</span> 27648 <span class="tok-nt">"propertyId"</span><span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27649 <span class="tok-nt">"propertyValue"</span><span class="tok-p">:</span> <span class="tok-kc">null</span> 27650 <span class="tok-p">}</span> 27651 <span class="tok-p">],</span> 27652 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27653 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27654 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27655 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27656 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27657<span class="tok-p">}</span> 27658</td></tr></table></code></pre> 27659</div> 27660</div> 27661</div> 27662<div class="sect3"> 27663<h4 id="_query_for_historic_details">13.8.22. Query for historic details</h4> 27664<div class="listingblock"> 27665<div class="content"> 27666<pre>POST query/historic-detail</pre> 27667</div> 27668</div> 27669<div class="paragraph"> 27670<p><strong>Request body:</strong></p> 27671</div> 27672<div class="listingblock"> 27673<div class="content"> 27674<pre>{ 27675 "processInstanceId" : "5", 27676}</pre> 27677</div> 27678</div> 27679<div class="paragraph"> 27680<p>All supported JSON parameter fields allowed are exactly the same as the parameters found for <a href="#restHistoricDetailGet">getting a collection of historic process instances</a>, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri’s that are too long.</p> 27681</div> 27682<table class="tableblock frame-all grid-all spread"> 27683<caption class="title">Table 199. Query for historic details - Response codes</caption> 27684<colgroup> 27685<col style="width: 50%;"> 27686<col style="width: 50%;"> 27687</colgroup> 27688<thead> 27689<tr> 27690<th class="tableblock halign-left valign-top">Response code</th> 27691<th class="tableblock halign-left valign-top">Description</th> 27692</tr> 27693</thead> 27694<tbody> 27695<tr> 27696<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27697<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the historic details are returned</p></td> 27698</tr> 27699<tr> 27700<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 27701<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 27702</tr> 27703</tbody> 27704</table> 27705<div class="paragraph"> 27706<p><strong>Success response body:</strong></p> 27707</div> 27708<div class="listingblock"> 27709<div class="content"> 27710<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27711 2 27712 3 27713 4 27714 5 27715 6 27716 7 27717 8 27718 9 2771910 2772011 2772112 2772213 2772314 2772415 2772516 2772617 2772718 2772819 2772920 2773021 2773122 2773223 2773324 2773425 2773526 2773627 2773728</div></td><td class="code"><span></span><span class="tok-p">{</span> 27738 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27739 <span class="tok-p">{</span>
27740 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"26"</span><span class="tok-p">,</span> 27741 <span class="tok-nt">"processInstanceId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27742 <span class="tok-nt">"processInstanceUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 27743 <span class="tok-nt">"executionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27744 <span class="tok-nt">"activityInstanceId"</span><span class="tok-p">,</span> <span class="tok-nt">"10"</span><span class="tok-p">,</span> 27745 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27746 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-task-instances/6"</span><span class="tok-p">,</span> 27747 <span class="tok-nt">"time"</span> <span class="tok-p">:</span> <span class="tok-s2">"2013-04-17T10:17:43.902+0000"</span><span class="tok-p">,</span> 27748 <span class="tok-nt">"detailType"</span> <span class="tok-p">:</span> <span class="tok-s2">"variableUpdate"</span><span class="tok-p">,</span> 27749 <span class="tok-nt">"revision"</span> <span class="tok-p">:</span> <span class="tok-mi">2</span><span class="tok-p">,</span> 27750 <span class="tok-nt">"variable"</span> <span class="tok-p">:</span> <span class="tok-p">{</span> 27751 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"myVariable"</span><span class="tok-p">,</span> 27752 <span class="tok-nt">"variableScope"</span><span class="tok-p">,</span> <span class="tok-nt">"global"</span><span class="tok-p">,</span> 27753 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"test"</span> 27754 <span class="tok-p">},</span> 27755 <span class="tok-nt">"propertyId"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27756 <span class="tok-nt">"propertyValue"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span> 27757 <span class="tok-p">}</span> 27758 <span class="tok-p">],</span> 27759 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27760 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27761 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27762 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27763 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27764<span class="tok-p">}</span> 27765</td></tr></table></code></pre> 27766</div> 27767</div> 27768</div> 27769<div class="sect3"> 27770<h4 id="_get_the_binary_data_for_a_historic_detail_variable">13.8.23. Get the binary data for a historic detail variable</h4> 27771<div class="listingblock"> 27772<div class="content"> 27773<pre>GET history/historic-detail/{detailId}/data</pre> 27774</div> 27775</div> 27776<table class="tableblock frame-all grid-all spread"> 27777<caption class="title">Table 200. Get the binary data for a historic detail variable - Response codes</caption> 27778<colgroup> 27779<col style="width: 50%;"> 27780<col style="width: 50%;"> 27781</colgroup> 27782<thead> 27783<tr> 27784<th class="tableblock halign-left valign-top">Response code</th> 27785<th class="tableblock halign-left valign-top">Description</th> 27786</tr> 27787</thead> 27788<tbody> 27789<tr> 27790<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27791<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the historic detail instance was found and the requested variable data is returned.</p></td> 27792</tr> 27793<tr> 27794<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 27795<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested historic detail instance was not found or the historic detail instance doesn’t have a variable with the given name or the variable doesn’t have a binary stream available. Status message provides additional information.</p></td> 27796</tr> 27797</tbody> 27798</table> 27799<div class="paragraph"> 27800<p><strong>Success response body:</strong></p> 27801</div> 27802<div class="paragraph"> 27803<p>The response body contains the binary value of the variable. When the variable is of type <code>binary</code>, the content-type of the response is set to <code>application/octet-stream</code>, regardless of the content of the variable or the request accept-type header. In case of <code>serializable</code>, <code>application/x-java-serialized-object</code> is used as content-type.</p> 27804</div> 27805</div> 27806</div> 27807<div class="sect2"> 27808<h3 id="_forms">13.9. Forms</h3> 27809<div class="sect3"> 27810<h4 id="_get_form_data">13.9.1. Get form data</h4> 27811<div class="listingblock"> 27812<div class="content"> 27813<pre>GET form/form-data</pre> 27814</div> 27815</div> 27816<table class="tableblock frame-all grid-all spread"> 27817<caption class="title">Table 201. Get form data - URL parameters</caption> 27818<colgroup> 27819<col style="width: 25%;"> 27820<col style="width: 25%;"> 27821<col style="width: 25%;"> 27822<col style="width: 25%;"> 27823</colgroup> 27824<thead> 27825<tr> 27826<th class="tableblock halign-left valign-top">Parameter</th> 27827<th class="tableblock halign-left valign-top">Required</th> 27828<th class="tableblock halign-left valign-top">Value</th> 27829<th class="tableblock halign-left valign-top">Description</th> 27830</tr> 27831</thead> 27832<tbody> 27833<tr> 27834<td class="tableblock halign-left valign-top"><p class="tableblock">taskId</p></td> 27835<td class="tableblock halign-left valign-top"><p class="tableblock">Yes (if no processDefinitionId)</p></td> 27836<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27837<td class="tableblock halign-left valign-top"><p class="tableblock">The task id corresponding to the form data that needs to be retrieved.</p></td> 27838</tr> 27839<tr> 27840<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 27841<td class="tableblock halign-left valign-top"><p class="tableblock">Yes (if no taskId)</p></td> 27842<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 27843<td class="tableblock halign-left valign-top"><p class="tableblock">The process definition id corresponding to the start event form data that needs to be retrieved.</p></td> 27844</tr> 27845</tbody> 27846</table> 27847<table class="tableblock frame-all grid-all spread"> 27848<caption class="title">Table 202. Get form data - Response codes</caption> 27849<colgroup> 27850<col style="width: 50%;"> 27851<col style="width: 50%;"> 27852</colgroup> 27853<thead> 27854<tr> 27855<th class="tableblock halign-left valign-top">Response code</th> 27856<th class="tableblock halign-left valign-top">Description</th> 27857</tr> 27858</thead> 27859<tbody> 27860<tr> 27861<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 27862<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that form data could be queried.</p></td> 27863</tr> 27864<tr> 27865<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 27866<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that form data could not be found.</p></td> 27867</tr> 27868</tbody> 27869</table> 27870<div class="paragraph"> 27871<p><strong>Success response body:</strong></p> 27872</div> 27873<div class="listingblock"> 27874<div class="content"> 27875<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27876 2 27877 3 27878 4 27879 5 27880 6 27881 7 27882 8 27883 9 2788410 2788511 2788612 2788713 2788814 2788915 2789016 2789117 2789218 2789319 2789420 2789521 2789622 2789723 2789824 2789925 2790026 2790127 2790228 2790329 2790430 2790531 2790632 2790733 2790834 2790935 2791036 2791137 2791238 2791339</div></td><td class="code"><span></span><span class="tok-p">{</span> 27914 <span class="tok-nt">"data"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 27915 <span class="tok-p">{</span>
27916 <span class="tok-nt">"formKey"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27917 <span class="tok-nt">"deploymentId"</span> <span class="tok-p">:</span> <span class="tok-s2">"2"</span><span class="tok-p">,</span> 27918 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 27919 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definition/3"</span><span class="tok-p">,</span> 27920 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"6"</span><span class="tok-p">,</span> 27921 <span class="tok-nt">"taskUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/runtime/task/6"</span><span class="tok-p">,</span> 27922 <span class="tok-nt">"formProperties"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 27923 <span class="tok-p">{</span> 27924 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"room"</span><span class="tok-p">,</span> 27925 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"Room"</span><span class="tok-p">,</span> 27926 <span class="tok-nt">"type"</span> <span class="tok-p">:</span> <span class="tok-s2">"string"</span><span class="tok-p">,</span> 27927 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27928 <span class="tok-nt">"readable"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span><span class="tok-p">,</span> 27929 <span class="tok-nt">"writable"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span><span class="tok-p">,</span> 27930 <span class="tok-nt">"required"</span> <span class="tok-p">:</span> <span class="tok-kc">true</span><span class="tok-p">,</span> 27931 <span class="tok-nt">"datePattern"</span> <span class="tok-p">:</span> <span class="tok-kc">null</span><span class="tok-p">,</span> 27932 <span class="tok-nt">"enumValues"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 27933 <span class="tok-p">{</span> 27934 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"normal"</span><span class="tok-p">,</span> 27935 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"Normal bed"</span> 27936 <span class="tok-p">},</span> 27937 <span class="tok-p">{</span> 27938 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"kingsize"</span><span class="tok-p">,</span> 27939 <span class="tok-nt">"name"</span> <span class="tok-p">:</span> <span class="tok-s2">"Kingsize bed"</span> 27940 <span class="tok-p">},</span> 27941 <span class="tok-p">]</span> 27942 <span class="tok-p">}</span> 27943 <span class="tok-p">]</span> 27944 <span class="tok-p">}</span> 27945 <span class="tok-p">],</span> 27946 <span class="tok-nt">"total"</span><span class="tok-p">:</span> <span class="tok-mi">1</span><span class="tok-p">,</span> 27947 <span class="tok-nt">"start"</span><span class="tok-p">:</span> <span class="tok-mi">0</span><span class="tok-p">,</span> 27948 <span class="tok-nt">"sort"</span><span class="tok-p">:</span> <span class="tok-s2">"name"</span><span class="tok-p">,</span> 27949 <span class="tok-nt">"order"</span><span class="tok-p">:</span> <span class="tok-s2">"asc"</span><span class="tok-p">,</span> 27950 <span class="tok-nt">"size"</span><span class="tok-p">:</span> <span class="tok-mi">1</span> 27951<span class="tok-p">}</span> 27952</td></tr></table></code></pre> 27953</div> 27954</div> 27955</div> 27956<div class="sect3"> 27957<h4 id="_submit_task_form_data">13.9.2. Submit task form data</h4> 27958<div class="listingblock"> 27959<div class="content"> 27960<pre>POST form/form-data</pre> 27961</div> 27962</div> 27963<div class="paragraph"> 27964<p><strong>Request body for task form:</strong></p> 27965</div> 27966<div class="listingblock"> 27967<div class="content"> 27968<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 279692 279703 279714 279725 279736 279747 279758 279769</div></td><td class="code"><span></span><span class="tok-p">{</span> 27977 <span class="tok-nt">"taskId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 27978 <span class="tok-nt">"properties"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 27979 <span class="tok-p">{</span>
27980 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"room"</span><span class="tok-p">,</span> 27981 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"normal"</span> 27982 <span class="tok-p">}</span> 27983 <span class="tok-p">]</span> 27984<span class="tok-p">}</span> 27985</td></tr></table></code></pre> 27986</div> 27987</div> 27988<div class="paragraph"> 27989<p><strong>Request body for start event form:</strong></p> 27990</div> 27991<div class="listingblock"> 27992<div class="content"> 27993<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 27994 2 27995 3 27996 4 27997 5 27998 6 27999 7 28000 8 28001 9 2800210</div></td><td class="code"><span></span><span class="tok-p">{</span> 28003 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 28004 <span class="tok-nt">"businessKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"myKey"</span><span class="tok-p">,</span> 28005 <span class="tok-nt">"properties"</span> <span class="tok-p">:</span> <span class="tok-p">[</span> 28006 <span class="tok-p">{</span> 28007 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"room"</span><span class="tok-p">,</span> 28008 <span class="tok-nt">"value"</span> <span class="tok-p">:</span> <span class="tok-s2">"normal"</span> 28009 <span class="tok-p">}</span> 28010 <span class="tok-p">]</span> 28011<span class="tok-p">}</span> 28012</td></tr></table></code></pre> 28013</div> 28014</div> 28015<table class="tableblock frame-all grid-all spread"> 28016<caption class="title">Table 203. Submit task form data - Response codes</caption> 28017<colgroup> 28018<col style="width: 50%;"> 28019<col style="width: 50%;"> 28020</colgroup> 28021<thead> 28022<tr> 28023<th class="tableblock halign-left valign-top">Response code</th> 28024<th class="tableblock halign-left valign-top">Description</th> 28025</tr> 28026</thead> 28027<tbody> 28028<tr> 28029<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28030<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates request was successful and the form data was submitted</p></td> 28031</tr> 28032<tr> 28033<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 28034<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an parameter was passed in the wrong format. The status-message contains additional information.</p></td> 28035</tr> 28036</tbody> 28037</table> 28038<div class="paragraph"> 28039<p><strong>Success response body for start event form data (no response for task form data):</strong></p> 28040</div> 28041<div class="listingblock"> 28042<div class="content"> 28043<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 280442 280453 280464 280475 280486 280497 280508 280519</div></td><td class="code"><span></span><span class="tok-p">{</span> 28052 <span class="tok-nt">"id"</span> <span class="tok-p">:</span> <span class="tok-s2">"5"</span><span class="tok-p">,</span> 28053 <span class="tok-nt">"url"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/history/historic-process-instances/5"</span><span class="tok-p">,</span> 28054 <span class="tok-nt">"businessKey"</span> <span class="tok-p">:</span> <span class="tok-s2">"myKey"</span><span class="tok-p">,</span> 28055 <span class="tok-nt">"suspended"</span><span class="tok-p">:</span> <span class="tok-kc">false</span><span class="tok-p">,</span> 28056 <span class="tok-nt">"processDefinitionId"</span> <span class="tok-p">:</span> <span class="tok-s2">"3"</span><span class="tok-p">,</span> 28057 <span class="tok-nt">"processDefinitionUrl"</span> <span class="tok-p">:</span> <span class="tok-s2">"http://localhost:8182/repository/process-definition/3"</span><span class="tok-p">,</span> 28058 <span class="tok-nt">"activityId"</span> <span class="tok-p">:</span> <span class="tok-s2">"myTask"</span> 28059<span class="tok-p">}</span> 28060</td></tr></table></code></pre> 28061</div> 28062</div> 28063</div> 28064</div> 28065<div class="sect2"> 28066<h3 id="_database_tables">13.10. Database tables</h3> 28067<div class="sect3"> 28068<h4 id="_list_of_tables">13.10.1. List of tables</h4> 28069<div class="listingblock"> 28070<div class="content"> 28071<pre>GET management/tables</pre> 28072</div> 28073</div> 28074<table class="tableblock frame-all grid-all spread"> 28075<caption class="title">Table 204. List of tables - Response codes</caption> 28076<colgroup> 28077<col style="width: 50%;"> 28078<col style="width: 50%;"> 28079</colgroup> 28080<thead> 28081<tr> 28082<th class="tableblock halign-left valign-top">Response code</th> 28083<th class="tableblock halign-left valign-top">Description</th> 28084</tr> 28085</thead> 28086<tbody> 28087<tr> 28088<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28089<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the request was successful.</p></td> 28090</tr> 28091</tbody> 28092</table> 28093<div class="paragraph"> 28094<p><strong>Success response body:</strong></p> 28095</div> 28096<div class="listingblock"> 28097<div class="content"> 28098<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 28099 2 28100 3 28101 4 28102 5 28103 6 28104 7 28105 8 28106 9 2810710 2810811 2810912 2811013</div></td><td class="code"><span></span><span class="tok-p">[</span> 28111 <span class="tok-p">{</span>
28112 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"ACT_RU_VARIABLE"</span><span class="tok-p">,</span> 28113 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/management/tables/ACT_RU_VARIABLE"</span><span class="tok-p">,</span> 28114 <span class="tok-nt">"count"</span><span class="tok-p">:</span><span class="tok-mi">4528</span> 28115 <span class="tok-p">},</span> 28116 <span class="tok-p">{</span> 28117 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"ACT_RU_EVENT_SUBSCR"</span><span class="tok-p">,</span> 28118 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/management/tables/ACT_RU_EVENT_SUBSCR"</span><span class="tok-p">,</span> 28119 <span class="tok-nt">"count"</span><span class="tok-p">:</span><span class="tok-mi">3</span> 28120 <span class="tok-p">}</span> 28121 28122<span class="tok-p">]</span> 28123</td></tr></table></code></pre> 28124</div> 28125</div> 28126</div> 28127<div class="sect3"> 28128<h4 id="_get_a_single_table">13.10.2. Get a single table</h4> 28129<div class="listingblock"> 28130<div class="content"> 28131<pre>GET management/tables/{tableName}</pre> 28132</div> 28133</div> 28134<table class="tableblock frame-all grid-all spread"> 28135<caption class="title">Table 205. Get a single table - URL parameters</caption> 28136<colgroup> 28137<col style="width: 25%;"> 28138<col style="width: 25%;"> 28139<col style="width: 25%;"> 28140<col style="width: 25%;"> 28141</colgroup> 28142<thead> 28143<tr> 28144<th class="tableblock halign-left valign-top">Parameter</th> 28145<th class="tableblock halign-left valign-top">Required</th> 28146<th class="tableblock halign-left valign-top">Value</th> 28147<th class="tableblock halign-left valign-top">Description</th> 28148</tr> 28149</thead> 28150<tbody> 28151<tr> 28152<td class="tableblock halign-left valign-top"><p class="tableblock">tableName</p></td> 28153<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28154<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28155<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the table to get.</p></td> 28156</tr> 28157</tbody> 28158</table> 28159<div class="paragraph"> 28160<p><strong>Success response body:</strong></p> 28161</div> 28162<div class="listingblock"> 28163<div class="content"> 28164<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 281652 281663 281674 281685</div></td><td class="code"><span></span><span class="tok-p">{</span> 28169 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"ACT_RE_PROCDEF"</span><span class="tok-p">,</span> 28170 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/management/tables/ACT_RE_PROCDEF"</span><span class="tok-p">,</span> 28171 <span class="tok-nt">"count"</span><span class="tok-p">:</span><span class="tok-mi">60</span> 28172<span class="tok-p">}</span> 28173</td></tr></table></code></pre> 28174</div> 28175</div> 28176<table class="tableblock frame-all grid-all spread"> 28177<caption class="title">Table 206. Get a single table - Response codes</caption> 28178<colgroup> 28179<col style="width: 50%;"> 28180<col style="width: 50%;"> 28181</colgroup> 28182<thead> 28183<tr> 28184<th class="tableblock halign-left valign-top">Response code</th> 28185<th class="tableblock halign-left valign-top">Description</th> 28186</tr> 28187</thead> 28188<tbody> 28189<tr> 28190<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28191<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the table exists and the table count is returned.</p></td> 28192</tr> 28193<tr> 28194<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28195<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested table does not exist.</p></td> 28196</tr> 28197</tbody> 28198</table> 28199</div> 28200<div class="sect3"> 28201<h4 id="_get_column_info_for_a_single_table">13.10.3. Get column info for a single table</h4> 28202<div class="listingblock"> 28203<div class="content"> 28204<pre>GET management/tables/{tableName}/columns</pre> 28205</div> 28206</div> 28207<table class="tableblock frame-all grid-all spread"> 28208<caption class="title">Table 207. Get column info for a single table - URL parameters</caption> 28209<colgroup> 28210<col style="width: 25%;"> 28211<col style="width: 25%;"> 28212<col style="width: 25%;"> 28213<col style="width: 25%;"> 28214</colgroup> 28215<thead> 28216<tr> 28217<th class="tableblock halign-left valign-top">Parameter</th> 28218<th class="tableblock halign-left valign-top">Required</th> 28219<th class="tableblock halign-left valign-top">Value</th> 28220<th class="tableblock halign-left valign-top">Description</th> 28221</tr> 28222</thead> 28223<tbody> 28224<tr> 28225<td class="tableblock halign-left valign-top"><p class="tableblock">tableName</p></td> 28226<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28227<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28228<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the table to get.</p></td> 28229</tr> 28230</tbody> 28231</table> 28232<div class="paragraph"> 28233<p><strong>Success response body:</strong></p> 28234</div> 28235<div class="listingblock"> 28236<div class="content"> 28237<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 28238 2 28239 3 28240 4 28241 5 28242 6 28243 7 28244 8 28245 9 2824610 2824711 2824812 2824913 2825014 2825115 2825216 2825317 2825418 2825519</div></td><td class="code"><span></span><span class="tok-p">{</span> 28256 <span class="tok-nt">"tableName"</span><span class="tok-p">:</span><span class="tok-s2">"ACT_RU_VARIABLE"</span><span class="tok-p">,</span> 28257 <span class="tok-nt">"columnNames"</span><span class="tok-p">:[</span>
28258 <span class="tok-s2">"ID_"</span><span class="tok-p">,</span> 28259 <span class="tok-s2">"REV_"</span><span class="tok-p">,</span> 28260 <span class="tok-s2">"TYPE_"</span><span class="tok-p">,</span> 28261 <span class="tok-s2">"NAME_"</span> 28262 28263 28264 <span class="tok-p">],</span> 28265 <span class="tok-nt">"columnTypes"</span><span class="tok-p">:[</span> 28266 <span class="tok-s2">"VARCHAR"</span><span class="tok-p">,</span> 28267 <span class="tok-s2">"INTEGER"</span><span class="tok-p">,</span> 28268 <span class="tok-s2">"VARCHAR"</span><span class="tok-p">,</span> 28269 <span class="tok-s2">"VARCHAR"</span> 28270 28271 28272 <span class="tok-p">]</span> 28273<span class="tok-p">}</span> 28274</td></tr></table></code></pre> 28275</div> 28276</div> 28277<table class="tableblock frame-all grid-all spread"> 28278<caption class="title">Table 208. Get column info for a single table - Response codes</caption> 28279<colgroup> 28280<col style="width: 50%;"> 28281<col style="width: 50%;"> 28282</colgroup> 28283<thead> 28284<tr> 28285<th class="tableblock halign-left valign-top">Response code</th> 28286<th class="tableblock halign-left valign-top">Description</th> 28287</tr> 28288</thead> 28289<tbody> 28290<tr> 28291<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28292<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the table exists and the table column info is returned.</p></td> 28293</tr> 28294<tr> 28295<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28296<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested table does not exist.</p></td> 28297</tr> 28298</tbody> 28299</table> 28300</div> 28301<div class="sect3"> 28302<h4 id="_get_row_data_for_a_single_table">13.10.4. Get row data for a single table</h4> 28303<div class="listingblock"> 28304<div class="content"> 28305<pre>GET management/tables/{tableName}/data</pre> 28306</div> 28307</div> 28308<table class="tableblock frame-all grid-all spread"> 28309<caption class="title">Table 209. Get row data for a single table - URL parameters</caption> 28310<colgroup> 28311<col style="width: 25%;"> 28312<col style="width: 25%;"> 28313<col style="width: 25%;"> 28314<col style="width: 25%;"> 28315</colgroup> 28316<thead> 28317<tr> 28318<th class="tableblock halign-left valign-top">Parameter</th> 28319<th class="tableblock halign-left valign-top">Required</th> 28320<th class="tableblock halign-left valign-top">Value</th> 28321<th class="tableblock halign-left valign-top">Description</th> 28322</tr> 28323</thead> 28324<tbody> 28325<tr> 28326<td class="tableblock halign-left valign-top"><p class="tableblock">tableName</p></td> 28327<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28328<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28329<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the table to get.</p></td> 28330</tr> 28331</tbody> 28332</table> 28333<table class="tableblock frame-all grid-all spread"> 28334<caption class="title">Table 210. Get row data for a single table - URL query parameters</caption> 28335<colgroup> 28336<col style="width: 25%;"> 28337<col style="width: 25%;"> 28338<col style="width: 25%;"> 28339<col style="width: 25%;"> 28340</colgroup> 28341<thead> 28342<tr> 28343<th class="tableblock halign-left valign-top">Parameter</th> 28344<th class="tableblock halign-left valign-top">Required</th> 28345<th class="tableblock halign-left valign-top">Value</th> 28346<th class="tableblock halign-left valign-top">Description</th> 28347</tr> 28348</thead> 28349<tbody> 28350<tr> 28351<td class="tableblock halign-left valign-top"><p class="tableblock">start</p></td> 28352<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28353<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 28354<td class="tableblock halign-left valign-top"><p class="tableblock">Index of the first row to fetch. Defaults to 0.</p></td> 28355</tr> 28356<tr> 28357<td class="tableblock halign-left valign-top"><p class="tableblock">size</p></td> 28358<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28359<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td> 28360<td class="tableblock halign-left valign-top"><p class="tableblock">Number of rows to fetch, starting from <code>start</code>. Defaults to 10.</p></td> 28361</tr> 28362<tr> 28363<td class="tableblock halign-left valign-top"><p class="tableblock">orderAscendingColumn</p></td> 28364<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28365<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28366<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the column to sort the resulting rows on, ascending.</p></td> 28367</tr> 28368<tr> 28369<td class="tableblock halign-left valign-top"><p class="tableblock">orderDescendingColumn</p></td> 28370<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28371<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28372<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the column to sort the resulting rows on, descending.</p></td> 28373</tr> 28374</tbody> 28375</table> 28376<div class="paragraph"> 28377<p><strong>Success response body:</strong></p> 28378</div> 28379<div class="listingblock"> 28380<div class="content"> 28381<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 28382 2 28383 3 28384 4 28385 5 28386 6 28387 7 28388 8 28389 9 2839010 2839111 2839212 2839313 2839414 2839515 2839616 2839717 2839818 2839919 2840020 2840121 2840222 2840323</div></td><td class="code"><span></span><span class="tok-p">{</span> 28404 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">3</span><span class="tok-p">,</span> 28405 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 28406 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 28407 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 28408 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">3</span><span class="tok-p">,</span> 28409 28410 <span class="tok-nt">"data"</span><span class="tok-p">:[</span>
28411 <span class="tok-p">{</span> 28412 <span class="tok-nt">"TASK_ID_"</span><span class="tok-p">:</span><span class="tok-s2">"2"</span><span class="tok-p">,</span> 28413 <span class="tok-nt">"NAME_"</span><span class="tok-p">:</span><span class="tok-s2">"var1"</span><span class="tok-p">,</span> 28414 <span class="tok-nt">"REV_"</span><span class="tok-p">:</span><span class="tok-mi">1</span><span class="tok-p">,</span> 28415 <span class="tok-nt">"TEXT_"</span><span class="tok-p">:</span><span class="tok-s2">"123"</span><span class="tok-p">,</span> 28416 <span class="tok-nt">"LONG_"</span><span class="tok-p">:</span><span class="tok-mi">123</span><span class="tok-p">,</span> 28417 <span class="tok-nt">"ID_"</span><span class="tok-p">:</span><span class="tok-s2">"3"</span><span class="tok-p">,</span> 28418 <span class="tok-nt">"TYPE_"</span><span class="tok-p">:</span><span class="tok-s2">"integer"</span> 28419 <span class="tok-p">}</span> 28420 28421 28422 28423 <span class="tok-p">]</span> 28424 28425<span class="tok-p">}</span> 28426</td></tr></table></code></pre> 28427</div> 28428</div> 28429<table class="tableblock frame-all grid-all spread"> 28430<caption class="title">Table 211. Get row data for a single table - Response codes</caption> 28431<colgroup> 28432<col style="width: 50%;"> 28433<col style="width: 50%;"> 28434</colgroup> 28435<thead> 28436<tr> 28437<th class="tableblock halign-left valign-top">Response code</th> 28438<th class="tableblock halign-left valign-top">Description</th> 28439</tr> 28440</thead> 28441<tbody> 28442<tr> 28443<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28444<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the table exists and the table row data is returned.</p></td> 28445</tr> 28446<tr> 28447<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28448<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested table does not exist.</p></td> 28449</tr> 28450</tbody> 28451</table> 28452</div> 28453</div> 28454<div class="sect2"> 28455<h3 id="_engine">13.11. Engine</h3> 28456<div class="sect3"> 28457<h4 id="_get_engine_properties">13.11.1. Get engine properties</h4> 28458<div class="listingblock"> 28459<div class="content"> 28460<pre>GET management/properties</pre> 28461</div> 28462</div> 28463<div class="paragraph"> 28464<p>Returns a read-only view of the properties used internally in the engine.</p> 28465</div> 28466<div class="paragraph"> 28467<p><strong>Success response body:</strong></p> 28468</div> 28469<div class="listingblock"> 28470<div class="content"> 28471<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 284722 284733 284744 284755</div></td><td class="code"><span></span><span class="tok-p">{</span> 28476 <span class="tok-nt">"next.dbid"</span><span class="tok-p">:</span><span class="tok-s2">"101"</span><span class="tok-p">,</span> 28477 <span class="tok-nt">"schema.history"</span><span class="tok-p">:</span><span class="tok-s2">"create(5.15)"</span><span class="tok-p">,</span> 28478 <span class="tok-nt">"schema.version"</span><span class="tok-p">:</span><span class="tok-s2">"5.15"</span> 28479<span class="tok-p">}</span> 28480</td></tr></table></code></pre> 28481</div> 28482</div> 28483<table class="tableblock frame-all grid-all spread"> 28484<caption class="title">Table 212. Get engine properties - Response codes</caption> 28485<colgroup> 28486<col style="width: 50%;"> 28487<col style="width: 50%;"> 28488</colgroup> 28489<thead> 28490<tr> 28491<th class="tableblock halign-left valign-top">Response code</th> 28492<th class="tableblock halign-left valign-top">Description</th> 28493</tr> 28494</thead> 28495<tbody> 28496<tr> 28497<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28498<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the properties are returned.</p></td> 28499</tr> 28500</tbody> 28501</table> 28502</div> 28503<div class="sect3"> 28504<h4 id="_get_engine_info">13.11.2. Get engine info</h4> 28505<div class="listingblock"> 28506<div class="content"> 28507<pre>GET management/engine</pre> 28508</div> 28509</div> 28510<div class="paragraph"> 28511<p>Returns a read-only view of the engine that is used in this REST-service.</p> 28512</div> 28513<div class="paragraph"> 28514<p><strong>Success response body:</strong></p> 28515</div> 28516<div class="listingblock"> 28517<div class="content"> 28518<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 285192 285203 285214 285225 285236</div></td><td class="code"><span></span><span class="tok-p">{</span> 28524 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"default"</span><span class="tok-p">,</span> 28525 <span class="tok-nt">"version"</span><span class="tok-p">:</span><span class="tok-s2">"5.15"</span><span class="tok-p">,</span> 28526 <span class="tok-nt">"resourceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"file://activiti/activiti.cfg.xml"</span><span class="tok-p">,</span> 28527 <span class="tok-nt">"exception"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 28528<span class="tok-p">}</span> 28529</td></tr></table></code></pre> 28530</div> 28531</div> 28532<table class="tableblock frame-all grid-all spread"> 28533<caption class="title">Table 213. Get engine info - Response codes</caption> 28534<colgroup> 28535<col style="width: 50%;"> 28536<col style="width: 50%;"> 28537</colgroup> 28538<thead> 28539<tr> 28540<th class="tableblock halign-left valign-top">Response code</th> 28541<th class="tableblock halign-left valign-top">Description</th> 28542</tr> 28543</thead> 28544<tbody> 28545<tr> 28546<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28547<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the engine info is returned.</p></td> 28548</tr> 28549</tbody> 28550</table> 28551</div> 28552</div> 28553<div class="sect2"> 28554<h3 id="_runtime">
2855413.12. Runtime</h3> 28555<div class="sect3"> 28556<h4 id="_signal_event_received">13.12.1. Signal event received</h4> 28557<div class="listingblock"> 28558<div class="content"> 28559<pre>POST runtime/signals</pre> 28560</div> 28561</div> 28562<div class="paragraph"> 28563<p>Notifies the engine that a signal event has been received, not explicitly related to a specific execution.</p> 28564</div> 28565<div class="paragraph"> 28566<p><strong>Body JSON:</strong></p> 28567</div> 28568<div class="listingblock"> 28569<div class="content"> 28570<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 285712 285723 285734 285745 285756 285767 285778 285789</div></td><td class="code"><span></span><span class="tok-p">{</span> 28579 <span class="tok-nt">"signalName"</span><span class="tok-p">:</span> <span class="tok-s2">"My Signal"</span><span class="tok-p">,</span> 28580 <span class="tok-nt">"tenantId"</span> <span class="tok-p">:</span> <span class="tok-s2">"execute"</span><span class="tok-p">,</span> 28581 <span class="tok-nt">"async"</span><span class="tok-p">:</span> <span class="tok-kc">true</span><span class="tok-p">,</span> 28582 <span class="tok-nt">"variables"</span><span class="tok-p">:</span> <span class="tok-p">[</span> 28583 <span class="tok-p">{</span><span class="tok-nt">"name"</span><span class="tok-p">:</span> <span class="tok-s2">"testVar"</span><span class="tok-p">,</span> <span class="tok-nt">"value"</span><span class="tok-p">:</span> <span class="tok-s2">"This is a string"</span><span class="tok-p">}</span> 28584 28585 <span class="tok-p">]</span> 28586<span class="tok-p">}</span> 28587</td></tr></table></code></pre> 28588</div> 28589</div> 28590<table class="tableblock frame-all grid-all spread"> 28591<caption class="title">Table 214. Signal event received - JSON Body parameters</caption> 28592<colgroup> 28593<col style="width: 33.3333%;"> 28594<col style="width: 33.3333%;"> 28595<col style="width: 33.3334%;"> 28596</colgroup> 28597<thead> 28598<tr> 28599<th class="tableblock halign-left valign-top">Parameter</th> 28600<th class="tableblock halign-left valign-top">Description</th> 28601<th class="tableblock halign-left valign-top">Required</th> 28602</tr> 28603</thead> 28604<tbody> 28605<tr> 28606<td class="tableblock halign-left valign-top"><p class="tableblock">signalName</p></td> 28607<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the signal</p></td> 28608<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28609</tr> 28610<tr> 28611<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 28612<td class="tableblock halign-left valign-top"><p class="tableblock">ID of the tenant that the signal event should be processed in</p></td> 28613<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28614</tr> 28615<tr> 28616<td class="tableblock halign-left valign-top"><p class="tableblock">async</p></td> 28617<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, handling of the signal will happen asynchronously. Return code will be <code>202 - Accepted</code> to indicate the request is accepted but not yet executed. If <code>false</code>, 28618 handling the signal will be done immediately and result (<code>200 - OK</code>) will only return after this completed successfully. Defaults to <code>false</code> if omitted.</p></td> 28619<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28620</tr> 28621<tr> 28622<td class="tableblock halign-left valign-top"><p class="tableblock">variables</p></td> 28623<td class="tableblock halign-left valign-top"><p class="tableblock">Array of variables (in the general variables format) to use as payload to pass along with the signal. Cannot be used in case <code>async</code> is set to <code>true</code>, this will result in an error.</p></td> 28624<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 28625</tr> 28626</tbody> 28627</table> 28628<div class="paragraph"> 28629<p><strong>Success response body:</strong></p> 28630</div> 28631<table class="tableblock frame-all grid-all spread"> 28632<caption class="title">Table 215. Signal event received - Response codes</caption> 28633<colgroup> 28634<col style="width: 50%;"> 28635<col style="width: 50%;"> 28636</colgroup> 28637<thead> 28638<tr> 28639<th class="tableblock halign-left valign-top">Response code</th> 28640<th class="tableblock halign-left valign-top">Description</th> 28641</tr> 28642</thead> 28643<tbody> 28644<tr> 28645<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28646<td class="tableblock halign-left valign-top"><p class="tableblock">Indicated signal has been processed and no errors occurred.</p></td> 28647</tr> 28648<tr> 28649<td class="tableblock halign-left valign-top"><p class="tableblock">202</p></td> 28650<td class="tableblock halign-left valign-top"><p class="tableblock">Indicated signal processing is queued as a job, ready to be executed.</p></td> 28651</tr> 28652<tr> 28653<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 28654<td class="tableblock halign-left valign-top"><p class="tableblock">Signal not processed. The signal name is missing or variables are used together with async, which is not allowed. Response body contains additional information about the error.</p></td> 28655</tr> 28656</tbody> 28657</table> 28658</div> 28659</div> 28660<div class="sect2"> 28661<h3 id="_jobs">13.13. Jobs</h3> 28662<div class="sect3"> 28663<h4 id="_get_a_single_job">13.13.1. Get a single job</h4> 28664<div class="listingblock"> 28665<div class="content"> 28666<pre>GET management/jobs/{jobId}</pre> 28667</div> 28668</div> 28669<table class="tableblock frame-all grid-all spread"> 28670<caption class="title">Table 216. Get a single job - URL parameters</caption> 28671<colgroup> 28672<col style="width: 25%;"> 28673<col style="width: 25%;"> 28674<col style="width: 25%;"> 28675<col style="width: 25%;"> 28676</colgroup> 28677<thead> 28678<tr> 28679<th class="tableblock halign-left valign-top">Parameter</th> 28680<th class="tableblock halign-left valign-top">Required</th> 28681<th class="tableblock halign-left valign-top">Value</th> 28682<th class="tableblock halign-left valign-top">Description</th> 28683</tr> 28684</thead> 28685<tbody> 28686<tr> 28687<td class="tableblock halign-left valign-top"><p class="tableblock">jobId</p></td> 28688<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28689<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28690<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the job to get.</p></td> 28691</tr> 28692</tbody> 28693</table> 28694<div class="paragraph"> 28695<p><strong>Success response body:</strong></p> 28696</div> 28697<div class="listingblock"> 28698<div class="content"> 28699<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 28700 2 28701 3 28702 4 28703 5 28704 6 28705 7 28706 8 28707 9 2870810 2870911 2871012 2871113 2871214</div></td><td class="code"><span></span><span class="tok-p">{</span> 28713 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"8"</span><span class="tok-p">,</span> 28714 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/management/jobs/8"</span><span class="tok-p">,</span> 28715 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 28716 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 28717 <span class="tok-nt">"processDefinitionId"</span><span class="tok-p">:</span><span class="tok-s2">"timerProcess:1:4"</span><span class="tok-p">,</span> 28718 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/timerProcess%3A1%3A4"</span><span class="tok-p">,</span> 28719 <span class="tok-nt">"executionId"</span><span class="tok-p">:</span><span class="tok-s2">"7"</span><span class="tok-p">,</span> 28720 <span class="tok-nt">"executionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/7"</span><span class="tok-p">,</span> 28721 <span class="tok-nt">"retries"</span><span class="tok-p">:</span><span class="tok-mi">3</span><span class="tok-p">,</span> 28722 <span class="tok-nt">"exceptionMessage"</span><span class="tok-p">:</span><span class="tok-kc">null</span><span class="tok-p">,</span> 28723 <span class="tok-nt">"dueDate"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-04T22:05:05.474+0000"</span><span class="tok-p">,</span> 28724 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 28725<span class="tok-p">}</span> 28726</td></tr></table></code></pre> 28727</div> 28728</div> 28729<table class="tableblock frame-all grid-all spread"> 28730<caption class="title">Table 217. Get a single job - Response codes</caption> 28731<colgroup> 28732<col style="width: 50%;"> 28733<col style="width: 50%;"> 28734</colgroup> 28735<thead> 28736<tr> 28737<th class="tableblock halign-left valign-top">Response code</th> 28738<th class="tableblock halign-left valign-top">Description</th> 28739</tr> 28740</thead> 28741<tbody> 28742<tr> 28743<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28744<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the job exists and is returned.</p></td> 28745</tr> 28746<tr> 28747<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28748<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested job does not exist.</p></td> 28749</tr> 28750</tbody> 28751</table> 28752</div> 28753<div class="sect3"> 28754<h4 id="_delete_a_job">13.13.2. Delete a job</h4> 28755<div class="listingblock"> 28756<div class="content"> 28757<pre>DELETE management/jobs/{jobId}</pre> 28758</div> 28759</div> 28760<table class="tableblock frame-all grid-all spread"> 28761<caption class="title">
28761Table 218. Delete a job - URL parameters</caption> 28762<colgroup> 28763<col style="width: 25%;"> 28764<col style="width: 25%;"> 28765<col style="width: 25%;"> 28766<col style="width: 25%;"> 28767</colgroup> 28768<thead> 28769<tr> 28770<th class="tableblock halign-left valign-top">Parameter</th> 28771<th class="tableblock halign-left valign-top">Required</th> 28772<th class="tableblock halign-left valign-top">Value</th> 28773<th class="tableblock halign-left valign-top">Description</th> 28774</tr> 28775</thead> 28776<tbody> 28777<tr> 28778<td class="tableblock halign-left valign-top"><p class="tableblock">jobId</p></td> 28779<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28780<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28781<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the job to delete.</p></td> 28782</tr> 28783</tbody> 28784</table> 28785<table class="tableblock frame-all grid-all spread"> 28786<caption class="title">Table 219. Delete a job - Response codes</caption> 28787<colgroup> 28788<col style="width: 50%;"> 28789<col style="width: 50%;"> 28790</colgroup> 28791<thead> 28792<tr> 28793<th class="tableblock halign-left valign-top">Response code</th> 28794<th class="tableblock halign-left valign-top">Description</th> 28795</tr> 28796</thead> 28797<tbody> 28798<tr> 28799<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 28800<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the job was found and has been deleted. Response-body is intentionally empty.</p></td> 28801</tr> 28802<tr> 28803<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28804<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested job was not found.</p></td> 28805</tr> 28806</tbody> 28807</table> 28808</div> 28809<div class="sect3"> 28810<h4 id="_execute_a_single_job">13.13.3. Execute a single job</h4> 28811<div class="listingblock"> 28812<div class="content"> 28813<pre>POST management/jobs/{jobId}</pre> 28814</div> 28815</div> 28816<div class="paragraph"> 28817<p><strong>Body JSON:</strong></p> 28818</div> 28819<div class="listingblock"> 28820<div class="content"> 28821<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 288222 288233</div></td><td class="code"><span></span><span class="tok-p">{</span> 28824 <span class="tok-nt">"action"</span> <span class="tok-p">:</span> <span class="tok-s2">"execute"</span> 28825<span class="tok-p">}</span> 28826</td></tr></table></code></pre> 28827</div> 28828</div> 28829<table class="tableblock frame-all grid-all spread"> 28830<caption class="title">Table 220. Execute a single job - JSON Body parameters</caption> 28831<colgroup> 28832<col style="width: 33.3333%;"> 28833<col style="width: 33.3333%;"> 28834<col style="width: 33.3334%;"> 28835</colgroup> 28836<thead> 28837<tr> 28838<th class="tableblock halign-left valign-top">Parameter</th> 28839<th class="tableblock halign-left valign-top">Description</th> 28840<th class="tableblock halign-left valign-top">Required</th> 28841</tr> 28842</thead> 28843<tbody> 28844<tr> 28845<td class="tableblock halign-left valign-top"><p class="tableblock">action</p></td> 28846<td class="tableblock halign-left valign-top"><p class="tableblock">Action to perform. Only <code>execute</code> is supported.</p></td> 28847<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28848</tr> 28849</tbody> 28850</table> 28851<table class="tableblock frame-all grid-all spread"> 28852<caption class="title">Table 221. Execute a single job - Response codes</caption> 28853<colgroup> 28854<col style="width: 50%;"> 28855<col style="width: 50%;"> 28856</colgroup> 28857<thead> 28858<tr> 28859<th class="tableblock halign-left valign-top">Response code</th> 28860<th class="tableblock halign-left valign-top">Description</th> 28861</tr> 28862</thead> 28863<tbody> 28864<tr> 28865<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 28866<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the job was executed. Response-body is intentionally empty.</p></td> 28867</tr> 28868<tr> 28869<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28870<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested job was not found.</p></td> 28871</tr> 28872<tr> 28873<td class="tableblock halign-left valign-top"><p class="tableblock">500</p></td> 28874<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the an exception occurred while executing the job. The status-description contains additional detail about the error. The full error-stacktrace can be fetched later on if needed.</p></td> 28875</tr> 28876</tbody> 28877</table> 28878</div> 28879<div class="sect3"> 28880<h4 id="_get_the_exception_stacktrace_for_a_job">13.13.4. Get the exception stacktrace for a job</h4> 28881<div class="listingblock"> 28882<div class="content"> 28883<pre>GET management/jobs/{jobId}/exception-stacktrace</pre> 28884</div> 28885</div> 28886<table class="tableblock frame-all grid-all spread"> 28887<caption class="title">
28887Table 222. Get the exception stacktrace for a job - URL parameters</caption> 28888<colgroup> 28889<col style="width: 33.3333%;"> 28890<col style="width: 33.3333%;"> 28891<col style="width: 33.3334%;"> 28892</colgroup> 28893<thead> 28894<tr> 28895<th class="tableblock halign-left valign-top">Parameter</th> 28896<th class="tableblock halign-left valign-top">Description</th> 28897<th class="tableblock halign-left valign-top">Required</th> 28898</tr> 28899</thead> 28900<tbody> 28901<tr> 28902<td class="tableblock halign-left valign-top"><p class="tableblock">jobId</p></td> 28903<td class="tableblock halign-left valign-top"><p class="tableblock">Id of the job to get the stacktrace for.</p></td> 28904<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 28905</tr> 28906</tbody> 28907</table> 28908<table class="tableblock frame-all grid-all spread"> 28909<caption class="title">Table 223. Get the exception stacktrace for a job - Response codes</caption> 28910<colgroup> 28911<col style="width: 50%;"> 28912<col style="width: 50%;"> 28913</colgroup> 28914<thead> 28915<tr> 28916<th class="tableblock halign-left valign-top">Response code</th> 28917<th class="tableblock halign-left valign-top">Description</th> 28918</tr> 28919</thead> 28920<tbody> 28921<tr> 28922<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 28923<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested job was not found and the stacktrace has been returned. The response contains the raw stacktrace and always has a Content-type of <code>text/plain</code>.</p></td> 28924</tr> 28925<tr> 28926<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 28927<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested job was not found or the job doesn’t have an exception stacktrace. Status-description contains additional information about the error.</p></td> 28928</tr> 28929</tbody> 28930</table> 28931</div> 28932<div class="sect3"> 28933<h4 id="_get_a_list_of_jobs">13.13.5. Get a list of jobs</h4> 28934<div class="listingblock"> 28935<div class="content"> 28936<pre>GET management/jobs</pre> 28937</div> 28938</div> 28939<table class="tableblock frame-all grid-all spread"> 28940<caption class="title">Table 224. Get a list of jobs - URL query parameters</caption> 28941<colgroup> 28942<col style="width: 33.3333%;"> 28943<col style="width: 33.3333%;"> 28944<col style="width: 33.3334%;"> 28945</colgroup> 28946<thead> 28947<tr> 28948<th class="tableblock halign-left valign-top">Parameter</th> 28949<th class="tableblock halign-left valign-top">Description</th> 28950<th class="tableblock halign-left valign-top">Type</th> 28951</tr> 28952</thead> 28953<tbody> 28954<tr> 28955<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 28956<td class="tableblock halign-left valign-top"><p class="tableblock">Only return job with the given id</p></td> 28957<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28958</tr> 28959<tr> 28960<td class="tableblock halign-left valign-top"><p class="tableblock">processInstanceId</p></td> 28961<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs part of a process with the given id</p></td> 28962<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28963</tr> 28964<tr> 28965<td class="tableblock halign-left valign-top"><p class="tableblock">executionId</p></td> 28966<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs part of an execution with the given id</p></td> 28967<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28968</tr> 28969<tr> 28970<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitionId</p></td> 28971<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs with the given process definition id</p></td> 28972<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 28973</tr> 28974<tr> 28975<td class="tableblock halign-left valign-top"><p class="tableblock">withRetriesLeft</p></td> 28976<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return jobs with retries left. If false, this parameter is ignored.</p></td> 28977<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 28978</tr> 28979<tr> 28980<td class="tableblock halign-left valign-top"><p class="tableblock">executable</p></td> 28981<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return jobs which are executable. If false, this parameter is ignored.</p></td> 28982<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 28983</tr> 28984<tr> 28985<td class="tableblock halign-left valign-top"><p class="tableblock">timersOnly</p></td> 28986<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return jobs which are timers. If false, this parameter is ignored. Cannot be used together with <code>'messagesOnly'</code>.</p></td> 28987<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 28988</tr> 28989<tr> 28990<td class="tableblock halign-left valign-top"><p class="tableblock">messagesOnly</p></td> 28991<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return jobs which are messages. If false, this parameter is ignored. Cannot be used together with <code>'timersOnly'</code></p></td> 28992<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 28993</tr> 28994<tr> 28995<td class="tableblock halign-left valign-top"><p class="tableblock">withException</p></td> 28996<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only return jobs for which an exception occurred while executing it. If false, this parameter is ignored.</p></td> 28997<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 28998</tr> 28999<tr> 29000<td class="tableblock halign-left valign-top"><p class="tableblock">dueBefore</p></td> 29001<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs which are due to be executed before the given date. Jobs without duedate are never returned using this parameter.</p></td> 29002<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 29003</tr> 29004<tr> 29005<td class="tableblock halign-left valign-top"><p class="tableblock">dueAfter</p></td> 29006<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs which are due to be executed after the given date. Jobs without duedate are never returned using this parameter.</p></td> 29007<td class="tableblock halign-left valign-top"><p class="tableblock">Date</p></td> 29008</tr> 29009<tr> 29010<td class="tableblock halign-left valign-top"><p class="tableblock">exceptionMessage</p></td> 29011<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs with the given exception message</p></td> 29012<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29013</tr> 29014<tr> 29015<td class="tableblock halign-left valign-top"><p class="tableblock">tenantId</p></td> 29016<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 29017<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29018</tr> 29019<tr> 29020<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs with the given tenantId.</p></td> 29021<td class="tableblock halign-left valign-top"><p class="tableblock">tenantIdLike</p></td> 29022<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 29023</tr> 29024<tr> 29025<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29026<td class="tableblock halign-left valign-top"><p class="tableblock">Only return jobs with a tenantId like the given value.</p></td> 29027<td class="tableblock halign-left valign-top"><p class="tableblock">withoutTenantId</p></td> 29028</tr> 29029<tr> 29030<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 29031<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> 29032<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code>, only returns jobs without a tenantId set. If <code>false</code>, the <code>withoutTenantId</code> parameter is ignored.</p></td> 29033</tr> 29034<tr> 29035<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 29036<td class="tableblock halign-left valign-top"><p class="tableblock">Field to sort results on, should be one of <code>id</code>, <code>dueDate</code>, <code>executionId</code>, <code>processInstanceId</code>, <code>retries</code> or <code>tenantId</code>.</p></td> 29037<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29038</tr> 29039</tbody> 29040</table> 29041<div class="paragraph"> 29042<p><strong>Success response body:</strong></p> 29043</div> 29044<div class="listingblock"> 29045<div class="content"> 29046<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 29047 2 29048 3 29049 4 29050 5 29051 6 29052 7 29053 8 29054 9 2905510 2905611 2905712 2905813 2905914 2906015 2906116 2906217 2906318 2906419 2906520 2906621 2906722 2906823 2906924 2907025 2907126</div></td><td class="code"><span></span><span class="tok-p">{</span> 29072 <span class="tok-nt">"data"</span><span class="tok-p">:[</span>
29073 <span class="tok-p">{</span> 29074 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"13"</span><span class="tok-p">,</span> 29075 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/management/jobs/13"</span><span class="tok-p">,</span> 29076 <span class="tok-nt">"processInstanceId"</span><span class="tok-p">:</span><span class="tok-s2">"5"</span><span class="tok-p">,</span> 29077 <span class="tok-nt">"processInstanceUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/process-instances/5"</span><span class="tok-p">,</span> 29078 <span class="tok-nt">"processDefinitionId"</span><span class="tok-p">:</span><span class="tok-s2">"timerProcess:1:4"</span><span class="tok-p">,</span> 29079 <span class="tok-nt">"processDefinitionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/repository/process-definitions/timerProcess%3A1%3A4"</span><span class="tok-p">,</span> 29080 <span class="tok-nt">"executionId"</span><span class="tok-p">:</span><span class="tok-s2">"12"</span><span class="tok-p">,</span> 29081 <span class="tok-nt">"executionUrl"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/runtime/executions/12"</span><span class="tok-p">,</span> 29082 <span class="tok-nt">"retries"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 29083 <span class="tok-nt">"exceptionMessage"</span><span class="tok-p">:</span><span class="tok-s2">"Can't find scripting engine for 'unexistinglanguage'"</span><span class="tok-p">,</span> 29084 <span class="tok-nt">"dueDate"</span><span class="tok-p">:</span><span class="tok-s2">"2013-06-07T10:00:24.653+0000"</span><span class="tok-p">,</span> 29085 <span class="tok-nt">"tenantId"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 29086 <span class="tok-p">}</span> 29087 29088 29089 29090 <span class="tok-p">],</span> 29091 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">2</span><span class="tok-p">,</span> 29092 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 29093 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"id"</span><span class="tok-p">,</span> 29094 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 29095 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">2</span> 29096<span class="tok-p">}</span> 29097</td></tr></table></code></pre> 29098</div> 29099</div> 29100<table class="tableblock frame-all grid-all spread"> 29101<caption class="title">Table 225. Get a list of jobs - Response codes</caption> 29102<colgroup> 29103<col style="width: 50%;"> 29104<col style="width: 50%;"> 29105</colgroup> 29106<thead> 29107<tr> 29108<th class="tableblock halign-left valign-top">Response code</th> 29109<th class="tableblock halign-left valign-top">Description</th> 29110</tr> 29111</thead> 29112<tbody> 29113<tr> 29114<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29115<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested jobs were returned.</p></td> 29116</tr> 29117<tr> 29118<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 29119<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates an illegal value has been used in a url query parameter or the both <code>'messagesOnly'</code> and <code>'timersOnly'</code> are used as parameters. Status description contains additional details about the error.</p></td> 29120</tr> 29121</tbody> 29122</table> 29123</div> 29124</div> 29125<div class="sect2"> 29126<h3 id="_users">13.14. Users</h3> 29127<div class="sect3"> 29128<h4 id="_get_a_single_user">13.14.1. Get a single user</h4> 29129<div class="listingblock"> 29130<div class="content"> 29131<pre>GET identity/users/{userId}</pre> 29132</div> 29133</div> 29134<table class="tableblock frame-all grid-all spread"> 29135<caption class="title">Table 226. Get a single user - URL parameters</caption> 29136<colgroup> 29137<col style="width: 25%;"> 29138<col style="width: 25%;"> 29139<col style="width: 25%;"> 29140<col style="width: 25%;"> 29141</colgroup> 29142<thead> 29143<tr> 29144<th class="tableblock halign-left valign-top">Parameter</th> 29145<th class="tableblock halign-left valign-top">Required</th> 29146<th class="tableblock halign-left valign-top">Value</th> 29147<th class="tableblock halign-left valign-top">Description</th> 29148</tr> 29149</thead> 29150<tbody> 29151<tr> 29152<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29153<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29154<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29155<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to get.</p></td> 29156</tr> 29157</tbody> 29158</table> 29159<div class="paragraph"> 29160<p><strong>Success response body:</strong></p> 29161</div> 29162<div class="listingblock"> 29163<div class="content"> 29164<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 291652 291663 291674 291685 291696 291707</div></td><td class="code"><span></span><span class="tok-p">{</span> 29171 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"testuser"</span><span class="tok-p">,</span> 29172 <span class="tok-nt">"firstName"</span><span class="tok-p">:</span><span class="tok-s2">"Fred"</span><span class="tok-p">,</span> 29173 <span class="tok-nt">"lastName"</span><span class="tok-p">:</span><span class="tok-s2">"McDonald"</span><span class="tok-p">,</span> 29174 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser"</span><span class="tok-p">,</span> 29175 <span class="tok-nt">"email"</span><span class="tok-p">:</span><span class="tok-s2">"[email protected]"</span> 29176<span class="tok-p">}</span> 29177</td></tr></table></code></pre> 29178</div> 29179</div> 29180<table class="tableblock frame-all grid-all spread"> 29181<caption class="title">Table 227. Get a single user - Response codes</caption> 29182<colgroup> 29183<col style="width: 50%;"> 29184<col style="width: 50%;"> 29185</colgroup> 29186<thead> 29187<tr> 29188<th class="tableblock halign-left valign-top">Response code</th> 29189<th class="tableblock halign-left valign-top">Description</th> 29190</tr> 29191</thead> 29192<tbody> 29193<tr> 29194<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29195<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user exists and is returned.</p></td> 29196</tr> 29197<tr> 29198<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29199<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user does not exist.</p></td> 29200</tr> 29201</tbody> 29202</table> 29203</div> 29204<div class="sect3"> 29205<h4 id="_get_a_list_of_users">13.14.2. Get a list of users</h4> 29206<div class="listingblock"> 29207<div class="content"> 29208<pre>GET identity/users</pre> 29209</div> 29210</div> 29211<table class="tableblock frame-all grid-all spread"> 29212<caption class="title">Table 228. Get a list of users - URL query parameters</caption> 29213<colgroup> 29214<col style="width: 33.3333%;"> 29215<col style="width: 33.3333%;"> 29216<col style="width: 33.3334%;"> 29217</colgroup> 29218<thead> 29219<tr> 29220<th class="tableblock halign-left valign-top">Parameter</th> 29221<th class="tableblock halign-left valign-top">Description</th> 29222<th class="tableblock halign-left valign-top">Type</th> 29223</tr> 29224</thead> 29225<tbody> 29226<tr> 29227<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 29228<td class="tableblock halign-left valign-top"><p class="tableblock">Only return user with the given id</p></td> 29229<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29230</tr> 29231<tr> 29232<td class="tableblock halign-left valign-top"><p class="tableblock">firstName</p></td> 29233<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users with the given firstname</p></td> 29234<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29235</tr> 29236<tr> 29237<td class="tableblock halign-left valign-top"><p class="tableblock">lastName</p></td> 29238<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users with the given lastname</p></td> 29239<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29240</tr> 29241<tr> 29242<td class="tableblock halign-left valign-top"><p class="tableblock">email</p></td> 29243<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users with the given email</p></td> 29244<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29245</tr> 29246<tr> 29247<td class="tableblock halign-left valign-top"><p class="tableblock">firstNameLike</p></td> 29248<td class="tableblock halign-left valign-top"><p class="tableblock">Only return userswith a firstname like the given value. Use <code>%</code> as wildcard-character.</p></td> 29249<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29250</tr> 29251<tr> 29252<td class="tableblock halign-left valign-top"><p class="tableblock">lastNameLike</p></td> 29253<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users with a lastname like the given value. Use <code>%</code> as wildcard-character.</p></td> 29254<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29255</tr> 29256<tr> 29257<td class="tableblock halign-left valign-top"><p class="tableblock">emailLike</p></td> 29258<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users with an email like the given value. Use <code>%</code> as wildcard-character.</p></td> 29259<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29260</tr> 29261<tr> 29262<td class="tableblock halign-left valign-top"><p class="tableblock">memberOfGroup</p></td> 29263<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users which are a member of the given group.</p></td> 29264<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29265</tr> 29266<tr> 29267<td class="tableblock halign-left valign-top"><p class="tableblock">potentialStarter</p></td> 29268<td class="tableblock halign-left valign-top"><p class="tableblock">Only return users which are potential starters for a process-definition with the given id.</p></td> 29269<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29270</tr> 29271<tr> 29272<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 29273<td class="tableblock halign-left valign-top"><p class="tableblock">Field to sort results on, should be one of <code>id</code>, <code>firstName</code>, <code>lastname</code> or <code>email</code>.</p></td> 29274<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29275</tr> 29276</tbody> 29277</table> 29278<div class="paragraph"> 29279<p><strong>Success response body:</strong></p> 29280</div> 29281<div class="listingblock"> 29282<div class="content"> 29283<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 29284 2 29285 3 29286 4 29287 5 29288 6 29289 7 29290 8 29291 9 2929210 2929311 2929412 2929513 2929614 2929715 2929816 2929917 2930018 2930119 2930220 2930321 2930422 2930523 2930624 2930725 2930826 2930927 2931028 2931129 2931230</div></td><td class="code"><span></span><span class="tok-p">{</span> 29313 <span class="tok-nt">"data"</span><span class="tok-p">:[</span>
29314 <span class="tok-p">{</span> 29315 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"anotherUser"</span><span class="tok-p">,</span> 29316 <span class="tok-nt">"firstName"</span><span class="tok-p">:</span><span class="tok-s2">"Tijs"</span><span class="tok-p">,</span> 29317 <span class="tok-nt">"lastName"</span><span class="tok-p">:</span><span class="tok-s2">"Barrez"</span><span class="tok-p">,</span> 29318 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/anotherUser"</span><span class="tok-p">,</span> 29319 <span class="tok-nt">"email"</span><span class="tok-p">:</span><span class="tok-s2">"[email protected]"</span> 29320 <span class="tok-p">},</span> 29321 <span class="tok-p">{</span> 29322 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 29323 <span class="tok-nt">"firstName"</span><span class="tok-p">:</span><span class="tok-s2">"Kermit"</span><span class="tok-p">,</span> 29324 <span class="tok-nt">"lastName"</span><span class="tok-p">:</span><span class="tok-s2">"the Frog"</span><span class="tok-p">,</span> 29325 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/kermit"</span><span class="tok-p">,</span> 29326 <span class="tok-nt">"email"</span><span class="tok-p">:</span><span class="tok-kc">null</span> 29327 <span class="tok-p">},</span> 29328 <span class="tok-p">{</span> 29329 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"testuser"</span><span class="tok-p">,</span> 29330 <span class="tok-nt">"firstName"</span><span class="tok-p">:</span><span class="tok-s2">"Fred"</span><span class="tok-p">,</span> 29331 <span class="tok-nt">"lastName"</span><span class="tok-p">:</span><span class="tok-s2">"McDonald"</span><span class="tok-p">,</span> 29332 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser"</span><span class="tok-p">,</span> 29333 <span class="tok-nt">"email"</span><span class="tok-p">:</span><span class="tok-s2">"[email protected]"</span> 29334 <span class="tok-p">}</span> 29335 <span class="tok-p">],</span> 29336 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">3</span><span class="tok-p">,</span> 29337 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 29338 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"id"</span><span class="tok-p">,</span> 29339 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 29340 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">3</span> 29341<span class="tok-p">}</span> 29342</td></tr></table></code></pre> 29343</div> 29344</div> 29345<table class="tableblock frame-all grid-all spread"> 29346<caption class="title">Table 229. Get a list of users - Response codes</caption> 29347<colgroup> 29348<col style="width: 50%;"> 29349<col style="width: 50%;"> 29350</colgroup> 29351<thead> 29352<tr> 29353<th class="tableblock halign-left valign-top">Response code</th> 29354<th class="tableblock halign-left valign-top">Description</th> 29355</tr> 29356</thead> 29357<tbody> 29358<tr> 29359<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29360<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested users were returned.</p></td> 29361</tr> 29362</tbody> 29363</table> 29364</div> 29365<div class="sect3"> 29366<h4 id="_update_a_user">13.14.3. Update a user</h4> 29367<div class="listingblock"> 29368<div class="content"> 29369<pre>PUT identity/users/{userId}</pre> 29370</div> 29371</div> 29372<div class="paragraph"> 29373<p><strong>Body JSON:</strong></p> 29374</div> 29375<div class="listingblock"> 29376<div class="content"> 29377<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 293782 293793 293804 293815 293826</div></td><td class="code"><span></span><span class="tok-p">{</span> 29383 <span class="tok-nt">"firstName"</span><span class="tok-p">:</span><span class="tok-s2">"Tijs"</span><span class="tok-p">,</span> 29384 <span class="tok-nt">"lastName"</span><span class="tok-p">:</span><span class="tok-s2">"Barrez"</span><span class="tok-p">,</span> 29385 <span class="tok-nt">"email"</span><span class="tok-p">:</span><span class="tok-s2">"[email protected]"</span><span class="tok-p">,</span> 29386 <span class="tok-nt">"password"</span><span class="tok-p">:</span><span class="tok-s2">"pass123"</span> 29387<span class="tok-p">}</span> 29388</td></tr></table></code></pre> 29389</div> 29390</div> 29391<div class="paragraph"> 29392<p>All request values are optional. For example, you can only include the <em>firstName</em> attribute in the request body JSON-object, only updating the firstName of the user, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the user-value will be updated to null. Example: <code>{"firstName" : null}</code> will clear the firstName of the user).</p> 29393</div> 29394<table class="tableblock frame-all grid-all spread"> 29395<caption class="title">Table 230. Update a user - Response codes</caption> 29396<colgroup> 29397<col style="width: 50%;"> 29398<col style="width: 50%;"> 29399</colgroup> 29400<thead> 29401<tr> 29402<th class="tableblock halign-left valign-top">Response code</th> 29403<th class="tableblock halign-left valign-top">Description</th> 29404</tr> 29405</thead> 29406<tbody> 29407<tr> 29408<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29409<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was updated.</p></td> 29410</tr> 29411<tr> 29412<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29413<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found.</p></td> 29414</tr> 29415<tr> 29416<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 29417<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was updated simultaneously.</p></td> 29418</tr> 29419</tbody> 29420</table> 29421<div class="paragraph"> 29422<p><strong>Success response body:</strong> see response for <code>identity/users/{userId}</code>.</p> 29423</div> 29424</div> 29425<div class="sect3"> 29426<h4 id="_create_a_user">13.14.4. Create a user</h4> 29427<div class="listingblock"> 29428<div class="content"> 29429<pre>POST identity/users</pre> 29430</div> 29431</div> 29432<div class="paragraph"> 29433<p><strong>Body JSON:</strong></p> 29434</div> 29435<div class="listingblock"> 29436<div class="content"> 29437<pre>{ 29438 "id":"tijs", 29439 "firstName":"Tijs", 29440 "lastName":"Barrez", 29441 "email":"[email protected]", 29442 "password":"pass123" 29443}</pre> 29444</div> 29445</div> 29446<table class="tableblock frame-all grid-all spread"> 29447<caption class="title">Table 231. Create a user - Response codes</caption> 29448<colgroup> 29449<col style="width: 50%;"> 29450<col style="width: 50%;"> 29451</colgroup> 29452<thead> 29453<tr> 29454<th class="tableblock halign-left valign-top">Response code</th> 29455<th class="tableblock halign-left valign-top">Description</th> 29456</tr> 29457</thead> 29458<tbody> 29459<tr> 29460<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 29461<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was created.</p></td> 29462</tr> 29463<tr> 29464<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 29465<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the id of the user was missing.</p></td> 29466</tr> 29467</tbody> 29468</table> 29469<div class="paragraph"> 29470<p><strong>Success response body:</strong> see response for <code>identity/users/{userId}</code>.</p> 29471</div> 29472</div> 29473<div class="sect3"> 29474<h4 id="_delete_a_user">13.14.5. Delete a user</h4> 29475<div class="listingblock"> 29476<div class="content"> 29477<pre>DELETE identity/users/{userId}</pre> 29478</div> 29479</div> 29480<table class="tableblock frame-all grid-all spread"> 29481<caption class="title">Table 232. Delete a user - URL parameters</caption> 29482<colgroup> 29483<col style="width: 25%;"> 29484<col style="width: 25%;"> 29485<col style="width: 25%;"> 29486<col style="width: 25%;"> 29487</colgroup> 29488<thead> 29489<tr> 29490<th class="tableblock halign-left valign-top">Parameter</th> 29491<th class="tableblock halign-left valign-top">Required</th> 29492<th class="tableblock halign-left valign-top">Value</th> 29493<th class="tableblock halign-left valign-top">Description</th> 29494</tr> 29495</thead> 29496<tbody> 29497<tr> 29498<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29499<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29500<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29501<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to delete.</p></td> 29502</tr> 29503</tbody> 29504</table> 29505<table class="tableblock frame-all grid-all spread"> 29506<caption class="title">Table 233. Delete a user - Response codes</caption> 29507<colgroup> 29508<col style="width: 50%;"> 29509<col style="width: 50%;"> 29510</colgroup> 29511<thead> 29512<tr> 29513<th class="tableblock halign-left valign-top">Response code</th> 29514<th class="tableblock halign-left valign-top">Description</th> 29515</tr> 29516</thead> 29517<tbody> 29518<tr> 29519<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 29520<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and has been deleted. Response-body is intentionally empty.</p></td> 29521</tr> 29522<tr> 29523<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29524<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found.</p></td> 29525</tr> 29526</tbody> 29527</table> 29528</div> 29529<div class="sect3"> 29530<h4 id="_get_a_user_s_picture">13.14.6. Get a user’s picture</h4> 29531<div class="listingblock"> 29532<div class="content"> 29533<pre>GET identity/users/{userId}/picture</pre> 29534</div> 29535</div> 29536<table class="tableblock frame-all grid-all spread"> 29537<caption class="title">Table 234. Get a user’
29537s picture - URL parameters</caption> 29538<colgroup> 29539<col style="width: 25%;"> 29540<col style="width: 25%;"> 29541<col style="width: 25%;"> 29542<col style="width: 25%;"> 29543</colgroup> 29544<thead> 29545<tr> 29546<th class="tableblock halign-left valign-top">Parameter</th> 29547<th class="tableblock halign-left valign-top">Required</th> 29548<th class="tableblock halign-left valign-top">Value</th> 29549<th class="tableblock halign-left valign-top">Description</th> 29550</tr> 29551</thead> 29552<tbody> 29553<tr> 29554<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29555<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29556<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29557<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to get the picture for.</p></td> 29558</tr> 29559</tbody> 29560</table> 29561<div class="paragraph"> 29562<p><strong>Response Body:</strong></p> 29563</div> 29564<div class="paragraph"> 29565<p>The response body contains the raw picture data, representing the user’s picture. The Content-type of the response corresponds to the mimeType that was set when creating the picture.</p> 29566</div> 29567<table class="tableblock frame-all grid-all spread"> 29568<caption class="title">Table 235. Get a user’s picture - Response codes</caption> 29569<colgroup> 29570<col style="width: 50%;"> 29571<col style="width: 50%;"> 29572</colgroup> 29573<thead> 29574<tr> 29575<th class="tableblock halign-left valign-top">Response code</th> 29576<th class="tableblock halign-left valign-top">Description</th> 29577</tr> 29578</thead> 29579<tbody> 29580<tr> 29581<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29582<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and has a picture, which is returned in the body.</p></td> 29583</tr> 29584<tr> 29585<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29586<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found or the user does not have a profile picture. Status-description contains additional information about the error.</p></td> 29587</tr> 29588</tbody> 29589</table> 29590</div> 29591<div class="sect3"> 29592<h4 id="_updating_a_user_s_picture">13.14.7. Updating a user’s picture</h4> 29593<div class="listingblock"> 29594<div class="content"> 29595<pre>GET identity/users/{userId}/picture</pre> 29596</div> 29597</div> 29598<table class="tableblock frame-all grid-all spread"> 29599<caption class="title">Table 236. Updating a user’s picture - URL parameters</caption> 29600<colgroup> 29601<col style="width: 25%;"> 29602<col style="width: 25%;"> 29603<col style="width: 25%;"> 29604<col style="width: 25%;"> 29605</colgroup> 29606<thead> 29607<tr> 29608<th class="tableblock halign-left valign-top">Parameter</th> 29609<th class="tableblock halign-left valign-top">Required</th> 29610<th class="tableblock halign-left valign-top">Value</th> 29611<th class="tableblock halign-left valign-top">Description</th> 29612</tr> 29613</thead> 29614<tbody> 29615<tr> 29616<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29617<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29618<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29619<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to get the picture for.</p></td> 29620</tr> 29621</tbody> 29622</table> 29623<div class="paragraph"> 29624<p><strong>Request body:</strong></p> 29625</div> 29626<div class="paragraph"> 29627<p>The request should be of type <code>multipart/form-data</code>. There should be a single file-part included with the binary value of the picture. On top of that, the following additional form-fields can be present:</p> 29628</div> 29629<div class="ulist"> 29630<ul> 29631<li> 29632<p><code>mimeType</code>: Optional mime-type for the uploaded picture. If omitted, the default of <code>image/jpeg</code> is used as a mime-type for the picture.</p> 29633</li> 29634</ul> 29635</div> 29636<table class="tableblock frame-all grid-all spread"> 29637<caption class="title">Table 237. Updating a user’s picture - Response codes</caption> 29638<colgroup> 29639<col style="width: 50%;"> 29640<col style="width: 50%;"> 29641</colgroup> 29642<thead> 29643<tr> 29644<th class="tableblock halign-left valign-top">Response code</th> 29645<th class="tableblock halign-left valign-top">Description</th> 29646</tr> 29647</thead> 29648<tbody> 29649<tr> 29650<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29651<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and the picture has been updated. The response-body is left empty intentionally.</p></td> 29652</tr> 29653<tr> 29654<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29655<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found.</p></td> 29656</tr> 29657</tbody> 29658</table> 29659</div> 29660<div class="sect3"> 29661<h4 id="_list_a_user_s_info">13.14.8. List a user’s info</h4> 29662<div class="listingblock"> 29663<div class="content"> 29664<pre>PUT identity/users/{userId}/info</pre> 29665</div> 29666</div> 29667<table class="tableblock frame-all grid-all spread"> 29668<caption class="title">Table 238. List a user’s info - URL parameters</caption> 29669<colgroup> 29670<col style="width: 25%;"> 29671<col style="width: 25%;"> 29672<col style="width: 25%;"> 29673<col style="width: 25%;"> 29674</colgroup> 29675<thead> 29676<tr> 29677<th class="tableblock halign-left valign-top">Parameter</th> 29678<th class="tableblock halign-left valign-top">Required</th> 29679<th class="tableblock halign-left valign-top">Value</th> 29680<th class="tableblock halign-left valign-top">Description</th> 29681</tr> 29682</thead> 29683<tbody> 29684<tr> 29685<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29686<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29687<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29688<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to get the info for.</p></td> 29689</tr> 29690</tbody> 29691</table> 29692<div class="paragraph"> 29693<p><strong>Response Body:</strong></p> 29694</div> 29695<div class="listingblock"> 29696<div class="content"> 29697<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 29698 2 29699 3 29700 4 29701 5 29702 6 29703 7 29704 8 29705 9 2970610</div></td><td class="code"><span></span><span class="tok-p">[</span> 29707 <span class="tok-p">{</span>
29708 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"key1"</span><span class="tok-p">,</span> 29709 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser/info/key1"</span> 29710 <span class="tok-p">},</span> 29711 <span class="tok-p">{</span> 29712 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"key2"</span><span class="tok-p">,</span> 29713 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser/info/key2"</span> 29714 <span class="tok-p">}</span> 29715<span class="tok-p">]</span> 29716</td></tr></table></code></pre> 29717</div> 29718</div> 29719<table class="tableblock frame-all grid-all spread"> 29720<caption class="title">Table 239. List a user’s info - Response codes</caption> 29721<colgroup> 29722<col style="width: 50%;"> 29723<col style="width: 50%;"> 29724</colgroup> 29725<thead> 29726<tr> 29727<th class="tableblock halign-left valign-top">Response code</th> 29728<th class="tableblock halign-left valign-top">Description</th> 29729</tr> 29730</thead> 29731<tbody> 29732<tr> 29733<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29734<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and list of info (key and url) is returned.</p></td> 29735</tr> 29736<tr> 29737<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29738<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found.</p></td> 29739</tr> 29740</tbody> 29741</table> 29742</div> 29743<div class="sect3"> 29744<h4 id="_get_a_user_s_info">13.14.9. Get a user’s info</h4> 29745<div class="listingblock"> 29746<div class="content"> 29747<pre>GET identity/users/{userId}/info/{key}</pre> 29748</div> 29749</div> 29750<table class="tableblock frame-all grid-all spread"> 29751<caption class="title">Table 240. Get a user’s info - URL parameters</caption> 29752<colgroup> 29753<col style="width: 25%;"> 29754<col style="width: 25%;"> 29755<col style="width: 25%;"> 29756<col style="width: 25%;"> 29757</colgroup> 29758<thead> 29759<tr> 29760<th class="tableblock halign-left valign-top">Parameter</th> 29761<th class="tableblock halign-left valign-top">Required</th> 29762<th class="tableblock halign-left valign-top">Value</th> 29763<th class="tableblock halign-left valign-top">Description</th> 29764</tr> 29765</thead> 29766<tbody> 29767<tr> 29768<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29769<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29770<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29771<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to get the info for.</p></td> 29772</tr> 29773<tr> 29774<td class="tableblock halign-left valign-top"><p class="tableblock">key</p></td> 29775<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29776<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29777<td class="tableblock halign-left valign-top"><p class="tableblock">The key of the user info to get.</p></td> 29778</tr> 29779</tbody> 29780</table> 29781<div class="paragraph"> 29782<p><strong>Response Body:</strong></p> 29783</div> 29784<div class="listingblock"> 29785<div class="content"> 29786<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 297872 297883 297894 297905</div></td><td class="code"><span></span><span class="tok-p">{</span> 29791 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"key1"</span><span class="tok-p">,</span> 29792 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"Value 1"</span><span class="tok-p">,</span> 29793 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser/info/key1"</span> 29794<span class="tok-p">}</span> 29795</td></tr></table></code></pre> 29796</div> 29797</div> 29798<table class="tableblock frame-all grid-all spread"> 29799<caption class="title">Table 241. Get a user’s info - Response codes</caption> 29800<colgroup> 29801<col style="width: 50%;"> 29802<col style="width: 50%;"> 29803</colgroup> 29804<thead> 29805<tr> 29806<th class="tableblock halign-left valign-top">Response code</th> 29807<th class="tableblock halign-left valign-top">Description</th> 29808</tr> 29809</thead> 29810<tbody> 29811<tr> 29812<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29813<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and the user has info for the given key..</p></td> 29814</tr> 29815<tr> 29816<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29817<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found or the user doesn’t have info for the given key. Status description contains additional information about the error.</p></td> 29818</tr> 29819</tbody> 29820</table> 29821</div> 29822<div class="sect3"> 29823<h4 id="_update_a_user_s_info">13.14.10. Update a user’s info</h4> 29824<div class="listingblock"> 29825<div class="content"> 29826<pre>PUT identity/users/{userId}/info/{key}</pre> 29827</div> 29828</div> 29829<table class="tableblock frame-all grid-all spread"> 29830<caption class="title">Table 242. Update a user’s info - URL parameters</caption> 29831<colgroup> 29832<col style="width: 25%;"> 29833<col style="width: 25%;"> 29834<col style="width: 25%;"> 29835<col style="width: 25%;"> 29836</colgroup> 29837<thead> 29838<tr> 29839<th class="tableblock halign-left valign-top">Parameter</th> 29840<th class="tableblock halign-left valign-top">Required</th> 29841<th class="tableblock halign-left valign-top">Value</th> 29842<th class="tableblock halign-left valign-top">Description</th> 29843</tr> 29844</thead> 29845<tbody> 29846<tr> 29847<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29848<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29849<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29850<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to update the info for.</p></td> 29851</tr> 29852<tr> 29853<td class="tableblock halign-left valign-top"><p class="tableblock">key</p></td> 29854<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29855<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29856<td class="tableblock halign-left valign-top"><p class="tableblock">The key of the user info to update.</p></td> 29857</tr> 29858</tbody> 29859</table> 29860<div class="paragraph"> 29861<p><strong>Request Body:</strong></p> 29862</div> 29863<div class="listingblock"> 29864<div class="content"> 29865<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 298662 298673</div></td><td class="code"><span></span><span class="tok-p">{</span> 29868 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"The updated value"</span> 29869<span class="tok-p">}</span> 29870</td></tr></table></code></pre> 29871</div> 29872</div> 29873<div class="paragraph"> 29874<p><strong>Response Body:</strong></p> 29875</div> 29876<div class="listingblock"> 29877<div class="content"> 29878<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 298792 298803 298814 298825</div></td><td class="code"><span></span><span class="tok-p">{</span> 29883 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"key1"</span><span class="tok-p">,</span> 29884 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"The updated value"</span><span class="tok-p">,</span> 29885 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser/info/key1"</span> 29886<span class="tok-p">}</span> 29887</td></tr></table></code></pre> 29888</div> 29889</div> 29890<table class="tableblock frame-all grid-all spread"> 29891<caption class="title">Table 243. Update a user’s info - Response codes</caption> 29892<colgroup> 29893<col style="width: 50%;"> 29894<col style="width: 50%;"> 29895</colgroup> 29896<thead> 29897<tr> 29898<th class="tableblock halign-left valign-top">Response code</th> 29899<th class="tableblock halign-left valign-top">Description</th> 29900</tr> 29901</thead> 29902<tbody> 29903<tr> 29904<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 29905<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and the info has been updated.</p></td> 29906</tr> 29907<tr> 29908<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 29909<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the value was missing from the request body.</p></td> 29910</tr> 29911<tr> 29912<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 29913<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found or the user doesn’t have info for the given key. Status description contains additional information about the error.</p></td> 29914</tr> 29915</tbody> 29916</table> 29917</div> 29918<div class="sect3"> 29919<h4 id="_create_a_new_user_s_info_entry">13.14.11. Create a new user’s info entry</h4> 29920<div class="listingblock"> 29921<div class="content"> 29922<pre>POST identity/users/{userId}/info</pre> 29923</div> 29924</div> 29925<table class="tableblock frame-all grid-all spread"> 29926<caption class="title">Table 244. Create a new user’s info entry - URL parameters</caption> 29927<colgroup> 29928<col style="width: 25%;"> 29929<col style="width: 25%;"> 29930<col style="width: 25%;"> 29931<col style="width: 25%;"> 29932</colgroup> 29933<thead> 29934<tr> 29935<th class="tableblock halign-left valign-top">Parameter</th> 29936<th class="tableblock halign-left valign-top">Required</th> 29937<th class="tableblock halign-left valign-top">Value</th> 29938<th class="tableblock halign-left valign-top">Description</th> 29939</tr> 29940</thead> 29941<tbody> 29942<tr> 29943<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 29944<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 29945<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 29946<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to create the info for.</p></td> 29947</tr> 29948</tbody> 29949</table> 29950<div class="paragraph"> 29951<p><strong>Request Body:</strong></p> 29952</div> 29953<div class="listingblock"> 29954<div class="content"> 29955<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 299562 299573 299584</div></td><td class="code"><span></span><span class="tok-p">{</span> 29959 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"key1"</span><span class="tok-p">,</span> 29960 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"The value"</span> 29961<span class="tok-p">}</span> 29962</td></tr></table></code></pre> 29963</div> 29964</div> 29965<div class="paragraph"> 29966<p><strong>Response Body:</strong></p> 29967</div> 29968<div class="listingblock"> 29969<div class="content"> 29970<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 299712 299723 299734 299745</div></td><td class="code"><span></span><span class="tok-p">{</span> 29975 <span class="tok-nt">"key"</span><span class="tok-p">:</span><span class="tok-s2">"key1"</span><span class="tok-p">,</span> 29976 <span class="tok-nt">"value"</span><span class="tok-p">:</span><span class="tok-s2">"The value"</span><span class="tok-p">,</span> 29977 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/users/testuser/info/key1"</span> 29978<span class="tok-p">}</span> 29979</td></tr></table></code></pre> 29980</div> 29981</div> 29982<table class="tableblock frame-all grid-all spread"> 29983<caption class="title">Table 245. Create a new user’s info entry - Response codes</caption> 29984<colgroup> 29985<col style="width: 50%;"> 29986<col style="width: 50%;"> 29987</colgroup> 29988<thead> 29989<tr> 29990<th class="tableblock halign-left valign-top">Response code</th> 29991<th class="tableblock halign-left valign-top">Description</th> 29992</tr> 29993</thead> 29994<tbody> 29995<tr> 29996<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 29997<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and the info has been created.</p></td> 29998</tr> 29999<tr> 30000<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 30001<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the key or value was missing from the request body. Status description contains additional information about the error.</p></td> 30002</tr> 30003<tr> 30004<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30005<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found.</p></td> 30006</tr> 30007<tr> 30008<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 30009<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates there is already an info-entry with the given key for the user, update the resource instance (<code>PUT</code>).</p></td> 30010</tr> 30011</tbody> 30012</table> 30013</div> 30014<div class="sect3"> 30015<h4 id="_delete_a_user_s_info">13.14.12. Delete a user’s info</h4> 30016<div class="listingblock"> 30017<div class="content"> 30018<pre>DELETE identity/users/{userId}/info/{key}</pre> 30019</div> 30020</div> 30021<table class="tableblock frame-all grid-all spread"> 30022<caption class="title">Table 246. Delete a user’s info - URL parameters</caption> 30023<colgroup> 30024<col style="width: 25%;"> 30025<col style="width: 25%;"> 30026<col style="width: 25%;"> 30027<col style="width: 25%;"> 30028</colgroup> 30029<thead> 30030<tr> 30031<th class="tableblock halign-left valign-top">Parameter</th> 30032<th class="tableblock halign-left valign-top">Required</th> 30033<th class="tableblock halign-left valign-top">Value</th> 30034<th class="tableblock halign-left valign-top">Description</th> 30035</tr> 30036</thead> 30037<tbody> 30038<tr> 30039<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 30040<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30041<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30042<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to delete the info for.</p></td> 30043</tr> 30044<tr> 30045<td class="tableblock halign-left valign-top"><p class="tableblock">key</p></td> 30046<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30047<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30048<td class="tableblock halign-left valign-top"><p class="tableblock">The key of the user info to delete.</p></td> 30049</tr> 30050</tbody> 30051</table> 30052<table class="tableblock frame-all grid-all spread"> 30053<caption class="title">Table 247. Delete a user’s info - Response codes</caption> 30054<colgroup> 30055<col style="width: 50%;"> 30056<col style="width: 50%;"> 30057</colgroup> 30058<thead> 30059<tr> 30060<th class="tableblock halign-left valign-top">Response code</th> 30061<th class="tableblock halign-left valign-top">Description</th> 30062</tr> 30063</thead> 30064<tbody> 30065<tr> 30066<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 30067<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the user was found and the info for the given key has been deleted. Response body is left empty intentionally.</p></td> 30068</tr> 30069<tr> 30070<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30071<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user was not found or the user doesn’t have info for the given key. Status description contains additional information about the error.</p></td> 30072</tr> 30073</tbody> 30074</table> 30075</div> 30076</div> 30077<div class="sect2"> 30078<h3 id="_groups">13.15. Groups</h3> 30079<div class="sect3"> 30080<h4 id="_get_a_single_group">13.15.1. Get a single group</h4> 30081<div class="listingblock"> 30082<div class="content"> 30083<pre>GET identity/groups/{groupId}</pre> 30084</div> 30085</div> 30086<table class="tableblock frame-all grid-all spread"> 30087<caption class="title">Table 248. Get a single group - URL parameters</caption> 30088<colgroup> 30089<col style="width: 25%;"> 30090<col style="width: 25%;"> 30091<col style="width: 25%;"> 30092<col style="width: 25%;"> 30093</colgroup> 30094<thead> 30095<tr> 30096<t
30096h class="tableblock halign-left valign-top">Parameter</th> 30097<th class="tableblock halign-left valign-top">Required</th> 30098<th class="tableblock halign-left valign-top">Value</th> 30099<th class="tableblock halign-left valign-top">Description</th> 30100</tr> 30101</thead> 30102<tbody> 30103<tr> 30104<td class="tableblock halign-left valign-top"><p class="tableblock">groupId</p></td> 30105<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30106<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30107<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the group to get.</p></td> 30108</tr> 30109</tbody> 30110</table> 30111<div class="paragraph"> 30112<p><strong>Success response body:</strong></p> 30113</div> 30114<div class="listingblock"> 30115<div class="content"> 30116<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 301172 301183 301194 301205 301216</div></td><td class="code"><span></span><span class="tok-p">{</span> 30122 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"testgroup"</span><span class="tok-p">,</span> 30123 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/groups/testgroup"</span><span class="tok-p">,</span> 30124 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Test group"</span><span class="tok-p">,</span> 30125 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"Test type"</span> 30126<span class="tok-p">}</span> 30127</td></tr></table></code></pre> 30128</div> 30129</div> 30130<table class="tableblock frame-all grid-all spread"> 30131<caption class="title">Table 249. Get a single group - Response codes</caption> 30132<colgroup> 30133<col style="width: 50%;"> 30134<col style="width: 50%;"> 30135</colgroup> 30136<thead> 30137<tr> 30138<th class="tableblock halign-left valign-top">Response code</th> 30139<th class="tableblock halign-left valign-top">Description</th> 30140</tr> 30141</thead> 30142<tbody> 30143<tr> 30144<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 30145<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the group exists and is returned.</p></td> 30146</tr> 30147<tr> 30148<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30149<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested group does not exist.</p></td> 30150</tr> 30151</tbody> 30152</table> 30153</div> 30154<div class="sect3"> 30155<h4 id="_get_a_list_of_groups">13.15.2. Get a list of groups</h4> 30156<div class="listingblock"> 30157<div class="content"> 30158<pre>GET identity/groups</pre> 30159</div> 30160</div> 30161<table class="tableblock frame-all grid-all spread"> 30162<caption class="title">Table 250. Get a list of groups - URL query parameters</caption> 30163<colgroup> 30164<col style="width: 33.3333%;"> 30165<col style="width: 33.3333%;"> 30166<col style="width: 33.3334%;"> 30167</colgroup> 30168<thead> 30169<tr> 30170<th class="tableblock halign-left valign-top">Parameter</th> 30171<th class="tableblock halign-left valign-top">Description</th> 30172<th class="tableblock halign-left valign-top">Type</th> 30173</tr> 30174</thead> 30175<tbody> 30176<tr> 30177<td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td> 30178<td class="tableblock halign-left valign-top"><p class="tableblock">Only return group with the given id</p></td> 30179<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30180</tr> 30181<tr> 30182<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td> 30183<td class="tableblock halign-left valign-top"><p class="tableblock">Only return groups with the given name</p></td> 30184<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30185</tr> 30186<tr> 30187<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td> 30188<td class="tableblock halign-left valign-top"><p class="tableblock">Only return groups with the given type</p></td> 30189<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30190</tr> 30191<tr> 30192<td class="tableblock halign-left valign-top"><p class="tableblock">nameLike</p></td> 30193<td class="tableblock halign-left valign-top"><p class="tableblock">Only return groups with a name like the given value. Use <code>%</code> as wildcard-character.</p></td> 30194<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30195</tr> 30196<tr> 30197<td class="tableblock halign-left valign-top"><p class="tableblock">member</p></td> 30198<td class="tableblock halign-left valign-top"><p class="tableblock">Only return groups which have a member with the given username.</p></td> 30199<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30200</tr> 30201<tr> 30202<td class="tableblock halign-left valign-top"><p class="tableblock">potentialStarter</p></td> 30203<td class="tableblock halign-left valign-top"><p class="tableblock">Only return groups which members are potential starters for a process-definition with the given id.</p></td> 30204<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30205</tr> 30206<tr> 30207<td class="tableblock halign-left valign-top"><p class="tableblock">sort</p></td> 30208<td class="tableblock halign-left valign-top"><p class="tableblock">Field to sort results on, should be one of <code>id</code>, <code>name</code> or <code>type</code>.</p></td> 30209<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30210</tr> 30211</tbody> 30212</table> 30213<div class="paragraph"> 30214<p><strong>Success response body:</strong></p> 30215</div> 30216<div class="listingblock"> 30217<div class="content"> 30218<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 30219 2 30220 3 30221 4 30222 5 30223 6 30224 7 30225 8 30226 9 3022710 3022811 3022912 3023013 3023114 3023215</div></td><td class="code"><span></span><span class="tok-p">{</span> 30233 <span class="tok-nt">"data"</span><span class="tok-p">:[</span> 30234 <span class="tok-p">{</span>
30235 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"testgroup"</span><span class="tok-p">,</span> 30236 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/groups/testgroup"</span><span class="tok-p">,</span> 30237 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Test group"</span><span class="tok-p">,</span> 30238 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"Test type"</span> 30239 <span class="tok-p">}</span> 30240 <span class="tok-p">],</span> 30241 <span class="tok-nt">"total"</span><span class="tok-p">:</span><span class="tok-mi">3</span><span class="tok-p">,</span> 30242 <span class="tok-nt">"start"</span><span class="tok-p">:</span><span class="tok-mi">0</span><span class="tok-p">,</span> 30243 <span class="tok-nt">"sort"</span><span class="tok-p">:</span><span class="tok-s2">"id"</span><span class="tok-p">,</span> 30244 <span class="tok-nt">"order"</span><span class="tok-p">:</span><span class="tok-s2">"asc"</span><span class="tok-p">,</span> 30245 <span class="tok-nt">"size"</span><span class="tok-p">:</span><span class="tok-mi">3</span> 30246<span class="tok-p">}</span> 30247</td></tr></table></code></pre> 30248</div> 30249</div> 30250<table class="tableblock frame-all grid-all spread"> 30251<caption class="title">Table 251. Get a list of groups - Response codes</caption> 30252<colgroup> 30253<col style="width: 50%;"> 30254<col style="width: 50%;"> 30255</colgroup> 30256<thead> 30257<tr> 30258<th class="tableblock halign-left valign-top">Response code</th> 30259<th class="tableblock halign-left valign-top">Description</th> 30260</tr> 30261</thead> 30262<tbody> 30263<tr> 30264<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 30265<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested groups were returned.</p></td> 30266</tr> 30267</tbody> 30268</table> 30269</div> 30270<div class="sect3"> 30271<h4 id="_update_a_group">13.15.3. Update a group</h4> 30272<div class="listingblock"> 30273<div class="content"> 30274<pre>PUT identity/groups/{groupId}</pre> 30275</div> 30276</div> 30277<div class="paragraph"> 30278<p><strong>Body JSON:</strong></p> 30279</div> 30280<div class="listingblock"> 30281<div class="content"> 30282<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 302832 302843 302854</div></td><td class="code"><span></span><span class="tok-p">{</span> 30286 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Test group"</span><span class="tok-p">,</span> 30287 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"Test type"</span> 30288<span class="tok-p">}</span> 30289</td></tr></table></code></pre> 30290</div> 30291</div> 30292<div class="paragraph"> 30293<p>All request values are optional. For example, you can only include the <em>name</em> attribute in the request body JSON-object, only updating the name of the group, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the group-value will be updated to null.</p> 30294</div> 30295<table class="tableblock frame-all grid-all spread"> 30296<caption class="title">Table 252. Update a group - Response codes</caption> 30297<colgroup> 30298<col style="width: 50%;"> 30299<col style="width: 50%;"> 30300</colgroup> 30301<thead> 30302<tr> 30303<th class="tableblock halign-left valign-top">Response code</th> 30304<th class="tableblock halign-left valign-top">Description</th> 30305</tr> 30306</thead> 30307<tbody> 30308<tr> 30309<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> 30310<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the group was updated.</p></td> 30311</tr> 30312<tr> 30313<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30314<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested group was not found.</p></td> 30315</tr> 30316<tr> 30317<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 30318<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested group was updated simultaneously.</p></td> 30319</tr> 30320</tbody> 30321</table> 30322<div class="paragraph"> 30323<p><strong>Success response body:</strong> see response for <code>identity/groups/{groupId}</code>.</p> 30324</div> 30325</div> 30326<div class="sect3"> 30327<h4 id="_create_a_group">13.15.4. Create a group</h4> 30328<div class="listingblock"> 30329<div class="content"> 30330<pre>POST identity/groups</pre> 30331</div> 30332</div> 30333<div class="paragraph"> 30334<p><strong>Body JSON:</strong></p> 30335</div> 30336<div class="listingblock"> 30337<div class="content"> 30338<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 303392 303403 303414 303425</div></td><td class="code"><span></span><span class="tok-p">{</span> 30343 <span class="tok-nt">"id"</span><span class="tok-p">:</span><span class="tok-s2">"testgroup"</span><span class="tok-p">,</span> 30344 <span class="tok-nt">"name"</span><span class="tok-p">:</span><span class="tok-s2">"Test group"</span><span class="tok-p">,</span> 30345 <span class="tok-nt">"type"</span><span class="tok-p">:</span><span class="tok-s2">"Test type"</span> 30346<span class="tok-p">}</span> 30347</td></tr></table></code></pre> 30348</div> 30349</div> 30350<table class="tableblock frame-all grid-all spread"> 30351<caption class="title">Table 253. Create a group - Response codes</caption> 30352<colgroup> 30353<col style="width: 50%;"> 30354<col style="width: 50%;"> 30355</colgroup> 30356<thead> 30357<tr> 30358<th class="tableblock halign-left valign-top">Response code</th> 30359<th class="tableblock halign-left valign-top">Description</th> 30360</tr> 30361</thead> 30362<tbody> 30363<tr> 30364<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 30365<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the group was created.</p></td> 30366</tr> 30367<tr> 30368<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> 30369<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the id of the group was missing.</p></td> 30370</tr> 30371</tbody> 30372</table> 30373<div class="paragraph"> 30374<p><strong>Success response body:</strong> see response for <code>identity/groups/{groupId}</code>.</p> 30375</div> 30376</div> 30377<div class="sect3"> 30378<h4 id="_delete_a_group">13.15.5. Delete a group</h4> 30379<div class="listingblock"> 30380<div class="content"> 30381<pre>DELETE identity/groups/{groupId}</pre> 30382</div> 30383</div> 30384<table class="tableblock frame-all grid-all spread"> 30385<caption class="title">Table 254. Delete a group - URL parameters</caption> 30386<colgroup> 30387<col style="width: 25%;"> 30388<col style="width: 25%;"> 30389<col style="width: 25%;"> 30390<col style="width: 25%;"> 30391</colgroup> 30392<thead> 30393<tr> 30394<th class="tableblock halign-left valign-top">Parameter</th> 30395<th class="tableblock halign-left valign-top">Required</th> 30396<th class="tableblock halign-left valign-top">Value</th> 30397<th class="tableblock halign-left valign-top">Description</th> 30398</tr> 30399</thead> 30400<tbody> 30401<tr> 30402<td class="tableblock halign-left valign-top"><p class="tableblock">groupId</p></td> 30403<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30404<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30405<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the group to delete.</p></td> 30406</tr> 30407</tbody> 30408</table> 30409<table class="tableblock frame-all grid-all spread"> 30410<caption class="title">Table 255. Delete a group - Response codes</caption> 30411<colgroup> 30412<col style="width: 50%;"> 30413<col style="width: 50%;"> 30414</colgroup> 30415<thead> 30416<tr> 30417<th class="tableblock halign-left valign-top">Response code</th> 30418<th class="tableblock halign-left valign-top">Description</th> 30419</tr> 30420</thead> 30421<tbody> 30422<tr> 30423<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 30424<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the group was found and has been deleted. Response-body is intentionally empty.</p></td> 30425</tr> 30426<tr> 30427<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30428<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested group was not found.</p></td> 30429</tr> 30430</tbody> 30431</table> 30432</div> 30433<div class="sect3"> 30434<h4 id="_get_members_in_a_group">13.15.6. Get members in a group</h4> 30435<div class="paragraph"> 30436<p>There is no GET allowed on <code>identity/groups/members</code>. Use the <code>identity/users?memberOfGroup=sales</code> URL to get all users that are part of a particular group.</p> 30437</div> 30438</div> 30439<div class="sect3"> 30440<h4 id="_add_a_member_to_a_group">13.15.7. Add a member to a group</h4> 30441<div class="listingblock"> 30442<div class="content"> 30443<pre>POST identity/groups/{groupId}/members</pre> 30444</div> 30445</div> 30446<table class="tableblock frame-all grid-all spread"> 30447<caption class="title">Table 256. Add a member to a group - URL parameters</caption> 30448<colgroup> 30449<col style="width: 25%;"> 30450<col style="width: 25%;"> 30451<col style="width: 25%;"> 30452<col style="width: 25%;"> 30453</colgroup> 30454<thead> 30455<tr> 30456<th class="tableblock halign-left valign-top">Parameter</th> 30457<th class="tableblock halign-left valign-top">Required</th> 30458<th class="tableblock halign-left valign-top">Value</th> 30459<th class="tableblock halign-left valign-top">Description</th> 30460</tr> 30461</thead> 30462<tbody> 30463<tr> 30464<td class="tableblock halign-left valign-top"><p class="tableblock">groupId</p></td> 30465<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30466<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30467<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the group to add a member to.</p></td> 30468</tr> 30469</tbody> 30470</table> 30471<div class="paragraph"> 30472<p><strong>Body JSON:</strong></p> 30473</div> 30474<div class="listingblock"> 30475<div class="content"> 30476<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 304772 304783</div></td><td class="code"><span></span><span class="tok-p">{</span> 30479 <span class="tok-nt">"userId"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span> 30480<span class="tok-p">}</span> 30481</td></tr></table></code></pre> 30482</div> 30483</div> 30484<table class="tableblock frame-all grid-all spread"> 30485<caption class="title">Table 257. Add a member to a group - Response codes</caption> 30486<colgroup> 30487<col style="width: 50%;"> 30488<col style="width: 50%;"> 30489</colgroup> 30490<thead> 30491<tr> 30492<th class="tableblock halign-left valign-top">Response code</th> 30493<th class="tableblock halign-left valign-top">Description</th> 30494</tr> 30495</thead> 30496<tbody> 30497<tr> 30498<td class="tableblock halign-left valign-top"><p class="tableblock">201</p></td> 30499<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the group was found and the member has been added.</p></td> 30500</tr> 30501<tr> 30502<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30503<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the userId was not included in the request body.</p></td> 30504</tr> 30505<tr> 30506<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30507<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested group was not found.</p></td> 30508</tr> 30509<tr> 30510<td class="tableblock halign-left valign-top"><p class="tableblock">409</p></td> 30511<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested user is already a member of the group.</p></td> 30512</tr> 30513</tbody> 30514</table> 30515<div class="paragraph"> 30516<p><strong>Response Body:</strong></p> 30517</div> 30518<div class="listingblock"> 30519<div class="content"> 30520<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 305212 305223 305234 305245</div></td><td class="code"><span></span><span class="tok-p">{</span> 30525 <span class="tok-nt">"userId"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 30526 <span class="tok-nt">"groupId"</span><span class="tok-p">:</span><span class="tok-s2">"sales"</span><span class="tok-p">,</span> 30527 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/groups/sales/members/kermit"</span> 30528<span class="tok-p">}</span> 30529</td></tr></table></code></pre> 30530</div> 30531</div> 30532</div> 30533<div class="sect3"> 30534<h4 id="_delete_a_member_from_a_group">13.15.8. Delete a member from a group</h4> 30535<div class="listingblock"> 30536<div class="content"> 30537<pre>DELETE identity/groups/{groupId}/members/{userId}</pre> 30538</div> 30539</div> 30540<table class="tableblock frame-all grid-all spread"> 30541<caption class="title">Table 258. Delete a member from a group - URL parameters</caption> 30542<colgroup> 30543<col style="width: 25%;"> 30544<col style="width: 25%;"> 30545<col style="width: 25%;"> 30546<col style="width: 25%;"> 30547</colgroup> 30548<thead> 30549<tr> 30550<th class="tableblock halign-left valign-top">Parameter</th> 30551<th class="tableblock halign-left valign-top">Required</th> 30552<th class="tableblock halign-left valign-top">Value</th> 30553<th class="tableblock halign-left valign-top">Description</th> 30554</tr> 30555</thead> 30556<tbody> 30557<tr> 30558<td class="tableblock halign-left valign-top"><p class="tableblock">groupId</p></td> 30559<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30560<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30561<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the group to remove a member from.</p></td> 30562</tr> 30563<tr> 30564<td class="tableblock halign-left valign-top"><p class="tableblock">userId</p></td> 30565<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 30566<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 30567<td class="tableblock halign-left valign-top"><p class="tableblock">The id of the user to remove.</p></td> 30568</tr> 30569</tbody> 30570</table> 30571<table class="tableblock frame-all grid-all spread"> 30572<caption class="title">Table 259. Delete a member from a group - Response codes</caption> 30573<colgroup> 30574<col style="width: 50%;"> 30575<col style="width: 50%;"> 30576</colgroup> 30577<thead> 30578<tr> 30579<th class="tableblock halign-left valign-top">Response code</th> 30580<th class="tableblock halign-left valign-top">Description</th> 30581</tr> 30582</thead> 30583<tbody> 30584<tr> 30585<td class="tableblock halign-left valign-top"><p class="tableblock">204</p></td> 30586<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the group was found and the member has been deleted. The response body is left empty intentionally.</p></td> 30587</tr> 30588<tr> 30589<td class="tableblock halign-left valign-top"><p class="tableblock">404</p></td> 30590<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the requested group was not found or that the user is not a member of the group. The status description contains additional information about the error.</p></td> 30591</tr> 30592</tbody> 30593</table> 30594<div class="paragraph"> 30595<p><strong>Response Body:</strong></p> 30596</div> 30597<div class="listingblock"> 30598<div class="content"> 30599<pre class="pygments highlight"><code data-lang="json"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 306002 306013 306024 306035</div></td><td class="code"><span></span><span class="tok-p">{</span> 30604 <span class="tok-nt">"userId"</span><span class="tok-p">:</span><span class="tok-s2">"kermit"</span><span class="tok-p">,</span> 30605 <span class="tok-nt">"groupId"</span><span class="tok-p">:</span><span class="tok-s2">"sales"</span><span class="tok-p">,</span> 30606 <span class="tok-nt">"url"</span><span class="tok-p">:</span><span class="tok-s2">"http://localhost:8182/identity/groups/sales/members/kermit"</span> 30607<span class="tok-p">}</span> 30608</td></tr></table></code></pre> 30609</div> 30610</div> 30611</div> 30612</div> 30613</div> 30614</div> 30615<div class="sect1"> 30616<h2 id="cdiintegration">14. CDI integration</h2> 30617<div class="sectionbody"> 30618<div class="paragraph"> 30619<p>The activiti-cdi modules leverages both the configurability of Activiti and the extensibility of cdi. The most prominent features of activiti-cdi are:</p> 30620</div> 30621<div class="ulist"> 30622<ul> 30623<li> 30624<p>Support for @BusinessProcessScoped beans (Cdi beans the lifecycle of which is bound to a process instance),</p> 30625</li> 30626<l
30626i> 30627<p>A custom El-Resolver for resolving Cdi beans (including EJBs) from the process,</p> 30628</li> 30629<li> 30630<p>Declarative control over a process instance using annotations,</p> 30631</li> 30632<li> 30633<p>Activiti is hooked-up to the cdi event bus,</p> 30634</li> 30635<li> 30636<p>Works with both Java EE and Java SE, works with Spring,</p> 30637</li> 30638<li> 30639<p>Support for unit testing.</p> 30640</li> 30641</ul> 30642</div> 30643<div class="listingblock"> 30644<div class="content"> 30645<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 306462 306473 306484 306495</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 30650 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 30651 <span class="tok-nt"><artifactId></span>activiti-cdi<span class="tok-nt"></artifactId></span> 30652 <span class="tok-nt"><version></span>5.x<span class="tok-nt"></version></span> 30653<span class="tok-nt"></dependency></span> 30654</td></tr></table></code></pre> 30655</div> 30656</div> 30657<div class="sect2"> 30658<h3 id="_setting_up_activiti_cdi">14.1. Setting up activiti-cdi</h3> 30659<div class="paragraph"> 30660<p>Activiti cdi can be setup in different environments. In this section we briefly walk through the configuration options.</p> 30661</div> 30662<div class="sect3"> 30663<h4 id="_looking_up_a_process_engine">14.1.1. Looking up a Process Engine</h4> 30664<div class="paragraph"> 30665<p>The cdi extension needs to get access to a ProcessEngine. To achieve this, an implementation of the interface <code>org.activiti.cdi.spi.ProcessEngineLookup</code> is looked up at runtime. The cdi module ships with a default implementation named <code>org.activiti.cdi.impl.LocalProcessEngineLookup</code>, which uses the <code>ProcessEngines</code>-Utility class for looking up the ProcessEngine. In the default configuration <code>ProcessEngines#NAME_DEFAULT</code> is used to lookup the ProcessEngine. This class might be subclassed to set a custom name. NOTE: needs an <code>activiti.cfg.xml</code> configuration on the classpath.</p> 30666</div> 30667<div class="paragraph"> 30668<p>Activiti cdi uses a java.util.ServiceLoader SPI for resolving an instance of <code>org.activiti.cdi.spi.ProcessEngineLookup</code>. In order to provide a custom implementation of the interface, we need to add a plain text file named <code>META-INF/services/org.activiti.cdi.spi.ProcessEngineLookup</code> to our deployment, in which we specify the fully qualified classname of the implementation.</p> 30669</div> 30670<div class="admonitionblock note"> 30671<table> 30672<tr> 30673<td class="icon"> 30674<i class="fa icon-note" title="Note"></i> 30675</td> 30676<td class="content"> 30677<div class="paragraph"> 30678<p>If you do not provide a custom <code>org.activiti.cdi.spi.ProcessEngineLookup</code> implementation, Activiti will use the default <code>LocalProcessEngineLookup</code> implementation. In that case, all you need to do is providing a activiti.cfg.xml file on the classpath (see next section).</p> 30679</div> 30680</td> 30681</tr> 30682</table> 30683</div> 30684</div> 30685<div class="sect3"> 30686<h4 id="_configuring_the_process_engine">14.1.2. Configuring the Process Engine</h4> 30687<div class="paragraph"> 30688<p>Configuration depends on the selected ProcessEngineLookup-Strategy (cf. previous section). Here, we focus on the configuration options available in combination with the LocalProcessEngineLookup, which requires us to provide a Spring activiti.cfg.xml file on the classpath.</p> 30689</div> 30690<div class="paragraph"> 30691<p>Activiti offers different ProcessEngineConfiguration implementations mostly dependent on the underlying transaction management strategy. The activiti-cdi module is not concerned with transactions, which means that potentially any transaction management strategy can be used (even the Spring transaction abstraction). As a convenience, the cdi-module provides two custom ProcessEngineConfiguration implementations:</p> 30692</div> 30693<div class="ulist"> 30694<ul> 30695<li> 30696<p><code>org.activiti.cdi.CdiJtaProcessEngineConfiguration</code>: a subclass of the activiti JtaProcessEngineConfiguration, can be used if JTA-managed transactions should be used for Activiti</p> 30697</li> 30698<li> 30699<p><code>org.activiti.cdi.CdiStandaloneProcessEngineConfiguration</code>: a subclass of the activiti StandaloneProcessEngineConfiguration, can be used if plain JDBC transactions should be used for Activiti. The following is an example activiti.cfg.xml file for JBoss 7:</p> 30700</li> 30701</ul> 30702</div> 30703<div class="listingblock"> 30704<div class="content"> 30705<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 30706 2 30707 3 30708 4 30709 5 30710 6 30711 7 30712 8 30713 9 3071410 3071511 3071612 3071713 3071814 3071915 3072016 3072117 3072218 3072319 3072420 3072521 3072622 3072723</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="UTF-8"?></span> 30728<span class="tok-nt"><beans</span> <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.springframework.org/schema/beans"</span> 30729 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 30730 <span class="tok-na">xsi:schemaLocation=</span><span class="tok-s">"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"</span><span class="tok-nt">></span> 30731 30732 <span class="tok-c"><!-- lookup the JTA-Transaction manager --></span> 30733 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">class=</span><span class="tok-s">"org.springframework.jndi.JndiObjectFactoryBean"</span><span class="tok-nt">></span> 30734 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jndiName"</span> <span class="tok-na">value=</span><span class="tok-s">"java:jboss/TransactionManager"</span><span class="tok-nt">></property></span> 30735 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"resourceRef"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 30736 <span class="tok-nt"></bean></span> 30737 30738 <span class="tok-c"><!-- process engine configuration --></span> 30739 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> 30740 <span class="tok-na">class=</span><span class="tok-s">"org.activiti.cdi.CdiJtaProcessEngineConfiguration"</span><span class="tok-nt">></span> 30741 <span class="tok-c"><!-- lookup the default Jboss datasource --></span> 30742 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"dataSourceJndiName"</span> <span class="tok-na">value=</span><span class="tok-s">"java:jboss/datasources/ExampleDS"</span> <span class="tok-nt">/></span> 30743 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseType"</span> <span class="tok-na">value=</span><span class="tok-s">"h2"</span> <span class="tok-nt">/></span> 30744 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">ref=</span><span class="tok-s">"transactionManager"</span> <span class="tok-nt">/></span> 30745 <span class="tok-c"><!-- using externally managed transactions --></span> 30746 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"transactionsExternallyManaged"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 30747 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 30748 <span class="tok-nt"></bean></span> 30749<span class="tok-nt"></beans></span> 30750</td></tr></table></code></pre> 30751</div> 30752</div> 30753<div class="paragraph"> 30754<p>And this is how it would look like for Glassfish 3.1.1 (assuming a datasource named jdbc/activiti is properly configured):</p> 30755</div> 30756<div class="listingblock"> 30757<div class="content"> 30758<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 30759 2 30760 3 30761 4 30762 5 30763 6 30764 7 30765 8 30766 9 3076710 3076811 3076912 3077013 3077114 3077215 3077316 3077417 3077518 3077619 3077720 3077821</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="UTF-8"?></span> 30779<span class="tok-nt"><beans</span> <span class="tok-na">xmlns=</span><span class="tok-s">"http://www.springframework.org/schema/beans"</span> 30780 <span class="tok-na">xmlns:xsi=</span><span class="tok-s">"http://www.w3.org/2001/XMLSchema-instance"</span> 30781 <span class="tok-na">xsi:schemaLocation=</span><span class="tok-s">"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"</span><span class="tok-nt">></span> 30782 30783 <span class="tok-c"><!-- lookup the JTA-Transaction manager --></span> 30784 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">class=</span><span class="tok-s">"org.springframework.jndi.JndiObjectFactoryBean"</span><span class="tok-nt">></span> 30785 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"jndiName"</span> <span class="tok-na">value=</span><span class="tok-s">"java:appserver/TransactionManager"</span><span class="tok-nt">></property></span> 30786 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"resourceRef"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 30787 <span class="tok-nt"></bean></span> 30788 30789 <span class="tok-c"><!-- process engine configuration --></span> 30790 <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> 30791 <span class="tok-na">class=</span><span class="tok-s">"org.activiti.cdi.CdiJtaProcessEngineConfiguration"</span><span class="tok-nt">></span> 30792 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"dataSourceJndiName"</span> <span class="tok-na">value=</span><span class="tok-s">"jdbc/activiti"</span> <span class="tok-nt">/></span> 30793 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"transactionManager"</span> <span class="tok-na">ref=</span><span class="tok-s">"transactionManager"</span> <span class="tok-nt">/></span> 30794 <span class="tok-c"><!-- using externally managed transactions --></span> 30795 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"transactionsExternallyManaged"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 30796 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"databaseSchemaUpdate"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span> <span class="tok-nt">/></span> 30797 <span class="tok-nt"></bean></span> 30798<span class="tok-nt"></beans></span> 30799</td></tr></table></code></pre> 30800</div> 30801</div> 30802<div class="paragraph"> 30803<p>Note that the above configuration requires the "spring-context" module:</p> 30804</div> 30805<div class="listingblock"> 30806<div class="content"> 30807<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 308082 308093 308104 308115</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 30812 <span class="tok-nt"><groupId></span>org.springframework<span class="tok-nt"></groupId></span> 30813 <span class="tok-nt"><artifactId></span>spring-context<span class="tok-nt"></artifactId></span> 30814 <span class="tok-nt"><version></span>3.0.3.RELEASE<span class="tok-nt"></version></span> 30815<span class="tok-nt"></dependency></span> 30816</td></tr></table></code></pre> 30817</div> 30818</div> 30819<div class="paragraph"> 30820<p>The configuration in a Java SE environment looks exactly like the examples provided in section <a href="#configuration">Creating a ProcessEngine</a>, substitute "CdiStandaloneProcessEngineConfiguration" for "StandaloneProcessEngineConfiguration".</p> 30821</div> 30822</div> 30823<div class="sect3"> 30824<h4 id="_deploying_processes">14.1.3. Deploying Processes</h4> 30825<div class="paragraph"> 30826<p>Processes can be deployed using standard activiti-api (<code>RepositoryService</code>). In addition, activiti-cdi offers the possibility to auto-deploy processes listed in a file named <code>processes.xml</code> located top-level in the classpath. This is an example processes.xml file:</p> 30827</div> 30828<div class="listingblock"> 30829<div class="content"> 30830<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 308312 308323 308334 308345 308356</div></td><td class="code"><span></span><span class="tok-cp"><?xml version="1.0" encoding="utf-8" ?></span> 30836<span class="tok-c"><!-- list the processes to be deployed --></span> 30837<span class="tok-nt"><processes></span> 30838 <span class="tok-nt"><process</span> <span class="tok-na">resource=</span><span class="tok-s">"diagrams/myProcess.bpmn20.xml"</span> <span class="tok-nt">/></span> 30839 <span class="tok-nt"><process</span> <span class="tok-na">resource=</span><span class="tok-s">"diagrams/myOtherProcess.bpmn20.xml"</span> <span class="tok-nt">/></span> 30840<span class="tok-nt"></processes></span> 30841</td></tr></table></code></pre> 30842</div> 30843</div> 30844<div class="paragraph"> 30845<p>===Contextual Process Execution with CDI</p> 30846</div> 30847<div class="paragraph"> 30848<p>In this section we briefly look at the contextual process execution model used by the Activiti cdi extension. A BPMN business process is typically a long-running interaction, comprised of both user and system tasks. At runtime, a process is split-up into a set of individual units of work, performed by users and/or application logic. In activiti-cdi, a process instance can be associated with a cdi scope, the association representing a unit of work. This is particularly useful, if a unit of work is complex, for instance if the implementation of a UserTask is a complex sequence of different forms and "non-process-scoped" state needs to be kept during this interaction.</p> 30849</div> 30850<div class="paragraph"> 30851<p>In the default configuration, process instances are associated with the "broadest" active scope, starting with the conversation and falling back to the request if the conversation context is not active.</p> 30852</div> 30853</div> 30854<div class="sect3"> 30855<h4 id="_associating_a_conversation_with_a_process_instance">14.1.4. Associating a Conversation with a Process Instance</h4> 30856<div class="paragraph"> 30857<p>When resolving @BusinessProcessScoped beans, or injecting process variables, we rely on an existing association between an active cdi scope and a process instance. Activiti-cdi provides the <code>org.activiti.cdi.BusinessProcess</code> bean for controlling the association, most prominently:</p> 30858</div> 30859<div class="ulist"> 30860<ul> 30861<li> 30862<p>the <em>startProcessBy(…​)</em> methods, mirroring the respective methods exposed by the Activiti <code>RuntimeService</code> allowing to start and subsequently associating a business process,</p> 30863</li> 30864<li> 30865<p><code>resumeProcessById(String processInstanceId)</code>, allowing to associate the process instance with the provided id,</p> 30866</li> 30867<li> 30868<p><code>resumeTaskById(String taskId)</code>, allowing to associate the task with the provided id (and by extension, the corresponding process instance),</p> 30869</li> 30870</ul> 30871</div> 30872<div class="paragraph"> 30873<p>Once a unit of work (for example a UserTask) is completed, the <code>completeTask()</code>
30873 method can be called to disassociate the conversation/request from the process instance. This signals Activiti that the current task is completed and makes the process instance proceed.</p> 30874</div> 30875<div class="paragraph"> 30876<p>Note that the <code>BusinessProcess</code>-bean is a <code>@Named</code> bean, which means that the exposed methods can be invoked using expression language, for example from a JSF page. The following JSF2 snippet begins a new conversation and associates it with a user task instance, the id of which is passed as a request parameter (e.g. <code>pageName.jsf?taskId=XX</code>):</p> 30877</div> 30878<div class="listingblock"> 30879<div class="content"> 30880<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 308812 308823 308834</div></td><td class="code"><span></span><span class="tok-nt"><f:metadata></span> 30884<span class="tok-nt"><f:viewParam</span> <span class="tok-na">name=</span><span class="tok-s">"taskId"</span> <span class="tok-nt">/></span> 30885<span class="tok-nt"><f:event</span> <span class="tok-na">type=</span><span class="tok-s">"preRenderView"</span> <span class="tok-na">listener=</span><span class="tok-s">"#{businessProcess.startTask(taskId, true)}"</span> <span class="tok-nt">/></span> 30886<span class="tok-nt"></f:metadata></span> 30887</td></tr></table></code></pre> 30888</div> 30889</div> 30890</div> 30891<div class="sect3"> 30892<h4 id="_declaratively_controlling_the_process">14.1.5. Declaratively controlling the Process</h4> 30893<div class="paragraph"> 30894<p>Activiti-cdi allows declaratively starting process instances and completing tasks using annotations. The <code>@org.activiti.cdi.annotation.StartProcess</code> annotation allows to start a process instance either by "key" or by "name". Note that the process instance is started <em>after</em> the annotated method returns. Example:</p> 30895</div> 30896<div class="listingblock"> 30897<div class="content"> 30898<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 308992 309003 309014 309025</div></td><td class="code"><span></span><span class="tok-nd">@StartProcess</span><span class="tok-o">(</span><span class="tok-s">"authorizeBusinessTripRequest"</span><span class="tok-o">)</span> 30903<span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">submitRequest</span><span class="tok-o">(</span><span class="tok-n">BusinessTripRequest</span> <span class="tok-n">request</span><span class="tok-o">)</span> <span class="tok-o">{</span> 30904 <span class="tok-c1">// do some work</span> 30905 <span class="tok-k">return</span> <span class="tok-s">"success"</span><span class="tok-o">;</span> 30906<span class="tok-o">}</span> 30907</td></tr></table></code></pre> 30908</div> 30909</div> 30910<div class="paragraph"> 30911<p>Depending on the configuration of Activiti, the code of the annotated method and the starting of the process instance will be combined in the same transaction. The <code>@org.activiti.cdi.annotation.CompleteTask</code>-annotation works in the same way:</p> 30912</div> 30913<div class="listingblock"> 30914<div class="content"> 30915<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 309162 309173 309184 309195</div></td><td class="code"><span></span><span class="tok-nd">@CompleteTask</span><span class="tok-o">(</span><span class="tok-n">endConversation</span><span class="tok-o">=</span><span class="tok-kc">false</span><span class="tok-o">)</span> 30920<span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">authorizeBusinessTrip</span><span class="tok-o">()</span> <span class="tok-o">{</span> 30921 <span class="tok-c1">// do some work</span> 30922 <span class="tok-k">return</span> <span class="tok-s">"success"</span><span class="tok-o">;</span> 30923<span class="tok-o">}</span> 30924</td></tr></table></code></pre> 30925</div> 30926</div> 30927<div class="paragraph"> 30928<p>The <code>@CompleteTask</code> annotation offers the possibility to end the current conversation. The default behavior is to end the conversation after the call to Activiti returns. Ending the conversation can be disabled, as shown in the example above.</p> 30929</div> 30930</div> 30931<div class="sect3"> 30932<h4 id="_referencing_beans_from_the_process">14.1.6. Referencing Beans from the Process</h4> 30933<div class="paragraph"> 30934<p>Activiti-cdi exposes CDI beans to Activiti El, using a custom resolver. This makes it possible to reference beans from the process:</p> 30935</div> 30936<div class="listingblock"> 30937<div class="content"> 30938<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1
309392</div></td><td class="code"><span></span><span class="tok-nt"><userTask</span> <span class="tok-na">id=</span><span class="tok-s">"authorizeBusinessTrip"</span> <span class="tok-na">name=</span><span class="tok-s">"Authorize Business Trip"</span> 30940 <span class="tok-na">activiti:assignee=</span><span class="tok-s">"#{authorizingManager.account.username}"</span> <span class="tok-nt">/></span> 30941</td></tr></table></code></pre> 30942</div> 30943</div> 30944<div class="paragraph"> 30945<p>Where "authorizingManager" could be a bean provided by a producer method:</p> 30946</div> 30947<div class="listingblock"> 30948<div class="content"> 30949<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 30950 2 30951 3 30952 4 30953 5 30954 6 30955 7 30956 8 30957 9 3095810</div></td><td class="code"><span></span><span class="tok-nd">@Inject</span> <span class="tok-nd">@ProcessVariable</span> <span class="tok-n">Object</span> <span class="tok-n">businessTripRequesterUsername</span><span class="tok-o">;</span> 30959 30960<span class="tok-nd">@Produces</span> 30961<span class="tok-nd">@Named</span> 30962<span class="tok-kd">public</span> <span class="tok-n">Employee</span> <span class="tok-nf">authorizingManager</span><span class="tok-o">()</span> <span class="tok-o">{</span> 30963 <span class="tok-n">TypedQuery</span><span class="tok-o"><</span><span class="tok-n">Employee</span><span class="tok-o">></span> <span class="tok-n">query</span> <span class="tok-o">=</span> <span class="tok-n">entityManager</span><span class="tok-o">.</span><span class="tok-na">createQuery</span><span class="tok-o">(</span><span class="tok-s">"SELECT e FROM Employee e WHERE e.account.username='"</span> 30964 <span class="tok-o">+</span> <span class="tok-n">businessTripRequesterUsername</span> <span class="tok-o">+</span> <span class="tok-s">"'"</span><span class="tok-o">,</span> <span class="tok-n">Employee</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">);</span> 30965 <span class="tok-n">Employee</span> <span class="tok-n">employee</span> <span class="tok-o">=</span> <span class="tok-n">query</span><span class="tok-o">.</span><span class="tok-na">getSingleResult</span><span class="tok-o">();</span> 30966 <span class="tok-k">return</span> <span class="tok-n">employee</span><span class="tok-o">.</span><span class="tok-na">getManager</span><span class="tok-o">();</span> 30967<span class="tok-o">}</span> 30968</td></tr></table></code></pre> 30969</div> 30970</div> 30971<div class="paragraph"> 30972<p>We can use the same feature to call a business method of an EJB in a service task, using the <code>activiti:expression="myEjb.method()"</code>-extension. Note that this requires a <code>@Named</code>-annotation on the <code>MyEjb</code>-class.</p> 30973</div> 30974</div> 30975<div class="sect3"> 30976<h4 id="_working_with_businessprocessscoped_beans">14.1.7. Working with @BusinessProcessScoped beans</h4> 30977<div class="paragraph"> 30978<p>Using activiti-cdi, the lifecycle of a bean can be bound to a process instance. To this extend, a custom context implementation is provided, namely the BusinessProcessContext. Instances of BusinessProcessScoped beans are stored as process variables in the current process instance. BusinessProcessScoped beans need to be PassivationCapable (for example Serializable). The following is an example of a process scoped bean:</p> 30979</div> 30980<div class="listingblock"> 30981<div class="content"> 30982<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 309832 309843 309854 309865 309876 309887 309898</div></td><td class="code"><span></span><span class="tok-nd">@Named</span> 30990<span class="tok-nd">@BusinessProcessScoped</span> 30991<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">BusinessTripRequest</span> <span class="tok-kd">implements</span> <span class="tok-n">Serializable</span> <span class="tok-o">{</span> 30992 <span class="tok-kd">private</span> <span class="tok-kd">static</span> <span class="tok-kd">final</span> <span class="tok-kt">long</span> <span class="tok-n">serialVersionUID</span> <span class="tok-o">=</span> <span class="tok-mi">1L</span><span class="tok-o">;</span> 30993 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">startDate</span><span class="tok-o">;</span> 30994 <span class="tok-kd">private</span> <span class="tok-n">String</span> <span class="tok-n">endDate</span><span class="tok-o">;</span> 30995 <span class="tok-c1">
30995// ...</span> 30996<span class="tok-o">}</span> 30997</td></tr></table></code></pre> 30998</div> 30999</div> 31000<div class="paragraph"> 31001<p>Sometimes, we want to work with process scoped beans, in the absence of an association with a process instance, for example before starting a process. If no process instance is currently active, instances of BusinessProcessScoped beans are temporarily stored in a local scope (I.e. the Conversation or the Request, depending on the context. If this scope is later associated with a business process instance, the bean instances are flushed to the process instance.</p> 31002</div> 31003</div> 31004<div class="sect3"> 31005<h4 id="_injecting_process_variables">14.1.8. Injecting Process Variables</h4> 31006<div class="paragraph"> 31007<p>Process variables are available for injection. Activiti-CDI supports</p> 31008</div> 31009<div class="ulist"> 31010<ul> 31011<li> 31012<p>type-safe injection of <code>@BusinessProcessScoped</code> beans using <code>@Inject \[additional qualifiers\] Type fieldName</code></p> 31013</li> 31014<li> 31015<p>unsafe injection of other process variables using the <code>@ProcessVariable(name?)</code> qualifier:</p> 31016</li> 31017</ul> 31018</div> 31019<div class="listingblock"> 31020<div class="content"> 31021<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 310222</div></td><td class="code"><span></span><span class="tok-nd">@Inject</span> <span class="tok-nd">@ProcessVariable</span> <span class="tok-n">Object</span> <span class="tok-n">accountNumber</span><span class="tok-o">;</span> 31023<span class="tok-nd">@Inject</span> <span class="tok-nd">@ProcessVariable</span><span class="tok-o">(</span><span class="tok-s">"accountNumber"</span><span class="tok-o">)</span> <span class="tok-n">Object</span> <span class="tok-n">account</span> 31024</td></tr></table></code></pre> 31025</div> 31026</div> 31027<div class="paragraph"> 31028<p>In order to reference process variables using EL, we have similar options:</p> 31029</div> 31030<div class="ulist"> 31031<ul> 31032<li> 31033<p><code>@Named @BusinessProcessScoped</code> beans can be referenced directly,</p> 31034</li> 31035<li> 31036<p>other process variables can be referenced using the <code>ProcessVariables</code>-bean:</p> 31037</li> 31038</ul> 31039</div> 31040<div class="listingblock"> 31041<div class="content"> 31042<pre>#{processVariables['accountNumber']}</pre> 31043</div> 31044</div> 31045</div> 31046<div class="sect3"> 31047<h4 id="_receiving_process_events">14.1.9. Receiving Process Events</h4> 31048<div class="paragraph"> 31049<p><a href="#experimental">[EXPERIMENTAL]</a></p> 31050</div> 31051<div class="paragraph"> 31052<p>Activiti can be hooked-up to the CDI event-bus. This allows us to be notified of process events using standard CDI event mechanisms. In order to enable CDI event support for Activiti, enable the corresponding parse listener in the configuration:</p> 31053</div> 31054<div class="listingblock"> 31055<div class="content"> 31056<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 310572 310583 310594 310605</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"postBpmnParseHandlers"</span><span class="tok-nt">></span> 31061 <span class="tok-nt"><list></span> 31062 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.cdi.impl.event.CdiEventSupportBpmnParseHandler"</span> <span class="tok-nt">/></span> 31063 <span class="tok-nt"></list></span> 31064<span class="tok-nt"></property></span> 31065</td></tr></table></code></pre> 31066</div> 31067</div> 31068<div class="paragraph"> 31069<p>Now Activiti is configured for publishing events using the CDI event bus. The following gives an overview of how process events can be received in CDI beans. In CDI, we can declaratively specify event observers using the <code>@Observes</code>-annotation. Event notification is type-safe. The type of 31070process events is <code>org.activiti.cdi.BusinessProcessEvent</code>. 31071The following is an example of a simple event observer method:</p> 31072</div> 31073<div class="listingblock"> 31074<div class="content"> 31075<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 310762 310773</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">onProcessEvent</span><span class="tok-o">(</span><span class="tok-nd">@Observes</span> <span class="tok-n">BusinessProcessEvent</span> <span class="tok-n">businessProcessEvent</span><span class="tok-o">)</span> <span class="tok-o">{</span> 31078 <span class="tok-c1">// handle event</span> 31079<span class="tok-o">}</span> 31080</td></tr></table></code></pre> 31081</div> 31082</div> 31083<div class="paragraph"> 31084<p>This observer would be notified of all events. If we want to restrict the set of events the observer receives, we can add qualifier annotations:</p> 31085</div> 31086<div class="ulist"> 31087<ul> 31088<li> 31089<p><code>@BusinessProcess</code>: restricts the set of events to a certain process definition. Example: <code>
31089@Observes @BusinessProcess("billingProcess") BusinessProcessEvent evt</code></p> 31090</li> 31091<li> 31092<p><code>@StartActivity</code>: restricts the set of events by a certain activity. For example: <code>@Observes @StartActivity("shipGoods") BusinessProcessEvent evt</code> is invoke whenever an activity with the id "shipGoods" is entered.</p> 31093</li> 31094<li> 31095<p><code>@EndActivity</code>: restricts the set of events by a certain activity. For example: <code>@Observes @EndActivity("shipGoods") BusinessProcessEvent evt</code> is invoke whenever an activity with the id "shipGoods" is left.</p> 31096</li> 31097<li> 31098<p><code>@TakeTransition</code>: restricts the set of events by a certain transition.</p> 31099</li> 31100<li> 31101<p><code>@CreateTask</code>: restricts the set of events by a certain task’s creation.</p> 31102</li> 31103<li> 31104<p><code>@DeleteTask</code>: restricts the set of events by a certain task’s deletion.</p> 31105</li> 31106<li> 31107<p><code>@AssignTask</code>: restricts the set of events by a certain task’s assignment.</p> 31108</li> 31109<li> 31110<p><code>@CompleteTask</code>: restricts the set of events by a certain task’s completion.</p> 31111</li> 31112</ul> 31113</div> 31114<div class="paragraph"> 31115<p>The qualifiers named above can be combined freely. For example, in order to receive all events generated when leav
31115ing the "shipGoods" activity in the "shipmentProcess", we could write the following observer method:</p> 31116</div> 31117<div class="listingblock"> 31118<div class="content"> 31119<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 311202 311213</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">beforeShippingGoods</span><span class="tok-o">(</span><span class="tok-nd">@Observes</span> <span class="tok-nd">@BusinessProcess</span><span class="tok-o">(</span><span class="tok-s">"shippingProcess"</span><span class="tok-o">)</span> <span class="tok-nd">@EndActivity</span><span class="tok-o">(</span><span class="tok-s">"shipGoods"</span><span class="tok-o">)</span> <span class="tok-n">BusinessProcessEvent</span> <span class="tok-n">evt</span><span class="tok-o">)</span> <span class="tok-o">{</span> 31122 <span class="tok-c1">// handle event</span> 31123<span class="tok-o">}</span> 31124</td></tr></table></code></pre> 31125</div> 31126</div> 31127<div class="paragraph"> 31128<p>In the default configuration, event listeners are invoked synchronously and in the context of the same transaction. CDI transactional observers (only available in combination with JavaEE / EJB), allow to control when the event is handed to the observer method. Using transactional observers, we can for example assure that an observer is only notified if the transaction in which the event is fired succeeds:</p> 31129</div> 31130<div class="listingblock"> 31131<div class="content"> 31132<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 311332 311343</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">onShipmentSuceeded</span><span class="tok-o">(</span><span class="tok-nd">@Observes</span><span class="tok-o">(</span><span class="tok-n">during</span><span class="tok-o">=</span><span class="tok-n">TransactionPhase</span><span class="tok-o">.</span><span class="tok-na">AFTER_SUCCESS</span><span class="tok-o">)</span> <span class="tok-nd">@BusinessProcess</span><span class="tok-o">(</span><span class="tok-s">"shippingProcess"</span><span class="tok-o">)</span> <span class="tok-nd">@EndActivity</span><span class="tok-o">(</span><span class="tok-s">"shipGoods"</span><span class="tok-o">)</span> <span class="tok-n">BusinessProcessEvent</span> <span class="tok-n">evt</span><span class="tok-o">)</span> <span class="tok-o">{</span> 31135 <span class="tok-c1">// send email to customer.</span> 31136<span class="tok-o">}</span> 31137</td></tr></table></code></pre> 31138</div> 31139</div> 31140</div> 31141<div class="sect3"> 31142<h4 id="_additional_features">14.1.10. Additional Features</h4> 31143<div class="ulist"> 31144<ul> 31145<li> 31146<p>The ProcessEngine as well as the services are available for injection: <code>@Inject ProcessEngine, RepositoryService, TaskService</code>, …​</p> 31147</li> 31148<li> 31149<p>The current process instance and task can be injected: <code>@Inject ProcessInstance, Task</code>,</p> 31150</li> 31151<li> 31152<p>The current business key can be injected: <code>@Inject @BusinessKey String businessKey</code>,</p> 31153</li> 31154<li> 31155<p>The current process instance id be injected: <code>@Inject @ProcessInstanceId String pid</code>,</p> 31156</li> 31157</ul> 31158</div> 31159</div> 31160</div> 31161<div class="sect2"> 31162<h3 id="_known_limitations">14.2. Known Limitations</h3> 31163<div class="paragraph"> 31164<p>Although activiti-cdi is implemented against the SPI and designed to be a "portable-extension" it is only tested using Weld.</p> 31165</div> 31166</div> 31167</div> 31168</div> 31169<div class="sect1"> 31170<h2 id="chapter_ldap">15. LDAP integration</h2> 31171<div class="sectionbody"> 31172<div class="paragraph"> 31173<p>Companies often already have a user and group store in the form of an LDAP system. Since version 5.14, Activiti offers an out-of-the-box solution for easily configuring how Activiti should connect with an LDAP system.</p> 31174</div> 31175<div class="paragraph"> 31176<p>Before Activiti 5.14, it was already possible to integrate LDAP with Activiti. However, as of 5.14, the configuration has been simplified a lot. However, the <em>old</em> way of configuring LDAP still works. More specifically, the simplified configuration is just a wrapper on top of the <em>old</em>
31176 infrastructure.</p> 31177</div> 31178<div class="sect2"> 31179<h3 id="ldap_usage">15.1. Usage</h3> 31180<div class="paragraph"> 31181<p>To add the LDAP integration code to your project, simply add the following dependency to your pom.xml:</p> 31182</div> 31183<div class="listingblock"> 31184<div class="content"> 31185<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 311862 311873 311884 311895</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 31190 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 31191 <span class="tok-nt"><artifactId></span>activiti-ldap<span class="tok-nt"></artifactId></span> 31192 <span class="tok-nt"><version></span>latest.version<span class="tok-nt"></version></span> 31193<span class="tok-nt"></dependency></span> 31194</td></tr></table></code></pre> 31195</div> 31196</div> 31197</div> 31198<div class="sect2"> 31199<h3 id="ldap_usecases">15.2. Use cases</h3> 31200<div class="paragraph"> 31201<p>The LDAP integration has currently two main use cases:</p> 31202</div> 31203<div class="ulist"> 31204<ul> 31205<li> 31206<p>Allow for authentication through the IdentityService. This could be useful when doing everything through the IdentityService.</p> 31207</li> 31208<li> 31209<p>Fetching the groups of a user. This is important when for example querying tasks to see which tasks a certain user can see (i.e. tasks with a candidate group).</p> 31210</li> 31211</ul> 31212</div> 31213</div> 31214<div class="sect2"> 31215<h3 id="ldap_configuration">15.3. Configuration</h3> 31216<div class="paragraph"> 31217<p>Integrating the LDAP system with Activiti is done by injecting an instance of <code>org.activiti.ldap.LDAPConfigurator</code> in the <code>configurators</code> section of the process engine configuration. This class is highly extensible: methods can be easily overridden and many dependent beans are pluggable if the default implementation would not fit the use case.</p> 31218</div> 31219<div class="paragraph"> 31220<p>This is an example configuration (note: of course, when creating the engine programmatically this is completely similar). Don’t worry about all the properties for now, we’ll look at them in detail in a next section.</p> 31221</div> 31222<div class="listingblock"> 31223<div class="content"> 31224<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 31225 2 31226 3 31227 4 31228 5 31229 6 31230 7 31231 8 31232 9 3123310 3123411 3123512 3123613 3123714 3123815 3123916 3124017 3124118 3124219 3124320 3124421 3124522 3124623 3124724 3124825 3124926 3125027 3125128 3125229 3125330 3125431 3125532</div></td><td class="code"><span></span> <span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"...SomeProcessEngineConfigurationClass"</span><span class="tok-nt">></span> 31256 ... 31257 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"configurators"</span><span class="tok-nt">></span> 31258 <span class="tok-nt"><list></span> 31259 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.ldap.LDAPConfigurator"</span><span class="tok-nt">></span> 31260 31261 <span class="tok-c"><!-- Server connection params --></span> 31262 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"server"</span> <span class="tok-na">value=</span><span class="tok-s">"ldap://localhost"</span> <span class="tok-nt">/></span> 31263 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"port"</span> <span class="tok-na">value=</span><span class="tok-s">"33389"</span> <span class="tok-nt">/></span> 31264 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"user"</span> <span class="tok-na">value=</span><span class="tok-s">"uid=admin, ou=users, o=activiti"</span> <span class="tok-nt">/></span> 31265 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"password"</span> <span class="tok-na">value=</span><span class="tok-s">"pass"</span> <span class="tok-nt">/></span> 31266
31267 <span class="tok-c"><!-- Query params --></span> 31268 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"baseDn"</span> <span class="tok-na">value=</span><span class="tok-s">"o=activiti"</span> <span class="tok-nt">/></span> 31269 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"queryUserByUserId"</span> <span class="tok-na">value=</span><span class="tok-s">"(&(objectClass=inetOrgPerson)(uid={0}))"</span> <span class="tok-nt">/></span> 31270 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"queryUserByFullNameLike"</span> <span class="tok-na">value=</span><span class="tok-s">"(&(objectClass=inetOrgPerson)(|({0}=*{1}*)({2}=*{3}*)))"</span> <span class="tok-nt">/></span> 31271 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"queryGroupsForUser"</span> <span class="tok-na">value=</span><span class="tok-s">"(&(objectClass=groupOfUniqueNames)(uniqueMember={0}))"</span> <span class="tok-nt">/></span> 31272 31273 <span class="tok-c"><!-- Attribute config --></span> 31274 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"userIdAttribute"</span> <span class="tok-na">value=</span><span class="tok-s">"uid"</span> <span class="tok-nt">/></span> 31275 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"userFirstNameAttribute"</span> <span class="tok-na">value=</span><span class="tok-s">"cn"</span> <span class="tok-nt">/></span> 31276 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"userLastNameAttribute"</span> <span class="tok-na">value=</span><span class="tok-s">"sn"</span> <span class="tok-nt">/></span> 31277 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"userEmailAttribute"</span> <span class="tok-na">value=</span><span class="tok-s">"mail"</span> <span class="tok-nt">/></span> 31278 31279 31280 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"groupIdAttribute"</span> <span class="tok-na">value=</span><span class="tok-s">"cn"</span> <span class="tok-nt">/></span> 31281 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"groupNameAttribute"</span> <span class="tok-na">value=</span><span class="tok-s">"cn"</span> <span class="tok-nt">/></span> 31282 31283 <span class="tok-nt"></bean></span> 31284 <span class="tok-nt"></list></span> 31285 <span class="tok-nt"></property></span> 31286 <span class="tok-nt"></bean></span> 31287</td></tr></table></code></pre> 31288</div> 31289</div> 31290</div> 31291<div class="sect2"> 31292<h3 id="ldap_properties">15.4. Properties</h3> 31293<div class="paragraph"> 31294<p>Following properties can be set on <code>org.activiti.ldap.LDAPConfigurator</code>:</p> 31295</div> 31296<div class="literalblock"> 31297<div class="content"> 31298<pre>.LDAP configuration properties</pre> 31299</div> 31300</div> 31301<table class="tableblock frame-all grid-all spread"> 31302<colgroup> 31303<col style="width: 25%;"> 31304<col style="width: 25%;"> 31305<col style="width: 25%;"> 31306<col style="width: 25%;"> 31307</colgroup> 31308<thead> 31309<tr> 31310<th class="tableblock halign-left valign-top">Property name</th> 31311<th class="tableblock halign-left valign-top">Description</th> 31312<th class="tableblock halign-left valign-top">Type</th> 31313<th class="tableblock halign-left valign-top">Default value</th> 31314</tr> 31315</thead> 31316<tbody> 31317<tr> 31318<td class="tableblock halign-left valign-top"><p class="tableblock">server</p></td> 31319<td class="tableblock halign-left valign-top"><p class="tableblock">The server on which the LDAP system can be reached. For example <em>ldap://localhost:33389</em></p></td> 31320<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31321<td class="tableblock halign-left valign-top"></td> 31322</tr> 31323<tr> 31324<td class="tableblock halign-left valign-top"><p class="tableblock">port</p></td> 31325<td class="tableblock halign-left valign-top"><p class="tableblock">The port on which the LDAP system is running</p></td> 31326<td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> 31327<td class="tableblock halign-left valign-top"></td> 31328</tr> 31329<tr> 31330<td class="tableblock halign-left valign-top"><p class="tableblock">user</p></td> 31331<td class="tableblock halign-left valign-top"><p class="tableblock">The user id that is used to connect to the LDAP system</p></td> 31332<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31333<td class="tableblock halign-left valign-top"></td> 31334</tr> 31335<tr> 31336<td class="tableblock halign-left valign-top"><p class="tableblock">password</p></td> 31337<td class="tableblock halign-left valign-top"><p class="tableblock">The password that is used to connect to the LDAP system</p></td> 31338<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31339<td class="tableblock halign-left valign-top"></td> 31340</tr> 31341<tr> 31342<td class="tableblock halign-left valign-top"><p class="tableblock">initialContextFactory</p></td> 31343<td class="tableblock halign-left valign-top"><p class="tableblock">The InitialContextFactory name used to connect to the LDAP system</p></td> 31344<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31345<td class="tableblock halign-left valign-top"><p class="tableblock">com.sun.jndi.ldap.LdapCtxFactory</p></td> 31346</tr> 31347<tr> 31348<td class="tableblock halign-left valign-top"><p class="tableblock">securityAuthentication</p></td> 31349<td class="tableblock halign-left valign-top"><p class="tableblock">The value that is used for the <em>java.naming.security.authentication</em> property used to connect to the LDAP system</p></td> 31350<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31351<td class="tableblock halign-left valign-top"><p class="tableblock">simple</p></td> 31352</tr> 31353<tr> 31354<td class="tableblock halign-left valign-top"><p class="tableblock">customConnectionParameters</p></td> 31355<td class="tableblock halign-left valign-top"><p class="tableblock">Allows to set all LDAP connection parameters which do not have a dedicated setter. 31356 See for example <a href="http://docs.oracle.com/javase/tutorial/jndi/ldap/jndi.html" class="bare">http://docs.oracle.com/javase/tutorial/jndi/ldap/jndi.html</a> for custom 31357 properties. Such properties are for example to configure connection pooling, specific 31358 security settings, etc. All the provided parameters will be provided when creating a 31359 connection to the LDAP system.</p></td> 31360<td class="tableblock halign-left valign-top"><p class="tableblock">Map<String, String></p></td> 31361<td class="tableblock halign-left valign-top"></td> 31362</tr> 31363<tr> 31364<td class="tableblock halign-left valign-top"><p class="tableblock">baseDn</p></td> 31365<td class="tableblock halign-left valign-top"><p class="tableblock">The base <em>distinguished name</em> (DN) from which the searches for users and groups are started</p></td> 31366<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31367<td class="tableblock halign-left valign-top"></td> 31368</tr> 31369<tr> 31370<td class="tableblock halign-left valign-top"><p class="tableblock">userBaseDn</p></td> 31371<td class="tableblock halign-left valign-top"><p class="tableblock">The base <em>distinguished name</em> (DN) from which the searches for users are started. If not provided, baseDn (see above) will be used</p></td> 31372<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31373<td class="tableblock halign-left valign-top"></td> 31374</tr> 31375<tr> 31376<td class="tableblock halign-left valign-top"><p class="tableblock">groupBaseDn</p></td> 31377<td class="tableblock halign-left valign-top"><p class="tableblock">The base <em>distinguished name</em> (DN) from which the searches for groups are started. If not provided, baseDn (see above) will be used</p></td> 31378<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31379<td class="tableblock halign-left valign-top"></td> 31380</tr> 31381<tr> 31382<td class="tableblock halign-left valign-top"><p class="tableblock">searchTimeLimit</p></td> 31383<td class="tableblock halign-left valign-top"><p class="tableblock">The timeout that is used when doing a search in LDAP in milliseconds</p></td> 31384<td class="tableblock halign-left valign-top"><p class="tableblock">long</p></td> 31385<td class="tableblock halign-left valign-top"><p class="tableblock">one hour</p></td> 31386</tr> 31387<tr> 31388<td class="tableblock halign-left valign-top"><p class="tableblock">queryUserByUserId</p></td> 31389<td class="tableblock halign-left valign-top"><p class="tableblock">The query that is executed when searching for a user by userId. 31390 For example: (&(objectClass=inetOrgPerson)(uid={0})) 31391 Here, all the objects in LDAP with the class <em>inetOrgPerson</em> 31392 and who have the matching <em>uid</em> attribute value will be returned. 31393 As shown in the example, the user id is injected by using 31394 {0}. If setting the query alone is insufficient for your specific 31395 LDAP setup, you can alternatively plug in a different 31396 LDAPQueryBuilder, which allows for more customization than only the query.</p></td> 31397<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31398<td class="tableblock halign-left valign-top"></td> 31399</tr> 31400<tr> 31401<td class="tableblock halign-left valign-top"><p class="tableblock">queryUserByFullNameLike</p></td> 31402<td class="tableblock halign-left valign-top"><p class="tableblock">The query that is executed when searching for a user by full name. 31403 For example: (& (objectClass=inetOrgPerson) (</p></td> 31404<td class="tableblock halign-left valign-top"><p class="tableblock">({0}=<strong>{1}</strong>)({2}=<strong>{3}</strong>)) ) 31405 Here, all the objects in LDAP with the class <em>inetOrgPerson</em> 31406 and who have the matching first name and last name values will be returned. 31407 Note that {0} injects the firstNameAttribute (as defined above), {1} and {3} the search text 31408 and {2} the lastNameAttribute. If setting the query alone is insufficient for your specific 31409 LDAP setup, you can alternatively plug in a different 31410 LDAPQueryBuilder, which allows for more customization than only the query.</p></td> 31411<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31412</tr> 31413<tr> 31414<td class="tableblock halign-left valign-top"></td> 31415<td class="tableblock halign-left valign-top"><p class="tableblock">queryGroupsForUser</p></td> 31416<td class="tableblock halign-left valign-top"><p class="tableblock">The query that is executed when searching for the groups of a specific user. 31417 For example: (&(objectClass=groupOfUniqueNames)(uniqueMember={0})) 31418 Here, all the objects in LDAP with the class <em>groupOfUniqueNames</em> 31419 and where the provided DN (matching a DN for a user) is a <em>uniqueMember</em> are returned. 31420 As shown in the example, the user id is injected by using {0} 31421 If setting the query alone is insufficient for your specific 31422 LDAP setup, you can alternatively plug in a different 31423 LDAPQueryBuilder, which allows for more customization than only the query.</p></td> 31424<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31425</tr> 31426<tr> 31427<td class="tableblock halign-left valign-top"></td> 31428<td class="tableblock halign-left valign-top"><p class="tableblock">userIdAttribute</p></td> 31429<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the attribute that matches the user id. 31430 This property is used when looking for a User object 31431 and the mapping between the LDAP object and the Activiti User object 31432 is done.</p></td> 31433<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31434</tr> 31435<tr> 31436<td class="tableblock halign-left valign-top"></td> 31437<td class="tableblock halign-left valign-top"><p class="tableblock">userFirstNameAttribute</p></td> 31438<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the attribute that matches the user first name. 31439 This property is used when looking for a User object 31440 and the mapping between the LDAP object and the Activiti User object is done.</p></td> 31441<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31442</tr> 31443<tr> 31444<td class="tableblock halign-left valign-top"></td> 31445<td class="tableblock halign-left valign-top"><p class="tableblock">userLastNameAttribute</p></td> 31446<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the attribute that matches the user last name. 31447 This property is used when looking for a User object 31448 and the mapping between the LDAP object and the Activiti User object is done.</p></td> 31449<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31450</tr> 31451<tr> 31452<td class="tableblock halign-left valign-top"></td> 31453<td class="tableblock halign-left valign-top"><p class="tableblock">groupIdAttribute</p></td> 31454<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the attribute that matches the group id. 31455 This property is used when looking for a Group object 31456 and the mapping between the LDAP object and the Activiti Group object is done.</p></td> 31457<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> 31458</tr> 31459<tr> 31460<td class="tableblock halign-left valign-top"></td> 31461<td class="tableblock halign-left valign-top"><p class="tableblock">groupNameAttribute</p></td> 31462<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the attribute that matches the group name. 31463 This property is used when looking for a Group object 31464 and the mapping between the LDAP object and the Activiti Group object is done.</p></td> 31465<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31466</tr> 31467<tr> 31468<td class="tableblock halign-left valign-top"></td> 31469<td class="tableblock halign-left valign-top"><p class="tableblock">groupTypeAttribute</p></td> 31470<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the attribute that matches the group type. 31471 This property is used when looking for a Group object 31472 and the mapping between the LDAP object and the Activiti Group object 31473 is done.</p></td> 31474<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td> 31475</tr> 31476</tbody> 31477</table> 31478<div class="paragraph"> 31479<p>Following properties are when one wants to customize default behavior or introduced group caching:</p> 31480</div> 31481<table class="tableblock frame-all grid-all spread"> 31482<caption class="title">Table 260. Advanced properties</caption> 31483<colgroup> 31484<col style="width: 25%;"> 31485<col style="width: 25%;"> 31486<col style="width: 25%;"> 31487<col style="width: 25%;"> 31488</colgroup> 31489<thead> 31490<tr> 31491<th class="tableblock halign-left valign-top">Property name</th> 31492<th class="tableblock halign-left valign-top">Description</th> 31493<th class="tableblock halign-left valign-top">Type</th> 31494<th class="tableblock halign-left valign-top">Default value</th> 31495</tr> 31496</thead> 31497<tbody> 31498<tr> 31499<td class="tableblock halign-left
31499 valign-top"><p class="tableblock">ldapUserManagerFactory</p></td> 31500<td class="tableblock halign-left valign-top"><p class="tableblock">Set a custom implementation of the LDAPUserManagerFactory if the default implementation is not suitable.</p></td> 31501<td class="tableblock halign-left valign-top"><p class="tableblock">instance of LDAPUserManagerFactory</p></td> 31502<td class="tableblock halign-left valign-top"></td> 31503</tr> 31504<tr> 31505<td class="tableblock halign-left valign-top"><p class="tableblock">ldapGroupManagerFactory</p></td> 31506<td class="tableblock halign-left valign-top"><p class="tableblock">Set a custom implementation of the LDAPGroupManagerFactory if the default implementation is not suitable.</p></td> 31507<td class="tableblock halign-left valign-top"><p class="tableblock">instance of LDAPGroupManagerFactory</p></td> 31508<td class="tableblock halign-left valign-top"></td> 31509</tr> 31510<tr> 31511<td class="tableblock halign-left valign-top"><p class="tableblock">ldapMemberShipManagerFactory</p></td> 31512<td class="tableblock halign-left valign-top"><p class="tableblock">Set a custom implementation of the LDAPMembershipManagerFactory if the default implementation is not suitable. 31513 Note that this is very unlikely, as membership are managed in the LDAP system itself normally.</p></td> 31514<td class="tableblock halign-left valign-top"><p class="tableblock">An instance of LDAPMembershipManagerFactory</p></td> 31515<td class="tableblock halign-left valign-top"></td> 31516</tr> 31517<tr> 31518<td class="tableblock halign-left valign-top"><p class="tableblock">ldapQueryBuilder</p></td> 31519<td class="tableblock halign-left valign-top"><p class="tableblock">Set a custom query builder if the default implementation is not suitable. 31520 The LDAPQueryBuilder instance is used when the LDAPUserManager or 31521 LDAPGroupManage} does an actual query against the LDAP system. 31522 The default implementation uses the properties as set on this instance 31523 such as queryGroupsForUser and queryUserById</p></td> 31524<td class="tableblock halign-left valign-top"><p class="tableblock">An instance of org.activiti.ldap.LDAPQueryBuilder</p></td> 31525<td class="tableblock halign-left valign-top"></td> 31526</tr> 31527<tr> 31528<td class="tableblock halign-left valign-top"><p class="tableblock">groupCacheSize</p></td> 31529<td class="tableblock halign-left valign-top"><p class="tableblock">Allows to set the size of the group cache. 31530 This is an LRU cache that caches groups for users and thus 31531 avoids hitting the LDAP system each time the groups of 31532 a user needs to be known. 31533</p><p class="tableblock"> The cache will not be instantiated if the value is less than zero. 31534 By default set to -1, so no caching is done.</p></td> 31535<td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> 31536<td class="tableblock halign-left valign-top"><p class="tableblock">-1</p></td> 31537</tr> 31538<tr> 31539<td class="tableblock halign-left valign-top"><p class="tableblock">groupCacheExpirationTime</p></td> 31540<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the expiration time of the group cache in milliseconds. 31541 When groups for a specific user are fetched, and if the group cache exists, 31542 the groups will be stored in this cache for the time set in this property. 31543 I.e. when the groups were fetched at 00:00 and the expiration time is 30 minutes, 31544 any fetch of the groups for that user after 00:30 will not come from the cache, but do 31545 a fetch again from the LDAP system. Likewise, everything group fetch for that user done 31546 between 00:00 - 00:30 will come from the cache.</p></td> 31547<td class="tableblock halign-left valign-top"><p class="tableblock">long</p></td> 31548<td class="tableblock halign-left valign-top"><p class="tableblock">one hour</p></td> 31549</tr> 31550</tbody> 31551</table> 31552<div class="paragraph"> 31553<p>Note when using Active Directory: people in the Activiti forum have reported that for Activiti Directory, the <em>InitialDirContext</em> needs to be set to Context.REFERRAL. This can be passed through the customConnectionParameters map as described above.</p> 31554</div> 31555</div> 31556</div> 31557</div> 31558<div class="sect1"> 31559<h2 id="_advanced">16. Advanced</h2> 31560<div class="sectionbody"> 31561<div class="paragraph"> 31562<p>The following sections cover advanced use cases of Activiti, that go beyond typical execution of BPMN 2.0 processes. As such, a certain proficiency and experience with Activiti is advised to understand the topics described here.</p> 31563</div> 31564<div class="sect2"> 31565<h3 id="_async_executor">16.1. Async Executor</h3> 31566<div class="paragraph"> 31567<p>In Activiti version 5 (starting from version 5.17.0), the Async executor was added in addition to the existing job executor. The Async Executor has proved to be more performant than the old job executor by many users of Activiti and our benchmarks.</p> 31568</div> 31569<div class="paragraph"> 31570<p>In Activiti 6 (and later), the async executor is the only one available. For version 6, the async executor was completely refactored for optimal performance and pluggability (while still being compatible with existing API’s).</p> 31571</div> 31572<div class="sect3"> 31573<h4 id="async_executor_design">16.1.1. Async Executor design</h4> 31574<div class="paragraph"> 31575<p>Two types of jobs exist: timers (like those belonging to a boundary event on a user task) and async continuations (belonging to a service task with the <em>activiti:async="true"</em> attribute).</p> 31576</div> 31577<div class="paragraph"> 31578<p><strong>Timers</strong> are the easiest to explain: they are persisted in the ACT_RU_TIMER_JOB table with a certain due date. There is a thread in the async executor that periodically checks if there are new timers that fire (i.e. the due date is <em>before</em> the current time). When that happens, the timer is removed and an async job is created and inserted.</p> 31579</div> 31580<div class="paragraph"> 31581<p>An <strong>async job</strong> is inserted in the database during the execution of process instance steps (which means <em>during some API call that was made</em>). If the async executor is active for the current Activiti engine, the async job is actually already <em>locked</em>. This means that the job entry is inserted in the ACT_RU_JOB table and will have a <em>lock owner</em> and a <em>lock expiration time</em> set. A transaction listener that fires on a successful commit of the API call triggers the async executor of the same engine to execute the job (so the data is guaranteed to be in the database). To do this, the async executor has a (configurable) thread pool from which a thread will execute the job and continue the process asynchronously. If the Activiti engine does not have the async executor enabled, the async job is inserted in the ACT_RU_JOB table without being locked.</p> 31582</div> 31583<div class="paragraph"> 31584<p>Similar to the thread that checks for new timers, the async executor has a thread that <em>acquires</em> new async jobs. These are jobs that are present in the table and are not locked. This thread will lock these jobs for the current Activiti engine and pass it to the async executor.</p> 31585</div> 31586<div class="paragraph"> 31587<p>The thread pool executing the jobs uses an in-memory queue to take jobs from. When this queue is full (this is configurable), the job will be unlocked and re-inserted into its table. This way, other async executors can pick it up instead.</p> 31588</div> 31589<div class="paragraph"> 31590<p>In case an exception happens during job execution, the async job will be transformed to a timer job with a due date. It will be picked up like a regular timer job and become an async job again, to be retried soon. When a job has been retried for a (configurable) number of times and continues to fail, the job is assumed to be <em>dead</em> and moved to the ACT_RU_DEADLETTER_JOB. The <em>deadletter</em> concept is widely used in various other systems. An admin will now need to inspect the exception for the failed job and decide what the best course of action is.</p> 31591</div> 31592<div class="paragraph"> 31593<p>Process definitions and process instances can be suspended. Suspended jobs related to these definitions or instances are put in the ACT_RU_SUSPENDED_JOB table, to make sure the query to acquire jobs has a few as possible conditions in its where clause.</p> 31594</div> 31595<div class="paragraph"> 31596<p>One thing that is clear from the above, for people familiar with the old implementations of the job/async executor: the main goal is to allow the <em>acquire queries</em> to be as simple as possible. In the past (before version 6), one table was used for all job types/states, which made the <em>where</em> condition large as it catered for all the use cases. This problem is now solved and our benchmarks have proved that this new design delivers better performance and is more scalable.</p> 31597</div> 31598</div> 31599<div class="sect3"> 31600<h4 id="_async_executor_configuration">16.1.2. Async executor configuration</h4> 31601<div class="paragraph"> 31602<p>The async executor is a highly configurable component. It’
31602s always recommended to look into the default settings of the async executor and validate if they match the requirements of your processes.</p> 31603</div> 31604<div class="paragraph"> 31605<p>Alternatively, it’s possible to extend the default implementation or implement the <em>org.activiti.engine.impl.asyncexecutor.AsyncExecutor</em> interface with your own implementation.</p> 31606</div> 31607<div class="paragraph"> 31608<p>The following properties are available on the process engine configuration via setters:</p> 31609</div> 31610<table class="tableblock frame-all grid-all spread"> 31611<caption class="title">Table 261. Async executor configuration options</caption> 31612<colgroup> 31613<col style="width: 33.3333%;"> 31614<col style="width: 33.3333%;"> 31615<col style="width: 33.3334%;"> 31616</colgroup> 31617<thead> 31618<tr> 31619<th class="tableblock halign-left valign-top">Name</th> 31620<th class="tableblock halign-left valign-top">Default value</th> 31621<th class="tableblock halign-left valign-top">Description</th> 31622</tr> 31623</thead> 31624<tbody> 31625<tr> 31626<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorThreadPoolQueueSize</p></td> 31627<td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> 31628<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the queue on which jobs to be executed are placed after being acquired, before they are actually executed by a thread from the thread pool</p></td> 31629</tr> 31630<tr> 31631<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorCorePoolSize</p></td> 31632<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 31633<td class="tableblock halign-left valign-top"><p class="tableblock">The minimal number of threads that are kept alive in the thread pool for job execution.</p></td> 31634</tr> 31635<tr> 31636<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorMaxPoolSize</p></td> 31637<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td> 31638<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of threads that are created in the thread pool for job execution.</p></td> 31639</tr> 31640<tr> 31641<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorThreadKeepAliveTime</p></td> 31642<td class="tableblock halign-left valign-top"><p class="tableblock">5000</p></td> 31643<td class="tableblock halign-left valign-top"><p class="tableblock">The time (in milliseconds) a thread used for job execution must be kept alive before it is destroyed. Having a setting > 0 takes resources, but in the case of many job executions it avoids creating new threads all the time. If 0, threads will be destroyed after they’ve been used for job execution.</p></td> 31644</tr> 31645<tr> 31646<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorNumberOfRetries</p></td> 31647<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 31648<td class="tableblock halign-left valign-top"><p class="tableblock">The number of times a job will be retried before it is moved to the <em>deadletter</em> table.</p></td> 31649</tr> 31650<tr> 31651<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorMaxTimerJobsPerAcquisition</p></td> 31652<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 31653<td class="tableblock halign-left valign-top"><p class="tableblock">The number of timer jobs that are acquired during one acquirement query. Default value is 1, as this lowers the potential for optimistic locking exceptions. Larger values can perform better, but the chance of optimistic locking exceptions occurring between different engines becomes larger too.</p></td> 31654</tr> 31655<tr> 31656<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorMaxAsyncJobsDuePerAcquisition</p></td> 31657<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 31658<td class="tableblock halign-left valign-top"><p class="tableblock">The number of async jobs that are acquired during one acquirement query. Default value is 1, as this lowers the potential for optimistic locking exceptions. Larger values can perform better, but the chance of optimistic locking exceptions occurring between different engines becomes larger too.</p></td> 31659</tr> 31660<tr> 31661<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorDefaultTimerJobAcquireWaitTime</p></td> 31662<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td> 31663<td class="tableblock halign-left valign-top"><p class="tableblock">The time (in milliseconds) the timer acquisition thread will wait to execute the next acquirement query. This happens when no new timer jobs were found or when less timer jobs have been fetched than set in <em>asyncExecutorMaxTimerJobsPerAcquisition</em>.</p></td> 31664</tr> 31665<tr> 31666<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorDefaultAsyncJobAcquireWaitTime</p></td> 31667<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td> 31668<td class="tableblock halign-left valign-top"><p class="tableblock">The time (in milliseconds) the async job acquisition thread will wait to execute the next acquirement query. This happens when no new async jobs were found or when less async jobs have been fetched than set in <em>asyncExecutorMaxAsyncJobsDuePerAcquisition</em>.</p></td> 31669</tr> 31670<tr> 31671<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorDefaultQueueSizeFullWaitTime</p></td> 31672<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> 31673<td class="tableblock halign-left valign-top"><p class="tableblock">The time (in milliseconds) the async job (both timer and async continuations) acquisition thread will wait when the internal job queue is full to execute the next query. By default set to 0 (for backwards compatibility). Setting this property to a higher value allows the async executor to hopefully clear its queue a bit.</p></td> 31674</tr> 31675<tr> 31676<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorTimerLockTimeInMillis</p></td> 31677<td class="tableblock halign-left valign-top"><p class="tableblock">5 minutes</p></td> 31678<td class="tableblock halign-left valign-top"><p class="tableblock">The amount of time (in milliseconds) a timer job is locked when acquired by the async executor. During this period of time, no other async executor will try to acquire and lock this job.</p></td> 31679</tr> 31680<tr> 31681<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorAsyncJobLockTimeInMillis</p></td> 31682<td class="tableblock halign-left valign-top"><p class="tableblock">5 minutes</p></td> 31683<td class="tableblock halign-left valign-top"><p class="tableblock">The amount of time (in milliseconds) an async job is locked when acquired by the async executor. During this period of time, no other async executor will try to acquire and lock this job.</p></td> 31684</tr> 31685<tr> 31686<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorSecondsToWaitOnShutdown</p></td> 31687<td class="tableblock halign-left valign-top"><p class="tableblock">60</p></td> 31688<td class="tableblock halign-left valign-top"><p class="tableblock">The time (in seconds) that is waited to gracefully shut down the thread pool used for job execution when the a shutdown on the executor (or process engine) is requested.</p></td> 31689</tr> 31690<tr> 31691<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorResetExpiredJobsInterval</p></td> 31692<td class="tableblock halign-left valign-top"><p class="tableblock">60 seconds</p></td> 31693<td class="tableblock halign-left valign-top"><p class="tableblock">The amount of time (in milliseconds) that is between two consecutive checks of <em>expired jobs</em>. Expired jobs are jobs that were locked (a lock owner + time was written by some executor, but the job was never completed). During such a check, jobs that are expired are made available again, meaning the lock owner and lock time will be removed. Other executors will now be able to pick it up. A job is deemed expired if the lock time is before the current date.</p></td> 31694</tr> 31695<tr> 31696<td class="tableblock halign-left valign-top"><p class="tableblock">asyncExecutorResetExpiredJobsPageSize</p></td> 31697<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 31698<td class="tableblock halign-left valign-top"><p class="tableblock">The amount of jobs that are fetched at once by the <em>reset expired</em> thread of the async executor.</p></td> 31699</tr> 31700</tbody> 31701</table> 31702</div> 31703<div class="sect3"> 31704<h4 id="_message_queue_based_async_executor">16.1.3. Message Queue based Async Executor</h4> 31705<div class="paragraph"> 31706<p>When reading the <a href="#async_executor_design">async executor design section</a>, it becomes clear that the architecture is inspired by message queues. The async executor is designed in such a way that a message queue can easily be used to take over the job of the thread pool and the handling of async jobs.</p> 31707</div> 31708<div class="paragraph"> 31709<p>Benchmarks have shown that using a message queue is superior, throughput-wise, to the thread pool-backed async executor. However, it does come with an extra architectural component, which of course makes setup, maintenance and monitoring more complex. For many users, the performance of the thread pool-backed async executor is more than sufficient. It is nice to know however, that there is an alternative if the required performance grows.</p> 31710</div> 31711<div class="paragraph"> 31712<p>Currently, the only option that is supported out-of-the-box is JMS and Spring. The reason for supporting Spring before anything else is because Spring has some very nice features that ease a lot of the pain when it comes to threading and dealing with multiple message consumers. However, the integration is so simple, that it can easily be ported to any message queue implementation and/or protocol (Stomp, AMPQ, etc.). Feedback is appreciated for what should be the next implementation.</p> 31713</div> 31714<div class="paragraph"> 31715<p>When a new async job is created by the engine, a message is put on a message queue (in a transaction committed transaction listener, so we’re sure the job entry is in the database) containing the job identifier. A message consumer then takes this job identifier to fetch the job, and execute the job. The async executor will not create a thread pool anymore. It will insert and query for timers from a separate thread. When a timer fires, it is moved to the async job table, which now means a message is sent to the message queue too. The <em>reset expired</em> thread will also unlock jobs as usual, as message queues can fail too. Instead of <em>unlocking</em> a job, a message will now be resent. The async executor will not poll for async jobs anymore.</p> 31716</div> 31717<div class="paragraph"> 31718<p>The implementation consists of two classes:</p> 31719</div> 31720<div class="ulist"> 31721<ul> 31722<li> 31723<p>An implementation of the <em>org.activiti.engine.impl.asyncexecutor.JobManager</em> interface that puts a message on a message queue instead of passing it to the thread pool.</p> 31724</li> 31725<li> 31726<p>A <em>javax.jms.MessageListener</em> implementation that consumes a message from the message queue, using the job identifier in the message to fetch and execute the job.</p> 31727</li> 31728</ul> 31729</div> 31730<div class="paragraph"> 31731<p>First of all, add the <em>activiti-jms-spring-executor</em> dependency to your project:</p> 31732</div> 31733<div class="listingblock"> 31734<div class="content"> 31735<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 317362 317373 317384 317395</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 31740 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 31741 <span class="tok-nt"><artifactId></span>activiti-jms-spring-executor<span class="tok-nt"></artifactId></span> 31742 <span class="tok-nt"><version></span>${activiti.version}<span class="tok-nt"></version></span> 31743<span class="tok-nt"></dependency></span> 31744</td></tr></table></code></pre> 31745</div> 31746</div> 31747<div class="paragraph"> 31748<p>To enable the message queue based async executor, in the process engine configuration, the following needs to be done:</p> 31749</div> 31750<div class="ulist"> 31751<ul> 31752<li> 31753<p><em>asyncExecutorActivate</em> must be set to <em>true</em>, as usual</p> 31754</li> 31755<li> 31756<p><em>asyncExecutorMessageQueueMode</em> needs to be set to <em>true</em></p> 31757</li> 31758<li> 31759<p>The <em>org.activiti.spring.executor.jms.MessageBasedJobManager</em> must be injected as <em>JobManager</em></p> 31760</li> 31761</ul> 31762</div> 31763<div class="paragraph"> 31764<p>Below is a complete example of a Java based configuration, using <em>ActiveMQ</em> as message queue broker.</p> 31765</div> 31766<div class="paragraph"> 31767<p>Some things to note:</p> 31768</div> 31769<div class="ulist"> 31770<ul> 31771<li> 31772<p>The <em>MessageBasedJobManager</em> expects a <em>JMSTemplate</em> to be injected that is configured with a correct <em>connectionFactory</em>.</p> 31773</li> 31774<li> 31775<p>We’re using the <em>MessageListenerContainer</em> concept from Spring, as this simplifies threading and multiple consumers a lot.</p> 31776</li> 31777</ul> 31778</div> 31779<div class="listingblock"> 31780<div class="content"> 31781<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 31782 2 31783 3 31784 4 31785 5 31786 6 31787 7 31788 8 31789 9 3179010 3179111 3179212 3179313 3179414 3179515 3179616 3179717 3179818 3179919 3180020 3180121 3180222 3180323 3180424 3180525 3180626 3180727 3180828 3180929 3181030 3181131 3181232 3181333 3181434 3181535 3181636 3181737 3181838 3181939 3182040 3182141 3182242 3182343 3182444 3182545 3182646 3182747 3182848 3182949 3183050
3183151 3183252 3183353 3183454 3183555 3183656 3183757 3183858 3183959 3184060 3184161 3184262 3184363 3184464 3184565 3184666 3184767 3184868 3184969 3185070 3185171 3185272 3185373 3185474</div></td><td class="code"><span></span><span class="tok-nd">@Configuration</span> 31855<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">SpringJmsConfig</span> <span class="tok-o">{</span> 31856 31857 <span class="tok-nd">@Bean</span> 31858 <span class="tok-kd">public</span> <span class="tok-n">DataSource</span> <span class="tok-nf">dataSource</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31859 <span class="tok-c1">// Omitted</span> 31860 <span class="tok-o">}</span> 31861 31862 <span class="tok-nd">@Bean</span><span class="tok-o">(</span><span class="tok-n">name</span> <span class="tok-o">=</span> <span class="tok-s">"transactionManager"</span><span class="tok-o">)</span> 31863 <span class="tok-kd">public</span> <span class="tok-n">PlatformTransactionManager</span> <span class="tok-nf">transactionManager</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31864 <span class="tok-n">DataSourceTransactionManager</span> <span class="tok-n">transactionManager</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">DataSourceTransactionManager</span><span class="tok-o">();</span> 31865 <span class="tok-n">transactionManager</span><span class="tok-o">.</span><span class="tok-na">setDataSource</span><span class="tok-o">(</span><span class="tok-n">dataSource</span><span class="tok-o">());</span> 31866 <span class="tok-k">return</span> <span class="tok-n">transactionManager</span><span class="tok-o">;</span> 31867 <span class="tok-o">}</span> 31868 31869 <span class="tok-nd">@Bean</span> 31870 <span class="tok-kd">public</span> <span class="tok-n">SpringProcessEngineConfiguration</span> <span class="tok-nf">processEngineConfiguration</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31871 <span class="tok-n">SpringProcessEngineConfiguration</span> <span class="tok-n">configuration</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">SpringProcessEngineConfiguration</span><span class="tok-o">();</span> 31872 <span class="tok-n">configuration</span><span class="tok-o">.</span><span class="tok-na">setDataSource</span><span class="tok-o">(</span><span class="tok-n">dataSource</span><span class="tok-o">());</span> 31873 <span class="tok-n">configuration</span><span class="tok-o">.</span><span class="tok-na">setTransactionManager</span><span class="tok-o">(</span><span class="tok-n">transactionManager</span><span class="tok-o">());</span> 31874 <span class="tok-n">configuration</span><span class="tok-o">.</span><span class="tok-na">setDatabaseSchemaUpdate</span><span class="tok-o">(</span><span class="tok-n">SpringProcessEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">DB_SCHEMA_UPDATE_TRUE</span><span class="tok-o">);</span> 31875 <span class="tok-n">configuration</span><span class="tok-o">.</span><span class="tok-na">setAsyncExecutorMessageQueueMode</span><span class="tok-o">(</span><span class="tok-kc">true</span><span class="tok-o">);</span> 31876 <span class="tok-n">configuration</span><span class="tok-o">.</span><span class="tok-na">setAsyncExecutorActivate</span><span class="tok-o">(</span><span class="tok-kc">true</span><span class="tok-o">);</span> 31877 <span class="tok-n">configuration</span><span class="tok-o">.</span><span class="tok-na">setJobManager</span><span class="tok-o">(</span><span class="tok-n">jobManager</span><span class="tok-o">());</span> 31878 <span class="tok-k">return</span> <span class="tok-n">configuration</span><span class="tok-o">;</span> 31879 <span class="tok-o">}</span> 31880 31881 <span class="tok-nd">@Bean</span> 31882 <span class="tok-kd">public</span> <span class="tok-n">ProcessEngine</span> <span class="tok-nf">processEngine</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31883 <span class="tok-k">return</span> <span class="tok-n">processEngineConfiguration</span><span class="tok-o">().</span><span class="tok-na">buildProcessEngine</span><span class="tok-o">();</span> 31884 <span class="tok-o">}</span> 31885 31886 <span class="tok-nd">@Bean</span> 31887 <span class="tok-kd">public</span> <span class="tok-n">MessageBasedJobManager</span> <span class="tok-nf">jobManager</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31888 <span class="tok-n">MessageBasedJobManager</span> <span class="tok-n">jobManager</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">MessageBasedJobManager</span><span class="tok-o">();</span> 31889 <span class="tok-n">jobManager</span><span class="tok-o">.</span><span class="tok-na">setJmsTemplate</span><span class="tok-o">(</span><span class="tok-n">jmsTemplate</span><span class="tok-o">());</span> 31890 <span class="tok-k">return</span> <span class="tok-n">jobManager</span><span class="tok-o">;</span> 31891 <span class="tok-o">}</span> 31892 31893 <span class="tok-nd">@Bean</span> 31894 <span class="tok-kd">public</span> <span class="tok-n">ConnectionFactory</span> <span class="tok-nf">connectionFactory</span><span class="tok-o">()</span> <span class="tok-o">{</span>
31895 <span class="tok-n">ActiveMQConnectionFactory</span> <span class="tok-n">activeMQConnectionFactory</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">ActiveMQConnectionFactory</span><span class="tok-o">(</span><span class="tok-s">"tcp://localhost:61616"</span><span class="tok-o">);</span> 31896 <span class="tok-n">activeMQConnectionFactory</span><span class="tok-o">.</span><span class="tok-na">setUseAsyncSend</span><span class="tok-o">(</span><span class="tok-kc">true</span><span class="tok-o">);</span> 31897 <span class="tok-n">activeMQConnectionFactory</span><span class="tok-o">.</span><span class="tok-na">setAlwaysSessionAsync</span><span class="tok-o">(</span><span class="tok-kc">true</span><span class="tok-o">);</span> 31898 <span class="tok-k">return</span> <span class="tok-k">new</span> <span class="tok-n">CachingConnectionFactory</span><span class="tok-o">(</span><span class="tok-n">activeMQConnectionFactory</span><span class="tok-o">);</span> 31899 <span class="tok-o">}</span> 31900 31901 <span class="tok-nd">@Bean</span> 31902 <span class="tok-kd">public</span> <span class="tok-n">JmsTemplate</span> <span class="tok-nf">jmsTemplate</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31903 <span class="tok-n">JmsTemplate</span> <span class="tok-n">jmsTemplate</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">JmsTemplate</span><span class="tok-o">();</span> 31904 <span class="tok-n">jmsTemplate</span><span class="tok-o">.</span><span class="tok-na">setDefaultDestination</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">ActiveMQQueue</span><span class="tok-o">(</span><span class="tok-s">"activiti-jobs"</span><span class="tok-o">));</span> 31905 <span class="tok-n">jmsTemplate</span><span class="tok-o">.</span><span class="tok-na">setConnectionFactory</span><span class="tok-o">(</span><span class="tok-n">connectionFactory</span><span class="tok-o">());</span> 31906 <span class="tok-k">return</span> <span class="tok-n">jmsTemplate</span><span class="tok-o">;</span> 31907 <span class="tok-o">}</span> 31908 31909 <span class="tok-nd">@Bean</span> 31910 <span class="tok-kd">public</span> <span class="tok-n">MessageListenerContainer</span> <span class="tok-nf">messageListenerContainer</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31911 <span class="tok-n">DefaultMessageListenerContainer</span> <span class="tok-n">messageListenerContainer</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">DefaultMessageListenerContainer</span><span class="tok-o">();</span> 31912 <span class="tok-n">messageListenerContainer</span><span class="tok-o">.</span><span class="tok-na">setConnectionFactory</span><span class="tok-o">(</span><span class="tok-n">connectionFactory</span><span class="tok-o">());</span> 31913 <span class="tok-n">messageListenerContainer</span><span class="tok-o">.</span><span class="tok-na">setDestinationName</span><span class="tok-o">(</span><span class="tok-s">"activiti-jobs"</span><span class="tok-o">);</span> 31914 <span class="tok-n">messageListenerContainer</span><span class="tok-o">.</span><span class="tok-na">setMessageListener</span><span class="tok-o">(</span><span class="tok-n">jobMessageListener</span><span class="tok-o">());</span> 31915 <span class="tok-n">messageListenerContainer</span><span class="tok-o">.</span><span class="tok-na">setConcurrentConsumers</span><span class="tok-o">(</span><span class="tok-mi">2</span><span class="tok-o">);</span> 31916 <span class="tok-n">messageListenerContainer</span><span class="tok-o">.</span><span class="tok-na">start</span><span class="tok-o">();</span> 31917 <span class="tok-k">return</span> <span class="tok-n">messageListenerContainer</span><span class="tok-o">;</span> 31918 <span class="tok-o">}</span> 31919 31920 <span class="tok-nd">@Bean</span> 31921 <span class="tok-kd">public</span> <span class="tok-n">JobMessageListener</span> <span class="tok-nf">jobMessageListener</span><span class="tok-o">()</span> <span class="tok-o">{</span> 31922 <span class="tok-n">JobMessageListener</span> <span class="tok-n">jobMessageListener</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">JobMessageListener</span><span class="tok-o">();</span> 31923 <span class="tok-n">jobMessageListener</span><span class="tok-o">.</span><span class="tok-na">setProcessEngineConfiguration</span><span class="tok-o">(</span><span class="tok-n">
31923processEngineConfiguration</span><span class="tok-o">());</span> 31924 <span class="tok-k">return</span> <span class="tok-n">jobMessageListener</span><span class="tok-o">;</span> 31925 <span class="tok-o">}</span> 31926 31927<span class="tok-o">}</span> 31928</td></tr></table></code></pre> 31929</div> 31930</div> 31931<div class="paragraph"> 31932<p>In the code above, the <em>JobMessageListener</em> and <em>MessageBasedJobManager</em> are the only classes from the <em>activiti-jms-spring-executor</em> module. All the other code is from Spring. As such, when wanting to port this to other queues/protocols, these classes must be ported.</p> 31933</div> 31934</div> 31935</div> 31936<div class="sect2"> 31937<h3 id="advanced_parseHandlers">16.2. Hooking into process parsing</h3> 31938<div class="paragraph"> 31939<p>A BPMN 2.0 xml needs to be parsed to the Activiti internal model to be executed on the Activiti engine. This parsing happens during a deployment of the process or when a process is not found in memory, and the xml is fetched from the database.</p> 31940</div> 31941<div class="paragraph"> 31942<p>For each of these processes, the <code>BpmnParser</code> class creates a new <code>BpmnParse</code> instance. This instance will be used as container for all things that are done during parsing. The parsing on itself is very simple: for each BPMN 2.0 element, there is a matching instance of the <code>org.activiti.engine.parse.BpmnParseHandler</code> available in the engine. As such, the parser has a map which basically maps a BPMN 2.0 element class to an instance of <code>BpmnParseHandler</code>. By default, Activiti has <code>BpmnParseHandler</code> instances to handle all supported elements and also uses it to attach execution listeners to steps of the process for creating the history.</p> 31943</div> 31944<div class="paragraph"> 31945<p>It is possible to add custom instances of <code>org.activiti.engine.parse.BpmnParseHandler</code> to the Activiti engine. An often seen use case is for example to add execution listeners to certain steps that fire events to some queue for event processing. The history handling is done in such a way internally in Activiti. To add such custom handlers, the Activiti configuration needs to be tweaked:</p> 31946</div> 31947<div class="listingblock"> 31948<div class="content"> 31949<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 31950 2 31951 3 31952 4 31953 5 31954 6 31955 7 31956 8 31957 9 3195810 3195911 3196012</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"preBpmnParseHandlers"</span><span class="tok-nt">></span> 31961 <span class="tok-nt"><list></span> 31962 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.parsing.MyFirstBpmnParseHandler"</span> <span class="tok-nt">/></span> 31963 <span class="tok-nt"></list></span> 31964<span class="tok-nt"></property></span> 31965 31966<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"postBpmnParseHandlers"</span><span class="tok-nt">></span> 31967 <span class="tok-nt"><list></span> 31968 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.parsing.MySecondBpmnParseHandler"</span> <span class="tok-nt">/></span> 31969 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.parsing.MyThirdBpmnParseHandler"</span> <span class="tok-nt">/></span> 31970 <span class="tok-nt"></list></span> 31971<span class="tok-nt"></property></span> 31972</td></tr></table></code></pre> 31973</div> 31974</div> 31975<div class="paragraph"> 31976<p>The list of <code>BpmnParseHandler</code> instances that is configured in the <code>preBpmnParseHandlers</code> property are added before any of the default handlers. Likewise, the <code>postBpmnParseHandlers</code> are added after those. This can be important if the order of things matter for the logic contained in the custom parse handlers.</p> 31977</div> 31978<div class="paragraph"> 31979<p><code>org.activiti.engine.parse.BpmnParseHandler</code> is a simple interface:</p> 31980</div> 31981<div class="listingblock"> 31982<div class="content"> 31983<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 319842 319853 319864 319875 319886 319897</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">interface</span> <span class="tok-nc">BpmnParseHandler</span> <span class="tok-o">{</span> 31990 31991 <span class="tok-n">Collection</span><span class="tok-o"><</span><span class="tok-n">Class</span><span class="tok-o">>?</span> <span class="tok-kd">extends</span> <span class="tok-n">BaseElement</span><span class="tok-o">>></span> <span class="tok-nf">getHandledTypes</span><span class="tok-o">();</span> 31992 31993 <span class="tok-kt">void</span> <span class="tok-nf">parse</span><span class="tok-o">(</span><span class="tok-n">BpmnParse</span> <span class="tok-n">bpmnParse</span><span class="tok-o">,</span> <span class="tok-n">BaseElement</span> <span class="tok-n">element</span><span class="tok-o">);</span> 31994 31995<span class="tok-o">}</span> 31996</td></tr></table></code></pre> 31997</div> 31998</div> 31999<div class="paragraph"> 32000<p>The <code>getHandledTypes()</code> method returns a collection of all the types handled by this parser. The possible types are a subclass of <code>BaseElement</code>, as directed by the generic type of the collection. You can also extend the <code>AbstractBpmnParseHandler</code> class and override the <code>getHandledType()</code> method, which only returns one Class and not a collection. This class contains also some helper methods shared by many of the default parse handlers. The <code>BpmnParseHandler</code> instance will be called when the parser encounters any of the returned types by this method. In the following example, whenever a process contained in a BPMN 2.0 xml is encountered, it will execute the logic in the <code>executeParse</code> method (which is a typecasted method that replaces the regular <code>parse</code> method on the <code>BpmnParseHandler</code> interface).</p> 32001</div> 32002<div class="listingblock"> 32003<div class="content"> 32004<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32005 2 32006 3 32007 4 32008 5 32009 6 32010 7 32011 8 32012 9 3201310 3201411</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">TestBPMNParseHandler</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractBpmnParseHandler</span><span class="tok-o"><</span><span class="tok-n">Process</span><span class="tok-o">></span> <span class="tok-o">{</span> 32015 32016 <span class="tok-kd">protected</span> <span class="tok-n">Class</span><span class="tok-o"><?</span> <span class="tok-kd">extends</span> <span class="tok-n">BaseElement</span><span class="tok-o">></span> <span class="tok-nf">getHandledType</span><span class="tok-o">()</span> <span class="tok-o">{</span> 32017 <span class="tok-k">return</span> <span class="tok-n">Process</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">;</span> 32018 <span class="tok-o">}</span> 32019 32020 <span class="tok-kd">protected</span> <span class="tok-kt">void</span> <span class="tok-nf">executeParse</span><span class="tok-o">(</span><span class="tok-n">BpmnParse</span> <span class="tok-n">bpmnParse</span><span class="tok-o">,</span> <span class="tok-n">Process</span> <span class="tok-n">element</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32021 <span class="tok-o">..</span> 32022 <span class="tok-o">}</span> 32023 32024<span class="tok-o">}</span> 32025</td></tr></table></code></pre> 32026</div> 32027</div> 32028<div class="paragraph"> 32029<p><strong>Important note:</strong> when writing custom parse handler, do not use any of the internal classes that are used to parse the BPMN 2.0 constructs. This will cause difficult to find bugs. The safe way to implement a custom handler is to implement the <em>BpmnParseHandler</em> interface or extends the internal abstract class <em>org.activiti.engine.impl.bpmn.parser.handler.AbstractBpmnParseHandler</em>.</p> 32030</div> 32031<div class="paragraph"> 32032<p>It is possible (but less common) to replace the default <code>BpmnParseHandler</code> instances that are responsible for the parsing of the BPMN 2.0 elements to the internal Activiti model. This can be done by following snippet of logic:</p> 32033</div> 32034<div class="listingblock"> 32035<div class="content"> 32036<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 320372 320383 320394 320405</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"customDefaultBpmnParseHandlers"</span><span class="tok-nt">></span> 32041 <span class="tok-nt"><list></span> 32042 ... 32043 <span class="tok-nt"></list></span> 32044<span class="tok-nt"></property></span> 32045</td></tr></table></code></pre> 32046</div> 32047</div> 32048<div class="paragraph"> 32049<p>A simple example could for example be to force all of the service tasks to be asynchronous:</p> 32050</div> 32051<div class="listingblock"> 32052<div class="content"> 32053<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32054 2 32055 3 32056 4 32057 5 32058 6 32059 7 32060 8 32061 9 3206210 3206311 3206412 3206513</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">CustomUserTaskBpmnParseHandler</span> <span class="tok-kd">extends</span> <span class="tok-n">ServiceTaskParseHandler</span> <span class="tok-o">{</span> 32066 32067 <span class="tok-kd">protected</span> <span class="tok-kt">void</span> <span class="tok-nf">executeParse</span><span class="tok-o">(</span><span class="tok-n">BpmnParse</span> <span class="tok-n">bpmnParse</span><span class="tok-o">,</span> <span class="tok-n">ServiceTask</span> <span class="tok-n">serviceTask</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32068 32069 <span class="tok-c1">// Do the regular stuff</span> 32070 <span class="tok-kd">
32070super</span><span class="tok-o">.</span><span class="tok-na">executeParse</span><span class="tok-o">(</span><span class="tok-n">bpmnParse</span><span class="tok-o">,</span> <span class="tok-n">serviceTask</span><span class="tok-o">);</span> 32071 32072 <span class="tok-c1">// Make always async</span> 32073 <span class="tok-n">ActivityImpl</span> <span class="tok-n">activity</span> <span class="tok-o">=</span> <span class="tok-n">findActivity</span><span class="tok-o">(</span><span class="tok-n">bpmnParse</span><span class="tok-o">,</span> <span class="tok-n">serviceTask</span><span class="tok-o">.</span><span class="tok-na">getId</span><span class="tok-o">());</span> 32074 <span class="tok-n">activity</span><span class="tok-o">.</span><span class="tok-na">setAsync</span><span class="tok-o">(</span><span class="tok-kc">true</span><span class="tok-o">);</span> 32075 <span class="tok-o">}</span> 32076 32077<span class="tok-o">}</span> 32078</td></tr></table></code></pre> 32079</div> 32080</div> 32081</div> 32082<div class="sect2"> 32083<h3 id="advanced.uuid.generator">16.3. UUID id generator for high concurrency</h3> 32084<div class="paragraph"> 32085<p>In some (very) high concurrency load cases, the default id generator may cause exceptions due to not being able to fetch new id blocks quickly enough. Every process engine has one id generator. The default id generator reserves a block of ids in the database, such that no other engine will be able to use id’s from the same block. During engine operations, when the default id generator notices that the id block is used up, a new transaction is started to fetch a new block. In (very) limited use cases this can cause problems when there is a real high load. For most use cases the default id generator is more than sufficient. The default <code>org.activiti.engine.impl.db.DbIdGenerator</code> also has a property <code>idBlockSize</code> which can be configured to set the size of the reserved block of ids and to tweak the behavior of the id fetching.</p> 32086</div> 32087<div class="paragraph"> 32088<p>The alternative to the default id generator is the <code>org.activiti.engine.impl.persistence.StrongUuidGenerator</code>, which generates a unique <a href="http://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a> locally and uses that as identifier for all entities. Since the UUID is generated
32088without the need for database access, it copes better with very high concurrency use cases. Do note that performance may differ from the default id generator (both positive and negative) depending on the machine.</p> 32089</div> 32090<div class="paragraph"> 32091<p>The UUID generator can be configured in the activiti configuration as follows:</p> 32092</div> 32093<div class="listingblock"> 32094<div class="content"> 32095<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 320962 320973</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"idGenerator"</span><span class="tok-nt">></span> 32098 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.engine.impl.persistence.StrongUuidGenerator"</span> <span class="tok-nt">/></span> 32099<span class="tok-nt"></property></span> 32100</td></tr></table></code></pre> 32101</div> 32102</div> 32103<div class="paragraph"> 32104<p>The use of the UUID id generator depends on the following extra dependency:</p> 32105</div> 32106<div class="listingblock"> 32107<div class="content"> 32108<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 321092 321103 321114 321125</div></td><td class="code"><span></span> <span class="tok-nt"><dependency></span> 32113 <span class="tok-nt"><groupId></span>com.fasterxml.uuid<span class="tok-nt"></groupId></span> 32114 <span class="tok-nt"><artifactId></span>java-uuid-generator<span class="tok-nt"></artifactId></span> 32115 <span class="tok-nt"><version></span>3.1.3<span class="tok-nt"></version></span> 32116<span class="tok-nt"></dependency></span> 32117</td></tr></table></code></pre> 32118</div> 32119</div> 32120</div> 32121<div class="sect2"> 32122<h3 id="advanced.tenancy">16.4. Multitenancy</h3> 32123<div class="paragraph"> 32124<p>Multitenancy in general is a concept where the software is capable of serving multiple different organizations. Key is that the data is partitioned and no organization can see the data of other ones. In this context, such an organization (or a department, or a team or …​) is called a <em>tenant</em>.</p> 32125</div> 32126<div class="paragraph"> 32127<p>Note that this is fundamentally different from a multi-instance setup, where an Activiti Process Engine instance is running for each organization separately (and with a different database schema). Although Activiti is lightweight, and running a Process Engine instance doesn’t take much resources, it does add complexity and more maintenance. But, for some use cases it might be the right solution.</p> 32128</div> 32129<div class="paragraph"> 32130<p>Multitenancy in Activiti is mainly implemented around partitioning the data. It is important to note that <em>Activiti does not enforce multi tenancy rules</em>. This means it will not verify when querying and using data whether the user doing the operation is belonging to the correct tenant. This should be done in the layer calling the Activiti engine. Activiti does make sure that tenant information can be stored and used when retrieving process data.</p> 32131</div> 32132<div class="paragraph"> 32133<p>When deploying process definition to the Activiti Process Engine it is possible to pass a <em>tenant identifier</em>. This is a string (e.g. a UUID, department id, etc.), limited to 256 characters which is uniquely identifies the tenant:</p> 32134</div> 32135<div class="listingblock"> 32136<div class="content"> 32137<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 321382 321393 321404</div></td><td class="code"><span></span><span class="tok-n">repositoryService</span><span class="tok-o">.</span><span class="tok-na">createDeployment</span><span class="tok-o">()</span> 32141 <span class="tok-o">.</span><span class="tok-na">addClassPathResource</span><span class="tok-o">(...)</span> 32142 <span class="tok-o">.</span><span class="tok-na">tenantId</span><span class="tok-o">(</span><span class="tok-s">"myTenantId"</span><span class="tok-o">)</span>
32143 <span class="tok-o">.</span><span class="tok-na">deploy</span><span class="tok-o">();</span> 32144</td></tr></table></code></pre> 32145</div> 32146</div> 32147<div class="paragraph"> 32148<p>Passing a tenant id during a deployment has following implications:</p> 32149</div> 32150<div class="ulist"> 32151<ul> 32152<li> 32153<p>All the process definitions contained in the deployment inherit the tenant identifier from this deployment.</p> 32154</li> 32155<li> 32156<p>All process instances started from those process definitions inherit this tenant identifier from the process definition.</p> 32157</li> 32158<li> 32159<p>All tasks created at runtime when executing the process instance inherit this tenant identifier from the process instance. Standalone tasks can have a tenant identifier too.</p> 32160</li> 32161<li> 32162<p>All executions created during process instance execution inherit this tenant identifier from the process instance.</p> 32163</li> 32164<li> 32165<p>Firing a signal throw event (in the process itself or through the API) can be done whilst providing a tenant identifier. The signal will only be executed in the tenant context: i.e. if there are multiple signal catch events with the same name, only the one with the correct tenant identifier will actually be called.</p> 32166</li> 32167<li> 32168<p>All jobs (timers and async continuations) inherit the tenant identifier from either the process definition (e.g. timer start event) or the process instance (when a job is created at runtime, e.g. an async continuation). This could potentially be used for giving priority to some tenants in a custom job executor.</p> 32169</li> 32170<li> 32171<p>All the historic entities (historic process instance, task and activities) inherit the tenant identifier from their runtime counterparts.</p> 32172</li> 32173<li> 32174<p>As a side note, models can have a tenant identifier too (models are used e.g. by the Activiti Modeler to store BPMN 2.0 models).</p> 32175</li> 32176</ul> 32177</div> 32178<div class="paragraph"> 32179<p>To actually make use of the tenant identifier on the process data, all the query API’s have the capability to filter on tenant. For example (and can be replaced by the relevant query implementation of the other entities):</p> 32180</div> 32181<div class="listingblock"> 32182<div class="content"> 32183<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 321842 321853 321864 321875</div></td><td class="code"><span></span><span class="tok-n">runtimeService</span><span class="tok-o">.</span><span class="tok-na">createProcessInstanceQuery</span><span class="tok-o">()</span> 32188 <span class="tok-o">.</span><span class="tok-na">processInstanceTenantId</span><span class="tok-o">(</span><span class="tok-s">"myTenantId"</span><span class="tok-o">)</span> 32189 <span class="tok-o">.</span><span class="tok-na">processDefinitionKey</span><span class="tok-o">(</span><span class="tok-s">"myProcessDefinitionKey"</span><span class="tok-o">)</span> 32190 <span class="tok-o">.</span><span class="tok-na">variableValueEquals</span><span class="tok-o">(</span><span class="tok-s">"myVar"</span><span class="tok-o">,</span> <span class="tok-s">"someValue"</span><span class="tok-o">)</span> 32191 <span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">()</span> 32192</td></tr></table></code></pre> 32193</div> 32194</div> 32195<div class="paragraph"> 32196<p>The query API’s also allow to filter on the tenant identifier with <em>like</em> semantics and also to filter out entities without tenant id.</p> 32197</div> 32198<div class="paragraph"> 32199<p><strong>Important implementation detail:</strong> due to database quirks (more specifically: null handling in unique constraints) the <em>default</em> tenant identifier value indicating <em>no tenant</em> is the <strong>empty string</strong>. The combination of (process definition key, process definition version, tenant identifier) needs to be unique (and there is a database constraint checking this). Also note that the tenant identifier shouldn’t be set to null, as this will affect the queries since certain databases (Oracle) treat empty string as a null value (that’s why the query <em>.withoutTenantId</em> does a check against the empty string or null). This means that the same process definition (with same process definition key) can be deployed for multiple tenants, each with their own versioning. This does not affect the usage when tenancy is not used.<
32199/p> 32200</div> 32201<div class="paragraph"> 32202<p><strong>Do note that all of the above does not conflict with running multiple Activiti instances in a cluster.</strong></p> 32203</div> 32204<div class="paragraph"> 32205<p>[Experimental] It is possible to change the tenant identifier by calling the <em>changeDeploymentTenantId(String deploymentId, String newTenantId)</em> method on the <em>repositoryService</em>. This will change the tenant identifier everywhere it was inherited before. This can be useful when going from a non-multitenant setup to a multitenant configuration. See the Javadoc on the method for more detailed information.</p> 32206</div> 32207</div> 32208<div class="sect2"> 32209<h3 id="advanced.custom.sql.queries">16.5. Execute custom SQL</h3> 32210<div class="paragraph"> 32211<p>The Activiti API allows for interacting with the database using a high level API. For example, for retrieving data the Query API and the Native Query API are powerful in its usage. However, for some use cases they might not be flexible enough. The following section describes how a completely custom SQL statement (select, insert, update and delete are possible) can be executed against the Activiti data store, but completely within the configured Process Engine (and thus levering the transaction setup for example).</p> 32212</div> 32213<div class="paragraph"> 32214<p>To define custom SQL statements, the Activiti engine leverages the capabilities of its underlying framework, MyBatis. More info can be read <a href="http://mybatis.github.io/mybatis-3/java-api.html">in the MyBatis user guide</a>.</p> 32215</div> 32216<div class="sect3"> 32217<h4 id="_annotation_based_mapped_statements">16.5.1. Annotation based Mapped Statements</h4> 32218<div class="paragraph"> 32219<p>The first thing to do when using Annotation based Mapped Statements, is to create a MyBatis mapper class. For example, suppose that for some use case not the whole task data is needed, but only a small subset of it. A Mapper that could do this, looks as follows:</p> 32220</div> 32221<div class="listingblock"> 32222<div class="content"> 32223<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 322242 322253 322264 322275 322286</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">interface</span> <span class="tok-nc">MyTestMapper</span> <span class="tok-o">{</span> 32229 32230 <span class="tok-nd">@Select</span><span class="tok-o">(</span><span class="tok-s">"SELECT ID_ as id, NAME_ as name, CREATE_TIME_ as createTime FROM ACT_RU_TASK"</span><span class="tok-o">)</span> 32231 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>></span> <span class="tok-nf">selectTasks</span><span class="tok-o">();</span> 32232 32233<span class="tok-o">}</span> 32234</td></tr></table></code></pre> 32235</div> 32236</div> 32237<div class="paragraph"> 32238<p>This mapper must be provided to the Process Engine configuration as follows:</p> 32239</div> 32240<div class="listingblock"> 32241<div class="content"> 32242<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 322432 322443 322454 322465 322476 322487</div></td><td class="code"><span></span>... 32249<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"customMybatisMappers"</span><span class="tok-nt">></span> 32250 <span class="tok-nt"><set></span> 32251 <span class="tok-nt"><value></span>org.activiti.standalone.cfg.MyTestMapper<span class="tok-nt"></value></span> 32252 <span class="tok-nt"></set></span> 32253<span class="tok-nt"></property></span> 32254... 32255</td></tr></table></code></pre> 32256</div> 32257</div> 32258<div class="paragraph"> 32259<p>Notice that this is an interface. The underlying MyBatis framework will make an instance of it that can be used at runtime. Also notice that the return value of the method is not typed, but a list of maps (which corresponds to the list of rows with column values). Typing is possible with the MyBatis mappers if wanted.</p> 32260</div> 32261<div class="paragraph"> 32262<p>To execute the query above, the <em>managementService.executeCustomSql</em> method must be used. This method takes in a <em>CustomSqlExecution</em> instance. This is a wrapper that hides the internal bits of the engine otherwise needed to make it work.</p> 32263</div> 32264<div class="paragraph"> 32265<p>Unfortunately, Java generics make it a bit less readable than it could have been. The two generic types below are the mapper class and the return type class. However, the actual logic is simply to call the mapper method and return its results (if applicable).</p> 32266</div> 32267<div class="listingblock"> 32268<div class="content"> 32269<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32270 2 32271 3 32272 4 32273 5 32274 6 32275 7 32276 8 32277 9 3227810</div></td><td class="code"><span></span><span class="tok-n">CustomSqlExecution</span><span class="tok-o"><</span><span class="tok-n">MyTestMapper</span><span class="tok-o">,</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>>></span> <span class="tok-n">customSqlExecution</span> <span class="tok-o">=</span>
32279 <span class="tok-k">new</span> <span class="tok-n">AbstractCustomSqlExecution</span><span class="tok-o"><</span><span class="tok-n">MyTestMapper</span><span class="tok-o">,</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>>>(</span><span class="tok-n">MyTestMapper</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32280 32281 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>></span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">MyTestMapper</span> <span class="tok-n">customMapper</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32282 <span class="tok-k">return</span> <span class="tok-n">customMapper</span><span class="tok-o">.</span><span class="tok-na">selectTasks</span><span class="tok-o">();</span> 32283 <span class="tok-o">}</span> 32284 32285<span class="tok-o">};</span> 32286 32287<span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>></span> <span class="tok-n">results</span> <span class="tok-o">=</span> <span class="tok-n">managementService</span><span class="tok-o">.</span><span class="tok-na">executeCustomSql</span><span class="tok-o">(</span><span class="tok-n">customSqlExecution</span><span class="tok-o">);</span> 32288</td></tr></table></code></pre> 32289</div> 32290</div> 32291<div class="paragraph"> 32292<p>The Map entries in the list above will only contain <em>id, name and create time</em> in this case and not the full task object.</p> 32293</div> 32294<div class="paragraph"> 32295<p>Any SQL is possible when using the approach above. Another more complex example:</p> 32296</div> 32297<div class="listingblock"> 32298<div class="content"> 32299<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 323002 323013 323024 323035 323046</div></td><td class="code"><span></span> <span class="tok-nd">@Select</span><span class="tok-o">({</span> 32305 <span class="tok-s">"SELECT task.ID_ as taskId, variable.LONG_ as variableValue FROM ACT_RU_VARIABLE variable"</span><span class="tok-o">,</span> 32306 <span class="tok-s">"inner join ACT_RU_TASK task on variable.TASK_ID_ = task.ID_"</span><span class="tok-o">,</span> 32307 <span class="tok-s">"where variable.NAME_ = #{variableName}"</span> 32308 <span class="tok-o">})</span> 32309 <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Map</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">,</span> <span class="tok-n">Object</span><span class="tok-o">>></span> <span class="tok-nf">selectTaskWithSpecificVariable</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">variableName</span><span class="tok-o">);</span> 32310</td></tr></table></code></pre> 32311</div> 32312</div> 32313<div class="paragraph"> 32314<p>Using this method, the task table will be joined with the variables table. Only where the variable has a certain name is retained, and the task id and the corresponding numerical value is returned.</p> 32315</div> 32316<div class="paragraph"> 32317<p>For a working example on using Annotation based Mapped Statements check the unit test <em>org.activiti.standalone.cfg.CustomMybatisMapperTest</em> and other classes and resources in folders src/test/java/org/activiti/standalone/cfg/ and src/test/resources/org/activiti/standalone/cfg/</p> 32318</div> 32319</div> 32320<div class="sect3"> 32321<h4 id="_xml_based_mapped_statements">16.5.2. XML based Mapped Statements</h4> 32322<div class="paragraph"> 32323<p>When using XML based Mapped Statements, statements are defined in XML files. For the use case where not the whole task data is needed, but only a small subset of it. The XML file can look as follows:</p> 32324</div> 32325<div class="listingblock"> 32326<div class="content"> 32327<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32328 2 32329 3 32330 4 32331 5 32332 6 32333 7 32334 8 32335 9 3233610 3233711 3233812 3233913</div></td><td class="code"><span></span><span class="tok-nt"><mapper</span> <span class="tok-na">namespace=</span><span class="tok-s">"org.activiti.standalone.cfg.TaskMapper"</span><span class="tok-nt">></span> 32340 32341 <span class="tok-nt"><resultMap</span> <span class="tok-na">id=</span><span class="tok-s">"customTaskResultMap"</span> <span class="tok-na">type=</span><span class="tok-s">"org.activiti.standalone.cfg.CustomTask"</span><span class="tok-nt">></span> 32342 <span class="tok-nt"><id</span> <span class="tok-na">property=</span><span class="tok-s">"id"</span> <span class="tok-na">column=</span><span class="tok-s">"ID_"</span> <span class="tok-na">jdbcType=</span><span class="tok-s">"VARCHAR"</span><span class="tok-nt">/></span> 32343 <span class="tok-nt"><result</span> <span class="tok-na">property=</span><span class="tok-s">"name"</span> <span class="tok-na">column=</span><span class="tok-s">"NAME_"</span> <span class="tok-na">jdbcType=</span><span class="tok-s">"VARCHAR"</span><span class="tok-nt">/></span> 32344 <span class="tok-nt"><result</span> <span class="tok-na">property=</span><span class="tok-s">"createTime"</span> <span class="tok-na">column=</span><span class="tok-s">"CREATE_TIME_"</span> <span class="tok-na">jdbcType=</span><span class="tok-s">"TIMESTAMP"</span> <span class="tok-nt">/></span> 32345 <span class="tok-nt"></resultMap></span> 32346 32347 <span class="tok-nt"><select</span> <span class="tok-na">id=</span><span class="tok-s">"selectCustomTaskList"</span> <span class="tok-na">resultMap=</span><span class="tok-s">"customTaskResultMap"</span><span class="tok-nt">></span> 32348 select RES.ID_, RES.NAME_, RES.CREATE_TIME_ from ACT_RU_TASK RES 32349 <span class="tok-nt"></select></span> 32350 32351<span class="tok-nt"></mapper></span> 32352</td></tr></table></code></pre> 32353</div> 32354</div> 32355<div class="paragraph"> 32356<p>Results are mapped to instances of <em>org.activiti.standalone.cfg.CustomTask</em> class which can look as follows:</p> 32357</div> 32358<div class="listingblock"> 32359<div class="content"> 32360<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32361 2 32362 3 32363 4 32364 5 32365 6 32366 7 32367 8 32368 9 3236910 3237011 3237112 3237213 3237314 3237415 3237516</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">CustomTask</span> <span class="tok-o">{</span> 32376 32377 <span class="tok-kd">protected</span> <span class="tok-n">String</span> <span class="tok-n">id</span><span class="tok-o">;</span> 32378 <span class="tok-kd">protected</span> <span class="tok-n">String</span> <span class="tok-n">name</span><span class="tok-o">;</span> 32379 <span class="tok-kd">protected</span> <span class="tok-n">Date</span> <span class="tok-n">createTime</span><span class="tok-o">;</span> 32380 32381 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getId</span><span class="tok-o">()</span> <span class="tok-o">{</span> 32382 <span class="tok-k">return</span> <span class="tok-n">id</span><span class="tok-o">;</span> 32383 <span class="tok-o">}</span> 32384 <span class="tok-kd">public</span> <span class="tok-n">String</span> <span class="tok-nf">getName</span><span class="tok-o">()</span> <span class="tok-o">{</span> 32385 <span class="tok-k">return</span> <span class="tok-n">name</span><span class="tok-o">;</span> 32386 <span class="tok-o">}</span> 32387 <span class="tok-kd">public</span> <span class="tok-n">Date</span> <span class="tok-nf">getCreateTime</span><span class="tok-o">()</span> <span class="tok-o">{</span> 32388 <span class="tok-k">return</span> <span class="tok-n">createTime</span><span class="tok-o">;</span> 32389 <span class="tok-o">}</span> 32390<span class="tok-o">}</span> 32391</td></tr></table></code></pre> 32392</div> 32393</div> 32394<div class="paragraph"> 32395<p>Mapper XML files must be provided to the Process Engine configuration as follows:</p> 32396</div> 32397<div class="listingblock"> 32398<div class="content"> 32399<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 324002 324013 324024 324035 324046 324057</div></td><td class="code"><span></span>... 32406<span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"customMybatisXMLMappers"</span><span class="tok-nt">></span> 32407 <span class="tok-nt"><set></span> 32408 <span class="tok-nt"><value></span>org/activiti/standalone/cfg/custom-mappers/CustomTaskMapper.xml<span class="tok-nt"></value></span> 32409 <span class="tok-nt"></set></span> 32410<span class="tok-nt"></property></span> 32411... 32412</td></tr></table></code></pre> 32413</div> 32414</div> 32415<div class="paragraph"> 32416<p>The statement can be executed as follows:</p> 32417</div> 32418<div class="listingblock"> 32419<div class="content"> 32420<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 324212 324223 324234 324245 324256 324267 324278</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">CustomTask</span><span class="tok-o">></span> <span class="tok-n">tasks</span> <span class="tok-o">=</span> <span class="tok-n">managementService</span><span class="tok-o">.</span><span class="tok-na">executeCommand</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">Command</span><span class="tok-o"><</span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">CustomTask</span><span class="tok-o">>>()</span> <span class="tok-o">{</span> 32428
32429 <span class="tok-nd">@SuppressWarnings</span><span class="tok-o">(</span><span class="tok-s">"unchecked"</span><span class="tok-o">)</span> 32430 <span class="tok-nd">@Override</span> 32431 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">CustomTask</span><span class="tok-o">></span> <span class="tok-nf">execute</span><span class="tok-o">(</span><span class="tok-n">CommandContext</span> <span class="tok-n">commandContext</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32432 <span class="tok-k">return</span> <span class="tok-o">(</span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">CustomTask</span><span class="tok-o">>)</span> <span class="tok-n">commandContext</span><span class="tok-o">.</span><span class="tok-na">getDbSqlSession</span><span class="tok-o">().</span><span class="tok-na">selectList</span><span class="tok-o">(</span><span class="tok-s">"selectCustomTaskList"</span><span class="tok-o">);</span> 32433 <span class="tok-o">}</span> 32434 <span class="tok-o">});</span> 32435</td></tr></table></code></pre> 32436</div> 32437</div> 32438<div class="paragraph"> 32439<p>For uses cases that require more complicated statements, XML Mapped Statements can be helpful. Since Activiti uses XML Mapped Statements internally, it’s possible to make use of the underlying capabilities.</p> 32440</div> 32441<div class="paragraph"> 32442<p>Suppose that for some use case the ability to query attachments data is required based on id, name, type, userId, etc! To fulfill the use case a query class <em>AttachmentQuery</em> that extends <em>org.activiti.engine.impl.AbstractQuery</em> can be created as follows:</p> 32443</div> 32444<div class="listingblock"> 32445<div class="content"> 32446<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32447 2 32448 3 32449 4 32450 5 32451 6 32452 7 32453 8 32454 9 3245510 3245611 3245712 3245813 3245914 3246015 3246116 3246217 3246318 3246419 3246520 3246621 3246722 3246823 3246924 3247025 3247126 3247227 3247328 3247429 3247530 3247631 3247732 3247833 3247934 3248035 3248136 3248237 3248338 3248439 3248540 3248641 3248742</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">AttachmentQuery</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractQuery</span><span class="tok-o"><</span><span class="tok-n">AttachmentQuery</span><span class="tok-o">,</span> <span class="tok-n">Attachment</span><span class="tok-o">></span> <span class="tok-o">{</span> 32488 32489 <span class="tok-kd">protected</span> <span class="tok-n">String</span> <span class="tok-n">attachmentId</span><span class="tok-o">;</span> 32490 <span class="tok-kd">protected</span> <span class="tok-n">String</span> <span class="tok-n">attachmentName</span><span class="tok-o">;</span> 32491 <span class="tok-kd">protected</span> <span class="tok-n">String</span> <span class="tok-n">attachmentType</span><span class="tok-o">;</span> 32492 <span class="tok-kd">protected</span> <span class="tok-n">String</span> <span class="tok-n">userId</span><span class="tok-o">;</span> 32493 32494 <span class="tok-kd">public</span> <span class="tok-nf">AttachmentQuery</span><span class="tok-o">(</span><span class="tok-n">ManagementService</span> <span class="tok-n">managementService</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32495 <span class="tok-kd">super</span><span class="tok-o">(</span><span class="tok-n">managementService</span><span class="tok-o">);</span> 32496 <span class="tok-o">}</span> 32497 32498 <span class="tok-kd">public</span> <span class="tok-n">AttachmentQuery</span> <span class="tok-nf">attachmentId</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">attachmentId</span><span class="tok-o">){</span> 32499 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">attachmentId</span> <span class="tok-o">=</span> <span class="tok-n">attachmentId</span><span class="tok-o">;</span> 32500 <span class="tok-k">return</span> <span class="tok-k">this</span><span class="tok-o">;</span> 32501 <span class="tok-o">}</span> 32502 32503 <span class="tok-kd">public</span> <span class="tok-n">AttachmentQuery</span> <span class="tok-nf">attachmentName</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">attachmentName</span><span class="tok-o">){</span> 32504 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">attachmentName</span> <span class="tok-o">=</span> <span class="tok-n">attachmentName</span><span class="tok-o">;</span> 32505 <span class="tok-k">return</span> <span class="tok-k">this</span><span class="tok-o">;</span> 32506 <span class="tok-o">}</span> 32507 32508 <span class="tok-kd">public</span> <span class="tok-n">AttachmentQuery</span> <span class="tok-nf">attachmentType</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">attachmentType</span><span class="tok-o">){</span> 32509 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">attachmentType</span> <span class="tok-o">=</span> <span class="tok-n">attachmentType</span><span class="tok-o">;</span> 32510 <span class="tok-k">return</span> <span class="tok-k">this</span><span class="tok-o">;</span> 32511 <span class="tok-o">}</span> 32512 32513 <span class="tok-kd">public</span> <span class="tok-n">AttachmentQuery</span> <span class="tok-nf">userId</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">userId</span><span class="tok-o">){</span> 32514 <span class="tok-k">this</span><span class="tok-o">.</span><span class="tok-na">userId</span> <span class="tok-o">=</span> <span class="tok-n">userId</span><span class="tok-o">;</span> 32515 <span class="tok-k">return</span> <span class="tok-k">this</span><span class="tok-o">;</span> 32516 <span class="tok-o">}</span> 32517 32518 <span class="tok-nd">
32518@Override</span> 32519 <span class="tok-kd">public</span> <span class="tok-kt">long</span> <span class="tok-nf">executeCount</span><span class="tok-o">(</span><span class="tok-n">CommandContext</span> <span class="tok-n">commandContext</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32520 <span class="tok-k">return</span> <span class="tok-o">(</span><span class="tok-n">Long</span><span class="tok-o">)</span> <span class="tok-n">commandContext</span><span class="tok-o">.</span><span class="tok-na">getDbSqlSession</span><span class="tok-o">()</span> 32521 <span class="tok-o">.</span><span class="tok-na">selectOne</span><span class="tok-o">(</span><span class="tok-s">"selectAttachmentCountByQueryCriteria"</span><span class="tok-o">,</span> <span class="tok-k">this</span><span class="tok-o">);</span> 32522 <span class="tok-o">}</span> 32523 32524 <span class="tok-nd">@Override</span> 32525 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Attachment</span><span class="tok-o">></span> <span class="tok-nf">executeList</span><span class="tok-o">(</span><span class="tok-n">CommandContext</span> <span class="tok-n">commandContext</span><span class="tok-o">,</span> <span class="tok-n">Page</span> <span class="tok-n">page</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32526 <span class="tok-k">return</span> <span class="tok-n">commandContext</span><span class="tok-o">.</span><span class="tok-na">getDbSqlSession</span><span class="tok-o">()</span> 32527 <span class="tok-o">.</span><span class="tok-na">selectList</span><span class="tok-o">(</span><span class="tok-s">"selectAttachmentByQueryCriteria"</span><span class="tok-o">,</span> <span class="tok-k">this</span><span class="tok-o">);</span> 32528 <span class="tok-o">}</span> 32529</td></tr></table></code></pre> 32530</div> 32531</div> 32532<div class="paragraph"> 32533<p>Note that when extending <em>AbstractQuery</em> extended classes should pass an instance of <em>ManagementService</em> to super constructor and methods <em>executeCount</em> and <em>executeList</em> need to be implemented to call the mapped statements.</p> 32534</div> 32535<div class="paragraph"> 32536<p>The XML file containing the mapped statements can look as follows:</p> 32537</div> 32538<div class="listingblock"> 32539<div class="content"> 32540<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32541 2 32542 3 32543 4 32544 5 32545 6 32546 7 32547 8 32548 9 3254910 3255011 3255112 3255213 3255314 3255415 3255516 3255617 3255718 3255819 3255920 3256021 3256122 3256223 3256324 3256425 3256526 3256627 3256728 3256829 3256930 3257031 3257132 3257233</div></td><td class="code"><span></span><span class="tok-nt"><mapper</span> <span class="tok-na">namespace=</span><span class="tok-s">"org.activiti.standalone.cfg.AttachmentMapper"</span><span class="tok-nt">></span> 32573 32574 <span class="tok-nt"><select</span> <span class="tok-na">id=</span><span class="tok-s">"selectAttachmentCountByQueryCriteria"</span> <span class="tok-na">parameterType=</span><span class="tok-s">"org.activiti.standalone.cfg.AttachmentQuery"</span> <span class="tok-na">resultType=</span><span class="tok-s">"long"</span><span class="tok-nt">></span> 32575 select count(distinct RES.ID_) 32576 <span class="tok-nt"><include</span> <span class="tok-na">refid=</span><span class="tok-s">"selectAttachmentByQueryCriteriaSql"</span><span class="tok-nt">/></span> 32577 <span class="tok-nt"></select></span> 32578 32579 <span class="tok-nt"><select</span> <span class="tok-na">id=</span><span class="tok-s">"selectAttachmentByQueryCriteria"</span> <span class="tok-na">parameterType=</span><span class="tok-s">"org.activiti.standalone.cfg.AttachmentQuery"</span> <span class="tok-na">resultMap=</span><span class="tok-s">"org.activiti.engine.impl.persistence.entity.AttachmentEntity.attachmentResultMap"</span><span class="tok-nt">></span> 32580 ${limitBefore} 32581 select distinct RES.* ${limitBetween} 32582 <span class="tok-nt"><include</span> <span class="tok-na">refid=</span><span class="tok-s">"selectAttachmentByQueryCriteriaSql"</span><span class="tok-nt">/></span> 32583 ${orderBy} 32584 ${limitAfter} 32585 <span class="tok-nt"></select></span> 32586 32587 <span class="tok-nt"><sql</span> <span class="tok-na">id=</span><span class="tok-s">"selectAttachmentByQueryCriteriaSql"</span><span class="tok-nt">></span> 32588 from ${prefix}ACT_HI_ATTACHMENT RES 32589 <span class="tok-nt"><where></span> 32590 <span class="tok-nt"><if</span> <span class="tok-na">test=</span><span class="tok-s">"attachmentId != null"</span><span class="tok-nt">></span> 32591 RES.ID_ = #{attachmentId} 32592 <span class="tok-nt"></if></span> 32593 <span class="tok-nt"><if</span> <span class="tok-na">test=</span><span class="tok-s">"attachmentName != null"</span><span class="tok-nt">></span> 32594 and RES.NAME_ = #{attachmentName} 32595 <span class="tok-nt"></if></span> 32596 <span class="tok-nt"><if</span> <span class="tok-na">test=</span><span class="tok-s">"attachmentType != null"</span><span class="tok-nt">></span> 32597 and RES.TYPE_ = #{attachmentType} 32598 <span class="tok-nt"></if></span> 32599 <span class="tok-nt"><if</span> <span class="tok-na">test=</span><span class="tok-s">"userId != null"</span><span class="tok-nt">></span> 32600 and RES.USER_ID_ = #{userId} 32601 <span class="tok-nt"></if></span> 32602 <span class="tok-nt"></where></span> 32603 <span class="tok-nt"></sql></span> 32604<span class="tok-nt"></mapper></span> 32605</td></tr></table></code></pre> 32606</div> 32607</div> 32608<div class="paragraph"> 32609<p>Capabilities such as pagination, ordering, table name prefixing are available and can be used in the statements (since the parameterType is a subclass of <em>AbstractQuery</em>). Note that to map results the predefined <em>org.activiti.engine.impl.persistence.entity.AttachmentEntity.attachmentResultMap</em>
32609 resultMap can be used.</p> 32610</div> 32611<div class="paragraph"> 32612<p>Finally, the <em>AttachmentQuery</em> can be used as follows:</p> 32613</div> 32614<div class="listingblock"> 32615<div class="content"> 32616<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32617 2 32618 3 32619 4 32620 5 32621 6 32622 7 32623 8 32624 9 3262510 3262611 3262712 3262813</div></td><td class="code"><span></span><span class="tok-o">....</span> 32629<span class="tok-c1">// Get the total number of attachments</span> 32630<span class="tok-kt">long</span> <span class="tok-n">count</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">AttachmentQuery</span><span class="tok-o">(</span><span class="tok-n">managementService</span><span class="tok-o">).</span><span class="tok-na">count</span><span class="tok-o">();</span> 32631 32632<span class="tok-c1">// Get attachment with id 10025</span> 32633<span class="tok-n">Attachment</span> <span class="tok-n">attachment</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">AttachmentQuery</span><span class="tok-o">(</span><span class="tok-n">managementService</span><span class="tok-o">).</span><span class="tok-na">attachmentId</span><span class="tok-o">(</span><span class="tok-s">"10025"</span><span class="tok-o">).</span><span class="tok-na">singleResult</span><span class="tok-o">();</span> 32634 32635<span class="tok-c1">// Get first 10 attachments</span> 32636<span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Attachment</span><span class="tok-o">></span> <span class="tok-n">attachments</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">AttachmentQuery</span><span class="tok-o">(</span><span class="tok-n">managementService</span><span class="tok-o">).</span><span class="tok-na">listPage</span><span class="tok-o">(</span><span class="tok-mi">0</span><span class="tok-o">,</span> <span class="tok-mi">10</span><span class="tok-o">);</span> 32637 32638<span class="tok-c1">// Get all attachments uploaded by user kermit</span> 32639<span class="tok-n">attachments</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">AttachmentQuery</span><span class="tok-o">(</span><span class="tok-n">managementService</span><span class="tok-o">).</span><span class="tok-na">userId</span><span class="tok-o">(</span><span class="tok-s">"kermit"</span><span class="tok-o">).</span><span class="tok-na">list</span><span class="tok-o">();</span> 32640<span class="tok-o">....</span> 32641</td></tr></table></code></pre> 32642</div> 32643</div> 32644<div class="paragraph"> 32645<p>For working examples on using XML Mapped Statements check the unit test <em>org.activiti.standalone.cfg.CustomMybatisXMLMapperTest</em> and other classes and resources in folders src/test/java/org/activiti/standalone/cfg/ and src/test/resources/org/activiti/standalone/cfg/</p> 32646</div> 32647</div> 32648</div> 32649<div class="sect2"> 32650<h3 id="advanced.process.engine.configurators">16.6. Advanced Process Engine configuration with a ProcessEngineConfigurator</h3> 32651<div class="paragraph"> 32652<p>An advanced way of hooking into the process engine configuration is through the use of a <em>ProcessEngineConfigurator</em>. The idea is that an implementation of the <em>org.activiti.engine.cfg.ProcessEngineConfigurator</em> interface is created and injected into the process engine configuration:</p> 32653</div> 32654<div class="listingblock"> 32655<div class="content"> 32656<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32657 2 32658 3 32659 4 32660 5 32661 6 32662 7 32663 8 32664 9 3266510 3266611 3266712 3266813 3266914 3267015</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"...SomeProcessEngineConfigurationClass"</span><span class="tok-nt">></span> 32671 32672 ... 32673 32674 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"configurators"</span><span class="tok-nt">></span>
32675 <span class="tok-nt"><list></span> 32676 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"com.mycompany.MyConfigurator"</span><span class="tok-nt">></span> 32677 ... 32678 <span class="tok-nt"></bean></span> 32679 <span class="tok-nt"></list></span> 32680 <span class="tok-nt"></property></span> 32681 32682 ... 32683 32684<span class="tok-nt"></bean></span> 32685</td></tr></table></code></pre> 32686</div> 32687</div> 32688<div class="paragraph"> 32689<p>There are two methods required to implement this interface. The <em>configure</em> method, which gets a <em>ProcessEngineConfiguration</em> instance as parameter. The custom configuration can be added this way, and this method will guaranteed be called <strong>before the process engine is created, but after all default configuration has been done</strong>. The other method is the <em>getPriority</em> method, which allows for ordering the configurators in the case where some configurators are dependent on each other.</p> 32690</div> 32691<div class="paragraph"> 32692<p>An example of such a configurator is the <a href="#chapter_ldap">LDAP integration</a>, where the configurator is used to replace the default user and group manager classes with one that is capable of handling an LDAP user store. So basically a configurator allows to change or tweak the process engine quite heavily and is meant for very advanced use cases. Another example is to swap the process definition cache with a customized version:</p> 32693</div> 32694<div class="listingblock"> 32695<div class="content"> 32696<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 326972 326983 326994 327005 327016 327027 327038</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">ProcessDefinitionCacheConfigurator</span> <span class="tok-kd">extends</span> <span class="tok-n">AbstractProcessEngineConfigurator</span> <span class="tok-o">{</span> 32704 32705 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">configure</span><span class="tok-o">(</span><span class="tok-n">ProcessEngineConfigurationImpl</span> <span class="tok-n">processEngineConfiguration</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32706 <span class="tok-n">MyCache</span> <span class="tok-n">myCache</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">MyCache</span><span class="tok-o">();</span> 32707 <span class="tok-n">processEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">setProcessDefinitionCache</span><span class="tok-o">(</span><span class="tok-n">enterpriseProcessDefinitionCache</span><span class="tok-o">);</span> 32708 <span class="tok-o">}</span> 32709 32710<span class="tok-o">}</span> 32711</td></tr></table></code></pre> 32712</div> 32713</div> 32714<div class="paragraph"> 32715<p>Process Engine configurators can also be auto discovered from the classpath using the <a href="http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html">ServiceLoader</a> approach. This means that a jar with the configurator implementation must be put on the classpath, containing a file in the <em>META-INF/services</em> folder in the jar called <strong>org.activiti.engine.cfg.ProcessEngineConfigurator</strong>. The content of the file needs to be the fully qualified classname of the custom implementation. When the process engine is booted, the logging will show that these configurators are found:</p> 32716</div> 32717<div class="listingblock"> 32718<div class="content"> 32719<pre>INFO org.activiti.engine.impl.cfg.ProcessEngineConfigurationImpl - Found 1 auto-discoverable Process Engine Configurators 32720INFO org.activiti.engine.impl.cfg.ProcessEngineConfigurationImpl - Found 1 Process Engine Configurators in total: 32721INFO org.activiti.engine.impl.cfg.ProcessEngineConfigurationImpl - class org.activiti.MyCustomConfigurator</pre> 32722</div> 32723</div> 32724<div class="paragraph"> 32725<p>Note that this ServiceLoader approach might not work in certain environments. It c
32725an be explicitly disabled using the <em>enableConfiguratorServiceLoader</em> property of the ProcessEngineConfiguration (true by default).</p> 32726</div> 32727</div> 32728<div class="sect2"> 32729<h3 id="advanced.task.query.switching">16.7. Advanced query API: seamless switching between runtime and historic task querying</h3> 32730<div class="paragraph"> 32731<p>One core component of any BPM user interface is the task list. Typically, end users work on open, runtime tasks, filtering their inbox with various setting. Often also the historic tasks need to be displayed in those lists, with similar filtering. To make that code-wise easier, the <em>TaskQuery</em> and <em>HistoricTaskInstanceQuery</em> both have a shared parent interface, which contains all common operations (and most of the operations are common).</p> 32732</div> 32733<div class="paragraph"> 32734<p>This common interface is the <em>org.activiti.engine.task.TaskInfoQuery</em> class. Both <em>org.activiti.engine.task.Task</em> and <em>org.activiti.engine.task.HistoricTaskInstance</em> have a common superclass <em>org.activiti.engine.task.TaskInfo</em> (with common properties) which is returned from e.g. the <em>list()</em> method. However, Java generics are sometimes more harming than helping: if you want to use the <em>TaskInfoQuery</em> type directly, it would look like this:</p> 32735</div> 32736<div class="listingblock"> 32737<div class="content"> 32738<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">TaskInfoQuery</span><span class="tok-o"><?</span> <span class="tok-kd">extends</span> <span class="tok-n">TaskInfoQuery</span><span class="tok-o"><?,?>,</span> <span class="tok-o">?</span> <span class="tok-kd">extends</span> <span class="tok-n">TaskInfo</span><span class="tok-o">></span> <span class="tok-n">taskInfoQuery</span> 32739</td></tr></table></code></pre> 32740</div> 32741</div> 32742<div class="paragraph"> 32743<p>Ugh, Right. To <em>solve</em> this, a <em>org.activiti.engine.task.TaskInfoQueryWrapper</em> class that can be used to avoid the generics (the following code could come from REST code that returns a task list where the user can switch between open and completed tasks):</p> 32744</div> 32745<div class="listingblock"> 32746<div class="content"> 32747<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32748 2 32749 3 32750 4 32751 5 32752 6 32753 7 32754 8 32755 9 3275610 3275711 3275812</div></td><td class="code"><span></span><span class="tok-n">TaskInfoQueryWrapper</span> <span class="tok-n">taskInfoQueryWrapper</span> <span class="tok-o">=</span> <span class="tok-kc">null</span><span class="tok-o">;</span> 32759<span class="tok-k">if</span> <span class="tok-o">(</span><span class="tok-n">runtimeQuery</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32760 <span class="tok-n">taskInfoQueryWrapper</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">TaskInfoQueryWrapper</span><span class="tok-o">(</span><span class="tok-n">taskService</span><span class="tok-o">.</span><span class="tok-na">createTaskQuery</span><span class="tok-o">());</span> 32761<span class="tok-o">}</span> <span class="tok-k">else</span> <span class="tok-o">{</span> 32762 <span class="tok-n">taskInfoQueryWrapper</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">TaskInfoQueryWrapper</span><span class="tok-o">(</span><span class="tok-n">historyService</span><span class="tok-o">.</span><span class="tok-na">createHistoricTaskInstanceQuery</span><span class="tok-o">());</span> 32763<span class="tok-o">}</span> 32764 32765<span class="tok-n">List</span><span class="tok-o"><?</span> <span class="tok-kd">extends</span> <span class="tok-n">TaskInfo</span><span class="tok-o">></span> <span class="tok-n">taskInfos</span> <span class="tok-o">=</span> <span class="tok-n">taskInfoQueryWrapper</span><span class="tok-o">.</span><span class="tok-na">getTaskInfoQuery</span><span class="tok-o">().</span><span class="tok-na">or</span><span class="tok-o">()</span> 32766 <span class="tok-o">.</span><span class="tok-na">taskNameLike</span><span class="tok-o">(</span><span class="tok-s">"%k1%"</span><span class="tok-o">)</span> 32767 <span class="tok-o">.</span><span class="tok-na">taskDueAfter</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">Date</span><span class="tok-o">(</span><span class="tok-n">now</span><span class="tok-o">.</span><span class="tok-na">getTime</span><span class="tok-o">()</span> <span class="tok-o">+</span> <span class="tok-o">(</span><span class="tok-mi">3</span> <span class="tok-o">*</span> <span class="tok-mi">24L</span> <span class="tok-o">*</span> <span class="tok-mi">60L</span> <span class="tok-o">*</span> <span class="tok-mi">60L</span> <span class="tok-o">*</span> <span class="tok-mi">1000L</span><span class="tok-o">)))</span> 32768<span class="tok-o">.</span><span class="tok-na">endOr</span><span class="tok-o">()</span> 32769<span class="tok-o">.</span><span class="tok-na">list</span><span class="tok-o">();</span> 32770</td></tr></table></code></pre> 32771</div> 32772</div> 32773</div> 32774<div class="sect2"> 32775<h3 id="advanced.custom.session.manager">16.8. Custom identity management by overriding standard SessionFactory</h3> 32776<div class="paragraph"> 32777<p>If you do not want to use a full <em>
32777ProcessEngineConfigurator</em> implementation like in the <a href="#chapter_ldap">LDAP integration</a>, but still want to plug in your custom identity management framework, then you can also override the <em>SessionFactory</em> classes directly in the <em>ProcessEngineConfiguration</em>. In Spring this can be easily done by adding the following to the <em>ProcessEngineConfiguration</em> bean definition:</p> 32778</div> 32779<div class="listingblock"> 32780<div class="content"> 32781<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32782 2 32783 3 32784 4 32785 5 32786 6 32787 7 32788 8 32789 9 3279010 3279111 3279212 3279313 3279414</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"...SomeProcessEngineConfigurationClass"</span><span class="tok-nt">></span> 32795 32796 ... 32797 32798 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"customSessionFactories"</span><span class="tok-nt">></span> 32799 <span class="tok-nt"><list></span> 32800 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"com.mycompany.MyGroupManagerFactory"</span><span class="tok-nt">/></span> 32801 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"com.mycompany.MyUserManagerFactory"</span><span class="tok-nt">/></span> 32802 <span class="tok-nt"></list></span> 32803 <span class="tok-nt"></property></span> 32804 32805 ... 32806 32807<span class="tok-nt"></bean></span> 32808</td></tr></table></code></pre> 32809</div> 32810</div> 32811<div class="paragraph"> 32812<p>The <em>MyGroupManagerFactory</em> and <em>MyUserManagerFactory</em> need to implement the <em>org.activiti.engine.impl.interceptor.SessionFactory</em> interface. The call to <em>openSession()</em> returns the custom class implementation that does the actual identity management. For groups this is a class that inherits from <em>org.activiti.engine.impl.persistence.entity.GroupEntityManager</em> and for managing users it must inherit from <em>org.activiti.engine.impl.persistence.entity.UserEntityManager</em>. The following code sample contains a custom manager factory for groups:</p> 32813</div> 32814<div class="listingblock"> 32815<div class="content"> 32816<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32817 2 32818 3 32819 4 32820 5 32821 6 32822 7 32823 8 32824 9 3282510 3282611 3282712 3282813 3282914 3283015 3283116 3283217 3283318 3283419</div></td><td class="code"><span></span><span class="tok-kn">package</span> <span class="tok-nn">com.mycompany</span><span class="tok-o">;</span> 32835 32836<span class="tok-kn">import</span> <span class="tok-nn">org.activiti.engine.impl.interceptor.Session</span><span class="tok-o">;</span> 32837<span class="tok-kn">import</span> <span class="tok-nn">org.activiti.engine.impl.interceptor.SessionFactory</span><span class="tok-o">;</span> 32838<span class="tok-kn">import</span> <span class="tok-nn">org.activiti.engine.impl.persistence.entity.GroupIdentityManager</span><span class="tok-o">;</span> 32839 32840<span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyGroupManagerFactory</span> <span class="tok-kd">implements</span> <span class="tok-n">SessionFactory</span> <span class="tok-o">{</span> 32841 32842 <span class="tok-nd">@Override</span> 32843 <span class="tok-kd">public</span> <span class="tok-n">Class</span><span class="tok-o"><?></span> <span class="tok-n">getSessionType</span><span class="tok-o">()</span> <span class="tok-o">{</span> 32844 <span class="tok-k">return</span> <span class="tok-n">GroupIdentityManager</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">;</span> 32845 <span class="tok-o">}</span> 32846 32847 <span class="tok-nd">@Override</span> 32848 <span class="tok-kd">public</span> <span class="tok-n">Session</span> <span class="tok-nf">openSession</span><span class="tok-o">()</span> <span class="tok-o">{</span> 32849 <span class="tok-k">return</span> <span class="tok-k">new</span> <span class="tok-n">MyCompanyGroupManager</span><span class="tok-o">();</span> 32850 <span class="tok-o">}</span> 32851 32852<span class="tok-o">}</span> 32853</td></tr></table></code></pre> 32854</div> 32855</div> 32856<div class="paragraph"> 32857<p>The <em>MyCompanyGroupManager</em> created by the factory is doing the actual work. You do not need to override all members of <em>GroupEntityManager</em> though, just the ones required for your use case. The following sample provides an indication of how this may look like (only a selection of members are shown):</p> 32858</div> 32859<div class="listingblock"> 32860<div class="content"> 32861<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 32862 2 32863 3 32864 4 32865 5 32866 6 32867 7 32868 8 32869 9 3287010 3287111 3287212 3287313 3287414 3287515 3287616 3287717 3287818 3287919 3288020 3288121 3288222 3288323 3288424 3288525 3288626 3288727 3288828 3288929 3289030 3289131 3289232</div></td><td class="code"><span></span><span class="tok-kd">public</span> <span class="tok-kd">class</span> <span class="tok-nc">MyCompanyGroupManager</span> <span class="tok-kd">extends</span> <span class="tok-n">GroupEntityManager</span> <span class="tok-o">{</span> 32893 32894 <span class="tok-kd">private</span> <span class="tok-kd">static</span> <span class="tok-n">Logger</span> <span class="tok-n">log</span> <span class="tok-o">=</span> <span class="tok-n">LoggerFactory</span><span class="tok-o">.</span><span class="tok-na">getLogger</span><span class="tok-o">(</span><span class="tok-n">MyCompanyGroupManager</span><span class="tok-o">.</span><span class="tok-na">class</span><span class="tok-o">);</span> 32895 32896 <span class="tok-nd">
32896@Override</span> 32897 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Group</span><span class="tok-o">></span> <span class="tok-nf">findGroupsByUser</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">userId</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32898 <span class="tok-n">log</span><span class="tok-o">.</span><span class="tok-na">debug</span><span class="tok-o">(</span><span class="tok-s">"findGroupByUser called with userId: "</span> <span class="tok-o">+</span> <span class="tok-n">userId</span><span class="tok-o">);</span> 32899 <span class="tok-k">return</span> <span class="tok-kd">super</span><span class="tok-o">.</span><span class="tok-na">findGroupsByUser</span><span class="tok-o">(</span><span class="tok-n">userId</span><span class="tok-o">);</span> 32900 <span class="tok-o">}</span> 32901 32902 <span class="tok-nd">@Override</span> 32903 <span class="tok-kd">public</span> <span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">Group</span><span class="tok-o">></span> <span class="tok-nf">findGroupByQueryCriteria</span><span class="tok-o">(</span><span class="tok-n">GroupQueryImpl</span> <span class="tok-n">query</span><span class="tok-o">,</span> <span class="tok-n">Page</span> <span class="tok-n">page</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32904 <span class="tok-n">log</span><span class="tok-o">.</span><span class="tok-na">debug</span><span class="tok-o">(</span><span class="tok-s">"findGroupByQueryCriteria called, query: "</span> <span class="tok-o">+</span> <span class="tok-n">query</span> <span class="tok-o">+</span> <span class="tok-s">" page: "</span> <span class="tok-o">+</span> <span class="tok-n">page</span><span class="tok-o">);</span> 32905 <span class="tok-k">return</span> <span class="tok-kd">super</span><span class="tok-o">.</span><span class="tok-na">findGroupByQueryCriteria</span><span class="tok-o">(</span><span class="tok-n">query</span><span class="tok-o">,</span> <span class="tok-n">page</span><span class="tok-o">);</span> 32906 <span class="tok-o">}</span> 32907 32908 <span class="tok-nd">@Override</span> 32909 <span class="tok-kd">public</span> <span class="tok-kt">long</span> <span class="tok-nf">findGroupCountByQueryCriteria</span><span class="tok-o">(</span><span class="tok-n">GroupQueryImpl</span> <span class="tok-n">query</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32910 <span class="tok-n">log</span><span class="tok-o">.</span><span class="tok-na">debug</span><span class="tok-o">(</span><span class="tok-s">"findGroupCountByQueryCriteria called, query: "</span> <span class="tok-o">+</span> <span class="tok-n">query</span><span class="tok-o">);</span> 32911 <span class="tok-k">return</span> <span class="tok-kd">super</span><span class="tok-o">.</span><span class="tok-na">findGroupCountByQueryCriteria</span><span class="tok-o">(</span><span class="tok-n">query</span><span class="tok-o">);</span> 32912 <span class="tok-o">}</span> 32913 32914 <span class="tok-nd">@Override</span> 32915 <span class="tok-kd">public</span> <span class="tok-n">Group</span> <span class="tok-nf">createNewGroup</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">groupId</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32916 <span class="tok-k">throw</span> <span class="tok-k">new</span> <span class="tok-n">UnsupportedOperationException</span><span class="tok-o">();</span> 32917 <span class="tok-o">}</span> 32918 32919 <span class="tok-nd">@Override</span> 32920 <span class="tok-kd">public</span> <span class="tok-kt">void</span> <span class="tok-nf">deleteGroup</span><span class="tok-o">(</span><span class="tok-n">String</span> <span class="tok-n">groupId</span><span class="tok-o">)</span> <span class="tok-o">{</span> 32921 <span class="tok-k">throw</span> <span class="tok-k">new</span> <span class="tok-n">UnsupportedOperationException</span><span class="tok-o">();</span> 32922 <span class="tok-o">}</span> 32923<span class="tok-o">}</span> 32924</td></tr></table></code></pre> 32925</div> 32926</div> 32927<div class="paragraph"> 32928<p>Add your own implementation in the appropriate methods to plugin your own identity management solution. 32929You have to figure out which member of the base class must be overridden. For example the following call:</p> 32930</div> 32931<div class="listingblock"> 32932<div class="content"> 32933<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-kt">long</span> <span class="tok-n">
32933potentialOwners</span> <span class="tok-o">=</span> <span class="tok-n">identityService</span><span class="tok-o">.</span><span class="tok-na">createUserQuery</span><span class="tok-o">().</span><span class="tok-na">memberOfGroup</span><span class="tok-o">(</span><span class="tok-s">"management"</span><span class="tok-o">).</span><span class="tok-na">count</span><span class="tok-o">();</span> 32934</td></tr></table></code></pre> 32935</div> 32936</div> 32937<div class="paragraph"> 32938<p>leads to a call on the following member of the <em>UserIdentityManager</em> interface:</p> 32939</div> 32940<div class="listingblock"> 32941<div class="content"> 32942<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">List</span><span class="tok-o"><</span><span class="tok-n">User</span><span class="tok-o">></span> <span class="tok-nf">findUserByQueryCriteria</span><span class="tok-o">(</span><span class="tok-n">UserQueryImpl</span> <span class="tok-n">query</span><span class="tok-o">,</span> <span class="tok-n">Page</span> <span class="tok-n">page</span><span class="tok-o">);</span> 32943</td></tr></table></code></pre> 32944</div> 32945</div> 32946<div class="paragraph"> 32947<p>The code for the <a href="#chapter_ldap">LDAP integration</a> contains full examples of how to implement this. Check out the code on Github, specifically the following classes 32948 <a href="https://github.com/Activiti/Activiti/blob/master/modules/activiti-ldap/src/main/java/org/activiti/ldap/LDAPGroupManager.java">LDAPGroupManager</a> and 32949 <a href="https://github.com/Activiti/Activiti/blob/master/modules/activiti-ldap/src/main/java/org/activiti/ldap/LDAPUserManager.java">LDAPUserManager</a>.</p> 32950</div> 32951</div> 32952<div class="sect2"> 32953<h3 id="advanced.safe.bpmn.xml">16.9. Enable safe BPMN 2.0 xml</h3> 32954<div class="paragraph"> 32955<p>In most cases the BPMN 2.0 processes that are being deployed to the Activiti engine are under tight control of e.g. the development team. However, in some use cases it might be desirable to upload arbitrary BPMN 2.0 xml to the engine. In that case, take into consideration that a user with bad intentions can bring the server down as described <a href="http://www.jorambarrez.be/blog/2013/02/19/uploading-a-funny-xml-can-bring-down-your-server/">here</a>.</p> 32956</div> 32957<div class="paragraph"> 32958<p>To avoid the attacks described in the link above, a property <em>enableSafeBpmnXml</em> can be set on the process engine configuration:</p> 32959</div> 32960<div class="listingblock"> 32961<div class="content"> 32962<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"enableSafeBpmnXml"</span> <span class="tok-na">value=</span><span class="tok-s">"true"</span><span class="tok-nt">/></span> 32963</td></tr></table></code></pre> 32964</div> 32965</div> 32966<div class="paragraph"> 32967<p><strong>By default this feature is disabled!</strong> The reason for this is that it relies on the availability of the <a href="http://download.java.net/jdk7/archive/b123/docs/api/javax/xml/transform/stax/StAXSource.html">StaxSource</a> class. Unfortunately, on some platforms (e.g. JDK 6, JBoss, etc.) this class is unavailable (due to older xml parser implementation) and thus the safe BPMN 2.0 xml feature cannot be enabled.</p> 32968</div> 32969<div class="paragraph"> 32970<p>If the platform on which Activiti runs does support it, do enable this feature.</p> 32971</div> 32972</div> 32973<div class="sect2"> 32974<h3 id="advanced.event.logging">16.10. Event logging (Experimental)</h3> 32975<div class="paragraph"> 32976<p>As of Activiti version 5.16, an (experimental) event logging mechanism has been introduced. The logging mechanism builds upon the general-purpose <a href="#eventDispatcher">event mechanism of the Activiti engine</a> and is disabled by default. The idea is that the events originating from the engine are caught, and a map containing all the event data (and some more) is created and provided to an <em>org.activiti.engine.impl.event.logger.EventFlusher</em> which will flush this data to somewhere else. By default, simple database-backed event handlers/flusher is used, which serializes the said map to JSON using Jackson and stores it in the database as an <em>EventLogEntryEntity</em> instance. The table required for this database logging is created by default (called <em>ACT_EVT_LOG</em>
32976). This table can be deleted if the event logging is not used.</p> 32977</div> 32978<div class="paragraph"> 32979<p>To enable the database logger:</p> 32980</div> 32981<div class="listingblock"> 32982<div class="content"> 32983<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-n">processEngineConfiguration</span><span class="tok-o">.</span><span class="tok-na">setEnableDatabaseEventLogging</span><span class="tok-o">(</span><span class="tok-kc">true</span><span class="tok-o">);</span> 32984</td></tr></table></code></pre> 32985</div> 32986</div> 32987<div class="paragraph"> 32988<p>or at runtime:</p> 32989</div> 32990<div class="listingblock"> 32991<div class="content"> 32992<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 329932</div></td><td class="code"><span></span>databaseEventLogger = new EventLogger(processEngineConfiguration.getClock()); 32994runtimeService.addEventListener(databaseEventLogger); 32995</td></tr></table></code></pre> 32996</div> 32997</div> 32998<div class="paragraph"> 32999<p>The EventLogger class can be subclassed. In particular, the <em>createEventFlusher()</em> method needs to return an instance of the <em>org.activiti.engine.impl.event.logger.EventFlusher</em> interface if the default database logging is not wanted. The <em>managementService.getEventLogEntries(startLogNr, size);</em> can be used to retrieve the <em>EventLogEntryEntity</em> instances through Activiti.</p> 33000</div> 33001<div class="paragraph"> 33002<p>It is easy to see how this table data can now be used to feed the JSON into a big data NoSQL store such as MongoDB, Elastic Search, etc. It is also easy to see that the classes used here (org.activiti.engine.impl.event.logger.EventLogger/EventFlusher and many EventHandler classes) are pluggable and can be tweaked to your own use case (eg not storing the JSON in the database, but firing it straight onto a queue or big data store).</p> 33003</div> 33004<div class="paragraph"> 33005<p>Note that this event logging mechanism is additional to the <em>traditional</em> history manager of Activiti. Although all the data is in the database tables, 33006it is not optimized for querying nor for easy retrieval. The real use case is audit trailing and feeding it into a big data store.</p> 33007</div> 33008</div> 33009<div class="sect2"> 33010<h3 id="_disabling_bulk_inserts">16.11. Disabling bulk inserts</h3> 33011<div class="paragraph"> 33012<p>By default, the engine will group multiple insert statements for the same database table together in a <em>bulk insert</em>, thus improving performance. This has been tested and implemented for all supported databases.</p> 33013</div> 33014<div class="paragraph"> 33015<p>However, it could be a specific version of a supported and tested database does not allow bulk inserts (we have for example a report for DB2 on z/OS, although DB2 in general works), the bulk insert can be disabled on the process engine configuration:</p> 33016</div> 33017<div class="listingblock"> 33018<div class="content"> 33019<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1</div></td><td class="code"><span></span><span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"bulkInsertEnabled"</span> <span class="tok-na">value=</span><span class="tok-s">"false"</span> <span class="tok-nt">/></span> 33020</td></tr></table></code></pre> 33021</div> 33022</div> 33023</div> 33024<div class="sect2"> 33025<h3 id="advancedSecureScripting">16.12. Secure Scripting</h3> 33026<div class="paragraph"> 33027<p><strong>Experimental</strong>: the secure scripting feature has been added as part of the Activiti 5.21 release.</p> 33028</div> 33029<div class="paragraph"> 33030<p>By default, when using a <a href="#bpmnScriptTask">script task</a>, the script that is executed has similar capabilities as a Java delegate. It has full access to the JVM, can run forever (due to infinite loops) or use up a lot of memory. However, Java delegates need to be written and put on the classpath in a jar and they have a different lifecyle from a process definitions. End-users generally will not write Java delegates, as this is a typical the job of a developer.</p> 33031</div> 33032<div class="paragraph"> 33033<p>Scripts on the other hand are part of the process definition and its lifecycle is the same. Script tasks don’t need the extra step of a jar deployment, but can be executed from the moment the process definition is deployed. Sometimes, scripts for script tasks are not written by developers. Yet, this poses a problem as stated above: a script has full access to the JVM and it is possible to block many system resources when executing the script. Allowing scripts from just about anyone is thus not a good idea.</p> 33034</div> 33035<div class="paragraph"> 33036<p>To solve this problem, the <em>secure scripting</em> feature can be enabled. Currently, this feature is implemented for <em>javascript</em> scripting only. To enable it, add the <em>activiti-secure-javascript</em> dependency to your project. When using maven:</p> 33037</div> 33038<div class="listingblock"> 33039<div class="content"> 33040<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 330412 330423 330434 330445</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 33045 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 33046 <span class="tok-nt"><artifactId></span>activiti-secure-javascript<span class="tok-nt"></artifactId></span> 33047 <span class="tok-nt"><version></span>${activiti.version}<span class="tok-nt"></version></span> 33048<span class="tok-nt"></dependency></span> 33049</td></tr></table></code></pre> 33050</div> 33051</div> 33052<div class="paragraph"> 33053<p>Adding this dependency will transitively bring in the Rhino dependency (see <a href="$https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino$$"><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino" class="bare">https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino</a></a>). Rhino is a javascript engine for the JDK. It used to be included in JDK version 6 and 7 and was superseded by the Nashorn engine. However, the Rhino project continued development after it was included in the JDK. Many features (including the ones Activiti uses to implement the secure scripting) were added afterwards. At the time of writing, the Nashorn engine <strong>
33053does not</strong> have the features that are needed to implement the secure scripting feature.</p> 33054</div> 33055<div class="paragraph"> 33056<p>This does mean that there could be (typically small) differences between scripts (for example, <em>importPackage</em> works on Rhino, but <em>load()</em> has to be used on Nashorn). The changes would be similar to switching from JDK 7 to 8 scripts.</p> 33057</div> 33058<div class="paragraph"> 33059<p>Configuring the secure scripting is done through a dedicated <em>Configurator</em> object that is passed to the process engine configuration before the process engine is instantiated:</p> 33060</div> 33061<div class="listingblock"> 33062<div class="content"> 33063<pre class="pygments highlight"><code data-lang="java"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 330642 330653 330664 330675 330686 330697 330708</div></td><td class="code"><span></span><span class="tok-n">SecureJavascriptConfigurator</span> <span class="tok-n">configurator</span> <span class="tok-o">=</span> <span class="tok-k">new</span> <span class="tok-n">SecureJavascriptConfigurator</span><span class="tok-o">()</span> 33071 <span class="tok-o">.</span><span class="tok-na">setWhiteListedClasses</span><span class="tok-o">(</span><span class="tok-k">new</span> <span class="tok-n">HashSet</span><span class="tok-o"><</span><span class="tok-n">String</span><span class="tok-o">>(</span><span class="tok-n">Arrays</span><span class="tok-o">.</span><span class="tok-na">asList</span><span class="tok-o">(</span><span class="tok-s">"java.util.ArrayList"</span><span class="tok-o">)))</span> 33072 <span class="tok-o">.</span><span class="tok-na">setMaxStackDepth</span><span class="tok-o">(</span><span class="tok-mi">10</span><span class="tok-o">)</span> 33073 <span class="tok-o">.</span><span class="tok-na">setMaxScriptExecutionTime</span><span class="tok-o">(</span><span class="tok-mi">3000L</span><span class="tok-o">)</span> 33074 <span class="tok-o">.</span><span class="tok-na">setMaxMemoryUsed</span><span class="tok-o">(</span><span class="tok-mi">3145728L</span><span class="tok-o">)</span> 33075 <span class="tok-o">.</span><span class="tok-na">setNrOfInstructionsBeforeStateCheckCallback</span><span class="tok-o">(</span><span class="tok-mi">10</span><span class="tok-o">);</span> 33076 33077<span class="tok-n">processEngineConfig</span><span class="tok-o">.</span><span class="tok-na">addConfigurator</span><span class="tok-o">(</span><span class="tok-n">configurator</span><span class="tok-o">);</span> 33078</td></tr></table></code></pre> 33079</div> 33080</div> 33081<div class="paragraph"> 33082<p>Following settings are possible:</p> 33083</div> 33084<div class="ulist"> 33085<ul> 33086<li> 33087<p><strong>enableClassWhiteListing</strong>: When true, all classes will be blacklisted and all classes that want to be used will need to be whitelisted individually. This gives tight control over what is exposed to scripts. By default <em>false</em>.</p> 33088</li> 33089<li> 33090<p><strong>whiteListedClasses</strong>: a Set of Strings corresponding with fully qualified classnames of the classes that are allowed to be used in the script. For example, to expose the <em>execution</em> object in a script, the <em>org.activiti.engine.impl.persistence.entity.ExecutionEntityImpl</em> String needs to be added to this Set. By default <em>empty</em>.</p> 33091</li> 33092<li> 33093<p><strong>maxStackDepth</strong>: Limits the stack depth while calling functions within a script. This can be used to avoid stackoverflow exceptions that occur when recursively calling a method defined in the script. By default <em>-1</em> (disabled).</p> 33094</li> 33095<li> 33096<p><strong>maxScriptExecutionTime</strong>: The maximum time a script is allowed to run. By default <em>-1</em> (disabled).</p> 33097</li> 33098<li> 33099<p><strong>maxMemoryUsed</strong>: The maximum memory, in bytes, that the script is allowed to use. Note that the script engine itself takes a a certain amount of memory that is counted here too. By default <em>-1</em> (disabled).</p> 33100</li> 33101<li> 33102<p><strong>nrOfInstructionsBeforeStateCheckCallback</strong>: The maximum script execution time and memory usage is implemented using a callback that is called every x instructions of the script. Note that these are not script instructions, but java byte code instructions (which means one script line could be hun
33102dreds of byte code instructions). By default 100.</p> 33103</li> 33104</ul> 33105</div> 33106<div class="paragraph"> 33107<p><em>Note:</em> the <em>maxMemoryUsed</em> setting can only be used by a JVM that supports the com.sun.management.ThreadMXBean#getThreadAllocatedBytes() method. The Oracle JDK has this.</p> 33108</div> 33109<div class="paragraph"> 33110<p>There is also a secure variant of the ScriptExecutionListener and ScriptTaskListener: <em>org.activiti.scripting.secure.listener.SecureJavascriptExecutionListener</em> and <em>org.activiti.scripting.secure.listener.SecureJavascriptTaskListener</em>.</p> 33111</div> 33112<div class="paragraph"> 33113<p>It’s used as follows:</p> 33114</div> 33115<div class="listingblock"> 33116<div class="content"> 33117<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 33118 2 33119 3 33120 4 33121 5 33122 6 33123 7 33124 8 33125 9 3312610</div></td><td class="code"><span></span><span class="tok-nt"><activiti:executionListener</span> <span class="tok-na">event=</span><span class="tok-s">"start"
33126</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.scripting.secure.listener.SecureJavascriptExecutionListener"</span><span class="tok-nt">></span> 33127 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"script"</span><span class="tok-nt">></span> 33128 <span class="tok-nt"><activiti:string></span> 33129 <span class="tok-cp"><![CDATA[</span> 33130<span class="tok-cp"> execution.setVariable('test');</span> 33131<span class="tok-cp"> ]]></span> 33132 <span class="tok-nt"></activiti:string></span> 33133 <span class="tok-nt"></activiti:field></span> 33134 <span class="tok-nt"><activiti:field</span> <span class="tok-na">name=</span><span class="tok-s">"language"</span> <span class="tok-na">stringValue=</span><span class="tok-s">"javascript"</span> <span class="tok-nt">/></span> 33135<span class="tok-nt"></activiti:executionListener></span> 33136</td></tr></table></code></pre> 33137</div> 33138</div> 33139<div class="paragraph"> 33140<p>For examples that demonstrate unsecure scripts and how they are made secure by the <em>secure scripting</em> feature, please check the <a href="https://github.com/Activiti/Activiti/tree/master/modules/activiti-secure-javascript/src/test/resources">unit tests on Github</a></p> 33141</div> 33142</div> 33143</div> 33144</div> 33145<div class="sect1"> 33146<h2 id="Tooling">17. Tooling</h2> 33147<div class="sectionbody"> 33148<div class="sect2"> 33149<h3 id="JMX">17.1. JMX</h3> 33150<div class="sect3"> 33151<h4 id="jmxIntroduction">17.1.1. Introduction</h4> 33152<div class="paragraph"> 33153<p>It is possible to connect to Activiti engine using standard Java Management Extensions (JMX) technology in order to get information or to change its behavior. Any standard JMX client can be used for that purpose. Enabling and disabling Job Executor, deploy new process definition files and deleting them are just samples of what could be done using JMX without writing a single line of code.</p> 33154</div> 33155</div> 33156<div class="sect3"> 33157<h4 id="jmxQuickStart">17.1.2. Quick Start</h4> 33158<div class="paragraph"> 33159<p>By default JMX is not enabled. To enable JMX in its default configuration, it is enough to add the activiti-jmx jar file to your classpath, using Maven or by any other means. In case you are using Maven, you can add proper dependency by adding the following lines in your pom.xml:</p> 33160</div> 33161<div class="listingblock"> 33162<div class="content"> 33163<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1 331642 331653 331664 331675</div></td><td class="code"><span></span><span class="tok-nt"><dependency></span> 33168 <span class="tok-nt"><groupId></span>org.activiti<span class="tok-nt"></groupId></span> 33169 <span class="tok-nt"><artifactId></span>activiti-jmx<span class="tok-nt"></artifactId></span> 33170 <span class="tok-nt"><version></span>latest.version<span class="tok-nt"></version></span> 33171<span class="tok-nt"></dependency></span> 33172</td></tr></table></code></pre> 33173</div> 33174</div> 33175<div class="paragraph"> 33176<p>After adding the dependency and building process engine, the JMX connection is ready to be used. Just run jconsole available in a standard JDK distribution. In the list of local processes, you will see the JVM containing Activiti. If for any reason the proper JVM is not listed in "local processes" section, try connecting to it using this URL in "Remote Process" section:</p> 33177</div> 33178<div class="listingblock"> 33179<div class="content"> 33180<pre>service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi/activiti</pre> 33181</div> 33182</div> 33183<div class="paragraph"> 33184<p>You can find the exact local URL in your log files. After connecting, you can see the standard JVM statistics and MBeans. You can view Activiti specific MBeans by selecting MBeans tab and select "org.activiti.jmx.Mbeans" on the right panel. By selecting any MBean, you can query information or change configuration. This snapshot shows how the jconsole looks like:</p> 33185</div> 33186<div class="paragraph"> 33187<p>Any JMX client not limited to jconsole can be used to access MBeans. Most of data center monitoring tools have some connectors which enables them to connect to JMX MBeans.</p> 33188</div> 33189</div> 33190<div class="sect3"> 33191<h4 id="_attributes_and_operations">17.1.3. Attributes and operations</h4> 33192<div class="paragraph"> 33193<p>Here is a list available attributes and operations at this moment. This list may extend in future releases based on needs.
33193</p> 33194</div> 33195<table class="tableblock frame-all grid-all spread"> 33196<colgroup> 33197<col style="width: 25%;"> 33198<col style="width: 25%;"> 33199<col style="width: 25%;"> 33200<col style="width: 25%;"> 33201</colgroup> 33202<thead> 33203<tr> 33204<th class="tableblock halign-left valign-top">MBean</th> 33205<th class="tableblock halign-left valign-top">Type</th> 33206<th class="tableblock halign-left valign-top">Name</th> 33207<th class="tableblock halign-left valign-top">Description</th> 33208</tr> 33209</thead> 33210<tbody> 33211<tr> 33212<td class="tableblock halign-left valign-top"><p class="tableblock">ProcessDefinitionsMBean</p></td> 33213<td class="tableblock halign-left valign-top"><p class="tableblock">Attribute</p></td> 33214<td class="tableblock halign-left valign-top"><p class="tableblock">processDefinitions</p></td> 33215<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Id</code>, <code>Name</code>, <code>Version</code>, <code>IsSuspended</code> properties of deployed process definitions as a list of list of Strings</p></td> 33216</tr> 33217<tr> 33218<td class="tableblock halign-left valign-top"></td> 33219<td class="tableblock halign-left valign-top"><p class="tableblock">Attribute</p></td> 33220<td class="tableblock halign-left valign-top"><p class="tableblock">deployments</p></td> 33221<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Id</code>, <code>Name</code>, <code>TenantId</code> properties of current deployments</p></td> 33222</tr> 33223<tr> 33224<td class="tableblock halign-left valign-top"></td> 33225<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33226<td class="tableblock halign-left valign-top"><p class="tableblock">getProcessDefinitionById(String id)</p></td> 33227<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Id</code>, <code>Name</code>, <code>Version</code> and <code>IsSuspended</code> properties of the process definition with given id</p></td> 33228</tr> 33229<tr> 33230<td class="tableblock halign-left valign-top"></td> 33231<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33232<td class="tableblock halign-left valign-top"><p class="tableblock">deleteDeployment(String id)</p></td> 33233<td class="tableblock halign-left valign-top"><p class="tableblock">Deletes deployment with the given <code>Id</code></p></td> 33234</tr> 33235<tr> 33236<td class="tableblock halign-left valign-top"></td> 33237<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33238<td class="tableblock halign-left valign-top"><p class="tableblock">suspendProcessDefinitionById(String id)</p></td> 33239<td class="tableblock halign-left valign-top"><p class="tableblock">Suspends the process definition with the given <code>Id</code></p></td> 33240</tr> 33241<tr> 33242<td class="tableblock halign-left valign-top"></td> 33243<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33244<td class="tableblock halign-left valign-top"><p class="tableblock">activatedProcessDefinitionById(String id)</p></td> 33245<td class="tableblock halign-left valign-top"><p class="tableblock">Activates the process definition with the given <code>Id</code></p></td> 33246</tr> 33247<tr> 33248<td class="tableblock halign-left valign-top"></td> 33249<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33250<td class="tableblock halign-left valign-top"><p class="tableblock">suspendProcessDefinitionByKey(String id)</p></td> 33251<td class="tableblock halign-left valign-top"><p class="tableblock">Suspends the process definition with the given <code>key</code></p></td> 33252</tr> 33253<tr> 33254<td class="tableblock halign-left valign-top"></td> 33255<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33256<td class="tableblock halign-left valign-top"><p class="tableblock">activatedProcessDefinitionByKey(String id)</p></td> 33257<td class="tableblock halign-left valign-top"><p class="tableblock">Activates the process definition with the given <code>key</code></p></td> 33258</tr> 33259<tr> 33260<td class="tableblock halign-left valign-top"></td> 33261<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33262<td class="tableblock halign-left valign-top"><p class="tableblock">deployProcessDefinition(String resourceName, String processDefinitionFile)</p></td> 33263<td class="tableblock halign-left valign-top"><p class="tableblock">Deploys the process definition file</p></td> 33264</tr> 33265<tr> 33266<td class="tableblock halign-left valign-top"><p class="tableblock">JobExecutorMBean</p></td> 33267<td class="tableblock halign-left valign-top"><p class="tableblock">attribute</p></td> 33268<td class="tableblock halign-left valign-top"><p class="tableblock">isJobExecutorActivated</p></td> 33269<td class="tableblock halign-left valign-top"><p class="tableblock">Returns true if job executor is activated, false otherwise</p></td> 33270</tr> 33271<tr> 33272<td class="tableblock halign-left valign-top"></td> 33273<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td> 33274<td class="tableblock halign-left valign-top"><p class="tableblock">setJobExecutorActivate(Boolean active)</p></td> 33275<td class="tableblock halign-left valign-top"><p class="tableblock">Activates and Deactivates Job executor based on the given boolean</p></td> 33276</tr> 33277</tbody> 33278</table> 33279</div> 33280<div class="sect3"> 33281<h4 id="_configuration_3">17.1.4. Configuration</h4> 33282<div class="paragraph"> 33283<p>JMX uses default configuration to make it easy to deploy with the most used configuration. However it is easy to change the default configuration. You can do it programmatically or via configuration file. The following code excerpt shows how this could be done in the configuration file:</p> 33284</div> 33285<div class="listingblock"> 33286<div class="content"> 33287<pre class="pygments highlight"><code data-lang="xml"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv"> 1 33288 2 33289 3 33290 4 33291 5 33292 6 33293 7 33294 8 33295 9 3329610 3329711 3329812 3329913 3330014</div></td><td class="code"><span></span><span class="tok-nt"><bean</span> <span class="tok-na">id=</span><span class="tok-s">"processEngineConfiguration"</span> <span class="tok-na">class=</span><span class="tok-s">"...SomeProcessEngineConfigurationClass"</span><span class="tok-nt">></span> 33301 ... 33302 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"configurators"</span><span class="tok-nt">></span> 33303 <span class="tok-nt"><list></span> 33304 <span class="tok-nt"><bean</span> <span class="tok-na">class=</span><span class="tok-s">"org.activiti.management.jmx.JMXConfigurator"</span><span class="tok-nt">></span> 33305 33306 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"connectorPort"</span> <span class="tok-na">value=</span><span class="tok-s">"1912"</span> <span class="tok-nt">/></span>
33307 <span class="tok-nt"><property</span> <span class="tok-na">name=</span><span class="tok-s">"serviceUrlPath"</span> <span class="tok-na">value=</span><span class="tok-s">"/jmxrmi/activiti"</span> <span class="tok-nt">/></span> 33308 33309 ... 33310 <span class="tok-nt"></bean></span> 33311 <span class="tok-nt"></list></span> 33312 <span class="tok-nt"></property></span> 33313<span class="tok-nt"></bean></span> 33314</td></tr></table></code></pre> 33315</div> 33316</div> 33317<div class="paragraph"> 33318<p>This table shows what parameters you can configure along with their default values:</p> 33319</div> 33320<table class="tableblock frame-all grid-all spread"> 33321<colgroup> 33322<col style="width: 33.3333%;"> 33323<col style="width: 33.3333%;"> 33324<col style="width: 33.3334%;"> 33325</colgroup> 33326<thead> 33327<tr> 33328<th class="tableblock halign-left valign-top">Name</th> 33329<th class="tableblock halign-left valign-top">Default value</th> 33330<th class="tableblock halign-left valign-top">Description</th> 33331</tr> 33332</thead> 33333<tbody> 33334<tr> 33335<td class="tableblock halign-left valign-top"><p class="tableblock">disabled</p></td> 33336<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> 33337<td class="tableblock halign-left valign-top"><p class="tableblock">if set, JMX will not be started even in presence of the dependency</p></td> 33338</tr> 33339<tr> 33340<td class="tableblock halign-left valign-top"><p class="tableblock">domain</p></td> 33341<td class="tableblock halign-left valign-top"><p class="tableblock">org.activiti.jmx.Mbeans</p></td> 33342<td class="tableblock halign-left valign-top"><p class="tableblock">Domain of MBean</p></td> 33343</tr> 33344<tr> 33345<td class="tableblock halign-left valign-top"><p class="tableblock">createConnector</p></td> 33346<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> 33347<td class="tableblock halign-left valign-top"><p class="tableblock">if true, creates a connector for the started MbeanServer</p></td> 33348</tr> 33349<tr> 33350<td class="tableblock halign-left valign-top"><p class="tableblock">MBeanDomain</p></td> 33351<td class="tableblock halign-left valign-top"><p class="tableblock">DefaultDomain</p></td> 33352<td class="tableblock halign-left valign-top"><p class="tableblock">domain of MBean server</p></td> 33353</tr> 33354<tr> 33355<td class="tableblock halign-left valign-top"><p class="tableblock">registryPort</p></td> 33356<td class="tableblock halign-left valign-top"><p class="tableblock">1099</p></td> 33357<td class="tableblock halign-left valign-top"><p class="tableblock">appears in the service URL as registry port</p></td> 33358</tr> 33359<tr> 33360<td class="tableblock halign-left valign-top"><p class="tableblock">serviceUrlPath</p></td> 33361<td class="tableblock halign-left valign-top"><p class="tableblock">/jmxrmi/activiti</p></td> 33362<td class="tableblock halign-left valign-top"><p class="tableblock">appears in the service URL</p></td> 33363</tr> 33364<tr> 33365<td class="tableblock halign-left valign-top"><p class="tableblock">connectorPort</p></td> 33366<td class="tableblock halign-left valign-top"><p class="tableblock">-1</p></td> 33367<td class="tableblock halign-left valign-top"><p class="tableblock">if greater than zero, will appear in service URL as connector port</p></td> 33368</tr> 33369</tbody> 33370</table> 33371</div> 33372<div class="sect3"> 33373<h4 id="_jmx_service_url">17.1.5. JMX Service URL</h4> 33374<div class="paragraph"> 33375<p>The JMX service URL has the following format:</p> 33376</div> 33377<div class="listingblock"> 33378<div class="content"> 33379<pre>service:jmx:rmi://<hostName>:<connectorPort>/jndi/rmi://<hostName>:<registryPort>/<serviceUrlPath></pre> 33380</div> 33381</div> 33382<div class="paragraph"> 33383<p><code>hostName</code> will be automatically set to the network name of the machine. 33384<code>connectorPort</code>, <code>registryPort</code> and <code>serviceUrlPath</code> can be configured.</p> 33385</div> 33386<div class="paragraph"> 33387<p>If <code>connectionPort</code> is less than zero, the corresponding part of service URL will be dropped and it will be simplified to:</p> 33388</div> 33389<div class="listingblock"> 33390<div class="content"> 33391<pre>service:jmx:rmi:///jndi/rmi://:<hostname>:<registryPort>/<serviceUrlPath></pre> 33392</div> 33393</div> 33394</div> 33395</div> 33396<div class="sect2"> 33397<h3 id="mavenArchetypes">17.2. Maven archetypes</h3> 33398<div class="sect3"> 33399<h4 id="_create_test_case">17.2.1. Create Test Case</h4> 33400<div class="paragraph"> 33401<p>During development, sometimes it is helpful to create a small test case to test an idea or a feature, 33402before implementing it in the real application. 33403This helps to isolate the subject under test. JUnit test cases are also the preferred tools for communicating 33404bug reports and feature requests. 33405Having a test case attached to a bug report or feature request jira issue, considerably reduces its fixing time.</p> 33406</div> 33407<div class="paragraph"> 33408<p>To facilitate creation of a test case, a maven archetype is available. By use of this archetype, one can rapidly create a standard test case. 33409The archetype should be already available in the standard repository. If not, you can easily install it in your local maven repository folder by just typing 33410 <strong>mvn install</strong> in <strong>tooling/archtypes</strong> folder.</p> 33411</div> 33412<div class="paragraph"> 33413<p>The following command creates the unit test project:</p> 33414</div> 33415<div class="listingblock"> 33416<div class="content"> 33417<pre class="pygments highlight"><code>mvn archetype:generate \ 33418-DarchetypeGroupId=org.activiti \ 33419-DarchetypeArtifactId=activiti-archetype-unittest \ 33420-DarchetypeVersion=<current version> \ 33421-DgroupId=org.myGroup \ 33422-DartifactId=myArtifact</code></pre> 33423</div> 33424</div> 33425<div class="paragraph"> 33426<p>The effect of each parameter is explained in the following table:</p> 33427</div> 33428<table class="tableblock frame-all grid-all spread"> 33429<caption class="title">Table 262. Unittest Generation archetype parameters</caption> 33430<colgroup> 33431<col style="width: 2.3255%;"> 33432<col style="width: 27.9069%;"> 33433<col style="width: 69.7676%;"> 33434</colgroup> 33435<thead> 33436<tr> 33437<th class="tableblock halign-left valign-top">Row</th> 33438<th class="tableblock halign-left valign-top">Parameter</th> 33439<th class="tableblock halign-left valign-top">Explanation</th> 33440</tr> 33441</thead> 33442<tbody> 33443<tr> 33444<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 33445<td class="tableblock halign-left valign-top"><p class="tableblock">archetypeGroupId</p></td> 33446<td class="tableblock halign-left valign-top"><p class="tableblock">Group id of the archetype. should be <strong>org.activiti</strong></p></td> 33447</tr> 33448<tr> 33449<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 33450<td class="tableblock halign-left valign-top"><p class="tableblock">archetypeArtifactId</p></td> 33451<td class="tableblock halign-left valign-top"><p class="tableblock">Artifact if of the archetype. should be <strong>activiti-archetype-unittest</strong></p></td> 33452</tr> 33453<tr> 33454<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 33455<td class="tableblock halign-left valign-top"><p class="tableblock">archetypeVersion</p></td> 33456<td class="tableblock halign-left valign-top"><p class="tableblock">Activiti version used in the generated test project</p></td> 33457</tr> 33458<tr> 33459<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> 33460<td class="tableblock halign-left valign-top"><p class="tableblock">groupId</p></td> 33461<td class="tableblock halign-left valign-top"><p class="tableblock">Group id of the generated test project</p></td> 33462</tr> 33463<tr> 33464<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> 33465<td class="tableblock halign-left valign-top"><p class="tableblock">artifactId</p></td> 33466<td class="tableblock halign-left valign-top"><p class="tableblock">Artifact id of the generated test project</p></td> 33467</tr> 33468</tbody> 33469</table> 33470<div class="paragraph"> 33471<p>The directory structure of the generated project would be like this:</p> 33472</div> 33473<div class="listingblock"> 33474<div class="content"> 33475<pre>. 33476âââ pom.xml 33477âââ src 33478 âââ test 33479 âââ java 33480 â  âââ org 33481 â  âââ myGroup 33482 â  âââ MyUnitTest.java 33483 âââ resources 33484 âââ activiti.cfg.xml 33485 âââ log4j.properties 33486 âââ org 33487 âââ myGroup 33488 âââ my-process.bpmn20.xml</pre> 33489</div> 33490</div> 33491<div class="paragraph"> 33492<p>You can modify java unit test case and its corresponding process model, or add new test cases and process models. 33493If you are using the project to articulate a bug or a feature, test case should fail initially. It should then pass 33494after the desired bug is fixed or the desired feature is implemented. 33495Please make sure to clean the project by typing <strong>mvn clean</strong> before sending it.</p> 33496</div> 33497</div> 33498</div> 33499</div> 33500</div> 33501</div> 33502<div id="footer"> 33503<div id="footer-text"> 33504Last updated 2017-05-25 10:52:43 EDT 33505</div> 33506</div> 33507</body> 33508</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.