Targetprocess

The Targetprocess Developer Hub

Welcome to the Targetprocess developer hub. Here you'll find comprehensive guides and documentation to help you start working with Targetprocess as quickly as possible and support you if you get stuck. Let's jump right in!

Docs

Custom units

Custom Unit mashups (add-ons) tweak the Customize Cards feature for your Board, List and Timeline views.

Cards on views can be configured in a flexible way. The layout of a card on each scale size (S, M, L etc) is composed from multiple units (fields). Many useful units are predefined already. However, it is possible to extend this list and implement custom units that are not available out-of-the-box.

The 'Name Length' unit in Customize Cards settings is not available out-of-the-box, but it can be added with the help of a custom mashup.

The 'Name Length' unit in Customize Cards settings is not available out-of-the-box, but it can be added with the help of a custom mashup.

Custom unit mashups are quite powerful with their ability to do advanced calculations. The system can evaluate values using multiple source fields and properties, common math, and string manipulation operations. As a result you get calculated numeric, date, boolean, text values. They can be displayed on cards on board, list, timeline views.

Besides Custom Unit mashups there are a few other features in Targetprocess that support custom calculations. More information: Custom Calculations and Formula Expressions

Examples of already created custom units

Examples of custom units for cards and Lists that can be added with the help of mashups are listed below.

Some of these mashups are not available in the public the Mashups Library and therefore are not available for immediate activation and usage. Private mashups can be requested from our Support Team and installed to your account with our help should you require any of them!

  • Colored Custom Field - helps to define custom rules for color highlighting of values in displayed custom field
  • Description - first 150 symbols of Description text field
  • Last Comment - first 150 symbols of most recent Comment text
  • Attachment - thumbnail picture of first attached (uploaded) image file
  • All Assigned People - displays initials of all assigned users
  • Owner Full Name - first and last name of Owner user
  • Relations Counters - сounts of open vs all items in Inbound and Outbound relations for any entity. Relations of type Link and all other types are counted separately
  • Assignment per Role - assigned users shown separately per role; useful when users with multiple roles estimate entities and work on them
  • Role Efforts - values of role effort (effort to do, effort complete), time spent and time remain shown separately per role; useful when users with multiple roles estimate entities and work on them
  • Parent Entity Planned Date, Release Iteration and TeamIteration dates - shows start and end dates for parent Feature / User Story / Release / Iteration (Sprint) / Team Iteration of User Story, Task, Bug, Feature
  • Current Release and Iteration for Project - displays name and clickable ID of Release and Iteration which is now current in a Project
  • Requesters - names of Requesters are shown on cards representing Requests
  • Company for requesters - name of the Company is shown on cards of Requesters
  • TestCasePercentage - percentage of passed and failed last runs or custom statuses of test cases, calculated separately by types of test case; type for each test case is specified in dropdown custom field. Useful for regression testing and acceptance workflow.

Advanced mashups not only display information, but also add interaction between cards and allow inline modification of cards in views:

Contact our Support Team!

Please let us know if you require a mashup similar to the ones listed above. We'll be glad to provide you with a relevant piece of code to be used as a starter. We'll also help to clarify the supported capabilities of the system and share any required documentation.

How to compose Custom Units mashup

Let's create a mashup that will show the length of the entity name in a custom unit.

Create the mashup with the following dependencies:

tau.mashups
  .addDependency('Underscore')
  .addDependency('jQuery')
  .addDependency('tau/configurator')
  .addDependency('tau/models/board.customize.units/const.entity.types.names')
  .addDependency('tau/models/board.customize.units/const.card.sizes')
  .addMashup(function(_, $, globalConfigurator, types, sizes) {

    //insert your custom code here

});

You'll have to do the following in your custom code:

Define the units array. The array should contain single JSON object with the fields id, classId, name, types, sizes, template, sampleData, model.

FieldName
Purpose
Example

id

Unique ID. Contains no spaces.

name_length

classId

ID of the CSS class applied to the unit. Use to apply custom style further.

tau-board-unit_type_name_length

name

Human-readable name. Displayed in Library and in List column header.

Name Length

types

Types of entities for which this unit is available.

[
types.EPIC, types.FEATURE, types.STORY, types.TASK, types.BUG
]

sizes

Sizes of cards for which this unit is available.

[sizes.XS, sizes.S, sizes.M, sizes.L, sizes.XL, sizes.LIST]

hideIf

Boolean function that determines whether the unit should be shown or hidden. Return 'true' to hide the unit.

template

HTML markup for rendering the data. Targetprocess uses jQote2 as a template engine.

'

<%= String(this.data.nameLength[0] || 0) %>
'

sampleData

Default data used for this unit in Customize Cards wizard. Format is JSON object.

nameLength: 42

model

How data for the unit is calculated from each entity. REST API v2 selector notation is used.

nameLength:Name.Length

Here is how the array is combined:

var units = [{
  id: 'name_length',
  name: 'Name Length',
  classId: 'tau-board-unit_type_name_length',
  types: [types.EPIC, types.FEATURE, types.STORY, types.TASK, types.BUG],
  template: [
    '<div class="tau-board-unit__value"><%= String(this.data.nameLength || 0) %></div>'
  ],
  sizes: [sizes.L, sizes.XL, sizes.LIST],
  sampleData: {
    nameLength: 42
  },
  model: 'nameLength:Name.Length'
}];

