incubator-hise-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r.@apache.org
Subject svn commit: r982901 - in /incubator/hise/trunk/hise-docs/src/main/resources: administrative-operations.xml deadline.xml delegate.xml generic-human_role.xml task-properties.xml user-guide.xml
Date Fri, 06 Aug 2010 07:57:45 GMT
Author: rr
Date: Fri Aug  6 07:57:44 2010
New Revision: 982901

URL: http://svn.apache.org/viewvc?rev=982901&view=rev
Log:
HISE-65: Documentation (Thanks to Michał Więcław)

Added:
    incubator/hise/trunk/hise-docs/src/main/resources/administrative-operations.xml
    incubator/hise/trunk/hise-docs/src/main/resources/deadline.xml
    incubator/hise/trunk/hise-docs/src/main/resources/delegate.xml
    incubator/hise/trunk/hise-docs/src/main/resources/generic-human_role.xml
    incubator/hise/trunk/hise-docs/src/main/resources/task-properties.xml
Modified:
    incubator/hise/trunk/hise-docs/src/main/resources/user-guide.xml

Added: incubator/hise/trunk/hise-docs/src/main/resources/administrative-operations.xml
URL: http://svn.apache.org/viewvc/incubator/hise/trunk/hise-docs/src/main/resources/administrative-operations.xml?rev=982901&view=auto
==============================================================================
--- incubator/hise/trunk/hise-docs/src/main/resources/administrative-operations.xml (added)
+++ incubator/hise/trunk/hise-docs/src/main/resources/administrative-operations.xml Fri Aug
 6 07:57:44 2010
@@ -0,0 +1,81 @@
+<sect1>
+	<title>Administrative Operations</title>
+
+	<para>Collection of operations that can be performed only by business
+	administrators. These operations support task management.</para>
+
+<table frame="all">
+<tgroup cols="4">
+        <thead>
+          <row>
+			<entry>Operation name</entry>
+            <entry>Desription</entry>
+            <entry>Parameters</entry>
+            <entry>Authorization</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+          	<entry><literallayout>activate</literallayout></entry>
+          	<entry>Activates the task. Lets move from state CREATE to READY 
+			or RESERVED. Type of transition depends on the number of Potential owners. 
+			If there is only one then is set state RESERVED and the Potential owners 
+			becomes Actual owner.
+		</entry>
+          	<entry>
+          		In
+				<itemizedlist>
+					<listitem>task identifier</listitem>
+				</itemizedlist>
+				Out
+				<itemizedlist>
+					<listitem>void</listitem>
+				</itemizedlist>
+			</entry>
+          	<entry>Business Administrator</entry>
+          </row>
+          <row>
+         	<entry>nominate</entry>
+          	<entry>Nominate organization entity to process the task. When one person
is 
+			nominated then task status changes to RESERVE and the person becomes Actual Owner. if

+			nominated more persons or group of people then task status changes to REDY. Each nominated

+			organization entity should be added to Potential owners. This operation can be performed

+			when the task is in the state CREATED 
+		</entry>
+          	<entry>
+          		In
+          		<itemizedlist>
+          			<listitem>task identifier</listitem>
+				<listitem>organizational entity</listitem>
+          		</itemizedlist>
+          		Out
+          		<itemizedlist>
+          			<listitem>void</listitem>
+          		</itemizedlist>
+          	</entry>
+          	<entry>Business Administrator</entry>
+          </row>
+          <row>
+          	<entry>setGenericHumanRole</entry>
+          	<entry>Sets the organization entity on exactly one Generic Human Role. 
+			All other membership to   some Generic Human Role are removed
+		</entry>
+          	<entry>
+          		In
+          		<itemizedlist>
+          			<listitem>task identifier</listitem>
+          			<listitem>generic human role</listitem>
+				<listitem>organizational entity</listitem>
+          		</itemizedlist>
+          		Out
+          		<itemizedlist>
+          			<listitem>void</listitem>
+          		</itemizedlist>
+          	</entry>
+          	<entry>Business Administrator</entry>
+          </row>
+	</tbody>
+ </tgroup>
+
+</table>
+</sect1>

