Processing Work Items

As a developer, you will mostly use Polarion to understand what work is assigned to you, to record your work progress, and to indication completion of assigned work, most of which revolves around the processing of Work Items. This section covers the most common things developers need to do when processing Work Items assigned to them.

Configuring your User Calendar

The global Working Calendar is used by Polarion's project planning engine to calculate the amount of actual working time available to projects. The Working Calendar defines the working days in a work week, and working hours within each working day. It may also specify special non-working days/times such as public holidays.

If your organization uses a Polarion product with this feature, you should check your User Calendar before you begin processing Work Items. Your User Calendar tells the system what days and hours you normally work, and enables you to report exceptions to that, such as vacation, leave, or other planned time off. This information is used by the project planning engine when creating and reporting project plans. The global Working Calendar settings, which define the standard working time, holidays, etc. for your company, appear by default in your User Calendar. You only need to change your User Calendar when your work schedule differs from that defined in the global Working Calendar.

You specify your actual work schedule in your User Calendar. You can also specify planned time off such as vacations or leaves of absence. You can also log temporary schedule differences. For example, if you plan to take several hours per week off over a period of 3 months to attend some classes, you can configure your User Calendar to reflect this.

Anything in your personal calendar that differs from the global calendar is taken into account by the planning engine and reflected in the project plan of each project in which you have Work Items assigned to you. Project managers and teammates can see your working and non-working time in the Live Plan chart.

Before configuring your User Calendar, you might want to read the section on the Working Calendars feature in the Administrator's Guide: Configuring the Global Working Calendar.

Accessing your User Calendar

Your User Calendar is available on your user profile page. Access this page by clicking the My Account link in the tool view of Navigation. Scroll the page until you find the User Calendar button. Click it to load your User Calendar. Here you will find a set of graphical controls enabling you to make and save changes to your User Calendar.

Editing your User Calendar

The Regular Schedule section lists the working days and times of your normal work schedule. By default, the values are from the global Working Calendar. If your regular working time differs from the global schedule on one or more working days, you can change the start and end time for the affected day(s).

To change the start or end time for a Working day:

  1. Click the check box beside the day to enable override of the global Working Calendar. The Start Time and End Time boxes are now editable.

  2. Change the Start Time and/or End Time value(s) as desired.

  3. Click the Save button in the toolbar above the section.

TIP

You can mark any day in the Regular Schedule section as a non-working day by clicking the icon after the End Time field.

Reverting to the Global Schedule

Suppose you changed the start and/or end time for several week days in your Regular Schedule because you were working only part time, and now you have started working full time and want to sync your User Calendar back to the global schedule. To do this, just clear the check box next to the modified work day(s) and save the change.

Defining Schedule Exceptions

In the Schedule Exceptions section you can define exceptions to the regular schedule. Exceptions can be permanent, or temporary for a specific period of time. For example, suppose you take time off for a religious holiday that occurs on the same date every year. This can be set up as a permanent exception to your normal work schedule. If such a holiday falls on a different date each year, it can be set up as a temporary exception.

Schedule Exceptions can be either of 2 types:

  • Time Off - the exception is time that will not be available for work in addition to any non-working time configured in the Regular Schedule.

  • Time Working - the exception is time that will be available for work in addition to the working time configured in the Regular Schedule.

To add a Schedule Exception:

  1. Enter a meaningful title for the exception in the Title field. For example: New Years Day Holiday.

  2. Select the exception type by choosing a value in the Type drop-down list. For example: Time Off.

  3. Specify the date when the schedule exception is to begin in the Date From field in this format: yyyy-mm-dd. Alternatively, click the calendar icon next to the field and choose a date in the pop-up calendar. For example: 2008-01-01.

  4. If the exception you are defining is temporary, specify the date when it should end in the Date To field, in the same format as mentioned in the previous step. For a one-day exception like our New Years Day example, the value should be the same date as in the Date From field. If the exception is ongoing, leave the Date To field empty.

  5. If the exception you are defining occurs only on one specific weekday in the time period defined, choose that day in the drop-down list in the Weekday column. Otherwise, leave the default value All days.

  6. If the exception you are defining is of the type "Time Working", set appropriate time values in the Time From and Time To fields, which are enabled when this type is selected. Time From is the time when the additional working hours start, and Time To is the time when the additional working hours finish.

  7. If you want to add another Schedule Exception, click the icon in the Actions column and repeat the above steps on the new row that appears.

  8. When you are finished defining your Schedule Exception(s), click the Save button in the Working Calendar toolbar. To cancel all changes, click the Revert button.

