How do I use it? - K2 ANZ · 2016-07-21 · HOW TO USE SPRINGBOARD FOR K2 5 | P a g e OPENING A WORKLIST ITEM When opening a K2 worklist Item, included in the URL (as part of the

HOW DO I USE IT?

Springboard for K2

SourceCode ANZ

How to use Springboard for K2

An outline of the architecture of Springboard for K2 and how to use it

HOW TO USE SPRINGBOARD FOR K2

1 | P a g e

CONTENTS

Introduction ................................................................................................................ 2

I deployed Springboard for K2, now what? ............................................................................ 2

Springboard for K2 Dashboard ........................................................................................... 3

The Architecture of Springboard for K2 ............................................................................... 4

Starting a New Instance ............................................................................................... 4

Opening a Worklist Item ............................................................................................... 5

Using the Templates ...................................................................................................... 5

Creating a New Form ................................................................................................... 6

Common Views ....................................................................................................... 8

K2ANZ.Framework.Template ....................................................................................... 13

K2ANZ.Framework.Template.StartProcessPage ................................................................. 14

K2ANZ.Framework.Template.ActionWorkItemPage ............................................................ 17

Administrative Functions ............................................................................................... 20

Administration ........................................................................................................ 20

Application .......................................................................................................... 20

Application Category .............................................................................................. 21

Help Text ............................................................................................................ 22

Key Value ............................................................................................................ 23

Key Value Category ................................................................................................ 23

Status ................................................................................................................ 24

Exception Log ......................................................................................................... 25

New Exception Log Items ......................................................................................... 25

Existing Exception Log Items..................................................................................... 25

Profile Maintenance .................................................................................................. 26

Application Actions ................................................................................................... 27

Set Background Image ............................................................................................... 27

Select Existing Image .............................................................................................. 27

Upload Custom Image ............................................................................................. 28

K2 Object Explorer ................................................................................................... 29

K2 Management Worklist ............................................................................................... 29


2 | P a g e

INTRODUCTION

Springboard for K2 provides a framework with building blocks to assist with the rapid creation of

applications using reusable components.

In this document, we will explore the architecture of Springboard for K2, along with a step by step

guide to create a new standalone application, along with creating an application that integrates with a

K2 blackpearl workflow process.

Springboard for K2 includes the following:

Dashboard and Process Tracking Interfaces

Workflow components and general reusable Views

Transactional and system SmartObjects

Task allocation and Purchase request processes

A Custom Management Worklist

K2 Object Explorer

The two working business processes offered with Springboard for K2 could be used “as-is”, or as a

base for more customized solutions.

Using the Task Allocation Process, you could validate the installation of a new K2 environment in a

matter of minutes. This process tests some of the key areas used within K2 – K2 SmartForms and

SmartObjects, workflow processes, email integration, the K2 worklist and K2 reporting capabilities.

Benefits of using Springboard for K2

• Immediate return on investment

• Instant capability to test a new K2 environment

• Provides customers with a unified and best practise approach for building K2 SmartForms and

workflow

• Rapid acceleration of K2 SmartForm development for all K2 projects

• Out of the box features, reporting and processes

For more details about the components included with Springboard for K2, please read the Bill of

Materials document found on http://www.SpringboardForK2.com.

I DEPLOYED SPRINGBOARD FOR K2, NOW WHAT?

At the end of deploying the Springboard for K2 package, the K2 Package and Deployment tool will

navigate to the “Set Background Image” screen. You can get back to this screen at any time in the

future from the Springboard for K2 Portal.

This screen requires to you select one of the preset background images, and then click “Save and

Close”, once done. This will navigate you to the main Springboard for K2 Dashboard.

Should you wish to add your own background image, please see the section below: “Adding Custom

Background Image”

http://www.springboardfork2.com/


3 | P a g e

To manually find the Main Dashboard, open any browser window, and browse to the following URL

(replace the [Runtime Site URL] placeholder with the appropriate value):

[Runtime Site URL]/Runtime/Runtime/Form/K2ANZ.Framework.Dashboard/

You could also find the Main Dashboard deployed here:

SPRINGBOARD FOR K2 DASHBOARD


4 | P a g e

THE ARCHITECTURE OF SPRINGBOARD FOR K2

Before continuing, it’s important to understand the architecture of Springboard for K2.

These functions are available within Springboard for K2:

custom reporting

data auditing

activity log

security

error reporting

background image

In order to use these functions, you will 1) need to register an Application with Springboard for K2,

