Copyright© 2012-2015 Archon Digital CC. South Africa

1.Preface

Archon BlueWave is a set of tools for K2 Blackpearl aimed at enhancing developer productivity and getting maximum value out of the K2 BPM suite.

If you're just getting started, you can learn more about system requirements, installation and configuring the software during the first run. If you're not quite sure what to do after that, you can get some ideas from the typical use section.

Head over to the design section to discover how the BlueWave front-end, back-end and K2 Blackpearl fit together, as well as the rationale for common deployment scenarios.

In-depth explanations of BlueWave's features can be found at the modules section.

The frequently asked questions section attempts to answer common questions.

2.Getting Started

If you're just getting started with BlueWave, the system requirements section explains the requirements in terms of hardware, software and access / K2 permissions.

If you are installing BlueWave, the following sections are recommended, in the order that they are needed during installation:

  1. The installation section walks you through the installer.
  2. Following installation, it will be necessary to request and install a license on your BlueWave server.
  3. The named licenses section describes where to find your license keys, and how to enter them on the BlueWave front-end.
  4. The first run involves configuring BlueWave to point to your K2 server(s).

Following installation, you may want to view the typical use section for examples and suggestions on how to use BlueWave.

2.1System Requirements

At the time of writing, no concrete minimum hardware requirements have been determined for BlueWave. With the exception of the simulation module, the software is not particularly resource heavy, and should run well on any relatively recent PC (or VM). More important are the software and permissions requirements, since failure to meet these will mean that BlueWave is unable to install, start, or function correctly.

2.1.1Suggested Minimum Hardware Specifications

2.1.2Software Requirements

2.1.3Required Permissions / Access

2.2Installation

Archon BlueWave uses a single, combined installer to install all the major components on to a single machine.

See installation types for more information about the two types of installations possible with BlueWave. If you're upgrading an existing installation, see the upgrade considerations section. The install application is otherwise very straightforward, but there's a step-by-step guide which shows each step involved.

2.2.1Installation Types

There are two main components to BlueWave: the client, and the server. The client is the main front-end for BlueWave, and contains all the main functionality for your users. The server is a support component which the clients connect to for their storage and licensing needs. See the architecture overview section for more information.

A typical installation scenario may have a number of developers using BlueWave on a single network. In this case, there should be a single BlueWave server for the entire network, and a BlueWave client installed locally for each developer. To avoid confusion, it is advisable to use the "BlueWave Client Only" option, if the BlueWave server is not required.

In certain cases, it may be necessary to install multiple BlueWave servers, specifically if you have multiple networks where you wish to make use of BlueWave. Each BlueWave server installation will need to go through the standard license request process. In these cases, it is a good idea to use proper environment descriptions when requesting licenses, since it will make the approval process easier.

2.2.2Upgrade Considerations

If you are upgrading an existing installation, BlueWave will generally not overwrite locally stored user information (e.g. the BlueWave server DB, snapshot data, etc). During the next startup any necessary data migrations will be performed.

The client and server installation versions should be kept in sync. During startup, the client and server will communicate to determine whether they are compatible with each other, and you will be notified if there's an issue. Typically, bug-fix releases may be backwards compatible with previous versions, but releases that make major changes to functionality are not.

2.2.3Step-by-Step Guide

Start the BlueWave installer by double clicking on setup.exe:

Setup (Installer File)

Figure: Setup (Installer File)

Next, click through the first steps of the install wizard. There's a welcome screen, a license agreement, and an installation folder confirmation.

Setup (Part 1)

Figure: Setup (Part 1)

Setup (Part 2)

Figure: Setup (Part 2)

Setup (Part 3)

Figure: Setup (Part 3)

On the 4th step, you have to make a choice regarding which BlueWave components to install. See the installation types section if you are not sure what to choose.

Setup (Part 4)

Figure: Setup (Part 4)

The remaining two steps involve a decision about desktop icons, and a confirmation screen. Once you've confirmed your choices, installation will begin. If the server components have been selected for installation, BlueWave will also install and register the BlueWave service on your machine:

Setup (Service Installation)

Figure: Setup (Service Installation)

This service needs to be running for the BlueWave front-end to start up.

BlueWave should now be installed. You will need to configure it to connect to your K2 server - please read the first run section for more information.

2.3License Request

BlueWave requires a valid license installed on the BlueWave server in order to work. License requests are registered against your company profile on the Archon BPM website, and each company is automatically assigned a trial license entitlement, which they can use to request trial licenses. There are two ways to request and install a license:

The two methods are equivalent, and can be used interchangeably. To keep the guides relatively short, only the successful path is shown. If you encounter any errors, please consult the troubleshooting license requests section, and contact our support team if you are still experiencing issues.

The most common license type in use is the named license, which means that the BlueWave front-end will require a serial number to connect to the BlueWave server. To see how this is done, please check the named licenses section.

2.3.1Integrated License Request Process

A step-by-step guide for requesting and installing a license using the integrated (preferred) method follows.

Start the BlueWave Service Manager application on the machine where it is installed. It will start up and connect to the BlueWave Service, and open on the License Request screen.

License Request (Part 1)

Figure: License Request (Part 1)

This screen allows you to connect to the Archon BPM website, request licenses, check the status of these requests, and finally install them when they have been issued. The "First Install" wizard on the right hand side of the screen picks up the status of your license installation, and will highlight the next action in blue.

Click the "Connect to Website" button to start the connection. Type in your website username and password and click connect. Depending on your connection to the internet, it may be necessary to specify your proxy server - this can be done via the "configure proxy" button.

License Request (Part 2)

Figure: License Request (Part 2)

Once you have successfully connected, you will be returned to the license requests screen. The license requests screen will be empty (unless your company has requested licenses in the past). The wizard on the right should reflect that the current action is to send a license request. Click the "New License Request" button to continue.

License Request (Part 3)

Figure: License Request (Part 3)

The license request screen allows you to pick a license entitlement against which to request a license. All newly signed-up companies are automatically given an evaluation entitlement, with a fixed expiry date. If you've purchased BlueWave, you should see at least one "standard" license entitlement, which typically does not carry an expiry date. Additionally, you can specify the environment type and environment name. These fields are mainly for maintenance purposes, but you are encouraged to fill them out accurately, since they may help resolve conflicts later.

Additionally, BlueWave captures the hardware profile of your server, and automatically attaches it to the license request. BlueWave licenses are tied to the server where they are installed, and this hardware profile allows it to determine how much the server's hardware profile has changed since the license was issued. If the server's profile has been changed too much, you will need to request a new license (e.g. if you replace half the hardware components in your sever).

Clicking the "Send Request" button will upload the license request to the Archon BPM website, and take you back to the license requests screen. You should also receive a notification via email about your license request.

License Request (Part 4)

Figure: License Request (Part 4)

The recent license request should be visible in the grid with a status of "requested", and the wizard will indicate that you need to wait for a license response. Your license request should be approved within a few minutes or hours, but depending on your time zone and time of day, it may take until the next business day. Clicking the "refresh" will update the grid, and you will also be notified of any license responses via email.

License Request (Part 5)

Figure: License Request (Part 5)

Once the license has been approved, your grid should reflect the status, and the wizard should indicate that the next step is to install the license. Simply select the license in the grid, and click "install". In case there are multiple license requests, BlueWave will only allow you to install licenses for the current server.

License Request (Part 6)

Figure: License Request (Part 6)

A confirmation dialog will show the details of the license, specifically the type and number of licenses. This is typically dictated by the license entitlement which was used to request the license. Clicking "yes" will install the license.

License Request (Part 7)

Figure: License Request (Part 7)

At this point, the license should be installed, and both the license request grid and wizard should reflect this status.

License Request (Part 8)

Figure: License Request (Part 8)

Optionally, you can use the local licenses screen to see what licenses have been installed for BlueWave. This screen is also useful to see the activation status of the license; the number should be at 100% at installation, but may be lower if hardware components have been changed. If it drops below a certain threshold, the license will start to be considered invalid.

2.3.2Manual License Request Process

In certain cases, it may not be possible to follow the above integrated license request process (primarily, when your server is not connected to the internet). In these cases, a manual process can be followed which parallels the above process, but involves a few extra steps.

The first step in the process is to export the hardware profile of the target BlueWave server. On the server, start the BlueWave Server Manager, and open the "Hardware Information" screen.

Manual License Request (Part 1)

Figure: Manual License Request (Part 1)

BlueWave will collect information about your server, and display it in a tree view. Click the "export" button and select a location to save the information. This file will need to be uploaded to the Archon BPM website, so copy it to the machine you are using to log in to the website.

Next, log in to the Archon BPM website, and click on "My Profile" in the navigation menu. Under the "license requests" section, click the "request a license" link.

Manual License Request (Part 2)

Figure: Manual License Request (Part 2)

Complete the license request form by selecting to upload the hardware profile XML file you exported in the previous step, selecting a license entitlement, as well as the environment type and name. Click the submit button to upload the license request.