To remove a Schedule Exception:

  1. Click the in the Actions column of the exception you want to remove.

  2. Click the Save button in the Working Calendar toolbar. To cancel the remove (before any Save), click the Revert button.

Viewing and Editing a Work Item

Once you have located a particular Work Item of interest, you may want to review its details, and perhaps change one of more of them. (See the previous section on Locating Work Items.)

When you have selected a Work Item in one of the views in the Work Items topic (Table, Tree, etc.) the item's detail appears in the Viewer/Editor pane. On most monitors, at least some of the information will be scrolled out of view. The Viewer/Editor toolbar provides three buttons that provide quick-scroll to commonly viewed detail information:

  • Comments: instantly scrolls up or down to the Comments section where you can see all comments for the Work Item.

  • Links: instantly scrolls up or down to the Links section where you can see all the Work Item's links (if any).

  • Attachments: instantly scrolls up or down to the Attachments section where you can see and access any files attached to the Work Item.

Editing a Work Item

The Edit button on the Detail pane toolbar triggers Edit mode in the Viewer/Editor pane. When you click this button, all information in the pane is editable (assuming you have write permissions). Make any changes you want and Click the Save button in the toolbar to save your changes. The Cancel button abandons any changes you may have made and restores the Detail pane to Read-only mode.

Note that some fields are editable "in place" without the need to click the Edit button. Hovering over a field for a moment will show if it can be edited in place.

Linking Source Code Elements for Traceability

The Resource Traceability feature enables developers to create semantic traceability links between elements in source code (stored in any configured repository) and Work Items. For example, some specific function in the source code might implement one or more Requirement type Work Items. You can create such a link by adding a comment before the function, using a prescribed comment syntax to identify the target item, the link role, etc. Currently supported languages are: Java, C and XML.

For more information about the feature, see the Administrator's Guide topic Configuring Resource Traceability..

For information about the comment syntax to use in source code, see the subtopic Link a Resource..

Estimating Work Item Time

In some development organizations, developers may be asked to provide an initial time estimate for Work Items. In other organizations, this may be done by a project leader or manager. Polarion provides the capability to estimate Work Items and track the time actually spent to resolve them. Over time, the data collected can be highly useful to both developers and managers in estimating time to complete projects, and understanding how accurately they can plan.

If you are tasked with providing an initial time estimate for Work Items, here is how you go about doing it.

  1. Locate the Work Item and select it to display its detail in the Detail pane.

  2. In the Detail pane toolbar, click Edit.

  3. Locate the Initial Estimate field and enter the amount of time you think it will take to complete the Work Item.

  4. Enter the same value in the Remaining Estimate field. (You will adjust this value as you work on the item.)

  5. Click Save to save the edit.

Time notation syntax

Polarion has a special syntax for entering and displaying time. Using this syntax, you can estimate Work Item time in days (d + integer), hours (h + integer), or a combination of days and hours. You can use 1/2 in front of the day or hour symbol to indicate half.

For some examples, click the ? icon to the right of the Initial Estimate field.

Hours as Decimal Values

It is possible for a system administrator to override the default factional syntax for hour values, and enable entry and display as decimal values. If this is has been done, the help dialog that appears when you click the ? icon appearing with time fields will indicate that entry of decimal hours is possible. If so, then instead of e.g. 1/2 h, you can enter .50.

Reporting Time for Individual Work Items

Polarion makes it easy and fast for developers to report their progress to management. There are several fields in the Work Item detail that are related to time tracking and planning accuracy analysis:

  • Initial Estimate

  • Time Spent

  • Remaining Estimate

  • Status

In addition to the above fields, Work Items contain the Work Records section. Work Records are useful when you have to spend several blocks of time on different days to complete a Work Item. You create one Work Record for each block of time you spend working on the item. Each Work Record updates the Time Spent and Remaining Estimate fields. You or your manager can then generate a Work Report that shows your Work Records using the Create Work Report item on the Actions menu found on the Work Item toolbar.

Note

The administrator of your project may optionally set a locking date, on and after which you cannot add or modify Work Records. If you need to compensate for time over-reported in a Work Record that is locked, you can create a Work Record for the next reporting period with a negative value for time spent.

