Usually, a question contains part of the answer :)

We currently have example of shark used from JSP application, Swing application and through CORBA (shark is used from CORBA wrappers that implement CORBA interface, and clients access the server through this CORBA interface).

Shark should be able to work in any environment, like in EJB container, but you need to write some wrappers around shark (as CORBA server did). However, Admin is not the part of engine, but a client application showing the engine capabilities. We have two kind of admin applications - one using shark directly (this is example of using shark from Swing application), and other CORBA Admin communicating with Shark CORBA server.

You can perform various queries on shark by using its standard OMG client interface. I.e. you can search for the process instances for a definition whose state is closed, you can search for all activities from a process instance that are in state "open.running", ...

You can read OMG spec. It defines possible queries, and we extend the possibilities a little by including queries by definition Ids.

If you are using local admin application (started by runSA script), for the first time you can log-on as you like (i.e. username=shark, pwd=s), but when you are again logging in shark, you must enter the same password. If you are using CORBA admin application, you have to log-on fist time as [admin,enhydra].

The SharkSwingClient does not need server - it is a swing application using shark as a library. The similar application can be found in SharkJSPClient module - it also uses shark as a library. On the other side, in module SharkCORBA\Client you can find CORBA client that needs Shark CORBA server.

Shark CORBA server is a wrapper around shark interfaces (it also uses shark as a library), and implements its own CORBA interfaces (which are similar to Shark POJO interfaces) which are provided to CORBA clients to access it.

Yes, thanks to these three-level object design, shark is very flexible and configurable:

* Wrapper objects are protecting core shark kernel objects from a client - client never gets the shark memory, just a wrappersaround in-memory objects. Thanks to them, shark can also use so called "External transactions" (the ones that can be used inexternal client app and in shark), they will also serve when we define security API to prevent some users of doing unallowed stuff,...

* Impl objects are the core of the shark's kernel, and they are actually doing the job

* In persistence layer, Activity, Process, ... objects are used for storing runtime information into DB (kernel sets/gets theruntime information to/from DB by the use of these objects)for each type of objects (wrapper, impl and instancepersistenct) there are defined interfaces, and shark can be easily configured touse one or another implementation of wrappers, impl, instpers. ...

One is the CORBA interace and the other is the POJO interface. So one is for a client/server application and the other is for an embedded workflow engine.

The shark engine (library) itself has a client API, that is placed in SharkAPI module (org.enhydra.shark.api.* and org.enhydra.shark.api.client.*). You can look at to see shark architecture. Clicking on the boxes, you get an Java documentation of shark APIs, and implementations. In shark project, there are two deployments of shark that make shark a server. The first is CORBA deployment, and when accessing shark CORBAserver (which is a wrapper around shark engine) from client side, you should use this API Recently, shark also can be deployed as a SOAP service, and there is an ASAP(Wf-XML) API.