Added: incubator/hise/trunk/hise-docs/src/main/resources/deadline.xml
URL: http://svn.apache.org/viewvc/incubator/hise/trunk/hise-docs/src/main/resources/deadline.xml?rev=982901&view=auto
==============================================================================
--- incubator/hise/trunk/hise-docs/src/main/resources/deadline.xml (added)
+++ incubator/hise/trunk/hise-docs/src/main/resources/deadline.xml Fri Aug  6 07:57:44 2010
@@ -0,0 +1,163 @@
+  
+
+
+<sect1>
+	<title>Deadline</title>
+	
+	<para>Hise implements a deadline mechanism. Deadlines are defined inside task definitions
and contains some <link linkend='escalations'>escalation</link> action. There
are two types of deadlines:
+
+	  <itemizedlist>
+	    <listitem> 
+		<para><emphasis>Start deadline</emphasis> : Specifies the time until
the task must start. It is defined as either the period of time or the point in time until
the task must reach state inProgress. The time starts to be measured
+from the time at which the task enters the state Created. If the task does not
+reach state InProgress by the deadline an escalation action or a set of
+escalation actions is performed. Once the task is started, the deadline becomes
+obsolete and are removed.</para>
+	    </listitem>
+
+	    <listitem> 
+		<para><emphasis>Comletion deadline</emphasis> : Specifies the due time
of the task. It is defined as either the period of time until the task gets due or the point
in time when the task gets due. The time starts to be measured from the time at which the
task enters the state Created. If the task does not reach one of the final states (Completed,
Failed, Error, Exited, Obsolete) by the deadline an escalation action or a set of escalation
actions is performed.</para>
+	    </listitem>
+	  </itemizedlist>
+	<para>A task may have multiple start deadlines and completion deadlines associated
with it. When the task reaches a final state (Completed, Failed, Error, Exited, Obsolete)
all deadlines are deleted.
+	</para>
+	</para>
+	  Simple example ot the deadline implementation:
+	<para>
+	<programlisting>
+	   <![CDATA[
+		<htd:deadlines>
+	    	  
+		    <htd:startDeadline>*
+    		        <htd:documentation xml:lang="xsd:language"?>*
+      			    Text
+    		        </htd:documentation>
+    		
+			( <htd:for expressionLanguage="anyURI"?>
+        		      duration-expression
+			  </htd:for>
+			| <htd:until expressionLanguage="anyURI"?>
+			      deadline-expression
+ 			  </htd:until>
+			)
+    		
+			<htd:escalation name="NCName">*
+      				...
+			</htd:escalation>
+  
+		    </htd:startDeadline>
+  
+		    <htd:completionDeadline>
+			 ...
+		    </htd:completionDeadline>
+
+	      	</htd:deadlines>
+	   ]]>
+	</programlisting>
+	</para>
+
+	<sect2>
+	   <title id='escalations'>Escalations</title>
+
+	   <para>Escalations is a definition of actions to be executed if a task's status
is not reached within a certain time. An escalation must specify exactly one escalation action
( notification or reassignment). In one deadline could be defined many escalations. 
+		<programlisting>
+	  	 <![CDATA[
+			<htd:escalation name="NCName">*
+      				...
+			</htd:escalation>
+		]]>
+		</programlisting>
+The escalatino definition may contain:
+	       <itemizedlist>
+	          <listitem><link linkend='condition'>condition</link></listitem>

+		  <listitem><link linkend='notification'>notification</link></listitem>

+		  <listitem><link linkend='notification'>localNotification</link></listitem>

+		  <listitem><link linkend='reassignment'>reassignment</link></listitem>