Your team will need to define the process for using the time estimating and reporting fields and Work Records. Here, we'll briefly discuss how they can be used to facilitate progress reporting.

Assuming that the relevant fields have been set as discussed in Estimating Work Item Time, there are two things you do as you work on a Work Item:

  1. When you begin working on an item, go to the Status and select Start Progress in the drop-down list.

  2. As you progress with the item, create a Work Record for every block of time spent on the Work Item.

Work Records in Multi Edit View

You can add Work Records in Multi-Edit view. To do this, you will need to add the Time Spent column to the table (see Customizing the Work Items Table). When this column is present, a special section is displayed in which you can add Work Records. You can only add new Work Records. Existing work records do not appear and so cannot be modified or deleted.

Using the Time Sheet View

You can use the Time Sheet view in the Work Items topic to report the time you have spent on Work Items during a period of time which you specify. You can also use this view to edit time already reported for individual items with Work Records, provided you want to report more time spent on the item that previously reported in the Work Record. (If you want to decrease the amount of time already reported in a Work Record, you must edit the specific Work Item in the Work Item form, accessible by clicking on a Work Item displayed in the Time Sheet.) The Time Sheet view itself is essentially a convenient way to create Work Reports on a number of Work Items without having to select each one in turn.

Figure 19.3. Time Sheet View

Time Sheet View

The Time Sheet view enables quick time reporting for multiple Work Items

The Time Sheet is comprised of 3 main areas:

  • Search Query: used to fetch a set of Work Items, specify a period of time for which to report time spent, and save or cancel changes.

  • Filtering: filter the set of Work Items according to time, and optionally select only items with Work Records and/or Work Records logged by you.

  • Time Sheet grid: used to report time spent on listed Work Items during the period shown. Rows are Work Items fetched by a normal query

The process of reporting time using the Time Sheet view is:

  1. Create a query to display a set of Work Items that contains the ones for which you want to report time spent, and to show a specific span of time in which you want to report hours spent.

  2. Locate the row for a Work Item on which you want to report time spent.

  3. Enter the amount of time spent in the column for the appropriate date.

  4. Save the edits when finished.

TIP

If you regularly split your working time between two or more projects, you can configure time splitting in your user account. This will help increase project planning accuracy in the Live Plan. For information on this configuration see Administrator's Guide: User Management: Configuring User Time-splitting. You can make this configuration yourself in your own user account (click the My Account link in the tool view of Navigation).

Work Item Discussion and Comments

You can add any number of textual comments to a Work Item. This can facilitate discussion of the item between team members in the same or a remote location. For example, a developer in Delhi may need some additional information from an architect in New York. The developer can add a comment and reassign the Work Item to the architect, which creates a notification for the architect. The architect can respond with another comment, and perhaps some attachment, and reassign the item back to the developer.

Since comments are a frequent action, it's very quick and easy to add one. Once you have located the item you want to comment:

  1. Click the Comments button in the Detail pane toolbar to quick-scroll to the Comments section.

  2. At the bottom of the Comments section, click the small Edit button. An edit form appears in the Detail pane.

  3. Type your comment and click the Save button.

You can also edit comments when editing a Work Item.

Resolving or Closing a Work Item

When you finish working on a Work Item it's time to indicate it in Polarion. By so doing, the project plan and overall status is automatically updated and your project manager can follow your progress without the need for you to write up some kind of status report.

You resolve a Work Item by changing the Status field. Here is the basic procedure:

  1. After locating the Work Item via navigation or search, select it in the Table (or other) view to display its details in the Detail pane.

  2. Locate the Status field and click the drop-down button to display the list of next workflow actions.

  3. Select the workflow action that is required by your team's process. Workflow is customizable by a Polarion administrator, so the list of actions may differ from the default. The default actions are Resolve and Resolve and Close. Selecting a workflow action toggles the Detail pane into edit mode.

  4. Before updating the Work Item you may wish to add a comment, attach a file, or create a link to a repository revision. After making any desired edits, finish the resolution process by clicking the Save button.

Linking a Resolved Item to a Repository Revision

When you resolve a Work Item (a Task, Change Request, or Defect for example), it can be highly useful for your development organization if you link the resolved Work Item to the repository revision that contains the code that implemented the feature or fix specified in the Work Item. Doing this consistently provides the organization the possibility to trace development from a requirement, through process and changes, to the source code. Aggregations of this kind of data can reveal flaws in the process which can subsequently be corrected to improve the overall quality of development.