and 2) start an Application Instance based on the registered Application’ GUID.

When an Application is registered (see Administration section below), a new entry is made to the

K2ANZ.Framework.Master.Application SmartObject (Application SmO). There are various properties for

this SmartObject, but the key is the Application ID which is a GUID.

STARTING A NEW INSTANCE

On the Dashboard, the applications are listed under the Registered Applications list. When a user clicks

on one of these applications, they will navigate to this application form. Included in the URL (as part of

the query string) will be a parameter Application Id. This is the GUID of the registered application.

The Application page (to which the user just navigated) will use the Application Id to do the following:

Populate the Header with information of the Application (title, description)

Determine any security that’s applied to this application

If applicable, when a new instance of the Application is started (e.g. a new Purchase Request

instance), the Application Id will be used to add a new entry to the

K2ANZ.Framework.Transaction.Application.Instance SmartObject (Application Instance SmO)

Please note the following:

If there is a custom K2 SmartObject involved (e.g. Purchase Request SmartObject), it’s advised

that the newly created Application Instance ID be saved as a property to the customer

SmartObject.

In turn, the custom SmartObject’s ID is to be saved to the Application Instance SmO’s

BusinessObjectID property.

If there is a K2 process involved, the K2 Process Instance ID should be saved to the

K2ProcessInstanceID property of the Application Instance SmO.

o Take note that it’s important that the K2 Process has a reference to the Application

Instance ID, should you need the process to add new Business Audit and Transactional

data. However, this is optional.


5 | P a g e

OPENING A WORKLIST ITEM

When opening a K2 worklist Item, included in the URL (as part of the query string) will be a parameter

SN. This is the K2 worklist Item Serial Number.

The K2 smartform View called K2ANZ.Framework.Workflow.TaskAction.Item has been configured to

accept SN as a parameter. The View’s Initialize-rule has been configured to open the Worklist Item and

retrieve the required information.

Using the Serial Number, the view is able to open the worklist item and retrieve the K2 Process

Instance ID (A). Using the K2 Process Instance ID, the rule then retrieves the ApplicationInstanceID and

BusinessObjectID properties from the Application Instance SmO (B). They are saved to the

corresponding parameters of the View.

If you do not require returning data field values from your K2 Workflow Process to your K2 SmartForm,

you need not make any changes. However, should you require to return data from your process, it’s

advised that you overwrite the event (A) on the form rules. Please ensure that the event is set up in a

similar way as the original, and add what you need.

USING THE TEMPLATES

Springboard for K2 has three templates available which will cover all scenarios where you might wish

to create an application for that interacts with Springboard for K2.

The templates are available here:


6 | P a g e

CREATING A NEW FORM

If you wish to use any of the templates, do not edit the original. Use the Save As function to create a

new Form which will inherit all the pre-built functionality.

You will only need to make changes to the Name, Description and the category where the Form must

be generated. You will not need to clone any of the Views.

Before you start working on your form, it’s recommended that you first create all the Views you wish to

use on this form. These are Views that are specific to the solution you’re building. E.g. if you want to

build a new Expense Claim application, you’ll need to create the Item View to capture the Expense

Claim Details and the List View for the line items.

Next, when you start editing the Form, first remove the items that are not required:

Information Label at the top of the form


7 | P a g e