Manual License Request (Part 3)

Figure: Manual License Request (Part 3)

Back on the "my profile" screen, there will be a message indicating that the license request was successful. The license requests grid shows the status of the request itself, which needs to be approved before it can be downloaded. As with the integrated license request process, the approval should be relatively quick, but may take until the next business day to complete. Email notifications are sent for both the license request, as well as the subsequent approval.

The user notifications section shows any messages that you have received since you last cleared the list. If you have any new notifications, the number will also be shown on the navigation menu next to "my profile". You may want to clear the notification list at this point, so that it's easier to notice when your license approval arrives.

Manual License Request (Part 4)

Figure: Manual License Request (Part 4)

Once the license has been approved, the license request grid will show the updated status, as well as a download link. Clicking the link downloads the license key itself (it is a binary file), which will need to be copied over to the target server, and imported using the BlueWave Service Manager.

Manual License Request (Part 5)

Figure: Manual License Request (Part 5)

Back in the Service Manager, open the "local licenses" screen, and click on the "install license" button. Select the file which you downloaded in the previous step, and click "open". A confirmation dialog will show, with the details of the license. Click "yes" to continue.

Manual License Request (Part 6)

Figure: Manual License Request (Part 6)

The local licenses screen will now show the license as installed.

2.3.3Troubleshooting License Requests

Some of the common issues which may occur during the license request process are detailed below, with suggested solutions:

2.4Named Licenses

There are three types of licenses available for BlueWave - named, concurrent, and site. Named licenses are the most common, and require a small amount of administration to set up; this section will guide you through it. If your license is a concurrent or site license, no further admin is required, and you can skip this section.

On the machine where you have the BlueWave Service installed, start the Service Manager and select the "named licenses" screen.

Named Licenses: List of Serial Numbers

Figure: Named Licenses: List of Serial Numbers

If you have one or more named license installed, each serial number will be listed here along with the machine that it's allocated to. The allocation of a serial number process occurs during the first run of the BlueWave front-end, when the user is requested to enter a serial number. To facilitate the communication of the serial numbers to your team members, you can export the serials to a text file, or copy them to the clipboard.

Named Licenses: Entering the Serial

Figure: Named Licenses: Entering the Serial

The serial number can then be entered directly in the BlueWave front-end during the first run. At this point, the serial number is allocated to the client machine. These allocations are visible on the "named licenses" screen, allowing you to keep track of available licenses or even re-assign them.

2.5First Run

In order to successfully start Archon BlueWave's front-end, it first needs to connect to the BlueWave Service, after which it needs to connect to an actual K2 environment. This K2 connection needs to satisfy the various requirements set out in system requirements and architecture sections. Namely, the BlueWave front-end needs to be able to create the following connections:

2.5.1Step 1: Connecting to the BlueWave Service and License Validation

The BlueWave will automatically attempt to connect to the BlueWave Service on localhost, using the default port (8555).

If you are using a default installation and the service is running, this step should be successful. If the BlueWave service is installed on another machine, you will have the opportunity to enter the machine name and retry the connection. Once successfully connected, BlueWave will attempt to check for a valid license from the Service.

In case of a named license being in use, the user will have to provide a valid serial number during the first run to connect to the server. See the named licenses section on how to find your installation's serial numbers. The serial number is short, and simply needs to be typed or pasted in to BlueWave during the first run.

If are stuck on this step, consult the troubleshooting guide. Specific problems which are likely:

2.5.2Step 2: Configuring a BlueWave Environment

On your first run of BlueWave, it will attempt to connect to the first defined K2 environment, which it assumes to be on the current machine (localhost). Chances are that your configuration is different, and in this case, you will encounter an error:

Splash Screen Error

Figure: Splash Screen Error

In this case, click the edit button to open the environment editor:

Splash Screen Environment Editor

Figure: Splash Screen Environment Editor

Select the default environment (Development), and click Edit. Insert valid values for the K2 Server (the machine name where the K2 is installed), and the SQL Server (the machine and SQL instance name of the K2 DBs, e.g. localhost or localhost\SQL2008).

Tick integrated authentication if you'd like to use your current Windows user to connect to the K2 SQL DB. Otherwise, untick it, and specify a SQL username and password.

When done, click Test Connection - a positive outcome is required here for BlueWave to work correctly. If you cannot connect, consult the cannot connect to K2 troubleshooting guide. When you've successfully, connected, click Close to get back to the splash screen. Here, use the Connect button to attempt to reconnect with the updated environment information. If your settings were correct, it should start up without any problems.

2.5.3Step 3: Successfully Started

Congratulations, you have a working copy of BlueWave. Not sure what to do next? Check out the typical use guide.

2.6Typical Use

BlueWave can make a variety of tasks easier. Not sure what you can use it for? Here are a few ideas:

2.6.1Worklist / Manual Testing

2.6.2Documentation Generation

2.6.3Process Version Upgrade

2.6.4Simulation

2.6.5Server Maintenance

3.Modules

Screens in BlueWave are grouped into high-level modules by functionality. These modules are:

3.1Worklist

BlueWave provides two separate "worklist" screens, each offering different capabilities and benefits:

Additionally, both worklist screens are able to open the advanced view flow screen.

3.1.1Manage Worklist

The manage worklist screen provides an advanced capability referred to as a "management worklist" in K2 terminology. It differs from a normal worklist in that all work items are potentially shown, not only the ones allocated to the current user.

The primary goals of the manage worklist are:

Filtering

Complex filters can be set up using the filter panel:

Manage Worklist - Filtering

Figure: Manage Worklist - Filtering

  1. Available Filters: Use this panel to quickly show / hide various filters that you can use in BlueWave to narrow your search. All your filter settings are stored when you close BlueWave, including which filters were open at the time, as well as the actual values in each filter.
  2. Filter Type: The filter type determines how the value specified will be used.
  3. Filter Value: The actual value to be filtered on.
  4. Search Button: Use the search button to trigger a search for work items. BlueWave will execute your search, and coalesce the resulting management worklist into the results grid. It is important to note that:

Each visible row in the results grid can be made up of multiple management worklist items, and the entire management worklist query is limited to 500 items. This means that if the maximum number of records are returned, there's a chance that the last visible row in the grid is incomplete (i.e. there may be further activity instance destinations for that item which were not retrieved). In this case, BlueWave shows a warning, and you should try to refine your filter:

Manage Worklist - Results Warning

Figure: Manage Worklist - Results Warning

Results

The results area has two main sections:

Actions - Context Menu

When you have one or more rows selected, right-click on the row(s) to bring up a context-sensitive menu. The available actions shown are highly dependent on the number of items selected, their respective statuses and processes, etc. In short, BlueWave attempts to give you actions which are equally applicable across all the selected items. The most complete set of options is given when a single row is selected, broken down into their respective sections, they are:

Manage Worklist - Popup Menu

Figure: Manage Worklist - Popup Menu

3.1.2Find Process Instance

The find process instance screen is similar to the manage worklist screen, except that it works with process instance history from the K2 Server Log DB. This has two major effects:

Filtering

Similarly to the manage worklist screen, filters are configured using the filter panel:

Find Process Instance

Figure: Find Process Instance

  1. Available Filters: As with the manage worklist screen, use this panel to quickly show / hide various filters that you can use in BlueWave to narrow your search. All your filter settings are stored when you close BlueWave, including which filters were open at the time, as well as the actual values in each filter. The set of available filters is slightly different to the ones on the manage worklist screen:
    • Date, Event Name, Status and Destination User are removed and not available.
    • Process Instance ID and DataField are available.
  2. Filter Type: The filter type determines how the value specified will be used.
  3. Filter Value: The actual value to be filtered on.
  4. Search Button: Use the search button to trigger a search for work items.

Results

The results area has two main sections:

Actions - Context Menu

When you have one or more rows selected, right-click on the row(s) to bring up a context-sensitive menu. The available actions shown are highly dependent on the number of items selected, their respective statuses and processes, etc. In short, BlueWave attempts to give you actions which are equally applicable across all the selected items. The most complete set of options is given when a single row is selected, broken down into their respective sections, they are:

3.1.3Advanced View Flow

BlueWave's advanced view flow makes use of Archon's process rendering technology to show the history of a K2 process instance. This allows for a very rapid, custom display of a process instance's flow.

The diagram shows:

3.2Testing

BlueWave provides automated testing of K2 processes. Being able to start a process with repeatable parameters and actioning certain K2 Activities in a repeatable manner can provide a more controlled development environment. The three main section of Testing are the Process Start, Test Scenario Runner and Test Scenario Editor tabs.

The Process Start tab is used to kick off K2 Process instances via a customisable editor. It is possible set datafields and process instance folio.

3.2.1Process Start

Documentation - Testing - Process Start

Figure: Documentation - Testing - Process Start