Usually you need to build the webapp serving the client browser by yourself (or somebody else). When coding this webapp you usually encapsulate the workflow engine with your webapp, meaning that your clients don't see anything that looks like "shark". I bet they will be lucky if you do so, because shark is a workflow ENGINE, not a wonderful presentation layer with golden sparks all over. The jsp client shows the admin interface, but this is for professional users only.so what you webapp will do is start a shark engine. This engine may share the same database with many other shark instances (e.g. the swing client, or the jsp client). Of course, every toolagent or process will run in the shark instance that's currenlty using this process or toolagent. For us humans it looks like shark "processes" a workflow, but what one instance does is changing a lot of database values and call tool-agents if needed. so a "running" process is just a database entry of a process marked "running". And as a result, all other sharks using the same database can perform any action as long as a user (or application) requested it for this instance. If you want to happen a specific action on a specific server (e.g. because this server is the only one that has connection to a special service) you could write a tool-agent connecting to this server (e.g. using RMI or EJB's,or CORBA). Or you use the corba api and connect to a running shark instance (see the corba client for details).

Subflow activities are automatically executed by shark, and client app can't control this. Also, when you define a subflow activity in XPDL, you have to provide the actual parameters for the formal parameters of the underlying process. Recently, we introduced so called "remote" subflow activities, which will may be used along with newly defined Wf-XML internal API for the remote process calls. Such subflow activities, won't have formal parameters, but only actual ones, because the actual definition of the underlying process is on some other system. However,this doesn't solve your problem.I think you need to redesign your XPDL, or maybe to make your toolagent(s) that will be used to instantiate processes from other definitions.

Yes, shark implemented WAPI, but through OMG object model . It is the core interface for running shark. However, we extended OMG model to provide lot of other features that could be used through Shark's ExecutionAdministration, SharkConnection, AdminMisc, ... APIs.

Standard implementation is useful in particular use cases when you use shark's UserGroup API along with ParticipantMapping API.HistoryRelated impl. extends standard implementation, and calculates assignments based on ext. attribs. I.e. you can set thatperformer that once executed some activity must execute such activity again if it comes again for execution in this particularprocess instance - if there is a loop in the process definition. Also, you can set that the performer of the activity has to be theone that actually performed some other activity in the process.XPDLStratight .... impl. determines the performer directly by the Id of Participant in XPDL. Also, using this last impl. you can setin XPDL that the performer of activity is some expression that will be evaluated at runtime (depending on process variables).It really depends on people's use cases which assignment manager they will use. Maybe your use case is such that you should writteyour own assignment manager impl. that will use the data provided in the assignment manager method call, and determing theassignments based on the info in your own UserGroup Database.

SharkTransaction is an API, and you can provide its implementation. However, than you have to provide an implementation ofTransactionManager API, and of persistence layers that will use such transaction (Inst. persistence and event audit persistence ifyou configure shark to use event audits).Last year, Vladislav Pernin from OpenWide provided Hibernate implementation of SharkTransaction and all relevant APIs, and it is inshark sources although it is not compiled (the work was not finished, and had bugs that prevented shark to work properly; he had notime to finish this work, and we either didn't, nor we maintained the code; maybe one day we'll finish this work). Also, AndyZeneski from OfBiz implemented all relevant APIs that he needed for his project, and he successfully integrated shark beta2 intoOfBiz. I think he will continue his work with new shark version. However, these implementations are not included in the shark.If you use our persistence layers and our implementation of transaction, than you need to use DODS to perform the manipulation onyour data, and than you can do the shark work and DB manipulation work in a same transaction. Otherwise, you need to separate thetransactions, and to cause shark transaction to rollback if your DB manipulation transaction fails.

You also have a Swing Admin that uses shark as a library (not through CORBA interfaces). Your approach is also possible. You canhave many shark VMs at a same time working on the same DB. In this case, you need to turn-off the caching so they can work in such cluster.

New shark requires that you define XPDL Script element (i.e. if your expressions are written using JavaScript syntax, you should have in your XPDL defined <Script Type="text/javascript"/>). You can look at the examples comming with shark about how they define this XPDL element.

If you read the JavaDoc for SharkConnection interface, you'll see that pDefId represents the Id of process definition inside the package with given pkgId, for which you want to instantiate the process. I.e., XPDL could look something like:

<Package Id="test" ....>
.....
.....
.....
    <WorkflowProcess Id="proc1" ...>
.....
.....
    </WorkflowProcess>
.....
....
....
</Package>
     

and if you call SharkConnection.createProcess("test","proc1") the instance of this process will be created (of course, the package had to be loaded into shark previously).

Shark doesn't provide such feature - you have to parse XPDL to find out next possible activities.

Shark has possibility of package versioning. When you load some package into shark, it automatically gets a version, and then you can update this package, and after that you'll have (from client's point of view) two packages with the same Id but different version. However, shark internally handles this packages as the packages with a different Ids (Id is created as combination of XPDL defined package Id and automatically generated package version).Shark uses a code for opening packages (xpdlManager.openPackage()) several times in order to validate package and its external packages, and only if they are valid to load it into memory.