Function addUnits should register the units array in a common list named units.registry defined as:

function addUnits(configurator) {
  var registry = configurator.getUnitsRegistry();
  _.extend(registry.units, registry.register(units));
}

We subscribe for event configurator.ready that is transferred by the global bus of events. When the event occurs, we execute the addUnits function.

var appConfigurator;
globalConfigurator.getGlobalBus().on('configurator.ready', function(e, configurator) {
  if (!appConfigurator && configurator._id && configurator._id.match(/board/)) {
    appConfigurator = configurator;
    addUnits(appConfigurator);
  }
});

We're almost done. Now let's combine all parts of the code together:

tau.mashups
  .addDependency('Underscore')
  .addDependency('jQuery')
  .addDependency('tau/configurator')
  .addDependency('tau/models/board.customize.units/const.entity.types.names')
  .addDependency('tau/models/board.customize.units/const.card.sizes')
  .addMashup(function(_, $, globalConfigurator, types, sizes) {

  
  var units = [{
    id: 'name_length',
    name: 'Name Length',
    classId: 'tau-board-unit_type_name_length',
    types: [types.EPIC, types.FEATURE, types.STORY, types.TASK, types.BUG],
    template: [
      '<div class="tau-board-unit__value"><%= String(this.data.nameLength || 0) %></div>'
    ],
    sizes: [sizes.L, sizes.XL, sizes.LIST],
    sampleData: {
      nameLength: 42
    },
    model: 'nameLength:Name.Length'
  }];

  function addUnits(configurator) {
    var registry = configurator.getUnitsRegistry();
    _.extend(registry.units, registry.register(units));
  }

  var appConfigurator;
  globalConfigurator.getGlobalBus().on('configurator.ready', function(e, configurator) {
    if (!appConfigurator && configurator._id && configurator._id.match(/board/)) {
      appConfigurator = configurator;
      addUnits(appConfigurator);
    }
  });
});

Now let's install this mashup to your Targetprocess application.

  1. Open Settings > System Settings > Mashups.
  2. In Mashup Manager, press the Add New Mashup button.
  3. Give this mashup the name CustomUnitNameLength
  4. Set the placeholder as restui_board.
  5. Copy & paste the source code into the Code area.
  6. Press the Save Mashup button.
  7. Reload any open Targetprocess pages in your web browser so that changes are applied.

Done: a mashup with the name CustomUnitNameLength appears in the list of installed mashups.

Usage of composed mashup

Now let's create a new List view showing Epics / Features / User Stories / Tasks / Bugs / Test Plans / Requests as cards.

In the Set up view wizard, open the Customize Cards tab. Among the available units, find the Name Length unit. Drag-n-drop it to card layout.

Then Finish setup of the view.

In the List view, the new column Name Length appears. The mashup calculates the length of the name for each User Story and displays it in this column.

Types of entities

Targetprocess Entity
Use type in mashup

(Any)

types.ANY_TYPE

User Story

types.STORY

Task

types.TASK

Bug

types.BUG

Feature

types.FEATURE

Epic

types.EPIC

Request

types.REQUEST

Requester

types.REQUESTER

Project

types.PROJECT

Team

types.RESPONSIBLE_TEAM
types.TEAM

Program

types.PROGRAM

Release

types.RELEASE

Iteration (Sprint)

types.ITERATION

Team Iteration

types.TEAM_ITERATION

Build

types.BUILD

Impediment

types.IMPEDIMENT

Test Case

types.TEST_CASE

Test Plan

types.TEST_PLAN

Test Plan Run

types.TEST_PLAN_RUN

Relations: Inbound Relation, Outbound Relation

types.INBOUND_RELATION_CARD
types.OUTBOUND_RELATION_CARD

Sizes of cards

Card size
Description
Use size in mashup

XS

Only basic info, just one line. Could be a card name or ID.

sizes.XS

S

A bit more info fits in here: two lines e.g. a card name + avatars of assigned people.

sizes.S

M

Still more info: three lines. Could be a card name + tags + avatars and time spent.

sizes.M

L

This size is for detailed info. Unlimited lines.

sizes.L

XL

A maxi stretch fit. This is how a card looks in the list-like mode.

sizes.XL

List

Displays maximum info in minimum space. Unlimited nested lists are allowed.

sizes.LIST

Custom styles for units

We can define the special function addCSSRule to extend the default Targetprocess stylesheet and append it with custom CSS classes for newly added custom units.

var style = document.createElement("style");
style.setAttribute('id', 'NameLengthCustomUnit');
style.appendChild(document.createTextNode(""));
document.head.appendChild(style);
var sheet = style.sheet;

var addCSSRule = function(selector, rules, index) {
  if (index === undefined) {
    index = sheet.cssRules.length;
  }
  sheet.insertRule(selector + "{" + rules + "}", index);
};

In this example, we define a new CSS style with the unique ID NameLengthCustomUnit and new class tau-board-unit_type_name_length as well. We add two different rules to customize font size: one for cards on Board views and another one solely for XL-sized cards.

addCSSRule(
  '.tau-card-v2__section .tau-board-unit_type_name_length .tau-board-unit__value',
  'font-size: 14px;');

addCSSRule(
  '.tau-ui-size-xl .tau-card-v2__section .tau-board-unit_type_name_length .tau-board-unit__value',
  'font-size: 16px;');

Custom units


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.