Important: You can also copy active data into this start screen from the worklist screen. In order to do this, right click a worklist item and select Copy Details to Process Start Screen.

  1. Testing Tab: Select the Testing tab to enter the Testing Module.
  2. Process Start Side Tab: Opens the K2 Process Start editor screen.
  3. K2 Process: The desired K2 process needs to be selected.
  4. Start Scenario: If there are already saved start scenarios for the selected K2 Process then they will show up in the dropdown. Selecting an already saved scenario will load the previously saved values for the folio and data-fields.
  5. Create New Start Scenario: Creates a new scenario and enables the screen below for editing.
  6. Name Textbox: If the scenario is new, it will require a name before saving. E.g. "Test 1 with Manager note"
  7. Folio: The folio Textbox can be used to dynamically generate a k2 Folio for the workitem.
  8. Populate tick-box: For each K2 DataField that needs to be populated the "Populate" tick-box must be checked.
  9. Data field value Text-box: Contains the DataField value to be populated into the workitem during process start.
  10. Drag to Folio Drag and drop the green box to the Folio text-box to dynamically populate the datafield's value into the K2 Folio.
  11. Save: Saves the Start Scenario for later reuse. (Don't forget to click save before closing the application).
  12. Cancel: Cancel all changes that were made to the Start Scenario.
  13. Delete: Delete the currently selected Start Scenario. (Not enabled if the scenario was not yet saved.)
  14. Start Process Starts the K2 Process with the provided values.
  15. Status Bar Notice After Starting, Saving or deleting a Start Scenario the status bar displays a notification of what has just occurred. E.g. "Scenario Test1 Saved."

3.2.2Process Scenario Editor

The Process Scenario Editor must be used first before the Test Scenario Runner can be used because a test scenario must be configured. For practical purposes the Test Scenario Runner has been placed higher than the editor in the user interface.

Documentation - Testing - Process Scenario Editor

Figure: Documentation - Testing - Process Scenario Editor

  1. Test Scenario Editor tab: Selecting this tab display the Test Scenario Editor.
  2. K2 Process Drop Down: Select the process you wish to create and automated testing scenario.
  3. Test Scenario Drop Down: Allows for selecting and loading a previsou saved scenario for the selected process.
  4. New Test scenario Button: This button creates a new scenario ready for editing and saving as a new scenario.
  5. Edit Test scenario: If a previously saved scenario was selected then this button enables the editing of the scenario.
  6. Delete Test Scenario: Deletes the currently selected scenario under the Test Scenario Dropdown (Point 3).
  7. Name Textbox: This is where the user definable
  8. New step: Drag the icon to the process to create a new Test Step, whereby you can define what conditions must be true for that step.
Documentation - Testing - Process Scenario Editor Screen 2

Figure: Documentation - Testing - Process Scenario Editor Screen 2

To create a new Test scenario the following steps could be followed:

  1. New Test scenario Button: This button creates a new scenario ready for editing and saving as a new scenario.
  2. Name Textbox: If the scenario is new, it will require a name before saving. E.g. "Test 1 with Manager note".
  3. Process Start Edit Icon: Clicking Yellow Pencil icon opens the Process Start Settings window. Enter the date for the desired datafields.
  4. Process Start Scenario Dropdown: Select a pre-saved Process Start Scenario from the Drop down.
  5. Import Button: The Import button populates the datafields from a pre-configured start scenario.
  6. Apply Button: Saves the start Settings for the Test Scenario.
Documentation - Testing - Process Scenario Editor Screen Setup Assertions

Figure: Documentation - Testing - Process Scenario Editor Screen Setup Assertions

  1. New Step Icon: Drag and drop the New Step icon onto any Activity that highlights "Drop Here" in red.
  2. Edit Test Icon: Click the Edit Test icon (yellow pencil) to edit the tests on the step.
  3. Process test window: The Process test window displays the assertions that need to be satisfied for that Activity to pass its test.
  4. Add Assertion: Click the Add Assertion button to add assertions.
  5. Datafield Dropdown: Select a datafield a comparison and a value for the assertion.
  6. Apply Button: Click Apply to save.
Documentation - Testing - Process Scenario Editor Screen Step Action Settings

Figure: Documentation - Testing - Process Scenario Editor Screen Step Action Settings

Finally, Edit the Activity Data after each step.

  1. Edit Action Icon: Click the edit action icon to open the Action Settings for a Test Step.
  2. Process Action Scenario: You can load a previously saved Action Scenario. The Action Scenarios are created by right clicking a worklist item and selecting Update and Action - Save new Scenario.
  3. Set Value Checkbox: Select the checkbox to set the value for datafield for this step.
  4. Action Dropdown: Select an action to be taken at the end of the step.
  5. Test Steps List: The Test Steps are visible here.
  6. Move Up: Moves the Test Step on up. Sometimes it is necessary to reorder steps, depending on which order they were captured.
  7. Move Down: Moves the Test Step on down.
  8. Delete: Deletes the currently selected Test Step.
  9. Save: Saves the Entire Test Scenario
  10. Cancel Discards the Latest changes to the current Test Scenario.

3.2.3Test Scenario Runner

After the Tests have been configured, they can be run from the Test Scenario Runner tab.

Documentation - Testing - Process Scenario Runner

Figure: Documentation - Testing - Process Scenario Runner

In the Test Scenario Runner it is possible to run and re-run the pre-configured tests in a repeatable fashion. This enables certain level of basic unit testing for your processes which ensures that they still work after modifications.

  1. Tree view Test Selector: Select the Tests you wish to run.
  2. Refresh Button: Click refresh if you recently added a new Test Scenario and they are not displayed in the treeview.
  3. Run Selected Tests: Runs all of the selected tests.
  4. Test Result Failed: The test result shows that the process did not run according to tests, or it has generated an error.
  5. Test Result Succeeded: The test result shows that the test ran successfully.

3.3Process Documentation

BlueWave caters for process documentation using to powerful, highly related features:

The combination of the above two allows for the rapid documentation of processes, as well as tracking changes to them.

3.3.1Documentation Generation

BlueWave's documentation generation analyses your K2 processes and exports key information about them to HTML. A quick overview of the core concepts follows:

Documentation generation can be used to document K2 processes as well as create a comparative documentation to an older version of the K2 processes. Comparing two different version of the same process can be useful for generating specification for the development team.

Documentation - Generation

Figure: Documentation - Generation

  1. Documentation Tab: Select the Documentation tab to Generate K2 Process Documentation.
  2. Documentation Generation Side Tab: Opens the K2 Documentation Generation screen.
  3. Project: Allows for the selection of a Bluwave Project. Projects must be configured under the Configuration before document generation. There are 3 different sources of K2 Processes that can be selected: "Snapshot", "K2 Server as of now", or Folder
  4. Snapshot: Select a previously created Project Snapshot as the source of the documentation. You can create a snapshot of projects from a K2 server at any time. Please refer to the Project Snapshot
  5. K2 Server as of: Now: Takes the current default project(s) from the K2 Server. Note the Projects are filtered by the Project Selection (point 3).
  6. Folder:: Allows for the selection of a folder where a .kprx file can be found as the source for the documentation generation.
  7. Output Formats: Currently only HTML are supported with PDF and MS Word formats on the roadmap.
  8. Output Folder: The folder where the K2 Project documentation will be saved to.
  9. Compare to previous: To compare an older version of the process this tick-box must be ticked. (Makes points 10-12 visible)
  10. Compare to Snapshot: Selected if a comparison to an older snapshot is required to be part of the documentation.
  11. Compare to K2 Server as of: Selected if a comparison to an older version of the K2 processes on the K2 server requires direct comparison to be part of the documentation. The date selected will be used to find the K2 Processes deployed last before the date of selection.
  12. Compare to Folder: Selected if a comparison to an older snapshot is required to be part of the documentation.
  13. Generate Documentation: Clicking this button generates the K2 Project documentation into the selected Output folder.

3.3.2Project Snapshot

Project Snapshots can be used to create snapshots of the state of a K2 server or a local folder. The Snapshot physically makes a copy of the K2 Processes that are contained in the BlueWave Project and they can be used later in the documentation generation screen to compare newer version of the Processes against.

Documentation - Generation - Project Snapshot

Figure: Documentation - Generation - Project Snapshot

  1. Documentation Tab: Select the Documentation tab to Generate K2 Process Documentation.
  2. Project Snapshot Side Tab: Opens the K2 Project Snapshot Screen.
  3. Bluewave Project: Select a BlueWave Project. BlueWave Projects specify the source location of K2 Projects. Projects must be configured under the Configuration before creating a snapshot.
  4. Preview Processes: Displays the list of processes as filtered by the selected BlueWave Project. The user can see which processes will be snapshot for later comparison.
  5. Preview Processes: Displays the BlueWave Project filter (if any)
  6. Project Snapshot Treeview: Displays the list of K2 Processes that form part of the currently selected BlueWave Project. Project that are excluded have a line drawn through them.
  7. Description: The snapshot description, e.g. "Before Leave process changes added." that describes the latest changes or version of K2 processes.
  8. Create Snapshot: Creates a physical snapshot of all processes visible in the treeview (point 6).

3.3.3Documentation Project View Snapshot

Documentation - Generation - Project View Snapshot

Figure: Documentation - Generation - Project View Snapshot

  1. Documentation Tab: Select the Documentation tab to Generate K2 Process Documentation.
  2. View Snapshots Side Tab: Opens the K2 Project Snapshot Screen.
  3. Project Snapshot Treeview: Display the snapshots taken previously for each BlueWave Project.
  4. Refresh: Refreshes the treeview to show all newly added snapshots.

3.4Support

The support module contains several tool which help with the day-to-day support and administration of a K2 installation. These tools are:

3.4.1Support: Process Versions

The process versions screen retrieves all the process instances on the server, and displays them in a format which allows for intelligent decisions to be made about the process versions, specifically whether to upgrade them or not.

Support: Process Versions

Figure: Support: Process Versions

  1. Support Tab: Opens the Support tab to enter the Support Module.
  2. Process Versions Side Tab: Opens the K2 Process Versions screen.
  3. Process Instance Versions Tree-View: Displays the Process Instances per Process and per Version in a tree-view format.
    • The different levels of the tree-view represent different levels of groupings. The first two levels represent the process' namespace (split into the first part or "project", and the remainder). The third level shows the process version number, where red nodes indicate outdated versions and green nodes indicate the latest version. The 4th (lowest) level represents process instances, grouped by activity. Since upgrades are often dependent on the current activities in the process, this last level is very important.
    • For the purposes of the "upgrade" and "analyse for upgrade buttons", one or more nodes of the lowest level need to be ticked. This can be done by ticking them individually, or by ticking higher level nodes (all child nodes will automatically be ticked).
    • Right-clicking on a specific version's node allows for the "compare to latest version" option. This option compares the selected process version to the latest process version, and displays the processes side-by-side. Please note that this feature is still experimental at the time of writing, and should be considered incomplete.
  4. Refresh: Refreshes the number of instances from the server and display any new instances were started in the mean time.
  5. Analyse for Upgrade: Analyses the selected node with regards to upgradeability to the latest version of the selected Process.
  6. Upgrade: Upgrade the version of the currently selected process instances to the latest process version. Takes into consideration the "goto current activity" checkbox during the upgrade.
  7. Goto current activity after upgrade: This checkbox determines BlueWave's post-upgrade behaviour. By default (if this checkbox is not ticked), no further action is taken after an upgrade. In many cases, however, the upgraded process doesn't function as expected after an upgrade, and needs a "goto activity" to re-initialise certain aspects of the process instances. One example is that action changes do not show up until action rights are re-calculated by K2, leaving new actions invisible unless the goto option is used. This option tells BlueWave to determine the current activities for each process instance, and to trigger a goto activity call to fix these types of issues. Please take into consideration any side-effects that the goto activity, e.g. escalations being reset, destination rules being re-executed, and so on.
Support: Process Versions Analyse

Figure: Support: Process Versions Analyse

The analyse process versions screen takes all the selected process instances, and checks whether upgrading them to the latest version would violate any basic rules. Example rules include the current activity being removed from the new version of the process, or data field types being changed. Please note that the analysis performed here is by no means exhaustive; as always, you should perform your own analysis and testing before upgrading process versions.

3.4.2Support: Instances by Process

The instances by process screen shows all process instances on the server, grouped by the process namespace (as with the process versions screen, split into the "project" part and the remainder). The primary purpose of the screen is to allow for quick, bulk deletion of process instances by project / process, typically on development / testing environments.

Support: Instances by Process

Figure: Support: Instances by Process

  1. Support Tab: Opens the Support tab to enter the Support Module.
  2. Instances by Process Side Tab: Opens the K2 Instances by Process screen.
  3. Instances by Process Tree View: Displays the Instances by Process tree-view. Every process instance is visible on the server in the treeview, per process.
  4. Refresh: Refreshes the tree-view data from the server.
  5. Expand All: Exands all nodes on the tree-view.
  6. Delete Selected Items: Deletes all selected process instances. NOTE: This action cannot be reversed and care must be taken not to delete process instances that were not meant to be deleted. A Database backup is strongly recommended before using this feature in production environments.

3.4.3Support: K2 Errors

The K2 errors screen shows all errors on the K2 server, grouped by the usual process namespace (project / remainder) levels. Multiple errors can quickly be selected and retried.

Support: K2 Errors

Figure: Support: K2 Errors

  1. Support Tab: Opens the Support tab to enter the Support Module.
  2. Instances by Process Side Tab: Opens the K2 Errors screen.
  3. K2 Process Instance Errors Tree View: Displays the K2 Errors in a tree-view. Every error is visible in the treeview, per process.
  4. Refresh: Refreshes the tree-view data from the server.
  5. Expand All: Exands all nodes on the tree-view.
  6. Retry Selected Items: Retries all selected process instances. If the Error could not be repaired the error will return momentarily into the tree-view.
  7. Delete Selected Items: Deletes all selected process instances. NOTE: This action cannot be reversed and care must be taken not to delete process instances that were not meant to be deleted. A Database backup is strongly recommended before using this feature in production environments.

Right Click action on an error node in the tree-view:

K2 Errors Popup

Figure: K2 Errors Popup

  1. Retry Error: Retries the error.
  2. Delete Process Instance: Deletes the K2 Process Instance that is in an error state.
  3. Find Process instance: Finds the Process Instance that causes the error in the Process Instance Search screen. This feature can be very useful when combined with the filtering capabilities of the process instances screen, since all related process instances (regardless of status) can be quickly found.
  4. Edit Data: Allows for editing the data fields of the process instance, and enables potential fixes to the data before retrying.
  5. Error Information: Numerious information about the error that was thrown, such as the Exception, the Date and the Stack Trace.
  6. Data Fields: Displays all of the data fields of the Process Instance.

3.4.4Support: SmartObjects

The SmartObjects Support tab enables the user to navigate SmartObjects and edit SmartObject data in a SQL Server Enterprise Manager like interface. It also enables executing SmartObjects with parameters.

Support: Smartobjects

Figure: Support: Smartobjects

  1. Support Tab: Opens the Support tab to enter the Support Module.
  2. Instances by Process Side Tab: Opens the K2 Smartobjects screen.
  3. Search box: Type specific keywords found in your Smartobject to quickly find it within the Smartobject hierachy. Please note that the treeview automatically refreshes as you type eliminating unwanted K2 Smartobjects and folders.
  4. Smartobject treeview: Display the tree of K2 Smartobjects, right click on a Smartobject to show a context sensitive popup menu
  5. Popup Menu From the Smartobject popup menu it is possible to interact with the Smartobjects directly by selecting commands such as Select top 1000 Rows, Edit to 200 Rows or Create, Save, Delete, Load, Getlist depending on the type of Smartobject was selected.
  6. Execute Button Executing a Select top 1000 Rows results in the results window being displayed. If the data requires editing the Edit top 200 Rows can enable editing. Alternatively the SQL query can be edited by the user as necessary.
  7. Results grid The selected data becomes visible in the results grid.
  8. Refresh Button The Refresh button refreshes the treeview with potentially new Smartobjects.
  9. Expand All Button: Expands the the Smartobjects treeview to make all nodes visible to the user.

3.5Simulation

The simulation module allows users to obtain high-level business-related information about how their K2 processes might behave in a real-life situation. This is done by providing BlueWave with K2 process definitions, along with worker pool sizes and activity effort estimates, which is then run through a custom discrete event simulation engine. Please note that the simulation module is still in an experimental phase.

The introduction to simulation section gives a short overview of simulation; what it is, and why you may want to perform simulations. The next section discusses BlueWave's Simulation Model, which is relatively complicated and required reading for actually performing simulations. The simulation editor screen section details how to create simulations, while the simulation runner screen explains how to run them and analyse the results. The limitations section discusses some of the shortcomings of the current simulation in BlueWave (i.e. where the behaviour will differ significantly from actual K2 processes), while the tips-and-techniques section gives some ideas and details about basic and intermediate techniques for simulation.

3.5.1An Introduction To Simulation

The purpose of simulation is to answer questions which cannot easily be deduced from the raw business process information. As an example, even if we can estimate the amount of human work involved in a single activity (and we know the size of the team performing the activity, as well as the number and distribution of requests per day), it is still very difficult to predict the kind of "backlogs" that will typically happen for that activity. In many cases, the total duration of a process instance will depend more on the amount of time it spends idling (waiting for a worker to become available). The problem becomes even more complex once we start considering multiple activities and processes, different work schedules, extreme scenarios, and so on. At this level of complexity, a simulation engine is needed, which can take all the above information and play out what would happen in reality.

In the end, simulation takes your K2 processes, team sizes, and activity duration estimates, and produces detailed information about backlog size (per activity or team), average duration by process (which can be compared to your defined service level agreements, or even give you a rough estimate of what your SLAs should be). By varying the inputs to the simulation, you can see what impact they would have on the behaviour of your business processes, allowing you to make informed decisions about your business.

In summary, typical uses of simulation are:

3.5.2BlueWave's Simulation Model

The simulation model used by BlueWave has three high-level, core concepts:

Process Simulation Scenarios

BlueWave uses K2 processes as a basic input into the simulation model. A number of additional pieces of information need to be added in order to make the process usable in a simulation:

A more in-depth description of each is given below.

Process start statistics: the number of process instances that will be started for this process, with an exact number given per day of week and a probability distribution* for the time of day. This allows the user to set up complicated and realistic scenarios, along the lines of "we get most of our work on Mondays and Fridays. For Mondays, they usually happen early in the day, while on Fridays it's usually after lunchtime". The above example highlights how important this type of information is for business processes (and simulation); assuming the responsible teams are not able to process everything at the rate it's coming in, there will be a large backlog during Monday.

* Probability distributions (or more correctly, probability density functions) are used in BlueWave simulations often. They allow the user to express how likely different values are to be selected from a range, relative to each other. First, the user specifies a range, e.g. saying that an activity may represent between 5 and 30 minutes of work. For the purposes of a simulation then, BlueWave will randomly select a value between the two numbers (never outside the given range). Most of the time, however, the user would wish to give more information about the range, e.g. they might know that the 5-minute end of the range is far more likely to happen than the 30-minute end. They can express this by adjusting the probability graph, specifically by moving the control points higher up on one side of the graph, relative to the other. Given probability graphs, BlueWave will still pick randomly, but the random choice will be weighted according to the graph - in the long run (after several dozen random selections), the probability density graph given by the user emerges. The example probability distributions figure below shows two typical distributions; the top one being a "uniform distribution" (where all values in the range are equally likely) and the bottom one being a "normal distribution" (where the middle of the range is the most likely, and values get rarer as we move towards the edges). For more information, please see: Wikipedia: Probability Density Function.

Example Probability Distributions

Figure: Example Probability Distributions

Work duration estimates: the minimum and maximum duration of work involved for a single work item, as well as a probability distribution for the range. This measure represents the amount of time the activity will take one person away from other productive work. When attempting to collect historical data for this estimate, it is important not to include the amount of time work items spent before being picked up by workers.

Role responsible for work: the group / role name responsible for the actual completion of work for the activity. This assignment disambiguates the K2 destination rule, and ties the activity to a fixed pool of simulated workers. The simulation engine will then wait until a worker from the relevant pool is free, and assign work to them on a "first-in-first-out" basis. The configuration of roles and number of workers is essential to the simulation, and is discussed below.

The relative probabilities for each line: the lines coming out of any given activity are assigned a percentage chance of being followed, and these percentages add up to 100% (for each activity). In this way, it is easy to model requirements such as "60% of the time, an approval takes place, 30% of the time, a rejection takes place, and the remaining 10% is re-work leading to the previous activity".

Roles Collection

A User Roles collection represents a particular configuration of a company and its employees. It defines the names of the various teams or roles in the company and their working hours

Business hours: defines the hours which the business is considered to be "open", or otherwise is expected to be productive. When the duration of activities and processes is measured, it is measured against the business hours defined here. Time falling outside business hours does not count towards any durations or SLAs.

Roles: more accurately defined as a group of people within an organisation. Conceptually, a person should only fall into a single group or role, never multiple roles. This allows the simulation engine to realistically keep track of the availability of employees to do work. Each role is assigned a fixed number of employees, and has its own working hours definition. Up to two shifts (with from and to times) can be defined for each working day.

The separation of concern between the process simulation scenarios and roles collections allows for either to be varied, answering interesting "what-if" questions.

Process Simulations

Finally, a process simulation ties together one or more process simulation scenarios with a single Roles collection. A process simulation is sometimes referred to as a simulation configuration, and can be saved and re-run on demand.

Simulation period: a starting date and simulation duration (in days) is defined. The significance of the starting date is important primarily due to the differences between various weekdays. It is advisable to pick a starting date and duration so that whatever tendency one wishes to study has enough time to emerge. As an example, if we wish to study the build-up of a backlog over several successive weekends, a simulation length of several weeks is necessary.

Random seed: when run, a simulation is a highly randomised and probabilistic series of calculations. The random seed (or simply seed) initialises the random number generator, therefore if it's kept the same, re-running the simulation will result in the same results each and every time. Changing the random seed at all - regardless of how much - will result in completely different set of random numbers for the simulation (although the simulation will still obey the scenarios defined by the user). In some cases and configurations*, variations in simulation results can be large. Therefore, being in control of the random seed is useful for two reasons:

  1. Keeping the seed the same, but varying the process simulation scenario(s) or the roles collection highlights the differences brought by the changes in processes or business (as opposed to just random "luck").
  2. By running simulations under different random seeds, a user can determine the sensitivity of their business to small random changes.

* Random numbers (and thus the simulations that use them) obey the law of averages. If a simulation is modelled which only experiences two process instances per day, any two simulations (with different seeds) are likely to produce wildly different results. One might have two process instances coming in during the early morning, while the other may have one in the morning and one in the afternoon. A simulation involving 200 process instances per day is going to be much more stable and thus appear more "fair". Furthermore, simulations with low numbers of process instances are also more sensitive to large activity duration ranges, e.g. given the previous examples, an activity duration ranging between 5 minutes and 4 hours (a large range) will be far more stable with a large number of process instances. Keep this in mind when running scenarios.

3.5.3Simulation Editor Screen

The simulation editor screen is large and complex, and so has been split into its three major components, the process simulation scenario selection panel (main controls), the roles collection panel, and the scenario editor panel.

Scenario Selection Panel

The scenario selection panel controls the selection of processes (from the current K2 server), as well as the loading or creation of an actual process simulation scenario.

Scenario Selection Panel

Figure: Scenario Selection Panel

  1. Process: allows the selection of a K2 process. Once a process has been selected, existing scenarios for that process are shown in the scenario drop-down, and new scenarios can be created.

  2. Scenario: shows existing scenarios which automatically load when selected.

  3. New Scenario: Creates a new scenario from scratch.

  4. Edit scenario: Edits the currently selected scenario.

  5. Delete Scenario: Deletes the currently selected simulation scenario. No actual K2 processes are deleted, only the Process Simulation scenario is deleted from the BlueWave server.

Roles collection Panel

The roles collection panel is used for loading of roles collections (as well as all their details). Roles collections are a number of roles that configured for the simulation. Each role has a name (e.g. Manager) and certain parameters such as the times they work during the days of the week.

The roles collection panel is also the area from which roles are drag-and-dropped on to the activities in the scenario editor panel.

roles collection Panel

Figure: roles collection Panel

  1. Roles collection: existing Roles can be loaded using the drop-down and load button, or a new roles collection can be created using the new button.

  2. Role list view: All roles in the roles collection are shown here. Individual roles can be drag-and-dropped on to activities in the simulation editor panel (only activities with client events accept this action, however).

Roles Editor Screen

The screen on the roles collection tab allows for the creation, loading, or deletion of roles collections (as well as all their details). It is also the area from which roles are drag-and-dropped on to the activities in the scenario editor panel.

roles collection Panel

Figure: roles collection Panel

  1. The roles editor screen is accessed via clicking the Roles editor tab.

  2. Roles collection: existing Roles collections can be selected and edited using the Simulation Roles Collection List.

  3. New Roles collections can be created by pressing the New Roles Collection button.

  4. Existing Roles collections can be edited by pressing the Edit roles collection button.5.

  5. Existing Roles collections can be completely removed by pressing the Remove Roles Collection button.

  6. Name: the name of the roles collection is shown here. Changing the name is useful for new roles collections, or if you intend on using the "save copy" feature.

  7. Role list view: All roles in the roles collection are shown here. Individual roles can be drag-and-dropped on to activities in the simulator editor panel (not on this screen). Only activities with client events can be allocated roles but all client events require a role for the simulation execution.

  8. The Save button saves all changes to the role collection to the BlueWave server.

  9. Save Copy: creates a clone of the existing roles collection under a new name. The new name should be typed into the Name box. The name should be unique. This feature is useful for creating similar roles collections for experimentation.

  10. Cancel: cancels all current changes to the Role collection. This includes all roles under that collection.

  11. New Role: opens the role editor screen (see below) for creation of a new role.

  12. Edit Role: opens the role editor screen (see below) for editing of the currently selected role.

  13. Remove Role: Deletes the currently selected role from the roles collection.

  14. Change Business hours: Opens the change business hours screen (see below).

Business hours screen

The business hours screen allows the user to specify what hours are considered to be "working hours" in terms of the business. This is done by specifying up to two working shifts per day of week, each defined by a start and end time.

Business Hours Screen

Figure: Business Hours Screen

  1. The day of week. Each day is treated completely separately, since it is possible for businesses to keep different working hours on different days (e.g. including a half-day for Saturdays is common for banks in certain countries).

  2. Is working day - indicates whether the day is considered a working day at all. When ticked, at least one shift has to be specified.

  3. Shift 1, shift 2 - indicates whether the shift is enabled for the selected day.

  4. Shift start / end times. Specifies the start and end of each shift, using a 24-hour time format. The times provided here must follow logical rules, start times must be before end times, shifts cannot overlap at all, and shift 2 must come after shift 1.

Role editor screen

A "role" in the context of BlueWave simulation models a fixed group of people in the business. They also need to be assigned a unique name, and may have a unique set of working hours (typically inherited from the roles collection's working hours).

Role Editor Screen

Figure: Role Editor Screen

  1. Number of employees - the size of the pool of people

  2. Edit working hours - allows editing of the working hours for this group of people, using a screen identical to the business hours screen above.

Scenario Editor Panel

The scenario editor panel shows the selected process, as well as the current simulation scenario. When in edit mode, it is fully interactive, allowing various embedded icons to be clicked, as well as roles to be drag-and-dropped on to activities with client events.

Scenario Editor Panel

Figure: Scenario Editor Panel

  1. Start step - every process has a start activity. In BlueWave simulations, this step carries special meaning, because it is here that the rate at which the process will be started in the simulation is defined.

  2. Edit button for start step - click this to open the scenario start settings screen (see below for details).

  3. Activity with client event - every activity which has a client event needs to have specific pieces of information filled out, in order for the simulation to be executable. These are: the role which will perform this activity (drag and drop the relevant one from the roles collection panel), the duration of the activity, and the probability of its lines being followed. Use the small green arrow to open and close the detail panel.

  4. Duration edit button - opens the activity duration edit screen.

  5. Line probabilities edit button - opens the line probabilities edit screen.

  6. Line probability preview - indicates the probability of a line being followed when the simulation is run.

Scenario Start Settings Screen

This screen configures the number of process instances which will be started for the current process simulation scenario, by specifying a total number and probability distribution for each day of week.

Scenario Start Screen

Figure: Scenario Start Screen

  1. Week overview - shows a quick summary of all the probability distributions in the week.

  2. Total number of instances for week - the sum of all the days' number of instances. It is automatically calculated when any of the days' instance counts are changed by the user. Alternatively, changing the total number itself causes BlueWave to attempt to distribute the new total according to the previous ratios. As an example, if Monday had 10 process instances, and Tuesday had 20, and we triple the total, Monday will now have 30, and Tuesday 60. Rounding errors are a possibility; any remainders are allocated in a left-to-right order of priority.

  3. Settings per day - the detailed process start settings per day of week. Each day of week has its own tab, and can be edited individually.

  4. Number of process instances - the total for the selected day. Changing this value will update the weekly total, while altering the day-to-day ratios.

  5. Time of day probability distribution - this is a probability distribution which describes when process instances are most likely to occur during a simulation. The X-axis represents the entire work-day, from start to end, as defined in the roles collection's business hours. The graph can be altered by clicking and dragging the control points (shown as orange circles on the graph) up and down. Portions of the graph which are relatively higher than the rest represent times of the day during which process instances are more likely to start when compared to portions of the graph which are lower. Next to each control point, a number indicating how many process instances would be started around that time of day (worked out from the day's total) is shown.

Activity Duration Edit Screen

Configures the minimum and maximum duration of an activity, as well as the relevant probability distribution.

Activity Duration Edit Screen

Figure: Activity Duration Edit Screen

  1. Minimum and maximum durations, expressed in hours : minutes : seconds. The duration here is defined as the amount of time one employee will be busy with this activity; it is not meant to include any time the work item itself will spend waiting to be picked up.

  2. The probability distribution graph for the range, using a similar graph as the scenario start settings screen. The left side of the graph represents the minimum time, the right side the maximum time, and the graph itself the relative probability of an instance taking that amount of time to complete.

Line Probability Edit Screen

Configures the relative probability of the various lines being taken. The sum of the percentages here add up to 100%.

Line Probability Edit Screen

Figure: Line Probability Edit Screen

  1. The name of the line.

  2. The probability of this line being followed during a simulation. When the activity is completed, the simulation engine will use this probability to determine which line to follow. In the current version, only a single line can be followed at a time.

  3. Sliders for changing the probabilities. Move the slider to the right to increase it's probability, and left to lower it. Whatever percentage is left over is divided among the remaining lines, proportionally to their current levels.

Edit SLA Groups

A Service Level Agreement (SLA) is a part of a service contract where a service is formally defined. In practice, the term SLA is sometimes used to refer to the contracted delivery time. On the Edit SLA Groups tab, it is possible to configure Service Level Agreement timelines for the purposes of the BlueWave K2 Process Simulations.

Edit SLA Groups Screen

Figure: Edit SLA Groups Screen

  1. Click the Edit SLA Groups tab to enter the SLA configuration screen.
  2. Creates a new SLA Group. A SLA group contains multiple SLAs that will be applicable to one or more Simulations.
  3. Edits the currently selected SLA Group.
  4. Deletes the currently selected SLA Group.
  5. Enter the name of the SLA group here. For example Company X SLAs
  6. Sometimes it is useful to exclude certain processes, so that the SLA group does not apply to them. He we can enter the first part of the K2 Process Full Name, and all processes starting with that name will be filtered out. The SLA group will not apply to processes that fall under the filtered processes, and the SLA lines will not show in the final simulation report for these processes.
  7. Preview which processes have been excluded from the current SLA group.
  8. This grid shows the SLAs in the SLA group. The Name, duration and the colour of the SLA in the final report is shown here. You can also select a SLA entry here by clicking it.
  9. Saves the SLA group and all of the SLAs in the group.
  10. Save a copy of the SLA group by changing the name of an existing SLA Group (using the name box) and clicking this button.
  11. Cancels the current changes in the SLA group. Also cancels any recently added SLAs in the group if the group has not been saved yet.
  12. Create a new SLA in the group. The New SLA popup window will allow for capturing the name, duration and colour of the SLA. E.g. Gold SLA agreement could signify completing the process within an hour.
  13. Edits the currently selected SLA.
  14. Deletes the currently selected SLA from the current SLA Group. Does not make any changes to K2, only to the BlueWave server.

3.5.4Run Simulation Screen

Run Simulation Screen Instances

Figure: Run Simulation Screen Instances

The run simulation screen is used to execute an already pre-configured Simulation definition.

  1. Click the Run Simulation tab to enter the Run Simulation screen.
  2. Select an previously saved simulation to load the simulation.
  3. Create a new simulation when a new simulation is needed.
  4. Edit an existing simulation allows for the editing of an existing simulation that was loaded.
  5. Delete simulation deletes the simulation from the BlueWave server without deleting anything on the K2 server. It removes the selected simulation from the dropdown list (point 2).
  6. Enter the simulation name here.
  7. Select a roles collection that was previously configured. The selected roles must contain roles with the same name that were used to allocate to each client event in the Edit Simulation Definitions tab. There can exist two similar roles collections that vary only by the number of people allocated to each role. This way multiple simulations can be run for each slightly varying roles collection. E.g. One could use this feature to see if 5 managers are enough to handle the workload for the week or maybe we need 10.
  8. Sets the number of days to run simulation for. Experimenting with longer times can help in discovering weaknesses in a process.
  9. Sets the start day of the simulation including the day of the week.
  10. Signifies randomization of work distribution. Set this value to 0 to simulate the same amount of work to enter the simulation every time it is run. Higher values will create more lifelike simulations with variable workload.
  11. The Randomize button renders a new random seed without having to type it in.
  12. Select whether to show or not the Service Level Agreements -which were configured under the Edit SLA Groups- to show in your simulations.
  13. Select the scenarios that were preconfigured in the Edit Simulation Definitions tab. Each selected scenario definition will form part of the simulation.
  14. Saves the Simulation and all its configurations on this screen.
  15. Cancels the current changes to the simulation.
  16. Complies and runs the current simulations. Any simulation errors will show up in the compile errors pane.
  17. In the Results pane, the simulation results become visible after the simulation is executed (ran). The Process Instances tab shows how many K2 process instances executed (Y axis) during the time of simulation (X axis). See below for more.
  18. Exports the all of the simulation results into and HTML format report.
Simulation Results Process Instances

Figure: Simulation Results Process Instances

The Process Instances tab shows how many K2 process instances executed (Y axis) during the time of simulation (X axis). With Gold Silver and Bronze SLA lines showing horizontally. The average number of work completion time is shown in a box and whiskers graph where the box is the average and the whiskers show maximum (top) and minimum (bottom) times the work items took to execute. Boxes or whiskers that are above a coloured SLA line will fail to satisfy that SLA.

The above figure demonstrates that the red SLA fails on day 6 and 7 due to unsatisfactory amount of workers to deal with the amount of work accumulating on the weekend. It also demonstrates that on day 8 the backlog is cleared up.

Simulation Results Process Activities

Figure: Simulation Results Process Activities

The Activities result tab shows the relative time each activity was utilised during the execution of the graph. Red, yellow and green signify bad, mediocre and good results respectively, relative to the execution time.

In above figure, the "Average Idle Time" column demonstrates that the Scanning, Indexing and Evaluation Application Activities of the K2 process were highest idlers. This means that those activities had the longest idling queues of work compared to other Activities of the K2 Process.

The "Average Work Time" column demonstrates that items with a red light spent the most time in the simulation's execution. This value is dependent on what value was configured for the execution of each Activity during configuration. For example if the Average work time on an activity is 8 hours, then 15 minutes of Idle time in relation is not very long.

The "Average Total Time" The average total time shows at which Activity most of time was spent. In the above example the red Activities could be rectified by adding more personnel to the role that is linked to them. Allocating more personnel will optimise the process to run faster and potentially achieve the set goals -Service Level Agreements- in a timely fashion.

Simulation Results Process Roles

Figure: Simulation Results Process Roles

The Results Roles tab shows each Role and how many work items sit in their in box. In the figure the Scanner clerks continue to receive scan items during the weekend but they don't actually work on the weekend. On Day 8 (Monday) they slowly clear the backlog.

3.5.5Limitations

The simulation engine currently does not support a number of features in K2, including:

These features will be addressed in future releases of BlueWave.

At this time, BlueWave also doesn't simulate employee downtime, breaks, delays in searching for and finding work items, etc. In short, it assumes perfect, productive workers who never take a break and work continuously during working hours. While a number of techniques can be used to simulate this type of behaviour (partially discussed below), it is likely that more accurate worker simulation will be implemented in future releases.

3.5.6Tips And Techniques

BlueWave's simulation engine has been designed to facilitate the testing of various scenarios with as little repetitive work as possible. Below are a few basic ideas about how you can use the engine.

Basic Alternate Team Sizes

One of the common questions simulation aims to answer is "how do our team sizes affect our processes". BlueWave facilitates this by allowing a role collection to be selected when the simulation is run; a last minute validation checks that the selected role collection is compatible with all the processes selected. Since role collections can be cloned, it is relatively easy to manage a set of alternate role collections.

Running the same simulation against different role collections can provide valuable feedback regarding optimal team sizes.

Rare Scenarios

In some cases, it is worthwhile simulating how your processes respond to extraordinary events, such as an unexpected influx of work. As with the basic alternate team sizes advice, it is a good idea to make use of the clone functionality to make a copy of an existing simulation definition, and to provide it with alternate process start settings. One example would be to create a "normal week" scenario, and an "unexpected weekend work" scenario. By keeping these separate, we can run a simulation for the normal week alone, and compare it to a simulation where both the normal week and the weekend work is enabled.

3.6Configuration

The configuration module contains important settings related to K2, namely environments and projects:

It is useful to note that the above settings are stored on a given BlueWave server, and shared between users connecting to that server. BlueWave generally stores all of its settings and data on the BlueWave server, allowing a team to collaborate and re-use existing settings and definitions.

3.6.1Configuration: Environments

An environment is information about how to connect to a K2 server environment, as well as a descriptive name for that server. The K2 server name and ports are required, as well as connection information for the K2 DBs.

Environments can be edited via the configuration module:

Configuration - Environments

Figure: Configuration - Environments

  1. Configuration Tab: Select the Configuration tab to configure K2 environments.
  2. Environment Side Tab: Opens the environments configuration screen.
  3. Add / Edit / Delete Buttons: Allows for adding, editing or removing of K2 environments.
  4. Environment Name: The name of the K2 environment. It is recommended to use descriptive names such as "Development", "Staging", "Pilot" and "Production".
  5. K2 Server: The machine name of the K2 Server (or its IP address).
  6. Host Service port: The K2 Host Service port. Default is 5555.
  7. Workflow Service port: The K2 Workflow Service port. Default is 5252.
  8. Authentication Type: Choose between the two authentication types available (see authentication types: additional information for more information):
    • Impersonate: The default setting, under which BlueWave will connect to K2 using the current Windows user's credentials.
    • Service Account: This specifies a single "service account" which BlueWave will use to connect to K2.
  9. K2 Security Prefix: The K2 Security Prefix is normally defaulted to "K2" but can be set to any security prefix your K2 server has been configured with.
  10. Service Account Username: The user name to be used when connecting to K2 if the authentication type is set to "service account".
  11. Service Account Password: The user password to be used when connecting to K2 if the authentication type is set to "service account".
  12. SQL Server: The SQL Server machine and instance names where the K2 DB is hosted. E.g.: K2DEV or K2DEV\SQL2008.
  13. Integrated Authentication: To enable the current user to be used for SQL security access.
  14. SQL Username: The SQL username for connecting to the K2 SQL server if integrated authentication is not used. Please note that the username specified here must be a valid SQL Server Authentication login, and cannot be a Windows / domain account.
  15. SQL Password: The SQL password for connecting to the K2 SQL server if integrated authentication is not used.
  16. Save: Saves the current environment.
  17. Cancel: Cancels editing without saving any changes.
  18. Test Connection: Confirms whether the environment is correctly configured by trying to connect to the K2 server as well as the K2 DB. It is recommended

Authentication Types: Additional Information

The authentication types available determine how BlueWave connects to K2 via the K2 APIs:

Configuration - Environments Service Accounts

Figure: Configuration - Environments Service Accounts

As mentioned above, the impersonate setting defaults to connecting with the current Windows user, while the service account setting will use the username and password provided. If the connection using the default settings (either impersonation or a specific service account) succeeds, BlueWave will start up and behave as expected. If the connection does not succeed, the user is presented with a K2 user credentials dialog:

K2 User Credentials

Figure: K2 User Credentials

This dialog allows the user to override the default settings for the environment, and either connect using impersonation, or provide a different username and password combination. If the connection is successful at this point, BlueWave will start up as expected, and the user's credentials are stored locally by BlueWave (albeit encrypted using the Windows Data Protection API). On subsequent startups, BlueWave will show this dialog again if the default credentials fail, but with the user's custom credentials pre-populated.

The above mechanism of having a default that's overridable by the user allows for reasonable defaults for the team (e.g. "impersonate" using each user's domain accounts), while still catering for edge cases (one user who is not on the domain, and specifies a username / password manually).