If you know the Id of the XPDL file, you can do the following using ExecutionAdministration interface (after calling connect method):

   WfProcessMgrIterator pmi=ea.get_iterator_processmgr(); // ea is ExecutionAdministration
   String query="packageId.equals(\""+pkgId+"\")";
   pmi.set_query_expression(query);
   WfProcessMgr[] mgrs=pmi.get_next_n_sequence(0);
					

WfProcessMgr objects correspond to WorkflowProcess definitions from XPDL. You can further use WfProcessMgr to instantiate the process instance. You can also get the WorkflowProcess definition Id or Name attribute using AdminMisc.getProcessMgrProcDefId(mgrname) and AdminMisc.getProcessMgrProcDefName(mgrname), where mgrname can be retrieved using WfProcessMgr.name()

There are no longer stored procedures, but now we use ToolAgent concept (you can read about it in docs). You can find a JavaClassToolAgent which acts similar like previous "storedprocedures".

Standard shark distribution comes with a ToolAgent called RuntimeApplicationToolAgent. It is supposed to execute system application (under Windows .exe application), and it can do it synchroniously (by waiting for application to finish, and then finishing activity), or asynchroniously (by starting application and finishing the activity). RuntimeApplication tool agent assumes that the application is on your system path, or that you've given the full path to application when performing its mapping (or in its extended attributes). In our test-JavaScript.xpdl example, you can see that we have defined a Package level Application called notepad. If in an existing process you add activity whose tool is a notepad application, the Windows notepad will be started when this activity comes to execution. Similar to that, you can specify an XPDL Application definition and map it (or specify its extended attributes) to some VB, VC,Delphi, ... .exe file. Of course, you must be aware that these applications will be started on the machine where the shark is running.

The ToolAgent can be started when starting AUTOMATIC "Tool" activity (with Start/Finished modes set to AUTOMATIC), or when finishing Tool activity, whose Start mode is MANUAL (you can define Tool activity with Start mode MANUAL, and Finish mode AUTOMATIC, and in that case, this activity will appear in your worklist, and when you complete it, the Tool defined will be executed by ToolAgent). There are no other possibilities to start ToolAgent in shark.

I think that you are missing a point. You can write anything you like in JaWE - it is XPDL editor, and it does not restrict you at this point, but it is a problem what particular engine supports. I.e., shark supports a following kind of expressions: JavaScript expressions, BeanShell expressions (pure Java expressions) and Python expressions. To use i.e. JavaScript expression, your XPDL must have Script element value defined to be "text/javascript". Shark can handle (through the use of appropriate script interpreters) all of the expressions you've written.

Tool agents may be executed only by the shark, and not by the client applications that use shark (there is no client interface forToolAgents). Note that when you use shark as a library (not through the CORBA), you are using it in the VM of your clientapplication.

Tool agents always get the copy of process context. If your POJO is Clonable, than it is cloned, and if it is not Clonable, it is being Serialized/Deserialized to get its copy (of course, process variables must be Serializable).

XPDL doesn't provide means to define which variables are specific for an activity, so Shark passes all variables from instance to all its activities.

We use some extended attributes, but these extensions are specific for our example applications - Shark kernel doesn't use any extended attribute from XPDL. For instance: in process definition: "specrelease" from test-JavaScript.xpdl activity test has extended attribute VariableToProcess_UPDATE with value status, signaling our application that this variable may be updated. This way *admin-application* "knows"to offer status variable for update.

IShark won't remove the packages for which there are process instances in DB (and by standard configuration, finished processes are not removed from DB), and if there are dependences on the package from some other package (External packages XPDL concept). If you want to be able to unload packages, you can do it in two ways:

Shark can't actually use files and move it around file system, but shark can use complex variables (Java classes). I.e., you can define any Java object to be a workflow variable (through the use of XPDL ExternalReference data type), and then use it in shark (of course, this class has to be on shark's classpath). This is how you can store a file (you can have XPDL type that represents your file).

Currently, shark has LimitAgent interface and two implementations (one contributed by Andy Zeneski) that checks process/activity limits, and this simple implementations only log to console if limit is exceeded. One could write its own implementation that could do something more useful.

