This chapter of the Polarion User Guide provides information about Polarion features and common tasks that are of interest mostly for software developers. Of course some features and topics may overlap with information for project managers or system administrators. In such cases, this chapter may contain only a cross reference to information elsewhere in the documentation.
If you are new to Polarion and haven't already read through the Quick Tour chapter, you might want to do that before going further in this chapter because here there will be references to the navigation and other user interface elements covered in the Quick Tour.
When you log in to Polarion, the first thing you normally see is the Repository Dashboard. (At least this is the case in a default installation ߝ depending on the way your Polarion administrator has set up the system and your system permissions it is possible you could see something different, such as the dashboard for a project.)
As a developer, you will need to access one or more Projects. In order to be able to do that, you of course need a Polarion user account, but you must also be assigned a role in each Project you have access to. Project roles are assigned by a Polarion administrator. (See Administrator's Guide: Configuring User Roles). Once you are set up administratively, you need to navigate to the Project you want to work on.
To access a Project you must be in the Projects perspective. Depending on your system configuration and permissions, that may be the only perspective available, or you may see either or both of the Repository perspective and the Administration perspective. Click on the perspective selector to enter the Projects perspective.
The Projects being managed with Polarion are listed in the Projects portlet of the main navigation panel. Depending on how Projects are organized in your system, the project you are seeking may be a top-level node in the portlet, or it may be under a Project Group or even a Project Sub-group. (You should be familiar with the organization of your system.)
When you locate the project in the Projects portlet, click on it and the project's dashboard will begin loading in your browser. You can either wait for it to load so you can review its information, or you can immediately begin navigation to the Work Item(s) you want to work on.
There are three basic ways you can locate Work Items:
Use Search features
Use Shortcuts
Use Topics
If you know the ID of the Work Item you want, or some text in its description, you may be able to get to it quickly using the Site Search in the Polarion header.
You can use the Shortcuts portlet in the main navigation panel to access some subset of Work Items. By default, there is a global shortcut named which accesses all unresolved Work Items assigned to you and displays them in the Table view in the Work Zone. Other shortcuts pull up other sets of Work Items. You can create your own shortcuts from queries you build using the Query Builder, accessed from the Search Bar in the Work Items Table view. (See Using the Query Builder.)
Once you have accessed a set of Work Items with a Shortcut, you can use the Search Bar in the Table and other Work Zone views to refine the list of Work Items. (See Searching.)
The Topics portlet contains navigational links that pull up sets of Work Items. The node accesses all Work Items of all types in the project. Beneath this link are several others which may vary according to configuration/customization of your system. By default, the following links are present:
Task: accesses all project Work Items of Task type
Change Request: accesses all project Work Items of Change Request type
Requirement: accesses all project Work Items of Requirement type
The list of Work Item types is configurable by a Polarion administrator, so you may see other items such as or which correspond to Work Item types custom configured for your system. (See Administrator's Guide: Configuring Work Items.) In every case, clicking on one of these items should access all project Work Items of the respective type.
Once you have accessed a set of Work Items with a Topic, you can use the Search Bar in the Table and other Work Zone views to refine the list of Work Items.
This section covers a number of tasks and operations that software developers typically need to do when working with Polarion.
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 Work Zone views (Table, Tree, etc.) the item's detail appears in the Detail pane. On most monitors, at least some of the information will be scrolled out of view. The Detail toolbar provides three buttons that provide quick-scroll to commonly viewed detail information:
Comments: instantly scrolls up or down to the Comments portlet where you can see all comments for the Work Item.
Links: instantly scrolls up or down to the Links portlet where you can see all the Work Item's links (if any).
Attachments: instantly scrolls up or down to the Attachments portlet where you can see and access any files attached to the Work Item.
Tip
You can maximize the Detail pane to the full size of the Work Zone, or minimize it to reveal more of the Work Items table/tree. Use the Maximize or Minimize icon on the Detail pane toolbar. Restore using the Restore icon.
The button on the Detail pane toolbar triggers Edit mode in the Detail pane. When you click this button, all information in the Detail pane is editable. Make any changes you want and Click the button in the toolbar to save your changes. The button abandons any changes you may have made and restores the Detail pane to Read-only mode.
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.
Locate the Work Item and select it to display its detail in the Detail pane.
In the Detail pane toolbar, click .
Locate the Initial Estimate field and enter the amount of time you think it will take to complete the Work Item.
Enter the same value in the Remaining Estimate field. (You will adjust this value as you work on the item.)
Click to save the edit.
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.
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 portlet. 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 item on the Actions menu found on the Work Item Search bar.
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:
When you begin working on an item, go to the Status and select in the drop-down list.
As you progress with the item, create a Work Record for every block of time spent on the Work Item.
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.
Beginning with Polarion 3.0.0, you can use a special Work Item view called Time Sheet to report the time you have spent on Work Items during a period of time which you specify. You can also use the view to edit time already reported with Work Records on individual items, 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 view.) 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 2.34. 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:
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.
Locate the row for a Work Item on which you want to report time spent.
Enter the amount of time spent in the column for the appropriate date.
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. Just access it by clicking your user name in the Polarion ALM portal header.
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:
Click the button in the Detail pane toolbar to quick-scroll to the Comments portlet.
At the bottom of the Comments portlet, click the small button. An edit form appears in the Detail pane.
Type your comment and click the button.
You can also edit comments when editing 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:
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.
Locate the Status field and click the drop-down button to display the list of next workflow actions.
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 and . Selecting a workflow action toggles the Detail pane into edit mode.
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 button.
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 implementers 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.
You can create a link to a revision in the Linked Repository Revisions portlet in the Detail pane of the Work Zone. You can also create a link to a revision at the same time you create a link to another Work Item. That is, you can select the revision of the target item to link. You can quickly navigate to the Linked Repository Revisions portlet using the button in the Detail pane toolbar.
There are two scenarios for creating a revision link. You can do it while editing a Work Item (i.e. when the Detail pane is in Edit mode), or directly in the Detail main without launching Edit mode. The steps are basically the same either way. 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 link in the Revision field and select one or more revisions in the Revision Picker dialog. This dialog has it's own Search bar 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.
With the Work Item detail in Edit mode, you can add create multiple revision links, or remove an existing link.
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 projectId/[WORKITEMID] 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.
Links derived from Subversion commit messages are shown on the Work Item detail form in italics, and they cannot be removed manually. If some revision is linked to the Work Item both explicitly by adding it on the Work Item form, and in a commit message, then it is shown twice in the linked revisions section on work item form.
In order to work with builds, you must have the necessary permissions set up by a Polarion administrator. Permission levels are: read, create (which allows you to start new builds), and download. You can access project builds via the topic which appears in the Topics portlet. Click this topic to show the list of builds in the Work Zone, where the Builds are listed in a table at the top. You can sort the table on any column by clicking the column header. Selecting a build in the table displays its detail in the Detail pane.
Build details include build status, build author (person who started the build, or the name of the system user (default "polarion") in case of initiation by a scheduled Job, and links to the build log and base directory.
If you have create permission for builds you can start a new build by clicking the in the Builds table. If you are not sure if you have the necessary permissions, mouse over the button and a tool tip will tell you if you cannot start a build. When you click the button, a new job is created (which you can see in the Monitor topic) and a new row appears in the Builds table (Builds topic). You can check the build status using the button. Your user name will appear in the Author column (and in any build notifications which may be sent as a result of the build).
It is necessary to set up a build configuration for each project. This is done in the Administration Perspective, in the Building topic and its sub-topics. You need to have administration rights for the project for which you want to configure building.
For detailed information on build configuration, see Administrator's Guide: Configuring Building.
See Administrator's Guide: Backups: Project Builds
Polarion provides extensive information about tests and test coverage. You can access this information via the topic in the Topics portlet. When you expand the topic, Polarion presents two report topics:
Unit Test Coverage: presents a summary of coverage statistics from which you can drill down to packages and source files to examine test coverage in detail.
Unit Tests: presents information about the unit tests themselves.
You can view the source code for any class (for the application or tests) in the current Project and access its Javadoc™ documentation without leaving Polarion. Source code is read-only.
To access source code:
In the Topics portlet, expand the node.
Next, click the node.
Locate the class you want to view in the All Classes portlet and click the class name Click the class name to open the source in the right-hand frame.
To access Javadoc documentation:
In the Topics portlet, expand the node.
Next, click the node.
Click any listed Build Artifact. If none are listed, no report has been generated. To generate the report, click the button.
Navigate to the class you want to see, clicking the class name to open its documentation in the main frame.
NOTE
The foregoing assumes that Javadoc has been generated for the classes in your Project. If no Javadoc exists, you will see No Data Available main frame of your browser after clicking the Build artifact name.
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 ALM version with this feature, you may be asked to configure you personal Working Calendar. This tells the system what days and hours you work. You only need to configure your personal calendar when your personal work schedule differs from that defined in the global Working Calendar. The global Working Calendar settings appear by default in your personal Working Calendar.
You can specify your actual work schedule in your personal Working Calendar. You can also specify planned time off such as vacations or leaves of absence. You can also put in temporary schedule differences. For example, suppose you plan to take several hours per week off over a period of 3 months to attend some classes. You can configure your personal Working 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 calendar, you might want to read the section on the Working Calendars feature in the Administrator's Guide: Configuring Working Calendars.
Your Working Calendar is available on your user profile page. Access this page by clicking on your user name displayed in the Polarion ALM portal header when your are logged in. If necessary, scroll the page until you find the Working Calendar portlet. Here you will find a set of graphical controls enabling you to make and save changes to your personal 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:
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.
Change the Start Time and/or End Time value(s) as desired.
Click the button in the toolbar above the portlet.
Suppose you changed the start and/or end time for several week days in your personal Working Calendar because you were working only part time, and now you have started working full time and want to set your personal calendar back to the global schedule. To do this, just clear the check box next to the modified week day(s) and save the change.
In the Schedule Exceptions portlet you can define exceptions to the regular schedule. Exceptions can be permanent, or temporary for a specific period of time. For example, holidays that occur on the same date every year can be set up as permanent exceptions to the normal work schedule. Holidays that fall on a different date each year can be set up as temporary exceptions.
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:
Enter a meaningful title for the exception in the Title field. For example:
New Years Day Holiday.Select the exception type by choosing a value in the Type drop-down list. For example: .
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.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.
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 .
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.
If you want to add another Schedule Exception, click the + (plus sign) in the Actions column and repeat the above steps on the new row that appears.
When you are finished defining your Schedule Exception(s), click the button in the Working Calendar toolbar. To cancel all changes, click the button.
To remove a Schedule Exception:
Click the - (minus sign) icon in the Actions column of the exception you want to remove.
Click the button in the Working Calendar toolbar. To cancel the remove (before any Save), click the button.