Create custom Kanban boards

Target groups

Solution developers

Context

As of censhare 2019.3, the standard workspace for dedicated solutions uses Kanban boards on the static Projects, Media, Products and Content pages, as well as on Subject and Product asset pages. Custom Kanban boards can be added to other static pages or asset pages.

Prerequisites

The Standard Kanban boards require censhare Dedicated solutions.

Introduction

The Kanban board is an agile tool to manage work projects and monitor marketing or publication cycles. Kanban boards visualize work projects at various stages of a cycle. The board uses cards to represent inividual items (assets), and columns to represent the stages of the work cycle. Custom Kanban boards can be configured to display the result of any asset query, or related assets in columns that represent different values of a property. In the standard use case, the columns represent workflow steps. Custom boards can display any property this distinct values (value type: value list). 

Dynamic value lists cannot be displayed in a Kanban board!

When a user drags a card from one column to the next, the Kanban board widget updates the respective workflow step and assigned workflow target. The Kanban board widget can be placed on any asset page or on static pages.

Kanban board in censhare Web

Standard Kanban boards

The censhare standard workspace for dedicated solutions uses Kanban boards on static pages:

Additionally, pre-configured Kanban boards are placed on Subject asset pages and Product asset pages:

Kanban boards - best practices

To create custom Kanban boards, you can change the standard configurations using Resource replace variants, or create new Kanban board configurations from scratch. You can create custom Kanban boards that cover more complex use cases such as multi-relations.

Before your create the actual Kanban board, decide what you want to display on your board, and where you want to display the board. This determines, which Kanban board configuration to use:

First, decide which data you want to display in the columns of the Kanban board:

• Workflow management: This is the standard use case of the Kanban board. Be aware that one Kanban board can only visualize one workflow. If the assets that you want to display on a Kanban board use different workflows, you must either configure multiple Kanban boards, or merge the different workflows into one. This can be difficult in a production system, but can be worth to consider during a project setup.

• Asset properties management: You can configure a Kanban board to display any asset property with limited distinct values (value type: value list). Other value types cannot be displayed in a Kanban board. For example, you can create a Kanban board that shows the Age group (0-18 years, 18-30 years, 30-45 years, etc). But you cannot create a Kanban board that shows the Age (integer value).

Next, decide where you want to place the Kanban board:

• Static page: Static workspace pages are accessible from the side navigation. Static workspace pages have no asset context. Therefore, they must be configured with an asset query (Non-contextual Kanban board).

• Asset page: Asset pages are configured for each asset type. An asset page displays data of the current asset. This asset is also called the context asset. To configure a Kanban board on an asset page, you can use asset relations (Contextual Kanban board) or an asset query (Non-contextual Kanban board). For a good usability, we recommend to place Kanban boards on a new tab.

• Add widget action: The Add widget action allows users to customize their workspace and place a Kanban board on an asset page. The Kanban board configuration is similar to the Asset page configuration. Make sure that the Kanban board configuration works on all asset pages (in all contexts) where you allow users to place it. To avoid confusion and unintended usage, we recommend to test the Kanban board in every possible context, and restrict the usage in other contexts.

Finally, decide which assets you want to display in the Kanban board:

• Non-contextual: Display assets that are not related to the context asset. For example, a Kanban board that is placed on a static page, or a Kanban board shows all assets of a certain type that exist in the system. This setup requires an asset query with the respective filters and conditions. You must create a separate Transformation that stores the query before you can configure the Kanban board.

• Contextual: Display assets that are related to the context asset. For example, a Kanban board that is placed on Group asset pages shows assets that are assigned to this Group. The relation type and direction can be configured directly in the Kanban board widget. An asset query is not required.

• Self-contextual: This special case displays the context asset on a Kanban board. You can include related assets to the context assets. For example, query the context asset (Product) and related assets (Product items). You must create a Transformation that stores the query before you can configure the Kanban board. You cannot configure this with a contextual configuration.

Transformation configuration

This configuration is only required for non-contextual Kanban boards that display assets that are not related to the context asset. This is always the case on static asset pages. It is also required for Kanban boards that include the context asset (self-contextual).

1. In censhare Web, create a new Module / Search / Transformation asset. You can also duplicate one of the Kanban board transformations that are part of the standard product.

2. Open the the Edit properties dialog of the asset and enter a name.

3. Enter or generate a resource key.

4. In the Usage field, select Kanban board query transformation.

5. Click OK to close the dialog.

6. Add and edit the XSL stylesheet Master file according to the following example: 

   <?xml version="1.0" encoding="UTF-8"?>
   <xsl:stylesheet version="2.0"
   	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
   	xmlns:xi="http://www.w3.org/2001/XInclude"
   	xmlns:xs="http://www.w3.org/2001/XMLSchema"
   	xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions">
    <xsl:param name="workflowId"/>
    <xsl:param name="featureValue"/>
   
    <xsl:template match="/">
   
     <query>
      <and>
       <condition name="censhare:asset.type" op="=" value="product."/>
       <condition name="censhare:asset.wf_id" value="{$workflowId}"/>
       <condition name="censhare:asset.wf_step" value="{$featureValue}"/>
      </and>
      <sortorders>
       <grouping mode="none"/>
       <order ascending="true" by="censhare:asset.name"/>
      </sortorders>
     </query>
    </xsl:template>
   </xsl:stylesheet>

   XML

   To adapt the query to other asset types and asset properties that you want to display in the Kanban board, change the respective query conditions. The column values must be declared in the query context as parameters. The AND condition in the example checks, if the parameters are present in the queried assets (in this case: products).