+		  <listitem><link linkend='toParts'>toParts element</link></listitem>
+	       </itemizedlist>	
+	   </para>
+
+	<sect3>
+	   <title>Condition</title>
+		
+	   <para id='condition'>Condition is a element that allows (if evaluates to true)
perform escalation. If the condition is not fulfilled during the cause deadline, the escalation
is removed along with the deadline. Condition is an optional element.
+
+		<programlisting>
+	  	 <![CDATA[
+			<htd:condition expressionLanguage="anyURI"?>?
+  				boolean-expression
+			</htd:condition>
+		]]>
+		</programlisting>
+	   </para>
+	</sect3>
+	<sect3>	
+	   <title>Notifications</title>
+
+	   <para id='notification'>Notifications are used to inform people about the status
of the task. Notifications are explained in more detail in section “Notifications”.
Notification can be either referred to, or defined inline. A notifications imported from a
different namespace can be added by a localNotification element. A inlined notification is
defined by a notification element. Notifications used in escalations may use the same type
of input data as the surrounding task, or different type of data. If the same type of data
is used then the input message of the task is passed to the notification implicitly.
+If not, then the toPart elements are used to assign appropriate data to the notification.
+
+		<programlisting>
+	  	 <![CDATA[
+			<!-- notification specified by reference -->
+			<htd:localNotification reference="QName">?
+  			  <htd:priority expressionLanguage="anyURI"?>?
+    			  	integer-expression
+  			  </htd:priority>
+
+  			  <htd:peopleAssignments>?
+    			      <htd:recipients>
+      				...
+   			      </htd:recipients>
+ 			  </htd:peopleAssignments>
+			</htd:localNotification>
+            
+            		...
+            
+			<!-- notification specified inline -->
+			<htd:notification name="NCName">?
+  				...
+			</htd:notification>
+		]]>
+		</programlisting>
+	   </para>
+	</sect3>
+	<sect3>	
+	   <title>ToParts</title>
+	
+	   <para id='toParts'>ToParts is a element used when notifications in escalations
use different type of data then input date. Then the toPart elements are used to assign appropriate
data to the notification. If any of the toParts fails, the escalation action will not be performed
and the execution of the task is not affected.
+
+		<programlisting>
+	  	 <![CDATA[
+			<htd:toParts>?
+  			    <htd:toPart part="NCName" expressionLanguage="anyURI"?>
+    				expression
+  			    </htd:toPart>
+   				...
+			</htd:toParts>
+		]]>
+		</programlisting>
+	   </para>
+
+	</sect3>	
+	<sect3>	
+	   <title>Reassignments</title>
+	
+	   <para id='reassignment'>Reassignments are used to replace the potential owners
of a task when an escalation is triggered. The reassignment element is used to specify reassignment.
If present, the element must specify potential owners. In the case where several reassignment
escalations are triggered, the first
+reassignment (lexical order) will be considered for execution. The task is set to state
+Ready after reassignment.
+
+		<programlisting>
+	  	 <![CDATA[
+			<htd:reassignment>?
+  			    <htd:potentialOwners>
+     				...
+  			    </htd:potentialOwners>
+			</htd:reassignment>
+		]]>
+		</programlisting>
+	   </para>
+	</sect3>	
+	</sect2>
+
+  </sect1>

Added: incubator/hise/trunk/hise-docs/src/main/resources/delegate.xml
URL: http://svn.apache.org/viewvc/incubator/hise/trunk/hise-docs/src/main/resources/delegate.xml?rev=982901&view=auto
==============================================================================
--- incubator/hise/trunk/hise-docs/src/main/resources/delegate.xml (added)
+++ incubator/hise/trunk/hise-docs/src/main/resources/delegate.xml Fri Aug  6 07:57:44 2010
@@ -0,0 +1,48 @@
+<sect1>
+	<title>Delegation</title>
+	
+	<para>Delegation element is used to specify constraints concerning delegation of the
task. Attribute potentialDelegatees defines to whom the task may be delegated. The fallowing
values are allowded:
+
+	<itemizedlist>
+          <listitem>
+             anybody - It is allowed to delegate the task to anybody
+          </listitem>
+	  <listitem>
+             potentialOwners - It is allowed to delegate the task to potential owners previously
selected.
+          </listitem>
+	  <listitem>
+             nobody - It is not allowed to delegate the task.
+          </listitem>
+	  <listitem>
+             other - It is allowed to delegate the task to other people or group of people.
+          </listitem>
+	</itemizedlist>
+	</para>
+	
+	<para>
+	The delegation element is optional. If this element is not present the task is allowed 
+	to be delegated to anybody.
+	</para>
+
+	<para>
+	Simple example:
+	</para>
+	<programlisting>
+	  <![CDATA[
+	   <htd:delegation potentialDelegatees="other">
+ 		<htd:from>
+                    <htd:literal>
+                        <htd:organizationalEntity>
+                            <htd:groups>
+                                <htd:group>group4</htd:group>
+                            </htd:groups>
+                            <htd:users>
+                                <htd:user>user2</htd:user>
+                            </htd:users>
+                        </htd:organizationalEntity>
+                    </htd:literal>
+                </htd:from>
+            </htd:delegation>
+	  ]]>
+	</programlisting>
+</sect1>