3.6.2Configuration: Projects

In BlueWave, projects are groupings of K2 processes, allowing various functionality to conveniently select all the processes at once. There are two main types of projects (differentiated by where they are stored), each with their own strengths:

Projects can be configured using the projects configuration screen:

Configuration - Projects

Figure: Configuration - Projects

  1. Projects Side Tab: Opens the projects configuration screen.
  2. Add / Edit / Delete Buttons: Allows for adding, editing, and removing of BlueWave projects.
  3. Project Name: The logical name of the project. The name does not necessarily have to tie up with the location or namespace filter, although it's a good idea to keep it descriptive (e.g.: if we wanted to group all projects under the folder "CompanyA" together then we can name the project "CompanyA").
  4. Project Default Local Path: A specific folder on the drive where the .k2proj file can be found which we want to work with.
  5. Project Full name start with: Allows the selection of a number of Projects under a specific K2 Project folder. For instance, if we wanted to work with K2 Processes which are located under a specific folder, we can use "CompanyA" as a start with. If we only wish to select a single project we can type its k2 full name e.g. "CompanyA LeaveRequest".
  6. Preview: Opens a popup screen to display which K2 Processes are encapsulated in the project.
  7. Filter: Displays the "Project Full name start with" with value "CompanyA LeaveRequest" as selected on the parent screen.
  8. Folder CompanyA: The K2 folder from the K2 server.
  9. K2 Process: LeaveRequest: The K2 Process from the K2 server.
  10. Refresh: Displays the K2 Processes that are encapsulated in the current Project.
  11. Close: Closes the current window.
