Making the work item visible

To have a work item visible, it needs to be defined in the VisibleWorkItemTypes section. For example, to have a work item Risk Evaluation, a line of XML similar to this one will be needed.

<VisibleWorkItemTypes>
    ...
    <WorkItemType Name="Risk Evaluation" AssignmentField="System.AssignedTo" DescriptionField="Microsoft.VSTS.Common.DescriptionHtml" />
</VisibleWorkItemTypes>

Once this is done, the new work item type will be visible as a card in Urban Turtle. However, it will display the default fields, the default color and since its states are not mapped to any columns, it will not be possible to move the card in the Task board. Instead, the card will be displayed at the bottom of the page under the following message:

! These work items need your attention

Enabling work items prioritization

To allow Urban Turtle to understand how work items should be prioritized in the backlog, a field in all the work items has to be defined to store that value and reference to that field has to be made so that Urban Turtle will know which field is designated to handle prioritization.  In each work item that is wanted to be able to be prioritized, it will be needed to add that field by using the Power Tools. It is recommended that the value of the field be of type Double.

For example, lets say the following field was created:

The field has now to be designated has the ranking field in Urban Turtle's configuration mapping file. This is done by adding a Ranking line under the Feature section of the file. In the case of our example, the following code would need to be added:

<Features>
    ...
    <Ranking Field="BacklogPriority" />
</Features>

Note: If the process template being customized is based on a templates that already support prioritization, adding an extra field will not be necessary. For example, Task, Bug and Product Backlog Item in the Microsoft Visual Studio 1.0 template already have the field Microsoft.VSTS.Common.BacklogPriority and the Urban Turtle configuration mapping file for that template already has a reference to it.

Displaying fields in the cards

In Urban Turtle, each work item is displayed on a element called a card. The cards allows user to interact with the work items and display information on their types and status. Each card can display up to 3 fields which are user configurable. The card can also show different fields whether it is displayed in the planning board or the task board or weather it is displayed has a list card or has a regular card. All that needs to be created is a Card block under the appropriate section of the configuration mapping file. The ReferenceName attribute of the Section name must point to the ref name of the field that need to be displayed. An optional Unit attribute can be added so that the card will display the units to the right of the field. The card block will look like that:

...
<Card WorkItemType="[Work item name]"
    <Sections>
        <Section ReferenceName="[First_field_ref_name]" Unit="[unit_type]" />
        <Section ReferenceName="[Second_field_ref_name]" Unit="[unit_type]" />
        <Section ReferenceName="[Third_field_ref_name]" Unit="[unit_type]" />
    </Sections>
</Card>
...

The section under which the Card block is placed defines how the card is displayed in a particular view.

For example, lets say it is wanted to have a card of type Risk Evaluation that displays the title, the assignee and the remaining work to be done and that these field have the reference names System.Title, System.AssignedTo and RemainingWork respectively.  Let's also say that the remaining work to be done is calculated in hours. To configure that card in the Task Board when the card is a child and the Card view is enabled, the code would look like this:

<TaskBoard>
...
    <ColumnCards>
        <Card WorkItemType="Risk Evaluation">
        ...
            <Sections>
                <Section ReferenceName="System.Title" />
                <Section ReferenceName="System.AssignedTo" />
                <Section ReferenceName="RemainingWork" Unit="h" />
            </Sections>
        </Card>
    </ColumnCards>
</TaskBoard>

Assigning a color to a work item type

Urban Turtle provides a quick way to identify the type of item a card represents by looking at the color of a specific area. When the card is displayed in the Task Board, this area is the vertical line on the left edge of the card. When the card is displayed in the Planning Board or as a parent card in the Task Board, this area is the one surrounding the icon, also on the left side of the card. It is possible to configure the color the card uses for a specific work item in the configuration mapping file. This is done by adding a CardStyle line under the CardStyles section.

<CardStyles>
    ...
    <CardStyle WorkItemType="[work_item_name]" Color="[color_name|hex_value]" />
</CardStyles>

 For example, to map the work item of type Risk Evaluation to the color blue, the following code would be needed:

<CardStyles>
    ...
    <CardStyle WorkItemType="Risk Evaluation" Color="blue" />
</CardStyles>