Merge pull request #22 from adamfowleruk/feature-21

Feature 21 Completed (Alerting)

Author: adamfowleruk

CONTRIBUTING.md

@@ -73,7 +73,7 @@ your vision does not align with that of a project maintainer.
 #### Create a branch for your feature
 
 Okay, so you have decided to add something. Create an issue on GitHub if you haven't already, as you'll need the ID.
-Now create a feature branch and start hacking:
+Now create a feature branch and start hacking. You can do this on your own fork, or the main site if a 'Contributor':
 
 ```sh
 $ git checkout -b feature-ISSUEID develop
@@ -93,7 +93,8 @@ To share the branch so others can see it (although advised not to work on it) do
 $ git push --set-upstream origin feature-ISSUEID
 ```
 
-Now your feature branch [will be visible on GitHub](https://github.com/adamfowleruk/marklogicworkflow/branches).
+Now your feature branch [will be visible on GitHub](https://github.com/adamfowleruk/marklogicworkflow/branches) if you
+are a contributor.
 
 #### Formatting code
 
@@ -119,16 +120,23 @@ Make sure that all tests pass. Please, do not submit patches that fail.
 
 When the feature is complete and ready to be integrated back in to the develop branch:-
 
+1. If on your own Fork (99% of people):-
 ```sh
 $ git commit -m "Fixes #ISSUEID"
 $ git pull origin develop
 $ git checkout develop
 $ git merge feature-ISSUEID
 $ git push
-$ git branch -d feature-ISSUEID
 ```
 
-Only do the last command if the others complete successfully. You may have to merge conflicts.
+2. If an assigned admin user (contributor) on the main project, do this instead:-
+```sh
+$ git commit -m "Fixes #ISSUEID"
+$ git push
+```
+
+Now issue a pull request for your changes to the main project.
+
 
 You're now done! Adding the 'Fixes #ISSUEID' comment to the last commit automatically closes the issue with a reference
 to your code.

data/restapi.json

@@ -6,7 +6,8 @@
     {"name": "processinbox", "methods": ["GET"]},
     {"name": "processqueue", "methods": ["GET"]},
     {"name": "processmodel", "methods": ["GET","POST","PUT"]},
-    {"name": "processsubscription", "methods": ["PUT"]}
+    {"name": "processsubscription", "methods": ["PUT"]},
+    {"name": "processsearch", "methods": ["PUT"]}
   ],
   "transforms": [],
   "triggers": [

documentation/DEV-MODELER.md

@@ -26,14 +26,39 @@ you access to everything you need.
 Until this happens, or if you need the very latest MarkLogic Workflow model element support whilst working on a new
 project, you will need to execute the extension manually.
 
-To execute the latest extension:-
-- Checkout or download the zip of the latest (develop branch) of MarkLogic Workflow at http://github.com/adamfowleruk/marklogicworkflow
+### Latest from source (any branch) for Plugin development
+
+Note: If following the Contributing guide, you should have logged an issue and created a new branch from develop using
+```sh
+$ git checkout -b feature-ISSUEID develop
+```
+
+To execute the latest extension from source:-
+- Checkout or download the zip of the latest (develop or feature branch) of MarkLogic Workflow at http://github.com/adamfowleruk/marklogicworkflow
 - Open Eclipse Luna (4.4) or above
 - Go to File -> Import project
 - Navigate to ./marklogicworkflow/eclipse/org.eclipse.bpmn2.modeler.runtime.marklogic (NOT just ./marklogicworkflow)
 - Import this workspace
 - Double click on the 'plugin.xml' file
 - In the top right of the edit dialogue for this file, click the green Play button. This launches Eclipse Luna with this extension
+
+### Current published In Development version
+
+- In Eclipse Luna (4.4) or above, go to Help -> Install new software
+- In the update site field type https://raw.githubusercontent.com/adamfowleruk/marklogicworkflow/develop/eclipse/MarkLogicWorkflowUpdateSite
+- It will take a few seconds to download plugin information
+- Select the Eclipse BPMN2 Modeler - MarkLogic Workflow Runtime Extension Feature
+- Click Next
+- Follow the prompts
+ - NOTE: If you are warned about the project not being signed, click on 'OK' and NOT 'Cancel' to proceed with installation
+- Restart Eclipse Luna
+
+### Current published released version
+
+- As for Current published in development version, except use this URL: https://raw.githubusercontent.com/adamfowleruk/marklogicworkflow/master/eclipse/MarkLogicWorkflowUpdateSite
+
+## Creating a new Workflow process diagram
+
 - Now go to File - Import or File - New Project to create your new modelling project
 - Right click the root folder and select New - Other
 - Open the 'BPMN2' category and select either 'MarkLogic CPF Process Diagram' or 'MarkLogic Workflow Process Diagram'
@@ -52,10 +77,16 @@ In the future MarkLogic Workflow will allow any arbitrary CPF pipeline to be exp
 modeler. This will allow for full round trip re-engineering of MarkLogic CPF processes.
 
 *WARNING: It should be noted that CPF diagram support is very much an Alpha product and not scheduled to be fully
-implemented for a while.* 
+implemented for a while.*
 
 ## Related information
 
-For the custom runtime/task videos, see this first:-
+The best source for Eclipse extension tutorials is:-
+https://wiki.eclipse.org/BPMN2-Modeler/DeveloperTutorials
+
+These have been updated for the latest Luna version of the Eclipse BPMN2 modeler
+
+You may also find it instructive to download the 'jBPM Runtime Extension' project from the above project's GitHub site.
+ I use this for many examples.
 
-http://bobsbizbuzz.blogspot.it/2014/06/blog-post_10.html
+A developer forum is also available: https://www.eclipse.org/forums/index.php/f/226/

documentation/DEVELOPER.md

@@ -2,6 +2,6 @@ Here is the developer documentation
 
 - [Adding a new Activity type](DEV-NEWACTIVITY.md)
 - [Creating a custom step processor](DEV-STEPPROC.md)
-- [Integrating your app to MarkLogic Workflow](./RESTAPI.md)
+- [Integrating your app to MarkLogic Workflow](RESTAPI.md)
 
 Any issues contact me at [email protected]

documentation/MODELLING.md

@@ -16,6 +16,8 @@ The Eclipse BPMN2 modeller is a good option, with support for pluggable runtime
 easy to define a MarkLogic runtime and set of custom tasks, and hide any BPMN2 tasks that we do not support the
 execution of.
 
+To install the MarkLogic Workflow BPMN2 Eclipse modeler extension, see the [Modelling Development page](DEV-MODELER.md).
+
 Also view the [BPMN2 specification summary document](bpmn2-spec.md)
 
 Also take a look at the [Step documentation](STEPS.md) for information on individual steps and supported parameters.

documentation/RESTAPI.md

@@ -1,6 +1,6 @@
 
 
-See also MODELLING.md for the REST API to install a MarkLogic workflow process model.
+See also the [Modelling Overview](MODELLING.md) for the REST API to install a MarkLogic workflow process model.
 
 
 ## How the workflow engine works

documentation/SPRINTS.md

@@ -34,6 +34,8 @@ steps if a duplicate is found. Requires search (by property hash AND not (same u
 
 ## Sprint 1 - Basic workflow
 
+Completed Sat 18 Apr 2015 14:30 BST by Adam Fowler
+
 - DONE BPMN2: generic blank task
 - DONE BPMN2: user task -> aka human step
 - DONE BPMN2: exclusive gateway -> Decision point with one outcome, multiple options
@@ -50,8 +52,8 @@ steps if a duplicate is found. Requires search (by property hash AND not (same u
 - DONE Tools: Process Data model XSD (for modeler import)
 - DONE Tools: Eclipse BPMN 2 Modeler Palette and Process diagram support, including new diagram creation for MarkLogic
 - DEFERRED UI: Ridiculously basic HTML widget in MLJS for rendering step and choosing action (for ease of testing)
-- TEST Start process using an Alert (content subscription)
-- TEST REST API: Basic process initiation, update and tracking methods
+- DONE Start process using an Alert (content subscription)
+- DONE REST API: Basic process initiation, update and tracking methods
  - DONE processmodel.xqy
   - DONE PUT create and publish process model, accepting BPMN2 content type .bpmn2, and to update process model without publishing
   - DONE GET to fetch process model
@@ -60,8 +62,8 @@ steps if a duplicate is found. Requires search (by property hash AND not (same u
   - DONE PUT create instance of a process (starts a process)
   - DONE POST complete a human task
   - DONE GET fetch the current state of a business process
- - TEST processsubscription.xqy
-  - TEST PUT create a process subscription (alert) to create a new process instance (creating a content doc creates a process doc with an initiating attachment)
+ - DONE processsubscription.xqy
+  - DONE PUT create a process subscription (alert) to create a new process instance (creating a content doc creates a process doc with an initiating attachment)
  - DONE processinbox.xqy
  - DONE processqueue.xqy
  - TEST support for roles (processroleinbox.xqy) on user tasks (For BD)

documentation/USING-SUBSCRIPTIONS.md

@@ -21,8 +21,8 @@ The above is why I decided to have a process document that CPF runs against, rat
 ## How it works
 
 1. A user, or application, creates a new document in MarkLogic - say a Bank Account Opening E-form
-2. A 'Process Subscription' (basically a MarkLogic alert that uses the alert-action-process.xqy action) fires, creating a new Account Opening process document
-3. A CPF Domain (set up by enabling/publishing a MarkLogic Workflow BPMN2 model) fires for this document, invoking the Account Opening V1.2 CPF pipeline process
+2. A 'Process Subscription' (basically a MarkLogic alert that uses the alert-action-process.xqy action) fires, creating a new Account Opening process document, and attaching the account opening form as the InitiatingAttachment attachment
+3. A CPF Domain (set up by enabling/publishing a MarkLogic Workflow BPMN2 model) fires for this process document, invoking the Account Opening V1.2 CPF pipeline process
 4. CPF manages the state transitions and execution of BPMN2 CPF actions throughout the process lifecycle
 5. Process eventually completes (or fails), leaving the process document as an audit record of what happened, with metrics for performance analysis
 
@@ -39,13 +39,19 @@ Several reasons.
 ## Isn't it a bit convoluted?
 
 If you had to create all these things by hand, yes. This is why the Workflow REST API provides a single endpoint
-(POST /v1/resource/process) to take a BPMN2 model, create a set of CPF pipelines, and create a
+(POST /v1/resources/process) to take a BPMN2 model, create a set of CPF pipelines, and create a
 domain configuration, for you.
 
 All you then need to do then is separately configure one or more Alerts (aka Process Subscriptions) via calls to
-PUT /v1/resource/processsubscription to start the relevant workflow based on criteria about a new or updated document
+PUT /v1/resources/processsubscription to start the relevant workflow based on criteria about a new or updated document
 in marklogic.
 
-Alternatively, manually start a process via PUT /v1/resource/process without needing a Process Subscription. This is useful
+Alternatively, manually start a process via PUT /v1/resources/process without needing a Process Subscription. This is useful
 if starting a process via an ESB or application. A good example is starting a process to tell a person to create a
 new document that doesn't exist yet.
+
+## Examples
+
+For examples of how to configure and call the REST extensions for alerting, see the /shtests/ folder, specifically:-
+- Automated start: 25-payload.xml and 25-processsubscription-create.sh
+- Manual start: 06-payload.xml 06-process-create.sh

documentation/USING.md

@@ -7,4 +7,4 @@ This section of the documentation is very much a work in progress. See the [REST
 details right now.
 
 - [Creating a Process Subscription](USING-SUBSCRIPTIONS.md)
-- Starting a process without a content document
+- Starting a process without a content document - see the above link, last paragraph

modules/app/models/alert-action-process.xqy

@@ -21,13 +21,12 @@ declare variable $alert:action as element(alert:action) external;
 (: Create a process instance for this document :)
 
 (: Find appropriate process from alert action option :)
-let $procname := $alert-action/alert:options/wf:process-name/text()
-return
-  wfu:create($procname,$alert:doc/element(),
-    <attachment name="InitiatingAttachment" cardinality="1">
-      <uri>{fn:base-uri($alert:doc)}</uri>
-    </attachment>
+let $procname := xs:string($alert:action/alert:options/wf:process-name)
+let $pid :=   wfu:create($procname,$alert:doc/element(),
+      (<wf:attachment name="InitiatingAttachment" uri="{fn:base-uri($alert:doc)}" cardinality="1"/>)
   )
+return ()
+
 
 (:)
   xdmp:document-insert($procname || "/" || sem:uuid-string() || ".xml",