Any place holder Views

There are a few specific rules which will need to change; we’ll discuss those for each individual

template below.

However, the common items applicable to all forms are the following:

1) Help Button (see image above)

If you wish to configure help text, see Administration below. To apply configured help text to

the Help Button, configure the rule behind the “Help” picture. The SmartObject event is

already set up; all that needs to be done is that it should be configured to point to the correct

configured help text.

If you do not wish to have the help button on the form, simply remove it.

2) When Form is in Error-rule

This rule is available on all forms. Due to an issue that’s currently present in K2 blackpearl

4.6.11 (and earlier), you will need to reconfigure the rule as indicated below:


8 | P a g e

When configuring the rule, you’ll notice that there is an Unresolved Item. Remove this item,

and replace with the Form Name value (as indicated in the image below).

You are also welcome to replace the value sent to the ExceptionLogSourceSubDetail and other

properties should that make more sense to your environment.

COMMON VIEWS

On each template, you’ll find the following Views and Data Label


9 | P a g e

(Note that the K2ANZ.Framework.Application.Access View is not on the

K2ANZ.Framework.Template.ActionWorkItemPage Form Template.)

Apart from the View containing the buttons, no additional configuration is required.

HEADER (K2ANZ.FRAMEWORK.HEADER.ITEM)

This View displays the current logged on user’s information, along with information based on

the Application Id. It is possible to overwrite the data displayed in the header by configuring

the View’s Initialize Event on the Form Initialize Rule.


10 | P a g e

Setting the Application ID parameter, will cause the form to load the Form’s title and

description from the Application SmO.

If you choose not to load information from the Application SmO, you can omit the Application

ID parameter, and supply an Unbound Title and Description Value.

Setting the “Hide Home Link” value to False, will hide the link which users can click on to

return to the Springboard for K2 dashboard.

If “Set Page Title” is set to True, the browser’s title will be set to the same value as the

Header’s title.

BUTTONS (K2ANZ.FRAMEWORK.SUBMITBUTTONS.ITEM)

This View contains the three most common used buttons on most applications:

Save as Draft

Submit

Cancel

By configuring the View’s Initialize Event on the Form Initialize Rule, you can manipulate which buttons

are visible when the form loads.


11 | P a g e

Note that there’s a “Parameter Change Event” that’s associated with each of the parameters

responsible for hiding or showing the buttons. Should you wish to change the visibility of these buttons

during the life cycle of the form (e.g. hide or show buttons based on selections made on the form), you

can simply set the parameter values of the View. Internally, the View will take care of hiding and

showing the buttons.

Setting any of the “Show”-parameters to False, will hide the button. The default setting is to be

True, so if no value is supplied, the buttons will be displayed.

The “On Cancel Navigate Back” parameter will inject a piece of Javascript on the form when the

Cancel button is pressed that will mimic the “Back” button of the browser itself. The default of

this property is False – if no value is specified, the Cancel button will not mimic the browser’s Back

button.

You should likely need to overwrite the different buttons’ click-events on the Form depending on the

behavior you require.

FOOTER (K2ANZ.FRAMEWORK.FOOTER.ITEM)

The Footer will simply display the version of Springboard for K2 that’s currently deployed to your

environment. There is no configuration available for this view.


12 | P a g e

BACKGROUND IMAGE (K2ANZ.FRAMEWORK.BACKGROUNDIMAGE.LOAD.ITEM)

This View will load the selected background image to the form. There is no configuration available for

this view.

ACCESS (K2ANZ.FRAMEWORK.APPLICATION.ACCESS)

This rule regulates access to a form based of the security configuration that’s set in the Administration

section of the Dashboard – the setting of this is described later in this document.

Note that this View’s Initialize event is the very first event to be executed on the Form Initializing

rule.

Configuring this rule will allow the form designer to determine what should happen on a failed access

attempt

Application Access is based off the Application ID – this parameter is set based on the