Configuration - Projects2

Figure: Configuration - Projects2

4.Design

The architecture overview section gives an overview of the architecture of BlueWave - what the major components are, and how they fit together. The installation and deployment section goes over typical installation scenarios, and sets out various guidelines and tips.

4.1Architecture Overview

The main components of Archon BlueWave are the front-end and the server. The front-end is the primary user interface for BlueWave, while the server is simply a support component used for license management and storage.

4.1.1BlueWave Server

At least one BlueWave server installation is requied in order for the BlueWave front-ends to function. Typically, one server installation is needed per network where you will be using BlueWave. The entire server component can be further broken down into the BlueWave service and its management tool, known as the BlueWave Service Manager.

BlueWave Service

The Archon BlueWave Service is a Windows Service which is responsible for:

The BlueWave Service can be found under Services as "Archon BlueWave Service":

Services Snap-In

Figure: Services Snap-In

The service needs to be running for the front-end to work correctly; for this reason, it is recommended that the default startup type of "Automatic" be kept. By default, the service is installed to run under the Local System security profile.

When running, the service listens for incoming connections from BlueWave front-ends and the Service Manager on port 8555. It does not communicate with the K2 server at all.

BlueWave Service Manager

The BlueWave Service Manager is a basic tool primarily used for managing BlueWave licenses.

