Merge pull request #101 from adamfowleruk/feature-100

Version 1.1 in flight fix. Introduces locking. Fixes #100.

Author: adamfowleruk

config/env.js renamed to config/env.json

@@ -1,4 +1,4 @@
-module.exports = {"host":"192.168.123.225","port":"6061","database":"workflow-content",
+{"host":"192.168.123.4","port":"6061","database":"workflow-content",
 "username":"admin","password":"admin","auth":"digest","defaultuser":"nobody","webport":5001,
 "alertport":5002,"apppath":"./app","defaultpath":"/workplace.html5","modulesport":6060,
 "modulesdatabase":"workflow-modules","ssl":false,"adminport":8002,"triggersdatabase":"Triggers"}

config/webserver-settings.sh

@@ -2,7 +2,7 @@
 
 # CREATED BY YEOMAN generator-mljsworkplace!
 
-RESTHOST=192.168.123.225
+RESTHOST=192.168.123.4
 RESTPORT=6061
 DATABASE=workflow-content
 MLADMINUSER=admin

modules/app/models/workflow-actions.xqy

@@ -21,18 +21,27 @@ declare namespace error="http://marklogic.com/xdmp/error";
 declare function update-userTask($processId as xs:string,$data as node()*,$attachments as node()*) as node()? {
   let $_ := xdmp:log("In wfa:update-userTask")
   return
-  update-generic($processId,$data,$attachments)
+    update-generic($processId,$data,$attachments)
 };
 
 (:
  : Complete a user task, moving it on to the next step. (Just marks as complete)
  :)
 declare function complete-userTask($processId as xs:string,$data as node()*,$attachments as node()*) as node()? {
   let $_ := xdmp:log("In wfa:complete-userTask")
+  let $unlock :=
+    if (fn:not(fn:empty(wfu:getProperties($processId)/wf:currentStep/wf:lock))) then
+      wfu:unlock($processId) (: We call this to ensure this user has the current lock, even though wf:currentStep will be deleted :)
+    else
+      ()
   (: Find process document :)
   (: Get next step ID :)
   (: TODO check required attachments and properties here (Should be done in the UI) :)
-  let $update := update-userTask($processId,$data,$attachments)
+  let $update :=
+    if (fn:empty($unlock)) then
+      update-userTask($processId,$data,$attachments)
+    else
+      $unlock (: report issue :)
   (: TODO lookup functionality from document patch in REST API to see if we can replicate that method here :)
   return
     if (fn:empty($update)) then complete-generic($processId) else $update

modules/app/models/workflow-util.xqy

@@ -192,6 +192,66 @@ declare function m:list($processName as xs:string?) as element(wf:list) {
 
 
 
+(:
+ : Called by the REST API only.
+ :)
+declare function m:lock($processId as xs:string) as node()? {
+  (: Check that this is a human queue task or user task :)
+  let $props := m:getProperties($processId)
+  return
+    if ($props/wf:currentStep/wf:step-type = "userTask" and $props/wf:currentStep/wf:step-status = "ENTERED") then
+      if ($props/wf:currentStep/wf:type = "user" or $props/wf:currentStep/wf:type = "queue" or $props/wf:currentStep/wf:type = "role") then
+        if (fn:empty($props/wf:currentStep/wf:lock)) then
+          (: lock and return success :) (: TODO check what happens if this call fails... :)
+          (
+            xdmp:node-insert-child($props/wf:currentStep,<wf:lock><wf:by>{xdmp:get-current-user()}</wf:by><wf:when>{fn:current-dateTime()}</wf:when></wf:lock>)
+            ,
+            m:audit(m:getProcessUri($processId),(),"ProcessEngine","Work item locked by '" || xdmp:get-current-user() || "'",())
+          )
+        else
+          if ($props/wf:currentStep/wf:lock/wf:by = xdmp:get-current-user()) then
+            (: Do nothing - ok :)
+            ()
+          else
+            (: Fail :)
+            "Could not lock work item. Work item is already locked by '" || xs:string($props/wf:currentStep/wf:lock/wf:by) || "'"
+      else
+        "Could not lock work item. userTask type '" || xs:string($props/wf:currentStep/wf:type) || "' not supported for locking."
+    else
+      "Could not lock work item. Step is not a userTask, or status is not 'ENTERED'. Try again."
+  (: If assigned to user task, and this user, always return true even if already locked :)
+  (: Check that this item is not already locked if a queue task :)
+  (: Lock the work item :)
+  (: Return blank if ok :)
+};
+
+(:
+ : Allow unlocking of a work item. (Not the same as completion). Does not return data.
+ :)
+declare function m:unlock($processId as xs:string) as node()? {
+let $props := m:getProperties($processId)
+return
+  if ($props/wf:currentStep/wf:step-type = "userTask" and $props/wf:currentStep/wf:step-status = "ENTERED") then
+    if ($props/wf:currentStep/wf:type = "user" or $props/wf:currentStep/wf:type = "queue" or $props/wf:currentStep/wf:type = "role") then
+      if (fn:empty($props/wf:currentStep/wf:lock)) then
+        () (: Just succeed, rather than error - means we are alreay unlocked! :)
+      else
+        if ($props/wf:currentStep/wf:lock/wf:by = xdmp:get-current-user()) then
+          (: Unlock :)
+          (
+            xdmp:node-delete($props/wf:currentStep/wf:lock)
+            ,
+            m:audit(m:getProcessUri($processId),(),"ProcessEngine","Work item unlocked by '" || xdmp:get-current-user() || "'",())
+          )
+        else
+          (: Fail :)
+          "Could not unlock work item. Work item is locked by a different user: '" || xs:string($props/wf:currentStep/wf:lock/wf:by) || "'"
+    else
+      "Could not unlock work item. userTask type '" || xs:string($props/wf:currentStep/wf:type) || "' not supported for locking."
+  else
+    "Could not unlock work item. Step is not a userTask, or status is not 'ENTERED'. Try again."
+};
+
 
 (:
  : This module performs process data document update functions via a high level abstraction.

rest-api/ext/process.xqy

@@ -17,6 +17,8 @@ import module namespace wfa="http://marklogic.com/workflow-actions" at "/app/mod
 declare namespace roxy = "http://marklogic.com/roxy";
 declare namespace wf="http://marklogic.com/workflow";
 
+declare namespace rapi = "http://marklogic.com/rest-api";
+
 (:
  : To add parameters to the functions, specify them in the params annotations.
  : Example
@@ -124,9 +126,17 @@ function ext:get(
 
 
 
-(: POST - update a process instance, potentially completing it (e.g. human step) :)
+(:
+ : POST - update a process instance, potentially completing it (e.g. human step)
+ :
+ : POST process?processid=1234 -> Updates data only, does not lock or unlock item. DEPRECATED in current form - In future this will respect locks. Does not yet.
+ : POST process?processid=1234&complete=true -> Completes work item. Respects locks. (optionally) updates work item data.
+ : POST process?processid=1234&lock=true -> Locks the work item for the current user. (optionally) updates work item data. Respects locks.
+ : POST process?processid=1234&unlock=true -> Unlocks the work item if locked by current user. (optionally) update work item data. Respects locks.
+ :)
 declare
 %roxy:params("")
+%rapi:transaction-mode("update")
 function ext:post(
    $context as map:map,
    $params  as map:map,
@@ -135,6 +145,8 @@ function ext:post(
 
  let $preftype := if ("application/xml" = map:get($context,"accept-types")) then "application/xml" else "application/json"
 
+ let $part := (map:get($params,"part"),"document")[1]
+
  let $_ := xdmp:log($input)
  let $pid := map:get($params,"processid")
  (:let $proc := wfu:get($pid):)
@@ -165,8 +177,63 @@ function ext:post(
        (: error - cannot call complete on non completable task :)
        <ext:updateResponse><ext:outcome>FAILURE</ext:outcome><ext:message>Cannot call complete on non completable task: {$props/wf:step-type/text()}</ext:message></ext:updateResponse>
    else
-     (: TODO perform a data update but leave incomplete :)
-     <ext:updateResponse><ext:outcome>SUCCESS</ext:outcome><ext:message>No complete parameter, or complete parameter false. Leaving incomplete.</ext:message></ext:updateResponse>
+
+     if ("true" = map:get($params,"lock")) then
+       (: Lock the work item, and return its details as if get had been called. If already locked, instead return an error :)
+       let $feedback := wfu:lock($pid)
+       let $update :=
+         if (fn:empty($feedback)) then
+           <ext:readResponse><ext:outcome>SUCCESS</ext:outcome>
+             {if ($part = "document") then
+               <ext:document>{wfu:get(map:get($params,"processid"))}</ext:document>
+              else if ($part = "properties") then
+                <ext:properties>{wfu:getProperties(map:get($params,"processid"))}</ext:properties>
+              else
+                (<ext:document>{wfu:get(map:get($params,"processid"))}</ext:document>,
+                <ext:properties>{wfu:getProperties(map:get($params,"processid"))}</ext:properties>)
+             }
+           </ext:readResponse>
+         else
+           <ext:updateResponse><ext:outcome>FAILURE</ext:outcome><ext:message>Work item could not be locked by user.</ext:message><ext:feedback>{$feedback}</ext:feedback></ext:updateResponse>
+        return
+          if (fn:empty($feedback)) then
+            let $fb := wfa:update-userTask($pid,$input/ext:updateRequest/wf:data/node(),$input/ext:updateRequest/wf:attachments/node())
+            return
+              if (fn:not(fn:empty($fb))) then
+                <ext:updateResponse><ext:outcome>FAILURE</ext:outcome><ext:message>Could not update userTask</ext:message><ext:feedback>{$fb}</ext:feedback></ext:updateResponse>
+              else
+                $update
+          else
+            $update
+      else
+        if ("true" = map:get($params,"unlock")) then
+          let $feedback := wfu:unlock($pid)
+          let $update :=
+           if (fn:empty($feedback)) then
+            <ext:readResponse><ext:outcome>SUCCESS</ext:outcome>
+              {if ($part = "document") then
+                <ext:document>{wfu:get(map:get($params,"processid"))}</ext:document>
+               else if ($part = "properties") then
+                 <ext:properties>{wfu:getProperties(map:get($params,"processid"))}</ext:properties>
+               else
+                 (<ext:document>{wfu:get(map:get($params,"processid"))}</ext:document>,
+                 <ext:properties>{wfu:getProperties(map:get($params,"processid"))}</ext:properties>)
+              }
+            </ext:readResponse>
+           else
+            <ext:updateResponse><ext:outcome>FAILURE</ext:outcome><ext:message>Work item could not be unlocked by user.</ext:message><ext:feedback>{$feedback}</ext:feedback></ext:updateResponse>
+          return
+            if (fn:empty($feedback)) then
+              let $fb := wfa:update-userTask($pid,$input/ext:updateRequest/wf:data/node(),$input/ext:updateRequest/wf:attachments/node())
+              return
+                if (fn:not(fn:empty($fb))) then
+                  <ext:updateResponse><ext:outcome>FAILURE</ext:outcome><ext:message>Could not update userTask</ext:message><ext:feedback>{$fb}</ext:feedback></ext:updateResponse>
+                else
+                  $update
+            else
+              $update
+        else
+          () (: Just default to updating the data, but doing nothing around locking :)
 
 
  let $out := ($res,<ext:updateResponse><ext:outcome>SUCCESS</ext:outcome></ext:updateResponse>)[1]