Application ID that’s set on the Form Parameter, and should not be changed.

The “On Access Fail Redirect to Portal” parameter is used to determine what should happen on

a failed access attempt.

o Users will receive a message to indicate that they do not have access to this

application.


13 | P a g e

o If the parameter is set to True (the Default setting), the user will be redirected to the

Springboard for K2 Dashboard immediately before anything else is loaded on the form.

No additional configuration is required.

o If the parameter is set to False, the user responsible for designing and configuring the

Form will have to overwrite a View Rule and extend it to perform the custom action

that’s required (e.g. log to a database, navigate to a different URL, load only selected

data on the form, etc.).

This is the rule which needs to be overwritten:

You’ll notice that there is a “Transfer Data” event that’s commented out,

along with a comment which indicates that this is where the rule should be

overwritten.

Add your custom event in this IF-Statement block as indicated by the arrows

above.

K2ANZ.FRAMEWORK.TEMPLATE

This template is used as a Stand Alone Application which doesn’t have a K2 Workflow Process

associated with it.

Apart from what was mentioned above, herewith the changes that will be required from you:

1) Drop your own custom View(s) onto the Form. It’s recommended that the Views be placed

between the Header View (K2ANZ.Framework.Header.Item) and the View which contains the

re-usable buttons (K2ANZ.Framework.SubmitButtons.Item) – see image below.


14 | P a g e

2) Next, configure the Form Initialize Rule and move your View’s Initialize event into the

appropriate position and configure the View as required.

3) Next, configure the other rules as indicated in the “Common Views” section above.

4) Add Rules for Button Click Events as required.

a. Keep in mind that you have different buttons available on the form and you would need

to configure these to work for your particular form.

K2ANZ.FRAMEWORK.TEMPLATE.STARTPROCESSPAGE

This template is used to start a K2 workflow process.

Apart from what was mentioned above, herewith the changes that will be required from you:

1) Drop your own custom View(s) onto the Form. As before, it’s recommended that the Views be

placed between the Header View (K2ANZ.Framework.Header.Item) and the View which

contains the re-usable buttons (K2ANZ.Framework.SubmitButtons.Item) – see image below.

Remember to set the View’s properties on the Form – such as its ability to collapse, its heading

etc.


15 | P a g e




4) Lastly, you’ll need to configure the Form Rule for the Submit button


16 | P a g e

A: Configure the form validation rules

B: This TRANSFER DATA event must be replaced by the Event Method\SmartObject method responsible

for creating\saving the business object (e.g. the Purchase Request CREATE method).

The Output ID from the above to be saved in the form parameter Business Object ID (note that you can

rename this parameter to something more meaningful, but then be reminded to reconfigure all of the

following wizards).

C: Create the Application Instance Entry. The newly created Application Instance ID should be stored in

the applicable form parameter (Application Instance ID).

D: Start your K2 process and set the values as required. The Process Instance ID must be saved to the

applicable Form Parameter (K2 Process Instance ID).

In this template, it starts the generic Task Allocation Process - please change this according to your

requirement.

E: In this step, the Application Instance is updated with the newly created process instance Id. You do

not need to reconfigure this Event.

F: Add an entry to the business audit table for reporting. Update this with applicable information.

G: Change the message that’s shown to the user once the form has been submitted.

No additional changes are required on this Form.


17 | P a g e

K2ANZ.FRAMEWORK.TEMPLATE.ACTIONWORKITEMPAGE

The “Action Work Item” template does not contain the Access view. The reason for this is because a K2

worklist item can be assigned to any user, and the security of the worklist item is inherent from the K2

Process permissions.

There is an additional view responsible for displaying a combination of Application and K2 Process

information based on the Application Instance ID. This Process Information View

(K2ANZ.Framework.ActivityInstance.Item) is located below the Header View and no configuration is

required.