The topic of licenses is covered in more detail in the license request section.

The BlueWave Service Manager can be used to:

4.1.2BlueWave Front-End

The BlueWave front-end is where the core of the BlueWave suite. It is connects to the BlueWave service during start up, as well as one K2 server. The connection to K2 server involves a number of simultaneous connections, all of which must be working for the BlueWave front-end to be fully functional:

* BlueWave has been designed from the ground-up around the various K2 APIs. In a small number of cases, BlueWave makes use of read-only SQL queries to obtain information from K2, where no appropriate K2 API solution was available.

4.1.3Connections and Ports

Conceptually, the following high-level connections take place in BlueWave:

Architecture: Connections

Figure: Architecture: Connections

If you are having trouble connecting BlueWave to any of the necessary services, please verify network connectivity (firewall rules, etc), as well as the ports configured by administrators:

4.2Installation and Deployment

The main questions around the installation and deployment of BlueWave are around the BlueWave server, namely: where to install it, how many of them to install. In order to work, the BlueWave front-end needs to able to connect to a BlueWave server (for licensing and storage needs), so this is a primary concern. Having said that, having multiple BlueWave server installations can mean an administrative burden (as each BlueWave server needs to go through the license request process), and also makes collaboration via BlueWave more difficult.

Therefore the best strategy will depend on the type of environment and typical usage scenario, and whether collaboration is important to the user. In short, for most cases, we recommend a team-oriented installation (a single BlueWave server), while for highly mobile scenarios an individual-oriented installation (a BlueWave server for each mobile user) may be more appropriate.

