History of GalaxiaTutorial
Version 35 | Current version | |||
---|---|---|---|---|
Workflow refers to procedures for processing documents, such as requiring an editor to review and approve a story.
Introductionbitweaver, has inherited a Workflow Engine from TikiWiki called Galaxia. This engine is quite powerful and easy to use once the basic concepts have been mastered. Rather than give you all the concepts now, I will introduce them throughout the tutorial to help understand their use and context in the scheme of workflow generation.Ensure Workflow is enabled on your website. If you have the permissions, you can visit Administration / Administer Packages / Features and check the Workflow feature. Click Change Preferences to save your change. If you have the permissions, you can visit Administration / Kernel / Packages and check the Galaxia package. Click Activate Tiki Packages to save your change. Admin ProcessesThe first part of creating a workflow is to create a Process. A process is usually the objective of the workflow. A process is defined as a set of activities that must be done to achieve some goal. Business circuits are mapped to processes to automate them. Be careful not to confuse a specific Activity with the Process. Some example Processes are:
To create our Test Process, open the Workflow / Admin Processes section of bitweaver. You notice at the top of the page are 4 icons.
In Process Name, enter the title of your process. As an example, we will do Hello World Process. Optionally in the Description, enter a short description about the process. Is active? indicates that the process is available for users. Leave this unchecked, as nothing will work while the process is blank. Now click Create. Just below the Create button are Browse and Upload buttons. Later in the tutorial, we will export our process to an XML file which can be later uploaded here or used on other bitweaver installations. To use, just Browse to your XML Process file and click Upload to create the process. Once you've created or uploaded your new process, you'll find it listed at the bottom of the Admin Processess page. Adjust the Find filter to find your process, if there are a lot of processes in the list - and click Filter to search. Our Hello World Process should appear in the list. The checkbox at the beginning is used if you wish to delete the process. Just check the checkbox and press the Delete button. If you do this now, be sure to recreate the process as shown above. Next is the process name. Click on the process name and you'll find the details are entered in the form above to allow editing of the title or description. Also note the icons have changed as well as the errors shown below This process is invalid:. Don't worry about these for now, as we will get to them later in the tutorial. Click Update to save changes. Next column is the Version. As you improve on your processes, you can create new versions to work on while leaving existing users on the previous stable version. Once you are convinced that the updated version is suitable for public use, you can make it the default process. All existing user instances of the previous version will continue to completion and not be affected by the new version. This ensures that your workflow functions correctly during upgrades. Active indicates if the process is free from errors and available for public use. Valid is a green or red circle indicating whether the process can be activated or not. This is dependent on whether it has any errors - mentioned above. Lastly, the Action icons are shortcuts to administer the process's activities, instances and other components. These are:
Click on the first Action icon - activities . Admin ActivitiesActivities are actions that are performed during your process. A process can consist of many activities. By default, a start and end activity are created for you, but these can be renamed or deleted at a later stage. I'll define two other terms so you can understand their context later.An instance is a particular process currently being executed. An activity can have many instances associated with it at any time. An instance is created when a process is initiated by a user and the instance will pass through the process activities until the process is terminated or completed. A transition is the path between two or more activities. A transition defines what has to be done after each activity is completed. Activities are broken up into different types. Here are two types listed below:
You can see on our Admin process activities page, at the top is the shortcut bar, similar to the previous page. Below that you will see errors shown below This process is invalid:. We will review these later. In the Add or edit an activity form, you are able to add new activities or by clicking on the names of existing activities, edit their properties. Apart from Name and Description, there is a Type drop down. From here, you are able to select different activity types as was shown above. Next there are two check boxes. Interactive: - Activities can be programmed or user interactive. Interactive activities are activities requiring some kind of interaction with the user and these activities usually present a form asking the user to fill information. After the information is submitted, the instance is ready to move on to the next activity. Automatic activities in contrast are executed automatically without any user interaction. Data manipulation and programming is the most common use of an automatic activity. Auto-Routed: - When an activitiy is completed, the instance may or may not automatically route to the next activity in the process. Activities with the Auto-Routing setting activated automatically route the instance to the next process activity on completion. If the activity is not Auto-Routing, the user must send the activity to let the process continue. This can be used in activities where the user can edit information and review it many times before deciding that the activity is completed. Next, there are two boxes in the section Add transitions. These two boxes allow you to highlight, what previous activities lead to the current activity and what activities can be reached from the current activity. At the bottom of the Add or edit an activity form, there are the roles associated with this activity. Roles: Activities are asocited to roles which define who can perform certain activities. Roles are defined at a per-process level and assigned to bitweaver groups. This allows simplified administration of particular activities and processes. In our first example, we will use just the start and end activities. In the start activity we will display our name. By default, two activities are created for you start and end. If you refer now to the This process is invalid: section at the top of the page, we can see what is left to edit before this activity becomes valid. The first line should say End activity is not reachable from start activity. Lets start by editing the end activity. Note that the end acitivity is 0 in the list. The list indicates the sequence in which the activities are performed. In the Process activities list, click on 0 end (no roles). This places the end activity in the edit form. You can see the details are entered into the Add or edit an activity form. The first step is to create a transition between the end and start activities and resolve the error. Once the start activity is completed, we wish to move to the end activity. Do this by highlighting the start activity in the Add transition from: list. As this is a end type activity, it does not allow anything selected in the Add transition to: box (see above). Click save to save changes. Check the This process is invalid: section and you will notice one of the errors has disappeared. In this section, you can now see a transition from start => end. You can quickly add transitions from here using the two dropdown boxes on the right and clicking add Look at the Process Activities list and notice that the start activity is now 0 in the list. Since we have edited the end activity to follow the start activity, the list has been sorted accordingly. Click on the start activity 0 start (no roles). Look at the Add transition to: box and note that end is already highlighted and is a result of our previous transition setting. Now lets refer to the next error Activity: start is interactive but has no role assigned. As the start is marked as an Interactive activity, we need to assign a role to the activity. In the Add role, enter testuser and press add role. You can see the screen update and testuser appears in the list of assigned roles. If you wish to remove an assigned role, click on the x next to the name. At this point, I will introduce you to the rest of the shortcut toolbar at the top of the page.
Click on roles to map a user. Admin RolesLook at the This process is invalid: section and you will notice a new error has appeared - Role: testuser is not mapped.If you look at the Process roles section of the page, you will see our testuser role that we created previously. Below that, you will see the Map groups to roles section. In our example we will map a group we belong to our role. If you are logged in as Admin, your group will be Admins or Administrators - otherwise, it is likely to be Registered. In the left Groups list, select your group and in the right Roles list, select the testuser role. Click map to save changes. You can now see an entry in the List of mappings. Shown here is the association between the group we just selected and our role. Notice there is only one error left. Admin CodeLook at the This process is invalid: section and you will notice one error left - Activity start is interactive so it must use the $instance->complete() method.Now we are ready to code some functionality. Click on code in the toolbar to begin coding. You will see a edit window with the start of a PHP script. {CODE()}<?php ?>{CODE} <?php and ?> signify the start and end of a PHP script respectively. If you've never programmed in PHP before, don't panic - its quite simple. Take a look at the tutorials mentioned at the start of this document. Look at the Select source dropdown list - this is used to quickly jump to different activity code and templates. Currently, this should be set to Shared source which is a holding place for activity related common or library code. Next you see the words Non Interactive - this indicates that the activity requires no user intervention and therefore does not display anything. If an activity is interactive, this will change to a template or code button to allow you to quickly swap between the two. Lastly are the save and cancel buttons. In Process activities you will see links to code and template for every activity. You can click on these links to jump straight to the relative code or template for modification. From the Select source dropdown, choose start. First thing we want to do is set some text to be displayed on the screen. Enter this in the edit window. {CODE()}<?php $smarty->assign('display_text', 'Hello world!'); if(isset($_REQUESTsave>'save')){ $instance->complete(); } ?>{CODE} You will notice that along the right side of the edit form are a number of links. These are coding shortcuts that allow you to quickly insert commonly used code. Let me explain these lines. The first line $smarty->assign('display_text', 'Hello world!'); is used to assign text to a variable which is used in template. Here we are assigning the variable display_text with the words 'Hello world!'. You will see this used when we edit the template section. The second line is an if statement checking if the save button was pressed. If the button was pressed, the $instance->complete(); function is executed telling the workflow, that we have finished the activity and are ready to move to the next actitivity - in our case end. Press save when finished editing. Press template to edit the display template. You will see a edit window with the start of a Smarty template. {CODE()}{*Smarty template*}{CODE} Both {* and *} are used for comments in Smarty, so this first line is effectively ignored. You will remember that in the previous PHP code, we assigned the variable display_text with some text. To display this variable, enter the following in the edit window. {CODE()}{*Smarty template*} <form method="post"> Ready to display text: {$display_text} <input type="submit" name="save" value="Ok" /> </form>{CODE} Anything surrounded by curly braces { and } are checked by Smarty and modified accordinly. Smarty provides many different functions using this method. Check the Smarty tutorial at the start of this document for more information. Agin you will notice that along the right side of the edit form are a number of links. These are Smarty shortcuts that allow you to quickly insert commonly used code. Press save when finished editing. Look at the toolbar, and you will see two new icons - a green valid dot and an activate icon. These indicate that all errors have been resolved and by clicking on the activate icon, you will activate the process. Click the activate icon. Starting an InstanceClick on Admin Processes and you will see the two columns Active and Valid have now changed. These indicated that the workflow appears to be complete and is ready for execution.The User Processes menu item shows all available processes, their number of activities and the number of current instances. The user can use this screen to see all their available processes. As you can see currently we have one activity and no (zero) instances. The User Activities menu item show all available activities. In our example, we have one item, the start activity. The arrow icon indicated that this activity can be started or instantiated. Click on the arrow to start our example process. Hello World!When you start our example process, the screen changes to show the form we designed earlier.Ready to display text: Hello world!
As you can see - our text that we set in our code has displayed in our form. If you'd like to save your process to an XML file for later restoration, this is how to do it. Go to the Admin Processes page and click the export icon. Depending on your browser, you will either be prompted to save the file somewhere or it will be displayed in the browser window. If it display, select File / Save As to save it to a file. New VersionSo we are going to create a more complex version of workflow. In the Admin Processes page, you can select new major or new minor, to create a duplicate process. This allows you to begin testing a new version of process and eventually, replace the old version with the new one.Click new minor You can see a duplicate Hello World Process, with a version number of 1.1 in your list. New ActivityWe will create a new activity to display our hello world information.Click on the Activities icon and create a new activity called display. In Add transitions from: list, select start and in the Add transitions to: list, select end. This places the activity between the two previous activities. Check auto routed: and select testuser role for this activity. As you can see a new error came up This process is invalid: Activity display is interactive so it must use the $instance->complete() method Another point to note is the graph of the process - click the graph icon. You can see the flow of the process is not right, as we want to start, then display and finally end. Click on the start activity. In the Add transitions to: list, select display and click Save. This places the start activity at the beginning of the process. Click the graph icon again to see the flow of the process. Inputting DataClick the template link on the start process. Edit the code, to display an INPUT TEXT field.{CODE()}{*Smarty template*} <form method="post"> Ready to display text: {$display_text} Please enter your name:<input type="text" name="name" /> <input type="submit" name="save" value="Ok" /> </form>{CODE} Click the code button to switch to the PHP code window. Edit the code, to store the text from the INPUT TEXT field. {CODE()}<?php $smarty->assign('display_text', 'Hello world!'); if(isset($_REQUESTsave>'save')){ $instance->set("name", $_REQUESTname>'name'); $instance->complete(); } ?>{CODE} Drop down the select source: list, and choose display. Edit the code, to retrieve the stored text. {CODE()}<?php $name = $instance->get("name"); $smarty->assign('name', $name); if(isset($_REQUESTsave>'save')){ $instance->complete(); } ?>{CODE} Press the template button and edit the template to display the retrieved value. {CODE()}{*Smarty template*} <form method="post"> Hello there {$name} Press <input type="submit" name="save" value="Continue" /> to finish. </form>{CODE} Click save to finish coding. Click the activate icon to activate the process. Go to ''User Activities and try version 1.1 of the Hello World Process. | Workflow refers to procedures for processing documents, such as requiring an editor to review and approve a story. ReferencesHere are some links to bitweaver and TikiWiki documentation where some of the definitions have been taken from:The above documents are not completely reflective of Galaxia in its current state within Bitweaver, but definitely informative.
Hello World Process 1.0 - IntroductionClick here to download the XML file of the process.bitweaver, has inherited a Workflow Engine from bitweaver and TikiWiki called Galaxia. This engine is quite powerful and easy to use once the basic concepts have been mastered. Rather than give you all the concepts now, I will introduce them throughout the tutorial to help understand their use and context in the scheme of workflow generation. Ensure Workflow is enabled on your website. If you have the permissions, you can visit Administration / Administer Packages / Features and check the Workflow feature. Click Change Preferences to save your change. If you have the permissions, you can visit Administration / Kernel / Packages and check the Galaxia package. Click Activate Tiki Packages to save your change. Admin ProcessesThe first part of creating a workflow is to create a Process. A process is usually the objective of the workflow. A process is defined as a set of activities that must be done to achieve some goal. Business circuits are mapped to processes to automate them. Be careful not to confuse a specific Activity with the Process. Some example Processes are:
To create our Test Process, open the Workflow / Admin Processes section of bitweaver. You notice at the top of the page are 4 icons.
In Process Name, enter the title of your process. As an example, we will do Hello World Process. Optionally in the Description, enter a short description about the process. Is active? indicates that the process is available for users. Leave this unchecked, as nothing will work while the process is blank. Now click Create. Just below the Create button are Browse and Upload buttons. Later in the tutorial, we will export our process to an XML file which can be later uploaded here or used on other bitweaver installations. To use, just Browse to your XML Process file and click Upload to create the process. Once you've created or uploaded your new process, you'll find it listed at the bottom of the Admin Processess page. Adjust the Find filter to find your process, if there are a lot of processes in the list - and click Filter to search. Our Hello World Process should appear in the list. The checkbox at the beginning is used if you wish to delete the process. Just check the checkbox and press the Delete button. If you do this now, be sure to recreate the process as shown above. Next is the process name. Click on the process name and you'll find the details are entered in the form above to allow editing of the title or description. Also note the icons have changed as well as the errors shown below This process is invalid:. Don't worry about these for now, as we will get to them later in the tutorial. Click Update to save changes. Next column is the Version. As you improve on your processes, you can create new versions to work on while leaving existing users on the previous stable version. Once you are convinced that the updated version is suitable for public use, you can make it the default process. All existing user instances of the previous version will continue to completion and not be affected by the new version. This ensures that your workflow functions correctly during upgrades. Active indicates if the process is free from errors and available for public use. Valid is a green or red circle indicating whether the process can be activated or not. This is dependent on whether it has any errors - mentioned above. Lastly, the Action icons are shortcuts to administer the process's activities, instances and other components. These are:
Click on the first Action icon - activities . Admin ActivitiesAn Activity is an action that is performed during your process. In Galaxia activities are mapped to PHP scripts so an activity can do anything that can be done from a PHP script. A process can consist of many activities. By default, a start and end activity are created for you, but these can be renamed or deleted at a later stage. I'll define two other terms so you can understand their context later.An instance is a particular process currently being executed. An activity can have many instances associated with it at any time. An instance is created when a process is initiated by a user and the instance will pass through the process activities until the process is terminated or completed. A transition is the path between two or more activities. A transition defines what has to be done after each activity is completed. A workitem is added to the instance when an activity is completed. Workitems thus represent completed activities. Activities are broken up into different types. Here are two types listed below:
You can see on our Admin process activities page, at the top is the shortcut bar, similar to the previous page. Below that you will see errors shown below This process is invalid:. We will review these later. In the Add or edit an activity form, you are able to add new activities or by clicking on the names of existing activities, edit their properties. Apart from Name and Description, there is a Type drop down. From here, you are able to select different activity types as was shown above. Next there are two check boxes. Interactive: - Activities can be programmed or user interactive. Interactive activities are activities requiring some kind of interaction with the user and these activities usually present a form asking the user to fill information. After the information is submitted, the instance is ready to move on to the next activity. Automatic activities in contrast are executed automatically without any user interaction. Data manipulation and programming is the most common use of an automatic activity. Auto-Routed: - When an activitiy is completed, the instance may or may not automatically route to the next activity in the process. Activities with the Auto-Routing setting activated automatically route the instance to the next process activity on completion. If the activity is not Auto-Routing, the user must send the activity to let the process continue. This can be used in activities where the user can edit information and review it many times before deciding that the activity is completed. Next, there are two boxes in the section Add transitions. These two boxes allow you to highlight, what previous activities lead to the current activity and what activities can be reached from the current activity. At the bottom of the Add or edit an activity form, there are the roles associated with this activity. Roles: Activities are asocited to roles which define who can perform certain activities. Roles are defined at a per-process level and assigned to bitweaver groups defining who is able to execute each activity. This allows simplified administration of particular activities and processes. In our first example, we will use just the start and end activities. In the start activity we will display our name. By default, two activities are created for you start and end. If you refer now to the This process is invalid: section at the top of the page, we can see what is left to edit before this activity becomes valid. The first line should say End activity is not reachable from start activity. Lets start by editing the end activity. Note that the end acitivity is 0 in the list. The list indicates the sequence in which the activities are performed. In the Process activities list, click on 0 end (no roles). This places the end activity in the edit form. You can see the details are entered into the Add or edit an activity form. The first step is to create a transition between the end and start activities and resolve the error. Once the start activity is completed, we wish to move to the end activity. Do this by highlighting the start activity in the Add transition from: list. As this is a end type activity, it does not allow anything selected in the Add transition to: box (see above). Click save to save changes. Check the This process is invalid: section and you will notice one of the errors has disappeared. In this section, you can now see a transition from start => end. You can quickly add transitions from here using the two dropdown boxes on the right and clicking add Look at the Process Activities list and notice that the start activity is now 0 in the list. Since we have edited the end activity to follow the start activity, the list has been sorted accordingly. Click on the start activity 0 start (no roles). Look at the Add transition to: box and note that end is already highlighted and is a result of our previous transition setting. Now lets refer to the next error Activity: start is interactive but has no role assigned. As the start is marked as an Interactive activity, we need to assign a role to the activity. In the Add role, enter testuser and press add role. You can see the screen update and testuser appears in the list of assigned roles. If you wish to remove an assigned role, click on the x next to the name. At this point, I will introduce you to the rest of the shortcut toolbar at the top of the page.
Click on roles to map a user. Admin RolesLook at the This process is invalid: section and you will notice a new error has appeared - Role: testuser is not mapped.If you look at the Process roles section of the page, you will see our testuser role that we created previously. Below that, you will see the Map groups to roles section. In our example we will map a group we belong to our role. If you are logged in as Admin, your group will be Admins or Administrators - otherwise, it is likely to be Registered. In the left Groups list, select your group and in the right Roles list, select the testuser role. Click map to save changes. You can now see an entry in the List of mappings. Shown here is the association between the group we just selected and our role. Notice there is only one error left. Admin CodeLook at the This process is invalid: section and you will notice one error left - Activity start is interactive so it must use the $instance->complete() method.Now we are ready to code some functionality. Click on code in the toolbar to begin coding. You will see a edit window with the start of a PHP script. {CODE()}<?php ?>{CODE} <?php and ?> signify the start and end of a PHP script respectively. If you've never programmed in PHP before, don't panic - its quite simple. Take a look at the tutorials mentioned at the start of this document. Look at the Select source dropdown list - this is used to quickly jump to different activity code and templates. Currently, this should be set to Shared source which is a holding place for activity related common or library code. Next you see the words Non Interactive - this indicates that the activity requires no user intervention and therefore does not display anything. If an activity is interactive, this will change to a template or code button to allow you to quickly swap between the two. Lastly are the save and cancel buttons. In Process activities you will see links to code and template for every activity. You can click on these links to jump straight to the relative code or template for modification. From the Select source dropdown, choose start. First thing we want to do is set some text to be displayed on the screen. Enter this in the edit window. {CODE()}<?php $gBitSmarty->assign('display_text', 'Hello world!'); if(isset($_REQUESTsave>'save')){ $instance->complete(); } ?>{CODE} You will notice that along the right side of the edit form are a number of links. These are coding shortcuts that allow you to quickly insert commonly used code. Let me explain these lines. The first line $gBitSmarty->assign('display_text', 'Hello world!'); is used to assign text to a variable which is used in template. Here we are assigning the variable display_text with the words 'Hello world!'. You will see this used when we edit the template section. The second line is an if statement checking if the save button was pressed. If the button was pressed, the $instance->complete(); function is executed telling the workflow, that we have finished the activity and are ready to move to the next actitivity - in our case end. Press save when finished editing. Press template to edit the display template. You will see a edit window with the start of a Smarty template. {CODE()}{*Smarty template*}{CODE} Both {* and *} are used for comments in Smarty, so this first line is effectively ignored. You will remember that in the previous PHP code, we assigned the variable display_text with some text. To display this variable, enter the following in the edit window. {CODE()}{*Smarty template*} <form method="post"> Ready to display text: {$display_text} <input type="submit" name="save" value="Ok" /> </form>{CODE} Anything surrounded by curly braces { and } are checked by Smarty and modified accordinly. Smarty provides many different functions using this method. Check the Smarty tutorial at the start of this document for more information. Agin you will notice that along the right side of the edit form are a number of links. These are Smarty shortcuts that allow you to quickly insert commonly used code. Press save when finished editing. Look at the toolbar, and you will see two new icons - a green valid dot and an activate icon. These indicate that all errors have been resolved and by clicking on the activate icon, you will activate the process. Click the activate icon. Starting an InstanceClick on Admin Processes and you will see the two columns Active and Valid have now changed. These indicated that the workflow appears to be complete and is ready for execution.The User Processes menu item shows all available processes, their number of activities and the number of current instances. The user can use this screen to see all their available processes. As you can see currently we have one activity and no (zero) instances. The User Activities menu item show all available activities. In our example, we have one item, the start activity. The arrow icon indicated that this activity can be started or instantiated. Click on the arrow to start our example process. Hello World!When you start our example process, the screen changes to show the form we designed earlier.Ready to display text: Hello world!
As you can see - our text that we set in our code has displayed in our form. If you'd like to save your process to an XML file for later restoration, this is how to do it. Go to the Admin Processes page and click the export icon. Depending on your browser, you will either be prompted to save the file somewhere or it will be displayed in the browser window. If it display, select File / Save As to save it to a file. Hello World Process 1.1 - New VersionClick here to download the XML file of the process.So we are going to create a more complex version of workflow. In the Admin Processes page, you can select new major or new minor, to create a duplicate process. This allows you to begin testing a new version of process and eventually, replace the old version with the new one. Click new minor You can see a duplicate Hello World Process, with a version number of 1.1 in your list. New ActivityWe will create a new activity to display our hello world information.Click on the Activities icon and create a new activity called display. In Add transitions from: list, select start and in the Add transitions to: list, select end. This places the activity between the two previous activities. Check auto routed: and select testuser role for this activity. As you can see a new error came up This process is invalid: Activity display is interactive so it must use the $instance->complete() method Another point to note is the graph of the process - click the graph icon. You can see the flow of the process is not right, as we want to start, then display and finally end. Click on the start activity. In the Add transitions to: list, select display and click Save. This places the start activity at the beginning of the process. Click the graph icon again to see the flow of the process. Inputting DataClick the template link on the start process. Edit the code, to display an INPUT TEXT field.{CODE()}{*Smarty template*} <form method="post"> Ready to display text: {$display_text} Please enter your name:<input type="text" name="name" /> <input type="submit" name="save" value="Ok" /> </form>{CODE} Click the code button to switch to the PHP code window. Edit the code, to store the text from the INPUT TEXT field. {CODE()}<?php $gBitSmarty->assign('display_text', 'Hello world!'); if(isset($_REQUESTsave>'save')){ $instance->set("name", $_REQUESTname>'name'); $instance->complete(); } ?>{CODE} Drop down the select source: list, and choose display. Edit the code, to retrieve the stored text. {CODE()}<?php $name = $instance->get("name"); $gBitSmarty->assign('name', $name); if(isset($_REQUESTsave>'save')){ $instance->complete(); } ?>{CODE} Press the template button and edit the template to display the retrieved value. {CODE()}{*Smarty template*} <form method="post"> Hello there {$name} Press <input type="submit" name="save" value="Continue" /> to finish. </form>{CODE} Click save to finish coding. Click the activate icon to activate the process. Go to ''User Activities and try version 1.1 of the Hello World Process. |