Another specific view responsible for interaction with the K2 Workflow Process is placed on the form

just ahead of the Buttons View. This Task Item View (K2ANZ.Framework.Workflow.TaskAction.Item)

need not be configured, unless there is a specific need to do so. More information provided below.

Apart from what was mentioned before, herewith the changes that will be required from you:

1) Drop your own custom View(s) onto the Form. It’s recommended that the Views be placed

between the Process Information View (K2ANZ.Framework.ActivityInstance.Item) and the Task

Item View (K2ANZ.Framework.Workflow.TaskAction.Item) – see image below.

Remember to set the View’s properties on the Form – such as its ability to collapse, its heading

etc.


18 | P a g e




4) Should your process not require Attachments and\or Comments, you’ll need to configure the

K2ANZ.Framework.Workflow.TaskAction.Item View’s Initialize Event on the Form Initialize

Rule.

To hide the display of the Comments or Attachments, simply set the appropriate parameter to

False. Note that leaving the value empty defaults the value to True.

You will also need to hide the specific List View on the form responsible to showing the

previous comments and attachments.

5) If you require returning data from a data field specific to the K2 workflow process, you will

need to overwrite the Initialize Rule of the Task Item View

(K2ANZ.Framework.Workflow.TaskAction.Item) – for more information, please visit the section

entitled Opening a Worklist Item earlier in this document.

6) Lastly, you’ll need to configure the Form Rule for the Submit button


19 | P a g e

A: Configure the form validation rules

B: This TRANSFER DATA must be replaced by the Event Method\SmartObject method responsible for

creating\saving the business object (e.g. the Purchase Request UPDATE method).

The Output ID from the above to be saved in the form parameter Business Object ID.

C: If required, set the Application Instance's Stage Gate. HOWEVER: it is recommended that this be

done as part of the workflow process rather than doing it here, hence why this rule is disabled.

D: Execute the Worklist Item. This is using an Unbound View Rule. Should you require sending

information back to the K2 process, you will need to overwrite this rule on the Form level.

E: Add an entry to the business audit table for reporting. This needs to be configured.

F: Change the message that’s shown to the user once the form has been submitted.

No additional changes are required on this Form.


20 | P a g e

ADMINISTRATIVE FUNCTIONS

ADMINISTRATION

Each of the maintenance areas allows you to perform different functions.

APPLICATION

Here you register and maintain registered applications. All applications registered here will be listed on

the Springboard for K2 Dashboard.


21 | P a g e

A: After providing a Title for Application, an Icon of the Application (to be displayed on the Dashboard

Application List) needs to be added.

A collection of application icons are available with the Springboard for K2 ZIP-file (Springboard for K2

Version 3.0.zip) in the Extra\Application Icons folder.

B: The new registered application can be a K2 smartform, or simply a link to any URL. Should this be a

K2 smartform, select the checkbox and provide only the K2 smartform name. When the checkbox is

selected, the user will be able to search for a form using the Search-icon.

C: Select a category under which the application will be listed on the Dashboard.

D: It is possible to disable Applications by selecting the “Close” option.

E: Additional information can be added to the application. This is not used by Springboard for K2, but

is available by means of the Application SmO and can be used on custom forms\applications.

APPLICATION CATEGORY

Here you add and maintain applications categories. All categories added here will be listed on the

Springboard for K2 Dashboard and available to link application to.


22 | P a g e

HELP TEXT

Springboard for K2 allows you to add and maintain help text that can be used in custom forms without

the need to create your own Help Text SmartObjects and Maintenance Screens.

The Help Text maintenance is broken up in three parts:

A: This section lists the available Help Text components – select an item here to edit it is section B.

Each Help Text Item’s GUID is available in this list – the reason for this is to allow the developer to get

to the GUID to use this with the Help Text SmartObject (K2ANZ.Framework.Master.HelpText) – the

SmartObject can be found here:

B: Section to add and edit Help Text information.