Yes, several instances can be instantiated based on the same activity definition, and this can also be in the same process instance if you have loop defined. However, there can't be two activity instances (for the same definition) that both have "open" state in the same process instance at the same time.

Shark will complete activity automatically only if it is Automatic activity (in XPDL definition these are: Route, SubFlow, Block and Tool activity with Automatic start and finish mode), and if it is manual activity (in XPDL definition this is No implementation activity) or partially manual activity (Tool activity with Manual start and Automatic finish mode), the client has to call WfActivity.complete() method to finish it, and after that shark will create the next activity instance, and so on...

For typical shark use, you do not need to use methods with Transaction parameter. The methods with Transaction as a parameter are supposed to be used for executing several shark operations in a same transaction, by calling all of them with an "external" transaction. You can look at discussion at mailing list to see how to do that.

To understand WfRequester concept, please read OMG specification, and search our mail archive - there are several discussions on WfRequester.

You can see in documentation (doc\shark\shark.html) or in default Shark.conf file comments about the entry called:

     SharkKernel.UnsatisfiedSplitConditionsHandling
  

Using this configuration parameter, you can configure shark kernel how to act in such cases. The possibilities are to ignore it (to stay hanging here), to finish process if possible (if there are no other branches with active activities), and to rollback. The last option is the one you need, so you just have to set this parameter to value ROLLBACK.

When the process is instantiated, the first activity will be created. If it is the manual activity, shark will stop here, and wait for client application interaction. If the first activity is automatic, it will be executed and the next activity will be created. Generally, when the process starts, or when the client application signals that manual activity is finished, shark will start all activities that come next, and execute the automatic ones until it comes to the next manual activity.

The assignment Id does not exist in OMG spec. To get a worklist, you just have to call the method getResourceObject() of SharkConnection, and then call method get_sequence_work_item(0) on the WfResource object you get. This method will give you the array of WfAssignment objects. If you want to get the activity of an assignment, you can call method WfAssignment.activity(), and if you want to get the process of assignment's activity, you can do WfAssignment.activity().container(). The activity/process Ids are retrieved by calling key() method on WfActivity/WfProcess. Please look at our ManualTest.java example (in modules\SharkTests\src).

Well, these methods are specified by OMG spec, and we have implemented it. An example for getting the maximum value could be getting first 10 assignments, and then when they are executed, another 10, ... but I don't know how much could it be useful.