4.2.1Team-Oriented Installation

If you have a single physical network (or a small number of fixed networks*), you should try to install one BlueWave server only (or one for each separate network, if necessary). This will cut down on the amount of BlueWave server administration you have to do, and simplify the license request process. Furthermore, BlueWave has several collaborative featues which are hosted on the server (e.g. process start scenarios, test cases, snapshots, etc.), and these will not be shared across BlueWave servers.

* A "network" here is meant to indicate network boundaries that cannot be crossed due to physical limitations or firewall rules. A complex network infrastructure over a WAN may still be considered a "single network", as long as the BlueWave server is reachable from the clients.

Deployment: Team-Oriented

Figure: Deployment: Team-Oriented

In the above diagram, a company with two completely separate networks ("development" and "production"), has several BlueWave users in the development network, and a single installation in the production network. The simplest team-oriented installation strategy here is to install a single BlueWave server for the devlelopment network, and one for the production network.

4.2.2Individual-Oriented Installation

In cases where you have a laptop or mobile workstation and you switch between company networks frequently, you may consider having a local installation of BlueWave server. This will allow you to use BlueWave on any network you connect to, because your local server will always be readily available. The downside of this type of installation is the additional administrative burden (each such "mobile" server installation will need to go through the license request process), and you lose all collaborative featues.