C: The Help Text Register is used to add “friendly” names to a single Help Text item. The reason is

that you might need to do this, is that you want to reuse a single piece of Help Text on multiple forms,

each form with a different description.


23 | P a g e

KEY VALUE

We have noticed that many solutions require a Key-Value list. As a result, we included a Key-Value

SmartObject and Maintenance Areas. The Key-Value pairing can be grouped together using the Key-

Value Category (see below).

The Key-Value SmartObject (K2ANZ.Framework.Master.KeyValueSetting) can be found here:

KEY VALUE CATEGORY

The Key-Value Category is used to categorize Key-Value settings (see above).


24 | P a g e

STATUS

The Status SmartObject (K2ANZ.Framework.Master.Status) can be used by custom applications to list

statuses. The SmartObject can be found here:


25 | P a g e

EXCEPTION LOG

Springboard for K2 logs all exceptions that might occur. Please see When Form is in Error-rule on

Creating a New Form section earlier in this document for the settings that needs to be applied on the

forms to log any error on the forms.

NEW EXCEPTION LOG ITEMS

All new exceptions will be available on the New Exception Log Items list. The Errors must be

acknowledged before being moved to the Existing Exception Log items.

Clicking on an exception item, details of the exception is displayed below.

EXISTING EXCEPTION LOG ITEMS

All existing exceptions that have been acknowledged on the New Exception Log Items list are displayed

in the Existing Exception Log Items.

Clicking on an exception item, details of the exception is displayed below.


26 | P a g e

PROFILE MAINTENANCE

Springboard for K2 allows for Profiles to be set up. If an Administration Profile exists that has at least

one user associated with it, only users linked to this profile will be the only ones that has access to the

Administration items on the Springboard for K2 Dashboard.

Similar to this, as soon as an Application is linked to a Profile that has at least one user, only users

linked to the profile will be able to access the application.


27 | P a g e

Note that if a user doesn’t have access to an application, the Application will not be visible on the

Dashboard. If the user attempts to connect to the page directly, access will be denied. See Access

(K2ANZ.Framework.Application.Access) section earlier in this document.

APPLICATION ACTIONS

It is possible to prevent users to perform specific actions on a Springboard for K2. This will not allow

users to select specific actions on the Task Item Form.

SET BACKGROUND IMAGE

SELECT EXISTING IMAGE

Select one of the items in the drop down list. Note that this image will be applied for all users that use

Springboard for K2.


28 | P a g e

UPLOAD CUSTOM IMAGE

To upload you own custom image, you will need to select the Custom image item in the Background

image list and click Save and Close.

Next, opening the K2 Designer, edit the View K2ANZ.Framework.BackgroundImage.Set.Item (see below

for location)

Select the Custom Image, and then change that to your own image by editing the Image Source.

It might be a requirement to reset IIS before the change is visible to clients.


29 | P a g e

K2 OBJECT EXPLORER

The K2 Object Browser is a valuable tool for K2 Administrators and Developers to see object

dependencies and how objects are used together.

K2 MANAGEMENT WORKLIST

The Springboard for K2 Management Worklist is used by K2 Administrators to do the following for all

Worklist items:

Release

Redirect

Delegate


30 | P a g e

There is no link from the dashboard to the Management Worklist. In order to add a link to the

Management Worklist, it’s recommended that a new Application needs to be registered with

Springboard for K2 (the K2 SmartForm name is K2ANZ.Framework.ManagementWorklist).

To connect directly to the Management Worklist, the URL is:

[Runtime Site URL]/Runtime/Runtime/Form/K2ANZ.Framework.ManagementWorklist/

The form can be located here:

Documents

How do I use it? - K2 ANZ · 2016-07-21 · HOW TO USE SPRINGBOARD FOR K2 5 | P a g e OPENING A WORKLIST ITEM When opening a K2 worklist Item, included in the URL (as part of the