The best time to link a Work Item to a revision is when your resolve the Work Item, as described in the previous section. However, you can create the link any time. If more than one revision contains code that resolves the Work Item, you can link to multiple revisions.

Creating a link to a revision

You can create a link to a source code revision in the Linked Revisions section in the Work Item's detail in the Table view. You can quickly navigate to the Linked Revisions section using the Links button in the detail pane toolbar. Click the Edit link at the lower left of the section to access the linking fields and actions.

If you know the revision number, you can enter it directly in the Revision field. If you don't know it, you can click the (Select Revision) icon next to the Revision field and select one or more revisions in the Revision Picker dialog. This dialog has its own search tool that enables you to locate the desired revision. The Revision Picker contains a preview area. When you click on any of the revisions shown, the preview area displays the changed items in the selected revision.

If your project has been configured to support revision linking from more than one repository, the Linked Revisions section contains a drop-down list from which you can select the repository before selecting the revision. For example, a project might have source code in both Polarion's default Subversion repository, and an external GIT repository. (For more information on this capability, see Administrator's Guide: Project Administration: Using External Repositories (GIT, SVN).)

With the Work Item detail in Edit mode, you can add create multiple revision links, or remove an existing link.

Figure 19.4. Linking to a Repository Revision

Linking to a Repository Revision

Linking current Work Item to a repository revision

Links Pinned to Revisions

If you link a Work Item to some revision of another Work Item other than the Head revision, the link is considered "pinned". If the link is followed and the revision of the Work Item viewed, then some aspects of the Work Item are different than if the link were to the Head revision. Specifically:

  • The Work Item cannot be edited.

  • The Actions menu contains only the Print option. Only the state of the Work Item in the revision will be reflected in the printed output.

  • The toolbar of the Work Item form displays the Show Current button. Clicking this button switches to the Head revision of the Work Item.

  • The browser status bar displays information about the revision when the pointer hovers over the title (Date-time when the item was created and last revised, and the revision number). This same information appears when the pointer hovers over a link to the revision in any Work Item.

  • URLs of linked Work Items point to the same revision as the item being viewed (unless they are linked explicitly to some other revision).

  • A clock icon () appears to the left of the Work Item title to indicate that you are viewing a revision. This same icon appears in links to the revision in any Work Item.

  • Backlinks are not displayed

  • Calculated fields do not show any values.

Figure 19.5. Viewing a Pinned Revision

Viewing a Pinned Revision

Revision that is other than Head

Auto-linking via Subversion Commit Messages

Polarion can recognize Work Item IDs in Subversion commit messages, so you can automatically create a link between a Work Item and a revision simply by including the ID in the commit message. If a commit resolves more than one Work Item, you can include multiple IDs in the commit message and revision links will be created for all mentioned items.

The commit message is scanned for occurrences of strings in form PROJECT_ID/WORKITEM_ID or just WORKITEM_ID, where WORKITEM_ID has the form PREFIX-number or PREFIX-AZ1234, where AZ1234 is the mixture of numbers and uppercase letters.

Example: myProject/PRJ-5678, or just PRJ-5678.

The Work Item identifier must be separated from the rest of the message by a space, or characters: () (parentheses), [] (square brackets), ? (question mark), ! (exclamation mark), , (comma), . (period), " (double straight quote), ' (single straight quote), or : (colon).

Links derived from Subversion commit messages are shown in the Linked Revisions section of the Work Item editor. If a link is incorrect as the result of a typo in the Work Item ID in the commit message, the link can be removed by deleting the relevant row in the Linked Revisions table. If some revision is linked to the Work Item both explicitly by adding it on the Work Item form, and also in a commit message, then it is shown twice in the Linked Revisions section on Work Item form.

Figure 19.6. Creating a revision link via SVN commit messages

Creating a revision link via SVN commit messages

Revision linking via SVN commit messages

TIP

If you accidentally specify the wrong Work Item ID in a commit message, resulting in an erroneous revision link, you can manually remove the link. Navigate to the Work Item whose ID you specified by mistake in the commit message, and in the Linked Revisions section of the detail form, use the icon to remove the linked revision. You should then navigate to the correct Work Item and link the revision manually, as previously described.

Note that the erroneous Work Item ID is not removed from the Subversion commit message, so it's a good idea to leave a comment in the Work Item erroneously referenced to explain what happened and what measures you took to correct it.