Deployment: Individual-Oriented

Figure: Deployment: Individual-Oriented

The above diagram shows a typical individual-oriented installation. The BlueWave server is installed on the local machine (typically a laptop), which can then easily move between various company networks, and remain functional without any further effort.

5.Frequently Asked Questions

Q: I found a bug! What do I do?

Please report it so that we can fix it! See the reporting bugs and issues section for more details.

Q: I'm having trouble installing / starting BlueWave

First, please make sure your software environment meets the system requirements, primarily the software prerequisites and permissions. Follow the installation and first run instructions, which reference the troubleshooting guidelines.

If that fails, contact us at:

support@archonbpm.com

Q: What about feature X?

If you have ideas on how to improve the software, we'd love to hear from you! The usual email address of support@archonbpm.com can be used.

Q: Will there be more support for SmartObjects and SmartForms?

Yes! SmartObject support is going to be added to all critical areas of BlueWave (worklists, etc). We are also looking to add both SmartObjects and SmartForms support to the documentation generation module shortly. These are likely to appear after the 1.0 release, but before a 2.0 release.

6.Reporting Bugs and Issues

First, thank you for taking the time to use our software, to find bugs and issues, and reporting them! We really appreciate the opportunity to make our product better.

If you are need help regarding how to install, configure or work with BlueWave, please consult the troubleshooting section section first. If you are unable to resolve the issue, consult the contact information section about how to contact support.

6.1Contact Information

The general support email address for BlueWave is:

In case of a crash the system logs the error into the tray icon from where it is possible to upload the error to the K2 error service online. It will help us with identification of the error.

If you have any specific question simply email us a description of the problem. We will contact you via email (or phone, if you prefer) to follow up on the issue (we may need further information, or an example process, etc).

6.2What Information Do I Include In An Error Report?

BlueWave goes through extensive testing, and we try to make sure that crashes and other unexpected behaviour is very rare. In many cases, errors stem from differences in environment or usage of BlueWave. To help us identify the source of problems, please try to provide us with as much information as you are able. Some specific suggestions for good error reports:

7.Troubleshooting

This section is intended to help when problems occur with BlueWave. The general advice section covers basic information about BlueWave, how to find relevant information, and what the general troubleshooting process looks like. The next section deals with a number of specific problems you may encounter.

7.1General Advice

This document is the primary source of information about BlueWave, and should allow you to understand the processes and normal behaviour of BlueWave. When troubleshooting any problems, it usually helps to have a good understanding of the application. The background reading section is intended to point you to the relevant parts of the documentation.

The help systems in BlueWave section discusses the two built-in help mechanisms available.

7.1.1Background Reading

Prior to installation, you may wish to read the installation and deployment section, which explains the two main ways of deploying and licensing BlueWave.

If you are having trouble installing and getting BlueWave to run, the getting started section has a wealth of information about system requirements, installation, requesting and installing a license, locating and entering named licenses, as well as what to expect on your first run. The typical use section simply gives some ideas to get you started.

If you are having problems post-installation, it may be a good idea to check the modules section relevant to your problem. Each major functionality group in BlueWave has its own section. The design section gives further information about how the components of BlueWave and K2 fit together, and the various types of communication that takes place between them.

7.1.2Help Systems in BlueWave

There are two types of embedded help systems in BlueWave, the first being links to documentation. At specific points in the application, you may see a link similar to the one below:

Troubleshooting: Links to Documentation

Figure: Troubleshooting: Links to Documentation

Clicking these links should take you to the relevant section in this document, so it is advisable to make use of them, unless you're sure of what to do next.

7.1.3Contacting Support

If you have not been able to resolve your problem using this guide, or simply have recommendations about how to improve it, please see the contact information section.

7.2Specific Problems

This sections contains discussions of several specific issues which may occur during the installation or day-to-day usage of BlueWave. For each problem, background information or links to relevant sections is provided, or a series of steps to identify and troubleshoot the problem. The issues documented are:

7.2.1Installer: K2 Client Components Required

BlueWave requires the K2 client components to be installed in order to successfully connect to K2 (please see software requirements under system requirements for more information). Possible solutions are:

7.2.2BlueWave Starting Up: Cannot Connect to BlueWave Service

During start-up, the BlueWave client attempts to connect to the last used BlueWave server (for new installations, the default is localhost). If this connection cannot be made, the following screen is shown:

Troubleshooting: Connect to BlueWave Server

Figure: Troubleshooting: Connect to BlueWave Server

If this is the first run of BlueWave, and your BlueWave server is on another machine, simply type in the name (or IP address), and click connect. If the problem persists, diagnose the problem using the following steps:

7.2.3BlueWave Starting Up: No Licenses Available

During the starting up of the BlueWave front-end a connection is made to the BlueWave service, at which point a valid license is required. You may see the following message on the splash screen:

Troubleshooting: No Licenses Available

Figure: Troubleshooting: No Licenses Available

Troubleshooting this problem will depend on whether you are working with a new installation of BlueWave, or an existing one:

7.2.4BlueWave Starting Up: Named Licenses

If the BlueWave server has been configured with a named license, the BlueWave front-end will ask the user to enter a license key:

Troubleshooting: Named License

Figure: Troubleshooting: Named License

You will need to obtain a license key from the BlueWave server using the Service Manager application, and enter it here. The named licenses section contains information about how to do this.

7.2.5BlueWave Starting Up: Cannot Connect to K2

Connecting to the K2 is the third and last step during the startup of BlueWave. A number of connections are made, and some information is cached from K2. For this reason, it must be possible to not only connect to K2 physically, but to also have the various permissions necessary to complete the initialisation. Some of this information is also available in the Architecture Overview section.

Connection Requirements

BlueWave must be able to physically connect to:

Security Requirements

Miscellaneous Requirements

BlueWave makes use of the K2 client installation on the machine that it's being run from. If K2 is not installed, or is of a different version to the target K2 server, the connection will likely fail.