Added: incubator/hise/trunk/hise-docs/src/main/resources/generic-human_role.xml
URL: http://svn.apache.org/viewvc/incubator/hise/trunk/hise-docs/src/main/resources/generic-human_role.xml?rev=982901&view=auto
==============================================================================
--- incubator/hise/trunk/hise-docs/src/main/resources/generic-human_role.xml (added)
+++ incubator/hise/trunk/hise-docs/src/main/resources/generic-human_role.xml Fri Aug  6 07:57:44
2010
@@ -0,0 +1,98 @@
+
+    <sect1>
+      <title>Generic Human Role</title>
+
+      <para>Generic human roles define what a person or group of people
+      resulting from a people query can do with tasks and notifications. The
+      aplication distinguish fallowing generic human roles: 
+	<itemizedlist>
+          <listitem>
+            <link linkend="taskInitiator">Task initiator</link>
+          </listitem>
+
+          <listitem>
+            <link linkend="taskStakeholders">Task stakeholders</link>
+          </listitem>
+
+          <listitem>
+            <link linkend="potentialOwners">Potential owners</link>
+          </listitem>
+
+          <listitem>
+            <link linkend="actualOner">Actual owner</link>
+          </listitem>
+
+          <listitem>
+            <link linkend="businessAdministrators">Business
+            administrators</link>
+          </listitem>
+
+          <listitem>
+            <link linkend="excludedOwners">Excluded owners </link>
+          </listitem>
+
+          <listitem>
+            <link linkend="recipients">Recipients</link>
+          </listitem>
+
+          <listitem>
+            <link linkend="potentialDelegatees">Potential delegatees</link>
+          </listitem>
+        </itemizedlist> </para>
+
+      <para id="taskInitiator"><emphasis>Task initiator</emphasis> is the
+      person who creates the task instance. Depending on how the task has been
+      instantiated the task initiator may or may not be defined. If task
+      initiator is defined it is exactly one person.</para>
+
+      <para id="taskStakeholders"><emphasis>Task stakeholders</emphasis>
are
+      the people ultimately responsible for the oversight and outcome of the
+      task instance. A task stakeholder can influence the progress of a task,
+      for example, by adding ad-hoc attachments, forwarding the task, or
+      simply observing the state changes of the task. It is also allowed to
+      perform administrative actions on the task instance and associated
+      notifications, such as resolving missed deadlines. Compliant
+      implementations MUST ensure that at least one person is associated with
+      this role at runtime.</para>
+
+      <para id="potentialOwners"><emphasis>Potential owners</emphasis>
of a
+      task are persons who receive the task so that they can claim and
+      complete it. A potential owner becomes the actual owner of a task by
+      explicitly claiming it. Before the task has been claimed, potential
+      owners can influence the progress of the task, for example by changing
+      the priority of the task, adding ad-hoc attachments or comments. All
+      excluded owners are implicitly removed from the set of potential
+      owners.</para>
+
+      <para id="actualOner"><emphasis>Actual owner</emphasis> is the person
+      actually performing the task. A task has exactly one actual owner. When
+      task is performed, the actual owner can execute actions, such as
+      revoking the claim, forwarding the task, suspending and resuming the
+      task execution or changing the priority of the task.</para>
+
+      <para id="businessAdministrators">Buisness administrators are the people
+      who can play the same role as task stakeholders but at task type level.
+      Therefore, business administrators can perform the exact same operations
+      as task stakeholders. Business administrators may also observe the
+      progress of notifications. Compliant implementations MUST ensure that at
+      runtime at least one person is associated with this role.</para>
+
+      <para id="excludedOwners"><emphasis>Excluded owners</emphasis> may
not
+      become an actual or potential owner and thus they may not reserve or
+      start the task. They can only doing statistic or information
+      operations.</para>
+
+      <para id="recipients"><emphasis>Recipients</emphasis> are persons
who
+      receive the notification, such as happens when a deadline is missed or
+      when a milestone is reached. This role is similar to the roles potential
+      owners and actual owner but has different repercussions because a
+      notification recipient does not have to perform any action and hence it
+      is more of informational nature than participation. A notification has
+      one or more recipients.</para>
+
+      <para id="potentialDelegatees"><emphasis>Potential delegatees</emphasis>
+      are persons or group peopels who can be delegate to perform the task.
+      Potential delegatees are indication durning creation task by the task
+      initiator. </para>
+    </sect1>
+