You can find who accepted an activity by AdminMisc.getActivityResourceUsername(procId,actId). If null is returned, it means that the activity is not accepted. We do not have an interface to tell you when did it happen. We could easily implement this interface (we'll put it on our TODO list), and meanwhile, you could find it out through event audits (take all WfAssignmentEventAudits for activity, find the last one, and check if is_accepted() returns true, and then extract the username by the use of new_resource_key() method).

Out of the CVS-040416, there have been changes to this methods. WfActivity.set_process_context() is used to update activity variables, but only variables set by WfActivity.set_result() will be updated back to the process (this is how OMG spec. proposes).

Here it is...

String type = WorkflowUtilities.getTypeKeyOfAnyObject (globalContext [i].the_value);
Object val = WorkflowUtilities.exstractValueOfAnyObject (globalContext [j].the_value, type);
      

In OMG docs, it says that it is up to engine how will it implement this operations.In shark, terminating and aborting process is the same.On the other hand, when you terminate activity, process tries to follow to the next activity(s), and if you abort it it doesn't.

There is no easy way to get the list of process insances that are instantiated based on process definitions from some package, but there is what you need to do:

It is the problem of improper shark configuration - you didn't setup DODS LockMaster properly.If you read the comments in Shark.conf file, you'll find that entry:DODSLockMaster.Timeoutdetermines how long to wait for a locked process. If this value is set to -1, it means wait forever, and this is probably your case.Also, there is another entry called:DODSLockMaster.LockWaitTimewhich determines how often will shark instance try to acquire a lock until DodsLockMaster.Timeout period has passed.If you setup DODSLockMaster.Timeout time to some positive value (let say 1000), you'll get an exception message from shark if itdoes not suceed to acquire a lock on some process during this time.

Yes. You can set a limit (both on process and activity), and you'll be informed if it expires. Additionally XPDL specification defines deadlines, which are implementedtoo.See (for limit example): test-JavaScript.xpdl or test-BeanShell.xpdl. For deadlines: deadlineexamples.xpdl.

Make an implementation of org.enhydra.shark.api.internal.eventaudit.EventAuditManagerInterface Default implementation only stores events into database, but thiscomponent IMHO fits nicely into your needs. Method public void persist(AssignmentEventAuditPersistenceInterface assea, SharkTransaction ti) throwsEventAuditException; gets called for each new assignment created.

If you look at shark's code in PackageAdmin or at SharkAdmin's JaWE's code in EngineTreeModel, you will see that we never call xm.parseDocument(content, false); but instead of this method, we are calling method public Package openPackage(String pkgReference, boolean openFromStream). You CAN'T call parseDocument method directly, because there are a lot of things that are done in its caller method(s) that prepare XPDL objects. To properly do things, you should do following:

Here is explanation how can you find out which asynchronous sub-processes are started from the main process:

Regarding second part of the question, I'm afraid that you have to find a way to model your XPDL in a right way and to make your client application to set some variable in the main process when asynchronous sub-processes are finished, and use that variable in transition condition to allow finishing of the main process. This is something that can't be automatically handled by shark, because shark immediatelly finishes subflow activities after instantiating their asynchronous process, and proceeds to the next XPDL activity.

You can do it in several ways:

You have to use: NameValue.the_value.insert_Value(val); The only requirement is that the "val" is instance of a class that implements Serializable interface (and java.util.LinkedList is such class). You can also provide your custom class object as a WRD, but than both, server and client has to have it in their classpath.

If you start the shark admin (look at quick start documentation), and try to execute some tasks from the worklist, you can see that you need to accept activity first, and than to complete it, and this is exactly what you need.When activity is created, several assignments to a different users can be created. Each of them can accept activity, and when (s)he does, the other user's assignments become invalid, and they can't accept it or complete an activity. If after some time the user that accepted activity rejects it,the previous user assignments again become valid, and any of them can accept it.

You need to call "process_context" method on WfProcess instance to get the whole process context Map. The map keys are variable Ids, and map values are variable values. So, if you i.e. need to get the value of variable "status" which type is String, you can do following:

   Map m=proc.process_context();
   String status=(String)m.get("status");
				     

If you use CORBA API, you get the array of NameValue objects.You should iterate through this array, and check for the name of the variable, and get its value, i.e. the same example for that case would be (look at our CORBA client to find out more):

   String val=null;
   for (int i=0; i<nv.length; i++) {
      NameValue nv=nv[i];
      String name=nv.the_name;
      if (name.equals("status")) {
         val=name.the_value.extract_wstring();
         break;
      }
   }
		     

To find out which activity(s) are active, you have a method on WfProcess object called get_activities_in_state(). It gives you in iterator on all activiites in which state is the one you provided to the method call, i.e.

   WfActivityIterator ai=proc.get_activities_in_state("open.running");
   WfActivity[] acts=ai.get_next_n_sequence(0);
					

gives you all the manual activities that are "accepted" and all the subflow activities that are running (and in the case you defined automatic activity to have manual end it also gives you all the Tool activities that are still running). If you use "open.not_running.not_started", you will get all Manual activities that are still not "accepted".

Through the usage of shark interface, you can get all activity instances that have ever been created, and that belong to some process instance, or the activity instances that are assigned to a certain user. However, you can't get an activity definitions for some WorkflowProcess definition using API (you can do it by the usage of JaWE or shark's XPDL module, but it's another story). Generally, you need to do the similar that our Admin application(s) does. It shows the process definition for selected process instance (using JaWE), and marks the currently active activities in this instance.

You can model your activity to have a deadline set to 30 minutes after work is assigned to a user. When you model deadline, you have to model an exception transition that will lead to the next activity, which is in your case automatic activity that will send a mail to the user after deadline happens. If this is asynchronous deadline, the user's activity won't be terminated, and if it is synchronous one, it will be terminated. You can read howto and look at deadlineexamples.xpdl comming with shark to see how to use deadlines. Of course, you must have a scheduler that will use shark's DeadlineAdministration interface and will call appropriate method i.e.every 15 minutes. (Our Admin application comes with such scheduler, and you can either directly call a method for checking deadlines, or setup admin application to automatically check for deadlines).Also, as already suggested on the list said, you can use Limits to notify user, but than you must provide your own LimitAgent implementation thatwill send mails.

Do you want anybody in s particular role to pick up the activity, or do you know who's going to be your participants? If it's the latter then you can create a workflow relevant data, map it (set it) to the particular userid and then set this as the performer for that activity. For example,

   <Activity Id="doAlert_enterData" Name="Enter Data">
      <Implementation>
         <No/>
      </Implementation>
      <Performer>myParticipant;</Performer>
      <StartMode>
         <Automatic/>
      </StartMode>
      <FinishMode>
         <Automatic/>
      </FinishMode>
     <!-- other activity definition -->
   </Activity>
							       

If using JaWE, put "myParticipant;" in the participant field in the activity's properties. Also, make sure that the following is uncommented from the Shark.conf file:

   AssignmentManagerClassName=org.enhydra.shark.assignment.XPDLStraightParticipantMappingAssignmentManagerThen
		     

when you assign a userid to the myParticipant WRD, that activity will be assigned to that user. Here is the code:

   Map context = new HashMap();context.put("myParticipant", "john");
   WfProcess proc = sc.createProcess(<pkgId>, <defId>);
   //change to suit your needs.
   proc.set_process_context(context);
   proc.start();
			

Since we see that there are many use cases where one wants to use process context in (re)evaluating activity Deadlines (your and BenAnderson's use case), and we think it is useful, we'll provide configuration parameter for shark kernel. This parameter will tell kernel to use activity or process context while re-evaluating deadlines, and it'll be included the next CVS update.In current version, you can setup shark to re-evaluate deadlines or not (in latter case, it evaluates deadlines ones when the activity is created, and stores the information in DB). When the deadline re-evaluation happens, shark uses activity context variables, so currently if you change activity context before second deadline re-evaluation happens, it should reflect the calculation of deadline limit time.If you use circular transition, every time the new instance of activity is created.

The extended attributes "VariableToProcess_X" are used to indicate which workflow data should be changed in all examples. From these values within an activity, the gui knows which workflow data should be updated (VariableToProcess_UPDATE) or presented to the user for review (VariableToProcess_VIEW). This is not standard shark behaviour, it's just the way the guys from shark implemented it in their examples and in the gui. If i don't use these "Variable...." (by the way you can name it whatever you want in your app), then i need to know what to change by programming (hard-wiring) it in my code that uses and changes these activities. Using these extended attributes one can define within the activity definition what should be changed or presented, and the code just reads these extended attributes and prompts the user for review and/or new values.

The instance in the resource table is created just when needed. So, you could have a thousand users in UserTable, but none in ResourceTable. This is because shark is very configurable, and it can work without UserGroup API at all. I.e., if you turn-off UserGroup API and Authentication API, you will always be able to log-on using username and password as you like, and shark will create an instance in ResourceTable at this time. Also, you can work without MappingAPI, so each activity will be assigned to the resource that created its process.

Now...

This is just a guess...

But that might be something about a query taking longer to execute than the the maximum time expected for execution. I wonder if that is in any way related to the conf setting that looks like this: DatabaseManager.defaults.maxExecuteTime=200

This column is introduced in this table and in some other tables where there is no column (or combination of two columns) that can represent the primary key. This is created in order to use the same data model with other O/RM tools than DODS (or at least to make obvious that there is no natural primary key in this specific table). When using DODS, in each table, we have additional column called OId that is always used as a primary key.