7. To include the context asset in the query, you must add the following lines: 

   ...
   <xsl:param name="context-id"/>
   ...
   <query>
    <and>
     ...
     <condition name="censhare:asset.id" value="{$context-id}"/>
     </and>
   </query>

   XML

8. Optionally, add a <sortorders/> element with the respective <order/> elements to sort the results.

9. Save your changes and copy the resource key if you want to create an XML configuration in a workspace template.

Widget configuration in personal workspace

1. In censhare Web, switch to the Developer mode.

2. Go to the asset page on which you want to add the Kanban board widget. The widget will be displayed on all asset pages of the same asset type.

3. Open the page actions menu and select Manage tabs.

   In the dialog, add a new tab and enter a name for the tab.

4. Open the page actions menu and select Add widget type.

5. In the dialog, select Kanban board and click OK.

6. Open the widget actions menu and select Configure widget.

7. In the Generic configuration section, fill out the fields and select the desired options. For more information, see Generic widget configuration.

8. In the Assets section, select a relation type and a direction, or select an asset query that you prepared for the Kanban board.

9. In the Columns section, select a workflow or an asset property to create the columns of the Kanban board. Optionally, you can exclude workflow steps or values from the board.

10. If you do not want to allow users to change the workflow step or the value of assets on the board, select Read only.

11. Click OK to close the dialog, and click SAVE to save your changes.

XML configuration in workspace template

Use this configuration to setup a new XML workspace template. For more information, see Workspace template with XML files.

To create an XML configuration for the Kanban board widget, add the following code snippet to the XML master file of the workspace template: 

<widget id="[RESOURCE_KEY]"
	kind="csKanbanBoardWidget"
	visibility-condition="[XPATH_EXPRESSION]"
	position="1" width="0" height="0">
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare"
	title_en="[WIDGET_TITLE]">
  <hideWidgetTitle censhare:_annotation.datatype="string">[true|false]</hideWidgetTitle>
  <listSize censhare:_annotation.datatype="string">[1|2|3]</listSize>
<!-- ASSET QUERY CONFIGURATION -->
  <transformationType censhare:_annotation.datatype="string">module.search.transformation.</transformationType>
  <transformationKey censhare:_annotation.datatype="string">[RESOURCE_KEY]</transformationKey>
<!-- ASSET RELATION CONFIGURATION -->
  <transformationType censhare:_annotation.datatype="string">relation-query</transformationType>
  <relationOrReference censhare:_annotation.datatype="string">[relation|reference]</relationOrReference>
  <relationKey censhare:_annotation.datatype="string">[RELATION_KEY|FEATURE_RESOURCE_KEY]</relationKey>
  <direction censhare:_annotation.datatype="string">[child|parent]</direction>
<!-- WORKFLOW COLUMN CONFIGURATION -->
  <workflowId censhare:_annotation.datatype="string">[WORKFLOW_ID]</workflowId>
  <hideColumns xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare">
   <value censhare:_annotation.datatype="number">[INTEGER]</value>
  </hideColumns>
<!-- ASSET PROPERTY COLUMN CONFIGURATION -->
  <featureKey censhare:_annotation.datatype="string">[RESOURCE_KEY]</featureKey>
  <hideColumns xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare">
   <value censhare:_annotation.datatype="string">[STRING]</value>
  </hideColumns>

  <readonlyMode censhare:_annotation.datatype="boolean">[true|false]</readonlyMode>
 </configuration>
</widget>

Elements and attributes

Recipes

Show product and product items workflow

This Kanban board can be placed on Product pages. The board displays the workflow steps of the current product and related product items. Users can see if all product items are in the same workflow step as the product from which they derive.

Proceed as follows:

1. Create a Module / Search / Transformation asset, enter a name and resource key, and select the Usage = Kanban board query transformation.

2. Add the following XSL stylesheet to the Master file: 

   <?xml version="1.0" encoding="UTF-8"?>
   <xsl:stylesheet  version="2.0"
   	xmlns:censhare="http://www.censhare.com/xml/3.0.0/xpath-functions"
   	xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions"
   	xmlns:csc="http://www.censhare.com/censhare-custom"
   	xmlns:xs="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   	exclude-result-prefixes="cs cs csc" >
    <xsl:param name="context-id"/>
    <xsl:param name="workflowId"/>
    <xsl:param name="featureValue"/>
   
    <xsl:template match="/">
    
    <query>
     <or>
      <and>
       <condition name="censhare:asset.wf_id" value="{$workflowId}"/>
       <condition name="censhare:asset.wf_step" value="{$featureValue}"/>
       <condition name="censhare:asset.id" value="{$context-id}"/>
      </and>
      <and>
       <condition name="censhare:asset.wf_id" value="{$workflowId}"/>
       <condition name="censhare:asset.wf_step" value="{$featureValue}"/>
       <relation direction="parent" type="user.product-item.">
       <target>
        <condition name="censhare:asset.id" value="{$context-id}"/>
        </target>
       </relation>
      </and>
      </or>
   
      <sortorders>
       <order ascending="true" by="censhare:asset.name"/>
      </sortorders>
     </query>
    </xsl:template>
   </xsl:stylesheet>

   XML

   
   The query consists of two parts (related with an OR logic). The first part queries the current asset (context asset). The second part queries child product items of the context asset.

3. On the Product asset page, add a new tab Status.

4. In the Status tab, add a new Kanban board widget (Developer mode must be activated to do this) and configure it as follows.

5. Add a title and an optional description.

6. Select the list size.

7. In the Assets section, in the Asset search field, select the Transformation that you created in the first step.

8. In the Columns section, in the Workflow field, select the Product workflow.

9. Click OK to save your changes.

Result

You know how to create custom Kanban boards. You know the differences between the query configuration and asset relation configuration. You know how to configure XML snippets for Kanban board widgets.