Added: incubator/hise/trunk/hise-docs/src/main/resources/task-properties.xml
URL: http://svn.apache.org/viewvc/incubator/hise/trunk/hise-docs/src/main/resources/task-properties.xml?rev=982901&view=auto
==============================================================================
--- incubator/hise/trunk/hise-docs/src/main/resources/task-properties.xml (added)
+++ incubator/hise/trunk/hise-docs/src/main/resources/task-properties.xml Fri Aug  6 07:57:44
2010
@@ -0,0 +1,23 @@
+<sect1>
+	<title>Task Properties</title>
+	
+	<para>The fallowing basic attributs are defined for tasks:
+
+	<itemizedlist>
+          <listitem>
+             <para>name - This attribute is mandatory. It is used to specity the name
of the task. 
+		The name, combined with namespace create a unique identifier the task definition.</para>
+          </listitem>
+	  <listitem>
+             <para>priority - This element is used to specify the priority of the task.
It is an
+		optional element which value is an integer expression. If not present, the priority of
the 			task is set to 0 what is the highest priority. Larger numbers identify lower priorites.</para>
+          </listitem>
+	  <listitem>
+             <para>autoActivate - This element allows enable automatic activation task
(if it is possible) 			immediately after it is creation. It is binary type and optional. If
not present the default 			value is false </para>
+          </listitem>
+	  <listitem>
+             <para>isSkipable - This element is used to determines whether a task can
actuall be skipped at 			runtime. It is binary type and optional. If not present the default
value is true. </para>
+          </listitem>
+	</itemizedlist>
+	</para>
+</sect1>

Modified: incubator/hise/trunk/hise-docs/src/main/resources/user-guide.xml
URL: http://svn.apache.org/viewvc/incubator/hise/trunk/hise-docs/src/main/resources/user-guide.xml?rev=982901&r1=982900&r2=982901&view=diff
==============================================================================
--- incubator/hise/trunk/hise-docs/src/main/resources/user-guide.xml (original)
+++ incubator/hise/trunk/hise-docs/src/main/resources/user-guide.xml Fri Aug  6 07:57:44 2010
@@ -13,6 +13,11 @@
 <!ENTITY intro SYSTEM "intro.xml">
 <!ENTITY states SYSTEM "states.xml">
 <!ENTITY taskInfoExample SYSTEM "taskInfoExample.xml">
+<!ENTITY deadline SYSTEM "deadline.xml">
+<!ENTITY delegate SYSTEM "delegate.xml">
+<!ENTITY administrative-operations SYSTEM "administrative-operations.xml">
+<!ENTITY generic-human_role SYSTEM "generic-human_role.xml">
+<!ENTITY task-properties SYSTEM "task-properties.xml">
 
 ]>
 
@@ -173,10 +178,17 @@ xsi:schemaLocation="http://docbook.org/n
   <title>Concepts</title>
   &intro;
   &taskInstanceData;
+  &generic-human_role;
+  </chapter>
+  <chapter id="task_properties">
+  <title>Task properties</title>
+	&task-properties;
   </chapter>
   <chapter id="task_features">
   <title>Task features</title>
     &states;
+    &deadline;
+    &delegate;
     &comments;
 	&rendering;
 	&attachments;
@@ -210,10 +222,11 @@ authorized to perform the operation. Sta
 explicitly. They have the same authorization rights as business administrators.
   </para>
 	&participant_operations;
-
+	
 	
 	
   </sect1>
+	&administrative-operations;
 	&simpleQuery;
   &all_rest_participant_operations;
   </chapter>



Mime
View raw message