Intland Retina User's Guide

1 Manage Workspaces and Permissions

A Workspace is a secure collaborative place for teams to work together to achieve a particular goal. In Retina, you can have an unlimited number of workplaces with different teams, workflows, and permissions set up for each workspace.

1.1 Create Workspaces

In Retina every user who is assigned to a group, that has project admin rights, can create a new workspace. When clicking on “Create new Workspace” on the user interface, a wizard guides the user through the workspace creation and a workspace can be created with four selection options: create an empty workspace, create a workspace by uploading an own workspace template or use one of Intland’s Smart templates. When creating a new Retina workspace, the workspace name is always mandatory and unique. Workspaces can be defined with a unique key, which is a workspace prefix and a category. A SCM Repository (Git, Mercurial, Subversion, CVS) can be directly connected or skipped when creating a workspace. The Workspaces page is a visual interface for viewing, navigating and managing workspaces with filter options (color, status, workspace name, categories) and grouping to compact working sets according to line of business or function. A card visualizes each workspace with a workspace icon, whereas by default it has a blue color with a globe symbol at medium size.

Workspace categories can be changed via drag&drop and each workspace has a built in arrow icon in the top-right corner when hovering with the mouse that shows the details and information about the workspace for the management.

1.1.1 Create a new blank workspace

When a new workspace is created without selecting a template, Retina generates a “standard” workspace, which means that workspace's default wiki page, some trackers of different types (e.g. requirements, risks, tasks, change requests, bugs, test cases, releases) with standard configuration, links and permissions will be created.

1.1.2 Remove workspaces

Upon "Remove workspace...", an Open or Closed workspace will be marked as Deleted (this is reversible, see below).

The workspace and any content will not be accessible any more, only workspace administrators can see their removed workspaces by clicking on the "Removed Workspaces" icon on the top right of the page (next to the Searching) of Workspaces page.

1. You can restore a logically Removed workspace via "Restore Workspace ..." to its original state (Open or Closed)
2. Only when you execute "Remove Workspace..." on a logically deleted/previously removed workspace, the workspace and all its contents will be physically deleted (irreversibly)!

• All the contents of the workspace (including trackers, forums and documents) are removed
• Source code from the server is deleted only if the source code is checked-out from a revision control system

Otherwise the source code remains on the server's file system.

To remove a workspace:

1. Open Workspaces tab
2. Click on More Functions next to the Workspace's name
3. Click on Settings
4. Open Remove tab
5. Click on Remove Workspace
6. Confirm the removal

1.1.3 Modify Workspace Configuration

Different workspace configurations can be modified from the Workspace settings page.

To edit the general options:

1. Open a workspace
2. Click on the Admin tab
3. Click on the Workspace Settings menu

This page allows the Workspace Administrators to edit various properties of the workspaces.

Meaning of Fields on the General tab:

Name: The name uniquely identifies the workspace.

Key: User can use the short name when he would refer to the workspace home page by an URL.

Category: User can select a category of the workspace.

"This workspace is available as template": workspace's configurations can be reused by enabling a workspace as a template.

Workspace's icon: User can select or upload a specific icon to the workspace.

Trackers tab:

Workspace administrators can override certain labels in the top menu bar. These changes only affect the active workspace, labels remain the same in any other workspaces. All workspace members will see these modified labels, when working within the workspace.

1.1.4 Create a new workspace using your own template

Alternatively on the first page of the wizard, an existing template workspace can be chosen to copy either by marking the other template as template and selecting this one in the drop down menu, or by uploading a file (e.g. Son, .bson, .zip compressed, .reqif, .reqifz). When creating a new workspace using an own workspace template, wiki templates, documents, reports, calendars and members can be copied. For workspace administration purposes, trackers, s and configuration items can be copied or inherited from the template workspace which means that the inherited settings can override the derived trackers, work items and configuration items. In the Admin page of the workspace in the Workspace settings tab, a workspace can be marked as a template.

1.1.4.1 Export workspace template as file

In Retina there is a possibility to export a workspace configuration file to use it as a workspace template. For this method user has to follow the steps below:

• Go to the Admin tab and select Workspace Settings
• Under the Export tab, user can select the artifacts that should be included in the template file (Documents, Wiki Pages, Dashboards, Work items, Reports, Trackers)
• By clicking on OK the workspace configuration file is exported as a template

1.1.4.2 Mark workspace as workspace template

When creating a new workspace in Retina, previous workspace's configurations can be reused by enabling the existing workspace as a template. By clicking on Admin, then opening the Workspace Settings, there is the following subtitle on the General tab: "This workspace is available as template". By enabling this function, user can re-use the template's configuration on the Workspace creation page.

1.1.4.3 Create a new workspace by selecting the workspace template

On the Workspaces tab, user can select the "Create new workspace" button on the top left of the page. There is a dropdown menu, where the user can decide which template category should be used for the new Workspace. By selecting "My Templates" the available workspace templates appear on the page.

1.1.4.4 Create new workspace and inherit configuration from workspace template

When using a template on the Workspace creation page user has to click on "Use template" button to set the configuration inheritance for the work items and config items. Inherit is a copy of all trackers with their notification settings. Workflow and permissions settings will be used from the original trackers of the template workspace. Reference fields will refer the newly created trackers. Inheritance is a live relation between the inherited trackers and their templates.

1.1.4.5 Create new workspace and copy configuration from workspace template

When using a template on the Workspace creation page, user has to click on "Use template" button to select the work items, config items, wiki pages, and members to copy. Whether to copy tracker configurations with their workflow-, permission- and notification settings, reference field will refer the newly created trackers. There is no relation between the copied trackers and their templates afterwards. In case of copying the wiki page, all pages from the template workspace will be copied along with the permission settings. When the user chooses to copy the members of the template workspace, the copied members will be assigned to the same roles.

1.1.4.6 Unmark template usage and modify workspace

In case of creating a new workspace in Retina by using a workspace as a template, user have the ability to uncheck the copied template's "Available as template" checkbox in the Workspace settings menu. If the checkbox is unchecked, the template will not appear in the list of available templates.

1.1.4.7 Delete workspace that uses as workspace template

When deleting a workspace that uses as workspace template, the centralized configuration of the derived trackers will no longer be possible. This will not affect its derived trackers, but the deleted template will be removed from the inheritance hierarchy. When deleting a tracker from the template workspace, error message appears to check if the user really wants to remove the tracker that is used as a template for derived trackers. The tracker will be moved to the trash, to delete (including tracker items), user has to delete from the trash.

1.1.4.8 Create new workspace by re-using the template file

By exporting a workspace in the Workspace settings, user can Upload the downloaded template file in the workspace creation page. For this method, "Upload new template" button should be selected. In addition to the workspace's configuration, user can include:

• all the workitems and documents
• wiki pages
• dashboards

if these are covered by the uploaded template. By unchecking the checkbox the created workspace will be created without the unchecked workspace contents.

1.1.5 Create a new workspace using one of Intland’s Smart templates

Intland provides out-of-the-box Smart templates with preconfigured trackers, workflows, documents, roles and permissions that can be copied for evaluation purposes quickly e.g. Agile Scrum template, Hybrid template, Document Management, Test Management, industry-related templates such as for Automotive, Medical, Pharmaceutical, Avionics. Own smart templates can be easily created by exporting existing workspaces, so artifacts can be reused several times and even between different Retina instances. Workspace export can be done in the Admin page of the workspace in the Workspace Settings tab.

1.2 Manage User Accounts

Users, or individual identities that have a Retina account, can be created. An account is used to identify a user by name and by password. Account information contains data such as name, organization, e-mail, skills, etc. A Retina user can have a set of roles in a workspace, which entitles that user to access all resources allowed by those roles. Users are also associated with a group, which specifies a different set of permissions that apply for all workspaces. In the System-Admin tab, new user accounts can be created, and user can be manually or automatically assigned to a group.

1.2.1 Creating Retina user accounts

Retina operates with user accounts. A user must have an account before logging in and participating in a workspace. When creating an account the user's name, password and e-mail address are required and other optional data may also be entered. The e-mail address will be used by the notification service and will not be visible to other users in the notification, except if the particular other users have certain ('member view') privileges. The optional data that can be entered includes telephone number, mobile number, organization name, time-zone and location. These personal data fields are visible to other registered users with the appropriate permissions.

To create an account:

1. Open the Login tab
2. Click on Register now! link
3. Fill in the registration form
4. Click on the Register button

1.2.2 Modifying Retina user accounts

System Administrators can edit the email address of anybody by default. By opening the User Profile, user can modify his own Personal details, Preferences, Groups and Password.

To Change the datas on the User Profile:

1. Click on Edit
2. Edit the changes
3. Click on Save

1.2.3 Deactivating user accounts

In Retina it's not possible to delete users, instead of disable them. Disabled users cannot log in; however the account remains on the server with all its related history, settings and references are preserved. The license manager does not count disabled user accounts, this is the reason why it is a better practice to disable a user account than to delete it. Disabled accounts cannot be reactivated because of fulfilling compliance rules. User accounts can be disabled by System Administrators, on the System Admin page, by opening User Accounts tab and changing the user's status on the Personal details tab to "Disabled".

Disabled users lose:

• Associated Product Licenses
• Roles
• Workspace memberships

1.2.4 Password recovery

If the user forgot his password while trying to log in to the system, "Forgot password?" link could be used on the login page. By clicking on the link, user can enter the username to send a password reset request or e-mail address could be used as well instead of the username.

1.3 Manage Workspace Roles

Roles reflect hierarchical or task-based team structures in a workspace (e.g. Developer, Tester, Stakeholder). A role's access permissions scope is workspace-wide. In the Members tab of a workspace, users and their roles including workspace permissions can be managed in Retina. On the left side, all available roles are listed. Additional roles can be added, and optionally existing role permission configuration can be reused by the workspace admin or any other role, which has workspace admin rights. Existing roles can be adjusted or deleted by double clicking on the role's name in the Roles list. Out-of-the-box, the workspace admin role always has all permissions, and this is not adjustable.

1.3.1 Add a new blank workspace role

When creating a new blank workspace in Retina user can add other users to the workspace in order to set up a team. Users added to a workspace become workspace members. To organize members into a team structure, user have to assign the right roles to each member.

A good practice is to set up the workspace roles (or custom roles) in advance when a workspace has been created by enabling the appropriate role access rights. Later on, when the team is finalized members can be assigned roles.

To add a new blank workspace role:

1. Click on a workspace
2. Click on Admin, then Members & roles
3. Click on the New Role link
4. By setting the proper permissions and the name of the new role, the role can be created by clicking on Save

1.3.2 Create workspace role by re-using an existing workspace role

When creating a new workspace role, user have the ability to re-use an existing workspace role, where the permissions are pre-defined properly.

1. Click on a workspace
2. Click on admin, then Members ＆ roles
3. Click on the New Role link, then use a Template from the dropdown menu

1.3.3 Modify workspace role

Group level visibility and access to workspace information such as trackers, forums, documents, builds, SCM and source code, can be controlled using roles. Roles ensure that both internal teams and business partners only see and access the information appropriate to their respective roles. Members of the same role have the same level of access to workspace information. When accessing workspace information, the system uses the highest level of a member's access permission based on his roles and group memberships.

To customize a role:

1. Open a workspace
2. Click on Admin tab, then Members ＆ Roles
3. On the left side panel, double click on the role you want to customize
4. Select the permissions
5. Edit the name and description if required
6. Click on save

1.3.4 Modify workspace admin role

In Retina there is no possibility to modify the permissions related to the Workspace admin role.

1.3.5 Delete workspace admin role

In Retina there is no possibility to delete the Workspace admin role.

1.3.6 Delete workspace role

In addition to the modification of the workspace roles, it is possible to delete them as well, except the workspace admin role. With a double click on the role's name on the Members＆roles page permitted user can delete the role by using the bin icon on the top right of the role editor window.

1.3.7 Assign user to workspace role

In Retina, there are two possibilities to assign a user to a workspace role. By double clicking on the user's name on the Members＆roles page, user can select the role that should be assigned to the current member. The other option is to drag and drop the role on the user's name on the Members＆roles page.

1.4 Templating

When creating a new workspace by using a template workspace, on the 1st page of the wizard user can choose to copy great many options from an already existing template workspace. If the user has chosen that option and picked the other workspace to copy from then a wizard page will appear. The page contains many options and artifacts (Tasks, Bugs, Requirements etc...) which can be copied or inherited from the selected template workspace.

By copying or inheriting artifacts from the template workspace, users can save great amount of configuration work.

When creating a new workspace by using Intland's Smart Templates user can use a preconfigured template that contains predefined trackers, workflows and documents. Retina comes with several Smart Templates that could be used to set up an environment for evaluation purposes quickly.

User can also create an own Smart Template by exporting an existing workspace. This way artifacts can be reused several times, even between different Retina instances. To export a workspace open the Admin tab of the workspace and click on Workspace Settings, open the Export tab and click on Export.

1.5 Manage Groups

A Retina group is a categorization, or a collation of users classified by common traits such as job profile, skill, title or representing an organizational structure (e.g. Marketing, Sales, Development). The scope of group permissions is workspace-wide. In the workspace User Groups tab, a group can be assigned with one/multiple role(s) instead of assigning individual members to a workspace. Only the group system-Admin or any group, which has system-admin rights, can define additional groups, manage or delete existing groups and assign user to groups. LDAP group synchronization is available.

1.5.1 Add a new Group

A group is a collection of users. Groups can represent organizational structure. The scope of group permissions is server-wide. A Retina group is a category of users classified by common traits, such as organization, job profile, skill or title. With the group structure users could be collected on the Retina server into logical sets, and assign them different sever-wide permissions such as workspace-creation permissions or permissions to view other users' personal data. Groups can only be administered by the System Administrator.

To create a new group:

1. Click on System Admin
2. Click on User Groups
3. Click on New Group
4. Fill out Group, Description (LDAP/AD Group Name)
5. Change the permissions (if the user selects an existing group from the "Based on" selector, the group permissions will be copied from this existing group)
6. Click on Save

1.5.2 Create group from an existing group

In Retina, if you select an existing group from the "Based on" selector, the group permissions will be copied from this existing group.

1.5.3 Modify a group

To modify a specific group in Retina, user has to open the group that should be modified, then click on Edit button on the top of the page. After changing the properties, this can be finalized by clicking on the Save button.

1.5.4 Delete a group

On User groups select the group to delete, and open its details page.

Click on the Delete button in top-left corner of the page to delete it.

1.5.5 Assign users to a group

In Retina, it is possible to assign users to specific groups. By clicking on the group name on the User groups tab, system admin user can access the group's properties. There is a button on the top of the page, called "Assign members".

1.5.6 Assign group to a role in a workspace

Groups can also be assigned different roles in different workspace. This makes the management of access rights very convenient, especially when a large number of users must be managed.

Roles are administered in each workspace by the Workspace Administrator. A role's access to workspace information is defined by the Workspace Administrator on the Members ＆ roles tab, by opening the Groups and assigning a role with a drag and drop a role to a created grup.

1.6 Workspace Categories

Administrators with proper permissions can create workspace categories. Workspace categories could be used to represent a hierarchy of concepts.

1.6.1 Category Admin role

Workspace category admin role is an ability to manage categories on the Workspaces page. This permission could be set in the System admin page below the User groups by specifying the group's permission.

1.6.2 Create/Modify/Delete Categories

Workspace categories could be created, modified and deleted by the Workspace Category Admins. To create a new category should be selected on the Workspaces page. To delete a category, three dots should be selected next to the category's name, then click on delete. To modify a category, Edit category should be selected.

2 Management of Personal and Workspace Wikis and Dashboards

A built-in workspace-related wiki is available in Retina. For limiting access, wiki pages could be specified with role-based permissions on the Permission page of the wiki's Properties. The role-specific wiki page is a limited workspace wiki which can be used to capture all relevant information related to existing roles. The (unlimited) workspace wiki helps to capture and manage knowledge in a transparent, scalable, secured, controlled and collaborative way. Any formal or informal conversation can be performed in the wiki.

2.1 Create a new Wiki Page

A new wiki page can be created by clicking on “Add New Wiki Page”. A wiki has a page tree, content, navigation and a property section. The wiki page tree contains the full wiki page structure from the root wiki page and pages can be hierarchically restructured via drag&drop. In the property section, wiki permissions, comments, attachments can be defined.

2.1.1 Rearrange wiki page hierarchy in the tree structure

The wiki page tree contains the full wiki page structure from the root wiki page (personal or main workspace wiki page). The wiki content can be loaded by clicking on the wiki page's name in the tree. The hierarchy of the tree structure could be rearranged easily by using the drag and drop functionality.

2.1.2 Change a Wiki Page's permissions

The Wiki page Permissions are based on user role and group level. Read and edit (write) access is controlled at each wiki page level, in a very similar way to how the Document Manager works.

To set page level read/edit security:

1. Select the Properties by right clicking on the editable wiki page
2. Click on the Permissions tab
3. Select the checkboxes from the Read and Edit columns for each of the user roles
4. Click on Save to activate the settings

2.2 Edit Wiki Page with WYSIWYG or Office-Edit

The wiki can be edited directly with the build-in “What you see is what you get”-Editor (WYSIWYG) or in the Office-Edit mode, which allows for editing on a Microsoft Office document e.g. Word. When using Microsoft Office, Retina will synchronize the changes back to the wiki page automatically, when the user hits the save button. During a wiki edit, another user is not able to apply any other changes in parallel, because it gets locked automatically.

2.2.1 Locking Wiki Pages for editing

When a user start editing a public wiki page, a warning message appears on the top of the page: "Currently locked by @username". After saving or closing the editor, the wiki is automatically updating and becoming unlocked. Retina allows the user to edit the wikis in Microsoft Word. Simply click on Edit via Office in the More Options dropdown menu and the wiki is automatically locked and the wiki is opened in an MS Word session. After editing, saving and closing MS Word, the wiki is automatically uploaded and unlocked for the next user. Headings, tables, links, bullet lists, and many symbols are automatically converted between Word and Wiki formats, so that you can either create them in Word, and have them upload into Retina wikis, or edit them in MS Word.

2.2.2 After modification, save the wiki page with the changes

By modifying a specific wiki page, the changes should be saved by clicking on the save button on the editor. The modifications are available in the wiki page's Properties, by clicking on the History tab. It is also possible to restore the previous version of the wiki page by selecting the down arrow next to the versions in the History.

2.3 Versioning of Wiki Pages in the history

Wiki pages are all fully audited and versioned. Each modification creates a new version, which is archived in the history tab in the property section.

2.3.1 Comparison between wiki page versions

Different wiki versions can be compared with each other and Retina highlights the difference between both versions.

2.4 Link Wiki Pages to Items via association

Items can be linked to one or several wiki pages. In the properties section, the Link tab shows incoming links (other documents that links to this document) as well as outgoing links to other documents. New associations can be created in the Associations tab.

2.5 Out-of-the-box plugins in the Knowledge Base

Wiki pages are highly customizable with numerous out-of-the-box plugins, which are accessible from our Knowledge Base, e.g. Activity Stream, MyCurrentItems.

2.6 Wiki comparison

Wiki page state of a specific workspace can be compared against a baselined state. By selecting the three dots (More Functions) in the middle of the wiki page, the user can select to Compare versions or Compare baselines. The following differences will be indicated in the left tree:

• new pages on a specific tree level
• modified pages
• removed pages
• moved pages

2.7 Management of Dashboards

Dashboards inherit many features from Wiki pages, like permission management, or the ability to export the content or the possibility of having child pages. However, it focuses more narrowly on visualization. Unlike Wiki pages, users don't have to type in content, but rather they can choose from available Widgets, which form the basis of all Dashboards. These Widgets are rendered using user-selectable layouts; all of them supports drag&drop operation to simplify arranging the widgets within the layout.

2.7.1 Add new widget to a Dashboard

In Retina it's possible to create expressive and informative "boards" by using Dashboards. Dashboards inherit many features from Wiki pages, like permission management, or the ability to export the content or the possibility of having child pages. However, it focuses more narrowly on visualization. Unlike Wiki pages, users don't have to type in content, but rather they can choose from available Widgets, which form the basis of all Dashboards. These Widgets are rendered using user-selectable layouts; all of them supports drag&drop operation to simplify arranging the widgets within the layout.

To add a new Dashboard there is an Analytics tab on the top of the page. By clicking on it, user can access the Dashboard page, where similarly to the wiki pages there is a personal dashboard which could be customized specifically to the current user, and there are public dashboards related to the active workspaces as well. When opening a dashboard, users can add widgets to visualize data by clicking on the Add widget button on the top of the page.

2.7.1.1 Report Visualization

In Retina there is an option to visualize previously saved reports on the Dashboard page. By adding a new widget to the dashboard page, Retina offers Report visualization widgets (Calendar, Chart, Simple, Table) on the first tab. By opening one up, the Data source should by specified by selecting a previously saved report from the dropdown menu. In addition to the data source, user can define the name, size, color, and other visualization related settings. By saving the preview, the report visualization widget becomes visible on the Dashboard page.

2.7.1.1.1 Chart

Chart Widget unifies the previously standalone report visualization widgets. This makes it possible to change the chart type after creating the widget. The configuration options for each widget type stayed the same.

2.7.1.1.2 Table

The Table Widget visualizes the result of any report in a tabular form.

On its editor there are some special fields:

• Columns: you can select the columns of the report that you want to show in the table
• Column order: you can change the order of the columns with drag and drop
• Order by: select the column used for ordering
• Sort: the direction of the ordering (ascending or descending)
• Page size: the maximum number of items shown in the table. If there are more rows, then the table is pageable.

2.7.1.2 Workspace

Workspace widgets has three kind of widget types, the Activity Stream, Item Count Trends and the Risk Matrix diagram. These widgets enable the user to visualize workspace-related data on the Dashboard page.

2.7.1.2.1 Activity Stream

Activity Steam Widget provides an aggregated view of all recent activities in a workspace, including wiki pages and item submissions.

2.7.1.2.2 Item Count Trends

The Item count trend displays the number of items created vs the number of items resolved over a period of time.

2.7.1.2.3 Risk Matrix Diagram

The Risk matrix diagram widget adds the risk matrix diagram as a widget to the page. It shows the number of Requirements or User Stories/Risk/Epic items according to the related Risk(s)' likelihood and severity values.

2.7.1.3 Agile

Agile dashboards help plan, track and manage agile development. These kinds of widgets show content that's relevant for agile teams. Users can monitor, improve, and predict the team’s performance on the dashboard page.

2.7.1.3.1 Burn Down Chart

The burn down chart widget displays the burn down chart based on open wok items for a release or sprint. Users can filter the burn down chart by teams.

2.7.1.3.2 Current Velocity

The current velocity widget displays the velocity of the last known (work)day within a release or sprint. Velocity (the number of items your team can complete) may be filtered by teams

2.7.1.3.3 Release stats

The release stats widget displays the statistics of a release. Data for these stats are pulled from the release dashboard page.

2.7.1.3.4 Remaining Time

The remaining time widget displays the number of days left until the planned release date of a release or sprint.

2.7.1.3.5 Sprint Break Down Widget

The sprint break down widget displays the status distribution of all items in a release or sprint. This gives the user a quick overview of the progress made.

2.7.1.4 Test

Test type widgets support teams to visualize test progresses and results on the dashboard.

2.7.1.4.1 Requirements Coverage

The Requirements coverage widget that shows the test or other work item coverage of the requirements.

2.7.1.4.2 Test Runs By Assignee

The test runs by assignee widget shows a bar chart based on all test runs in a workspace or just some test run trackers. The chart contains a single bar for each user that has executed a test run and one for the test runs that have no assignee. The bars show the distribution of the results of the test runs of that given user.

2.7.1.4.3 Test Runs By Test Set

The test runs by test set widget shows a bar chart of all or selected test runs in a workspace. Each test set is represented by a bar. The chart shows the distribution of the test run results of the selected test set.

2.7.1.5 Other

Under the Other tab there are some additional widgets which could be useful to display other kind of relevant data for the user (e.g.: reviews, wiki markups, etc.).

2.7.1.5.1 My Current Items

The “My current items” widget displays a list of the items assigned to the current user (that are not in closed or resolved statuses). Items are ordered by priority and last modification date (descending).

2.7.1.5.2 My Reviews

The "My reviews" widget displays a list of the specified user's reviews.

2.7.1.5.3 Tile

The tile widget displays data (title, subject) and navigates the user to the previously defined hyperlink.

2.7.1.5.4 Wiki Markup Widget

The wiki markup widget wraps a wiki markup into a widget and makes it reusable on dashboards.

2.7.2 Change the layout of a Dashboard

Dashboards can render widgets in grids. You can choose from a couple of predefined configurations with different number of columns and sizes. This Responsive setting could be changed in the Widget's editor. The options are:

• 4-2-1
• 3-3-1
• 1-1-1
• 4-4-1
• 2-1-1
• 6-3-1

2.7.3 Dashboard Permissions

In Retina it is possible to limit the permissions to access dashboards by opening the Dashboard's properties and selecting the related roles in the workspace whom you would like to grant read or write access to the dashboard and its widgets .

3 Managing documents in the "Integrated Documents Management" module

The built-in documents management of Retina lets the user store any type of document and secures role-based document access to share, download, upload and track documents. The documents follow the who-when-what-approach. Information on user, date, and action are displayed. Prior versions can be restored to any point in time. With the live-edit mode, Excel, Word, and PPT can be directly edited in Retina.

3.1 Upload documents

Any kind of files can be uploaded into the documents management either by selecting a file from the build-in browser or by dragging a document into Retina via drag&drop. The default maximum size of a document upload in Retina is currently 5 GB. You can also create directories to structure your data. The documents management has a directory tree, navigation and a property section. In the property section, documents permissions and notifications can be defined.

3.1.1 Allow duplicates

In Document Tracker configuration General tab you can setup your tracker to allow item name duplications.

Check on 'Allow item name duplications' and save configuration. From now on you can upload multiple documents with the same name.

If this option is not allowed, you can still define upload method on the bottom of the Create new documents dialog:

• create new version (default): new document with the same name will be uploaded as the new version of the doc with the same name
• skip existing: new document upload will be skipped
• create with new name: new document will be uploaded with a new name

3.1.2 Upload zip file

If you upload a zip file, you can choose between two upload method.

• if you select the Save button, zip file will be uploaded as one archive file item
• if you select the Unpack archive file button, zip will be unpacked, and the contained files will be uploaded into the document tracker

3.1.3 The Upload Manager

Upload manager is a visible log of your document item uploads. It displays the filename and the action is taken when uploading.

It is possible to minimize it to the bottom right corner so the user navigates away from the upload queue while it is in progress. The process runs uninterrupted in the background unless you close the Upload Manager window or cancel the upload within the UploadManager.After the upload starts, there are abilities to pause, restart, or even cancel the upload of individual files.

3.2 Edit Documents with Office Edit

Retina supports Office-Editing documents directly from the user desktop as well. Documents can be also be downloaded and edited in the traditional way as well.

3.3 Archiving-, and versioning documents

When modifying in the Office-Edit and saving the document, Retina will synchronize and create a new revision, which is archived in the history automatically. When the document is downloaded, modified and uploaded afterwards into the documents managements at the same directory again, Retina also creates a new revision for the existing document and archives old versions.

3.3.1 Restore old document versions

Document versions are separately stored and can be restored. If the user wishes to restore an older version of a document, detailed editor should be opened by clicking on the document's Retina ID. If the document has 1 or more previous version(s), the user has the possibility to choose "Revert state of field(s) back to this version" on the History tab.

3.4 Link Documents to Items via association

Items can be linked to one or several documents as well. In the properties section, the Link tab shows incoming links (other documents that links to this document) as well as outgoing links to other documents.

3.5 Search in Document content

Beyond the usual search option you can search in document content as well in document tracker.

Click on the gear icon in the header of the tree panel to open Settings dialog.

Check in Document content option in Search in section, and Save settings.

The filtered text will be searched in the content of the documents.

3.6 Download selected items as a zip file

You can also choose to download items as a zip file. When a folder is zipped, the tree structure is kept and contained files are zipped too.

Right-click on a document item, in the the left pane in Document view and choose Download selected as zip.

3.7 Download (selected) items

When selecting items in the documents tracker's tree structure, user have the possibility to download them by right clicking on one of them, then choosing the "Download selected" option from the dropdown menu. It is also possible to download the document by clicking on the item's Retina ID on the main panel, then selecting the name of the document to download.

3.8 Documents tracker folder's content on the main panel

When opening a folder in a document type tracker by clicking on its name, the content of the folder will be visible on the main panel of the tracker's Document view.

3.9 Store document in a document tracker

When exporting a tracker's content to office, user can decide if he would store the document in a document tracker instead of download. When selecting the Store option, the proper target workspace and the document type tracker should be selected. It is also possible to select what should happen when there is already a document with the same name. When selecting Overwrite, Retina will update the existing document with the new one. The Rename option means Retina will keep booth the existing and the new documents and rename the new one to avoid name collision.

3.10 Send document to requirement

In Retina you can feed your reviewed document into the requirement management process, transform it into requirement(s). For this process, the Details tab of the reviewed document item should be opened. By selecting the "Send document to requirement" option, a popup window appears where the user can select the target workspace and tracker which should contain the elements of the reviewed document. Once you are happy with the results on the Preview page, choose Finish.

3.11 Copy/move documents

When uploading documents in Retina it is possible to move them to another documents type tracker. For this process, the Details tab of the document item should be opened. By selecting the "Move to..." option, a popup window appears on the page where the user can select the target workspace and the target document type tracker which should contain the document. Only document type tracker could be selected from the dropdown menu as a target tracker.

3.12 Document sorting

In Retina the default ordering rule for folders and items is A-Z. It could be changed to Z-A, by clicking on the "Documents name" on the top of the page.

If the item name duplication is allowed the user can order by duplicated items by different fields.

3.13 Sharing folders and items

To share folders and their content or selected items with others from a document type tracker, a permanent link could be created. By selecting the "Share with others" option on the top right of the page, the page will be reloaded with the previous result a nd the URL can be copied or shared with other users/groups/e-mail addresses which will contain the configurations you set . When sharing a folder from one of the documents type trackers, their content will be visible as well. The shared folder will be highlighted in the tree and the content of the shared folder will be visible in the main panel.

4 Trackers

Trackers are the essential parts of Retina and are basically item containers or the equivalent of tables in a relational database or classes in object oriented programming. Trackers define properties (fields), relation to other items in other trackers via reference fields, that are similar to foreign keys and on trackers, the behavior, permission, workflow, escalation rules and notifications can be defined. There are different tracker types such as requirements, tasks, bugs, change requests, releases, risks, test cases, etc. and they can be “tracked”. Additional Trackers can be added individually, and the user can choose the tracker type.

4.1 Manage Trackers

--

4.1.1 Create trackers and define permissions

In Retina, trackers can be set up individually on the user interface by any role, which has workspace admin rights. For each tracker, the permission can be defined as per role. When creating trackers, Retina will create different default properties, workflow and permission according to the selected tracker types.

4.1.2 Customize tracker attributes

For each tracker, the tracker properties/attributes can be highly customized by each role that has tracker admin permissions. In the customization of any tracker, additional fields such as custom fields (of type text, integer, date, boolean, etc.), calculated fields with syntax, choice fields with different data sources (such as options, work/config item (CMDB), users, workspaces, etc.) or tables can be added with individual width and height in the Fields tab. Role-based permission can be defined for each field, which can be unrestricted, single or even different per any status. There are standard fields that cannot be removed e.g. summary, description, status due to managing the trackers. Dynamic pic-list fields with dependencies for parent and child hierarchies can be defined via association and distribution rules.

4.1.2.1 Create new tracker fields

By using Retina's Fields management page in the trackers' configuration, users can customize their preconfigured or newly created fields. It is possible to create, edit or remove fields and create computations as well. The newly created fields could be listed or hided and they could be categorized on the Layouts page as well.

4.1.2.1.1 Create a new simple custom field

In Retina, users can configure an arbitrary number of custom fields for a tracker. To add a new custom field for a tracker, the tracker's Configuration page should be opened by clicking on the More Functions. There is a button on the middle of the Fields page, called "New choice field". By clicking on the down arrow, next to the button's name, a dropdown menu appears which allows the user to select "New custom field". In the popup editor, user can add the Label, Description, Datasource, etc. of the new custom field. The "List" checkbox is used to configure which fields should be displayed (as table/list columns), and which should only appear on the details/editor screen.

4.1.2.1.2 Create a new choice field

Using Choice fields, tracker attributes or fields can be configured to allow selection from a list of choices.

To create a new choice field, the tracker's Configuration page should be opened by clicking on the More Functions. There is a button on the middle of the Fields page, called "New choice field". By clicking on the button, a popup window appears which enables the user to customize the new choice field's settings.

The "List" checkbox is used to configure which fields should be displayed (as table/list columns), and which should only appear on the details/editor screen.

4.1.2.2 Modify custom fields

To modify a custom field in a specific tracker, the tracker's configuration page should be opened. Selecting the Fields tab allows the user to find custom fields in the Type column. When the user hovers the cursor on the field's name, a down arrow appears on the right side of the Layout and Content column. The user can modify the field by clicking the arrow and then select the Edit button.

4.1.2.3 Delete custom fields

To delete a custom field, the tracker's configuration page should be opened. When hovering the cursor on the field's name, a down arrow appears on the right side of the Layout and Content column. By clicking on the arrow, then selecting the Remove button, the field becomes removed. The audit trail of the Fields could be checked in the tacker's configuration page, by selecting the Audit Trail tab.

4.1.2.4 Set displayed label of a field

To configure the displayed label of a field, tracker's configuration page should be opened. On the Fields tab, user have the possibility to rename the label of a specific field. By hovering the cursor on the field's name, a down arrow appears on the right side of the Layout and Content column. When clicking on Edit, user can customize the Label.

4.1.2.5 Set list view visibility of a field

To set the visibility of a field in list view eye icon (Visible columns) should be selected on the right side of the page. By selecting the fields from the dropdown list, the selected field(s) become displayed on the top of the page. It is possible to save this specific view as well by clicking on the Filter icon, then selecting the Save as button on the Standard filter tab.

4.1.2.6 Set a field to mandatory in a specific status

In Retina it is possible to set a field as mandatory in specific status(es). In this case, permitted user will be asked to fill the content of the field. To configure it properly, the Tracker's configuration page should be opened. By selecting the Fields tab and clicking on a field's name, the proper statuses could be selected below the Mandatory in status section.

4.1.2.7 Set allowed values per status to a field

For limiting the allowed values of a field based on different statuses, the Field's configuration page should be selected. If there are pre-configured Options for the selected fields, the options could be set per status in the Allowed values column, by opening the "Allowed/default field values".

4.1.2.8 Set default values per status to a field

In Retina user can set default values per status to a selected field. For this process, Field's configuration page should be selected. If there are pre-configured Options for the selected fields, the options could be set per status in the Default values column, by opening the "Allowed/default field values".

4.1.2.9 Set the permission model to a field

For limiting access to specific fields, users can modify the permission on the Fields configuration page.

4.1.2.9.1 Set field permission model to unrestricted

On the Fields configuration page, below the Permissions column, user can set unrestricted permission to a field. When creating a new Custom or Choice filed, the Permission is always Single, but this could be changed by clicking on it, then selecting the unrestricted option from the dropdown menu.

4.1.2.9.2 Set field permission model to single

On the Fields configuration page, below the Permissions column, user can set Single permission to a field. When creating a new Custom or Choice filed, the default Permission is always Single. If another user changed the field permission to a different one, it could be changed easily, by clicking on the name of the permission, then selecting the Single option from the dropdown menu.

4.1.2.9.3 Set field permission model to "per status"

On the Field's configuration page, below the Permissions column, user can set status-based permissions to specific roles. When creating a new Custom or Choice filed, the Permission is always Single. By clicking on it, there is a dropdown menu on the top of the page, where the Per Status option could be selected. When selecting this option, the statuses appear on the page based on the tracker's State Transition diagram. The default setting is the edit permission for each user, but this could be changed easily. It is also possible to set special permission for different statuses, by clicking on the down arrow, next to the Default label.

4.1.2.10 Set permissions for a field based on roles

It's possible to limit the access of different fields based on specific roles. When opening the field's permission on the fields configuration page the permission's name could be selected. Here it is possible to set role assigned to permissions for a field, based on selected permission model. If the status-based field access is Special, it is possible to click on the grey area where the access type could be set for the specific users in different statuses. It is also possible to set the default value's permission on the top of the page and then enable the default values for each status and each role.

4.1.2.11 Set a distribution rule for a field

If the user has parent/child hierarchies of configuration items or work items, it is possible to define dependencies between parent field values and the appropriate child field values (recursively). If the user wish to ensure that a parent work item is not closed until all the child-work items (children) are closed, then this dependency can be managed using one of the standard distribution rules (Set, Default, Least, Greatest, Fraction, Subset, Superset, Close recursively, Close restricted) on the field's configuration page below the Distribution rule column.

4.1.2.12 Set an aggregation rule for a field

Aggregation rule is when a parent Work Item’s Field Value depends on Child(ren)'s value(s). Standard aggregation rules (Minimum, Maximum, Sum/Total, Average, Union, Intersection, Mean status, Close upwards) can be set on the field's configuration page below the Aggregation rule column.

4.1.2.13 Setting field dependencies

Besides the dependencies between the same field of parent and child items in a tracker, which are controlled via the field's Aggregation and Distribution rules, Retina allows to define dependencies between different fields (of the same item). When opening a field by clicking on its name, below the Datasource section, there is a possibility to create dependencies between the selected field and another field of the item.

4.1.2.14 Setting up a computed field

In Retina it is possible to define read-only tracker fields whose content is calculated from other tracker item fields. Every custom field can become a computed field, by specifying an expression or formula for the field.

4.1.2.14.1 Calculated field values

To support the search and filtering opportunities in Retina, calculated field values are saved to the database immediately.

4.1.2.15 Static Dependency

To create static dependency, create two choice fields on tracker config's Fields tab: A and B.

Set available options for field A.

In field B set field A as Depends on in the Datasource section. Set avaliable options for field B too, and save configuration.

In Fields table, Layout and content column you can set up static dependency by clicking on Depends on <fieldName> link.

Choose an option from field A in the first column, and one or more options from field B in the second column, and save them. Any other option from field B will be forbidden when field A is selected in the .

4.1.3 Workflow configuration

Each tracker has its own customizable BP (business process) with Retina's strong workflow BPM (Business Process Management). The workflow can be configured in the tracker customization section amongst the State Transition tab. When creating a new tracker, Retina provides a standard workflow for each tracker type out-of-the-box. Two basic elements in the workflow are states that are equivalent to the concept of nodes and transitions that are the equivalent to directed edges in a graph. Additional status options can be added at any point of time and existing ones can be deleted, only if there are no items in that specific status. Status transitions can be defined on the user interface as well by selecting the initial status to the target status and by naming this status transition. With a Graphviz installation on the Retina server, the state transition will be visualized as an UML state diagram on the user interface. For each status transition, the permission as per role, optional conditions and guards can be defined. Condition defines in which context or for which tracker items this transition is applicable at all and a Guard is like a gatekeeper, which only will let the user pass the transition, if the subject tracker item matches specific criteria. Optional workflow actions can be defined for automatically execution upon this workflow transition.

4.1.3.1 Workflow Diagram

Workflows provide better control for critical tasks or requirements where the change has strong impact on resources or deliverables. Each workflow diagrams could be accessed by opening the tracker's configuration page, then selecting the State Transitions tab. Retina trackers integrate a simple and flexible process engine to model business process workflows. In Retina, work progress will be typically reflected in the Work Item status.

Each status can be given a Meaning, that tells Retina, to which phase of item processing the status belongs to:

• Open (pending): if none of the meanings are selected
• Obsolete
• In progress
• Resolved
• Closed

There can be multiple different statuses in the same phase. The color used for a status can be also an indicator/signal, how much attention a specific currently needs in this status.

Ideally, the order of status options should reflect the forward direction in the sense of work progress.

Related to the Workflow Diagrams, it's important to mention workflow actions as well. These are procedures, that should be called upon specific events to perform specific tasks. These can be parameterized, which greatly improves their reusability and transparency.

4.1.3.2 Default Tracker Workflow

Each tracker type has a default, configurable Tracker Workflow Diagram except Test runs and Teams. The default workflow diagram of the Test runs type tracker is not configurable. Teams type tracker doesn't have own workflow diagram.

4.1.3.3 Adding a new status

In Retina, work progress is typically reflected in the Work Item status. To create a new status, the tracker's configuration page should be opened, then by selecting the State Transitions tab user can click on the "Add status" button.

Each status can be given a Meaning, that tells Retina, to which phase of item processing the status belongs to:

• Open (pending): if none of the meanings are selected
• Obsolete
• In progress
• Resolved
• Closed

4.1.3.4 Modify a status

To modify a status in Retina, the tracker configuration page should be opened, then by selecting the State Transitions tab, user can click on the "Add status" button. When the user clicks on a status' name, an editor window pops up where the user can modify the ID, Name, Color, Description and the Meaning of a status.

4.1.3.5 Deleting a status (without work item in that specific status)

To delete a status from a configured workflow diagram, the tracker's configuration page should be opened, then by selecting the State Transitions tab, user can click on the "Add status" button. With the "Remove option" button, user can delete the specified status from the Status options list.

4.1.3.6 Add a new state transition

Trackers, where Workflow is enabled, have State Transitions. This allows fine grained control over the tracker item lifecycle (business processes) and associated workflow. To define a new state transition, Open the tracker's configuration page, then the State Transitions tab. By clicking on the "More..." dropdown menu, user can select the State Transition option. This will open a dialog, where you can enter the transition specification.

User must specify the From and To status for the transition:

• Because a transition is a status change, From and To must be different
• There can only be one transition with the same From and To status per tracker

4.1.3.6.1 Set transition from status

To set a transition from a specified status, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page. By choosing the State Transition from the dropdown menu, user can define a transition from a selected status to another one.

4.1.3.6.2 Set transition to status

To set a transition from a specified status, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page. By choosing the State Transition from the dropdown menu, user can define a transition from a selected status to another one.

4.1.3.6.3 Set transition name

To set a transition's name, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page . By choosing the State Transition from the dropdown menu, user can define the name of the state transition.

4.1.3.6.4 Set transition description

To set a description for a state transition, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page . By choosing the State Transition from the dropdown menu, user can define the description of the state transition.

4.1.3.6.5 Set transition permissions

To set permission for a state transition, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page . By choosing the State Transition from the dropdown menu, user can define the permission of the state transition below the Permitted section.

4.1.3.6.6 Add transition conditions

To add condition for a state transition, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page . By choosing the State Transition from the dropdown menu, user can define the condition for the state transition.

The following options are available:

• Expression
• Leads back to previous subject item status
• Subject approved
• Subject rejected

4.1.3.6.7 Add transition guards

To add guard for a state transition, tracker's configuration page should be opened, then by selecting the State Transitions tab, "More..." option could be selected on the bottom of the page . By choosing the State Transition from the dropdown menu, user can define the guard for the state transition below the Guard section, by clicking on Add.

4.1.3.6.8 Add transition actions

In Retina workflow actions can be associated with a state transition.

User can select from the following list of actions:

• Update item properties
• Trigger state transition
• Update referring items
• Create new Upstream/Downstream referring items
• Create a new sequential id/number
• Execute custom script
• New Baseline
• New Workspace Baseline
• New Tracker Baseline
• Remove attachments of the item
• Send a custom email to specific recipients
• Start a new review
• Validate the user signature (password)

4.1.3.7 Modify status transitions

To modify the general properties, permissions, conditions or the guards of a state transition in Retina, the tracker's configuration page should be opened. By selecting the State Transitions tab and clicking on the name of the transition, the properties could be edited. The other option for editing a transition is to click on the transition's arrow on the workflow diagram.

4.1.3.7.1 Add, edit, delete workflow actions

To add, edit, delete workflow actions, the tracker's configuration page should be opened. By selecting the State Transitions tab and clicking on the name of the transition, the actions could be edited on the bottom of the page.

4.1.3.7.1.1 Workflow action - update item properties

By using the update item properties workflow action, the field selector will show all updatable fields of the tracker item, that is source/subject of the triggering event.

For each selected field, you can choose, whether to

• Set or
• Clear

the value of th e field .

4.1.3.7.1.2 Workflow action - update referring items

When you select this action from the action selector, you also have to select

• the Relation between the tracker item, that is source/subject of the triggering event, and the items to update
• the Workspace where to update items (only if there are possible target Trackers in other workspaces, than the current one)
• the Tracker where to update items
• the Status of the items to update

There are basically two types of updating the referring items:

• Updating items that is referred from the item ( outgoing references )
  Example for a Requirement type of field:
  Parent (Requirement) -> Requirements -> New
• Updating items referring to the item ( incoming references )
  Example for a Requirement type of field ( which can also be read as its children ) :
  Requirements for Parent -> Requirements -> New

4.1.3.7.1.3 Workflow action - create new referring items

This workflow action is the equivalent of the Create Downstream Reference menu on the Tracker Item Details page, with the extension, that you can also create Upstream references, not only Downstream references.

When you select this action from the action selector, you also have to select

• the Relation between the tracker item, that is source/subject of the triggering event, and the new items to create
• the Workspace where to create new items (only if the target Tracker in another workspace)
• the Tracker where to create new items

4.1.3.7.1.4 Workflow action - create a new sequential id/number

This action can be used, to store a tracker specific sequential/consecutive ID/Number in a custom field of the tracker item, that is subject/source of the triggering event .

For example: You have a tracker called Orders and you want each Order (item of the Orders tracker), to have a sequential/consecutive Order No .

First you define Order No as a custom Orders field with type Integer (could also be Text ).

4.1.3.7.1.5 Workflow action - execute a custom script

Script action is a workflow action which executes a script on workflow transition.

First a System Administrator must carefully review and approve the Workflow transition script and then upload the script file to the "config/scripts/workflow" directory below the Retina installation.

The action has three parameters:

• Script Type
  is the script type/language
• Script Path
  is the file name of the script to execute
• Veto on exception
  whether a script execution error should abort the triggering event (true), or simply be logged (false)

Currently the following script languages are supported:

• Groovy
• Java Script

Writing the Workflow action as a script can have advantages

• Deployment is easier: no need to compile, deploy and restart the codeBeamer server for development
• Code is more compact: by using advanced features of Groovy your code can be shorter
• Quick to adapt: if the requirement changes it is easier to adjust by simply changing the Groovy script

but also has disadvantages:

• Scripts are a potential security risk
• No compile time errors/warnings. Errors can only be detected at run time.

4.1.3.7.1.6 Workflow action - create a new baseline

This action creates a new baseline.

The action has three parameters:

• Scope,
• Name and
• Description

of the new baseline.

Scope can be:

Tracker: to create a new baseline on the Tracker of the item, that is subject/source of the triggering event, or

Workspace: to create a new baseline on the whole Workspace of the item, that is subject/source of the triggering event

The Name and Description of the new baseline can be:

• (a constant) Value, that you can enter/select via the appropriate value editor, or
• Copied from text field of the tracker item, that is source/subject of the triggering event, or
• Computed as the result of an expression (on the tracker item, that is source/subject of the triggering event)

4.1.3.7.1.7 Workflow action - add a new workspace baseline

This workflow action creates a new workspace baseline.

The action has three parameters:

• Workspace
• Name
• Description

of the new workspace baseline.

The scope can be to create a new baseline on the whole Workspace of the item, that is subject/source of the triggering event

The Name and Description of the new baseline can be:

• (a constant) Value, that you can enter/select via the appropriate value editor, or
• Copied from text field of the tracker item, that is source/subject of the triggering event, or
• Computed as the result of an expression (on the tracker item, that is source/subject of the triggering event)

4.1.3.7.1.8 Workflow action - add a new tracker baseline

This workflow action creates a new workspace baseline.

The action has three parameters:

• Tracker
• Name
• Description

of the new workspace baseline.

The scope can be to create a new baseline on the Tracker of the item, that is subject/source of the triggering event

The Name and Description of the new baseline can be:

• (a constant) Value, that you can enter/select via the appropriate value editor, or
• Copied from text field of the tracker item, that is source/subject of the triggering event, or
• Computed as the result of an expression (on the tracker item, that is source/subject of the triggering event)

4.1.3.7.1.9 Workflow action - remove attachments of the item

This workflow action removes the attachment of the item.

By opening this action, and clicking on "Add" Guard condition can be created.

The guard needs 3 parameters:

• Name
• Description (not mandatory)
• Condition

4.1.3.7.1.10 Workflow action - send a custom email to specific recipients

This workflow action will send a custom email to the specified recipients.

The action has three parameters:

• Recipients
  are the email recipients (required), which can be specified as
  • Users
  • Groups
  • Roles
  • Member fields of the tracker item, that is subject/source of the triggering event
• Subject
  The name of the Velocity template file for the email subject line (required)
• Content
  The name of the Velocity template file for the email body/content (required)

4.1.3.7.1.11 Workflow action - start a new review

This workflow-based review mechanism gives control over:

• The specific (work) item states, where reviews should be performed
• The Reviewers (set of users, that are exclusively allowed/qualified to review/approve the (work) item in that specific state)
• The Review configuration:
  • What type of electronic Signature(extra reviewer authentication), is required for submitting votes ?
    • None (the user login is sufficient)
    • Password (the user must enter her/his password)
    • Username and Password (the user must enter her/his username and password)
  • In which function/role, did a reviewer perform the review
  • How many approvals (positive votes) are necessary, for the subject item to be considered successfully reviewed/approved ?
    • What should be the designated status of approved (work) items ?
  • How many rejections (negative votes) are allowed, before the subject item should be considered rejected/declined ?
    • What should be the designated status of rejected (work) items ?

To define a review state/stage, simply add the workflow action Start a new review to the appropriate state (entry) or those incoming state transitions, that should trigger the review.

4.1.3.7.1.12 Workflow action - validate user signature (password)

This workflow action only makes sense in the context of a state transition. Its purpose is, to enforce regulatory requirements, that required some kind of "electronic/digital signature" for special workflow steps.

In order to use this workflow action, you first have to define a custom tracker text field to hold the user signature/password.

The name/label of the field should be Signature or Password (You can use any name, but then the input field on the GUI will be a plain text field instead of a password field).

If the signature is optional, field should be created as optional. For those (transition target) states, where a signature is required, you have to make the Signature field a mandatory field.

4.1.3.8 Delete state transitions

In addition to the editing, it is possible to delete a state transition. First of all, the tracker's configuration page should be opened, and the State transitions tab should be selected. Next to each transition there is a Remove sign. By selecting this option the transition becomes deleted.

4.1.3.9 Suspect Guard

Suspected support in state transition guard, conditions and calculated fields. It has the possibility to ask whether an item has suspicions in calculated fields and as condition/guards in workflow actions.

"Suspected reference" guards:

• Has Suspected Link
• Has Upstream Suspected Link
• Has Downstream Suspected Link

4.1.3.10 Review Guard

With a review guard you can set some restrictions on the state transitions of a tracker.

You can require that an item is reviewed before moving to a specific status.

You can add a guard on the State Transitions tab of the tracker configuration page. Here you need to click on Edit from the context menu of a transition then on the Add link beside the Guard list.

After you set up the guard then Retina will check if there is a review for the item on Review Hub whenever you want to execute the transition.

4.1.4 Tracker History Audit Trail

The Audit Trail displays the configuration change history of the customized tracker. Tracked changes include general tracker changes, field related changes and state transition changes.

The following audit information is available in the Audit Trail:

• Tracker Changes - Customization changes which were done on the General tab
• Field Changes - Fields configuration changes
• Workflow Changes - Customization changes which were done to the state transitions
• Transition Diagrams - State transition diagrams for each baseline versions and for the head revision
• Permissions - Permission configuration listed by roles
• Permission changes - Lists the field and tracker permission changes over time

Figure: Field Changes in Audit Trail

4.1.4.1 Tracker Changes

For checking the audit trail of specific tracker changes, the proper tracker's configuration page should be opened. By selecting the Audit Trail tab, Tracker option can be selected.

4.1.4.2 Field Changes

For checking the audit trail of specific field changes, the proper tracker's configuration page should be opened. By selecting the Audit Trail tab, Field option can be selected.

4.1.4.3 Workflow changes

For checking the audit trail of specific workflow changes, the proper tracker's configuration page should be opened. By selecting the Audit Trail tab, Workflow option can be selected.

4.1.4.4 Transition Diagrams

For checking the audit trail of specific transition diagram changes, the proper tracker's configuration page should be opened. By selecting the Audit Trail tab, transition diagram option can be selected.

4.1.4.5 Permissions

For checking the audit trail of specific permission changes, the proper tracker's configuration page should be opened. By selecting the Audit Trail tab, Permissions option can be selected.

4.1.4.6 Export Audit Trail

To export Audit Trail from Retina, Export to Word option can be selected on the top of the Audit Trail page.

4.1.5 Workspace configuration diagram

The reference relations between trackers can be visualized as a diagram by clicking on Workspace Configuration Diagram on the Tools tab page. We can change the visibility of trackers on the left tree by clicking on trackers.

The selected tracker list is saved, so when the configuration diagram is opened again then the last saved selected tracker list is displayed.

4.1.6 Deleting a tracker

To delete a tracker in Retina, the General tab should be opened on the tracker's configuration page. On the bottom of the page, user can Delete the specified tracker.

4.1.7 Modify a tracker's general properties

To modify the general settings of a tracker, the General tab should be opened on the tracker's configuration page.

4.1.7.1 Modify the name of a tracker

By opening the General tab on the tracker's configuration page, the name can be modified below the Name section.

4.1.7.2 Modify the key of a tracker

By opening the General tab on the tracker's configuration page, the key of the tracker can be modified below the Key (short name) section.

4.1.7.3 Modify the default layout of a tracker

By opening the General tab on the tracker's configuration page, default layout of the tracker can be modified by selecting the proper one from the dropdown menu.

4.1.7.4 Modify the description of a tracker

By opening the General tab on the tracker's configuration page, the Description can be modified below the Description section.

4.1.7.5 Enable/disable tracker workflows

By opening the General tab on the tracker's configuration page, user can decide if the transitions and workflow actions should be available in the tracker by using the checkbox next to the "Workflow"'.

4.1.7.6 Enable disable tracker visibility

By opening the General tab on the tracker's configuration page, user can decide if the tracker should be hidden/available in the trackers overview by using the checkbox next to the "Visible"'.

4.1.8 Creating Trackers from a template

In Retina, users can easily create new tracker based on another one. Just mark the tracker that you would use as "Available as template" on the tracker's configuration page, below the General tab. Then by creating a new tracker on the Worksapces page, user can select the template tracker from the dropdown menu. With this setting the whole configuration of the original tracker is copied from the selected template.

4.1.9 Change the template of a tracker

By changing the template of a tracker in Retina, an error message comes up to warn the user, the new template tracker as a template will replace all current settings of the affected Tracker and might cause data loss and / or Configuration loss (including References). These modifications cannot be reverted.

4.1.10 Modify permissions of tracker in permission-role matrix

To modify permissions of a tracker, the Permissions tab should be opened on the tracker's configuration page. Permitted user can edit the permissions of specific roles.

4.1.11 Permissions

By using Permissions in each tracker, user can decide which roles should have access to different actions.

• Item - View if Owner: allows users to view items submitted by or associated with them. Owner fields: Submitted by, Assigned to and Owner
• Item - View Any: allows users to view any items
• Item - Add: allow users to submit new items to a tracker
• Item - Edit Any: allows users to edit any items
• Item - Edit if Owner: allows users to edit items submitted by or associated with them
  Owner fields: Submitted by, Assigned to and Owner
• Tracker - Mass Edit: allows users to update multiple items contained in the tracker
• Item - Close: allows users to close items (if workflow deactivated)
• Item - Delete: allows users to delete items
• Item - History View: allows users to view history of items
• Item - View Comment/Attachment: allows users to view comments and attachments
• Item - Add Comment/Attachment: allows users to add comments and attachments
• Item - Edit Comment/Attachment - Any: allows users to edit/delete any comments and attachments
• Item - Edit Comment/Attachment - Own: allows users to edit/delete own comments and attachments
• Public View - Admin: allows users to administrate public views of this tracker
• Item - View Associations: allows users to view tracker item associations
• Item - Edit Associations: allows users to edit and delete tracker item associations
• Item - Export: allows users to export tracker items for this tracker

4.2 Manage Tracker views

The documents view is a special type of view for items where they can be overviewed like they are paragraphs of a single document. Documents View is available only for Requirements, Risks, Change Requests, User Stories, Test Case tracker types and contains three panes, the node tree on the left, the middle one contains the document itself and the right pane contains the properties, libraries and releases. Items can be organized and restructured in the documents view via drag&drop.

The table view shows the tracker items in a specific order in a tree, which is in a table format. Parent items can be expanded to show the children items recursively.

The Cardboard view focuses on the work in progress and is only applicable for s. Work items are presented in form of cards in columns, which represent the status.

Test Coverage Browser view for a quick overview what requirements are verified by test cases and how including coverage information.

Traceability Browser view to see correlation of any number of any tracker or tracker types in a desired order with the focus on dependency visualization between the corresponding items to the neighboring selected tracker or tracker types.

For each tracker, Retina provides a number of implicit/out-of-the-box views, that are available when browsing items in a tracker e.g. all items, all open items, all items assigned to me, which will then present a filtered subset of the items in a table view. Any role, which has the permission to administrate tracker views can edit and delete public views. Users can also define personal or public accessible explicit/additional views on tracker items, choose the layout of the view (e.g. Table, Documents View) and which selected fields under which condition should be visible via this view. Criteria for the condition can be added using the condition tree and there are grouping operators as well. A public and personal view can be set/unset as default.

4.2.1 Document View

On the top of the page, over the tree and main panels, you can find Views dropdown. In order to change the tracker view click on the chevron down icon and select the desired view. By selecting the new view, page will be automatically reloaded accordingly .

4.2.2 Cardboard View

On the top of the page you can find Views dropdown. In order to change the tracker view click on the chevron down icon and select the desired view. By selecting the new view, page will be automatically reloaded accordingly .

4.2.3 List View

On the top of the page, over the items' table, you can find Views dropdown. In order to change the tracker view click on the chevron down icon and select the desired view. By selecting the new view, page will be automatically reloaded accordingly .

4.2.4 Default Field Filters in a Tracker View

On every tracker view you can find a filter icon on the top right section of the page. By clicking on it the filter panel will be displayed. Here you can see the selected filter attributes and values.

Click on the + icon in the Filters set. The fields overlay contains the Default Fields on the top of the field list. Select any of the default fields, and set the value(s) to filter.

By clicking on Go button, the tracker page will be reloaded, and display items regarding to the currently set filter.

4.2.5 Common Reference Fields Filters in a Tracker View

On every tracker view you can find a filter icon on the top right section of the page. By clicking on it the filter panel will be displayed. Here you can see the selected filter attributes and values.

Click on the + icon in the Filters set. The fields overlay contains the Common Reference Fields in the field list. Select any of the common reference fields, select the Workspaces and Trackers where you can find the reference item, and start typing the reference name in the input field at the bottom of the panel. The autocomplete will find every matching item. Click on the desired reference item, and start typing another if you want to filter by more than one reference item.

By clicking on Go button, the tracker page will be reloaded, and display items regarding to the currently set filter.

4.2.6 Custom Fields Filters in a Tracker View

On every tracker view you can find a filter icon on the top right section of the page. By clicking on it the filter panel will be displayed. Here you can see the selected filter attributes and values.

Click on the + icon in the Filters set. The fields overlay contains the Custom Fields after the Default Fields and the Common Reference Fields in the field list. They are in groups indicated by the workspace and tracker name. Select any of the fields, and set the value(s) to filter.

By clicking on Go button, the tracker page will be reloaded, and display items regarding to the currently set filter.

4.2.7 "AND/OR" logic options in Filters

If you filter by more than two attributes, you can add AND/OR logic to refine filtering. By default the conditions are using AND logic.

Add two conditions on the filter panel. Click on the -/+ icon next to the Add filer to define logic. A mandatory AND/OR logic text input will be displayed, and the given conditions will get numbering. Use this numbering to identify conditions, you can use 1 AND 2, or 1 OR 2 to define a logical phrase.

After you entered a valid logical phrase, Go button will be active again, and by clicking on it the s will be filtered.

4.2.8 Complex "AND/OR" logic options in Filters

If you filter by more than one attributes, you can add AND/OR logic to refine filtering. By default the conditions are using AND logic.

Add two or more conditions on the filter panel. Click on the -/+ icon next to the Add filer to define logic. A mandatory AND/OR logic text input will be displayed, and the given conditions will get numbering. Use this numbering to identify conditions, you can use AND, OR and round brackets to define a valid logical phrase.

After you entered a valid logical phrase, Go button will be active again, and by clicking on it the s will be filtered.

4.2.9 Order by options in List View

On List View you can order displayed s by click on the header of the columns. On the first click items will be ordered by the selected column in ascending order. If you click on the same header attribute again, the s will be ordered by the same column descending.

4.2.10 Order by options in Cardboard View

On Cardboard View you can order displayed s by selecting order in the Order by dropdown on the top of the page. Ordering will be activated automatically, and will be ascending every time.

4.2.11 Group by options in the List View

On the top right corner of the page you can display Filters panel by clicking on the filter icon.

On the bottom of this panel you can see Group by section, where you can select any field to group work items.

By selecting it and clicking on Go button the displayed work items will be organised in groups regarding to the selected field. Groups will be indicated in the list by highlighted rows.

4.2.12 Group by options on the Cardboard View

On the Cardboard View you can find a Swimlane dropdown on the top-right corner of the page. If you select an option in this field, the cards will be grouped regarding to this selected field. These groups are the swim lanes, and they are expandable / collapsible.

After you selected an option for swimlanes three new element will be displayed next to the dropdown field. By Swimlane order by you can define cards' order in swimlanes, and the switch button controls if the empty swimlanes are visible or not. By clicking on the button with arrow you can expand or collapse every swimlane at once.

4.2.13 Create your own Tracker View

To create own view click on the filter icon on the top-right corner of the page.

Create conditions, optionally define logic with the conditions, set visible columns (on List and Document views) and click on Save as button.

Set a name, whether it is public or private and optionally a description, and save it. After saving the newly created view will be selected and active, and it will be displayed in Views dropdown as well.

You can set it as default view by clicking on the pipe icon next to its name.

4.2.14 Default Views

On the top-left section of the tracker view you can select any default view in the Views dropdown.

By selecting a view it will be activated immediately, and page will be reloaded.

You can set any view as default view by clicking on the pipe icon next to the view's name, and unset as default by clicking on the x icon next to the view's name.

4.2.15 Modify Public/Private Views

Select a view from the Views dropdown. Click on the filter icon on the top-right corner of the page.

The settings of the view will be displayed. You can modify these conditions any time, and by clicking on Go button you can see the result of the filter.

If you modify a default view, then you can click on Save as to save a custom view based on the modified default view. The default view itself won't be changed.

If you modify a custom view, you can choose whether you want to modify the current view - click on the Save button - or you want to create a new view based on this custom view - then click on the Save as button on the dropdown menu of the Save button.

You can also change the properties of the current custom view by selecting Properties on the dropdown menu of the Save button.

4.2.16 Delete Public/Private Views

You can delete any custom view, but not the default ones.

Select the view to delete and click on the filter icon on the top-right corner of the page. Filters panel will be displayed. Open the dropdown menu of the save button and select Delete option. After the confirmation view will be deleted.

4.2.17 Reference Filters in a Tracker View

Open the filter panel by clicking on the filter icon on the top-right corner of the page.

After Default and Common Reference Field you can find Reference Filters. Here you can select s by a specific upstream/ downstream reference or by having any upstream/ downstream reference.

To filter by a specific reference you need to select one or more reference item in the filter.

4.2.18 Traceability Filter on Document and List view

Click on the filter icon on the top-right corner of the page and open Filters panel.

Select Traceability filter tab. You can see Initial level set, you can add filters, order by, visible columns and ancestor/ descendant items's visibility.

Set one or more level, and the filters of these levels, and click on Go button.

Traceability filter will be displayed in the list or document view.

On the List view, you can select horizontal or vertical view by selecting view mode on the top of the Filters panel.

4.2.19 Resize and reorder columns in a List view

On List view you can resize and reorder columns.

Hover the mouse on the header row between two columns, until mouse changes to resize cursor. After that by clicking and dragging column separator you can resize the column's width.

You can reorder displayed columns by drag-and-drop column headers.

4.2.20 Historical filters on Tracker views

You can find Historical Filter on the bottom of the Filters panel.

By Historical view you can display items by a selected baseline or a date.

The two other option is to display items regarding to a Release/Sprint start or end date.

After setting the filter click on Go button and page will be reloaded.

4.2.21 Managing Folder and Information type items

If you filter work items with Type attribute, you can select Folder and/or Information meanings for its value. In this case all the Folder and Information type item will be displayed.

4.2.22 Managing hidden fields in a saved report or view

If you set a field hidden, the field won't be available from filter list anymore.

All the saved filters and views that contains this hidden filed will work as before.

4.3 Manage Tracker Items

Trackers are differentiated into Work Items and Configuration Items. Work items are requirements, tasks or user stories, for example, and users can work on these items on a daily basis. The configuration and management of the s are handled in the configuration items, for example in the Releases.

4.3.1 Create an item

In a tracker, all roles with Item-Add permission can create new items either in the Document view, List view, Cardboard view and all implicit/out-of-the-box views.

4.3.2 Edit Work items with Froala or Office-Edit

Work items and config items can be edited directly with the build-in “What you see is what you get”-Editor (Froala). When opening an item in Retina, then selecting the "Edit via Office" option from the More Functions dropdown menu, Retina allows for editing in the Office-Edit mode. When using Microsoft Office, Retina will synchronize the changes back to the automatically, when the user hits the save button.

4.3.3 Versioning of Work items in the history

Creating a Work Item provides the first version of the item while modification generates a higher version number, which allows for versioning. Every item change or modification such as e.g. description, summary, status and reference change are archived in the History tab in the details and item versions can be compared to each other, highlighting the differences.

4.3.3.1 Comparison between versions in the history

Open a that have been modified before.

On history tab you can select two of the item versions. When they are selected the Compare tracker item versions button become active. Clicking on it you will be able to see all the differences between the versions of the item.

4.3.4 Working with associations and references

References are relations bound to Reference Fields of tracker items.

Reference fields are similar to foreign keys in relational databases, and

• can be required/mandatory
• can refer to multiple items
• can refer to items from multiple target trackers
• can refer to a specific subset of target tracker items

Associations are ad hoc relations between tracker items and any of the following:

• Other Retina entities (other items or documents)
• External web resources

In contrast to references, associations do not have a defined value set, severity, or permissions.

4.3.4.1 Associations

Via associations work items can be linked to any documents, wiki or between each other ad-hoc. Ad-hoc links via association can be created by anyone and they show suspected links. There are multiple ways to add associations to work items, either by dropping an item into the center panel of another item in the documents view, or in the details of an item by clicking on “Add Association”.

4.3.4.1.1 Modify Associations

Open tracker item details and select Associations tab.

If item has associations, they will be displayed in a table.

In the end of every row there is a caret down icon where you can select Edit option to modify association.

You can modify

• association type
• items order
• propagate suspect and suspect direction, and
• comment of association

4.3.4.1.2 Delete Associations

Open tracker item details and select Associations tab.

If item has associations, they will be displayed in a table.

In the end of every row there is a caret down icon where you can select Delete option to remove association.

4.3.4.1.3 Activate suspected links

In association creation or association modify dialog check the Propagate suspects link in order to activate suspected link function.

Check in the Reverse direction box to reverse suspected direction.

4.3.4.2 References

In order to establish links between tracker items, references can be defined while controlling role-based permission for each reference field. References can have any cardinality and can be defined under the property section under the Fields tab all along with permission that depends on status. Out of the box, each tracker has a reference field with the internal property name “subjects”. Additional reference fields can be added by any role with tracker admin rights, by adding a choice field and changing the data source to “work/config items”. When creating a foreign key in the target tracker which shows to the source tracker of a workspace, the user can create in the source tracker a „new referring item“ to the target tracker while Retina establishes the link automatically. If the user doesn’t use the new referring item and creates an item independently in the target tracker, he can link back to the source tracker manually as well. This way, with references, the processual approach to link items can be managed and predetermined.

4.3.4.2.1 Modify References

Switch reference field to edit mode. Next to the reference name an arrow icon will be displayed.

Here you can modify the reference by

• selecting a baseline or a version to refer to
• activate suspected link with Propagate suspects checkbox
• set suspected direction with Reverse direction or Bi-directional checkboxes

With the Set default values you can restore the predefined settings on reference field.

4.3.4.2.2 Delete References

Switch reference field to edit mode. To delete the reference click on the X icon next to the reference name.

4.3.4.2.3 Create a new referring item

Open tracker item details and click on the Add downstream reference or new item button on the top-left corner.

If there are any tracker in the workspace which refer to the actual tracker, they will be listed on the appeared panel.

Select one of the trackers and create a . This newly created will automatically refer to the previous item in its proper reference field.

4.3.4.2.4 Set up suspected-, and reverse suspected relation in references

Switch reference field to edit mode. Click on the arrow icon next to the reference name.

To set up suspected reference check in the Propagate suspects checkbox.

To change suspected direction check in the Reverse direction or the Bi-directional checkbox.

4.3.4.3 Suspected links

On the traceability matrix you can define dependencies between tracker items. If you check the "Propagate suspects" which means when item A changes in the dependency A <- B, then B is marked as suspected.

This information could be displayed in document view in three forms.

• First, when you open the Relations on the right panel of either item A or B and you will see a red Suspected icon below the referenced item.
• When you hover your cursor on the item's summary two arrows appear which shows the item's upstream and the downstream references and associations. Whenever the associated target item gets modified, the association will be flagged as a suspected link.
• By opening the item's properties, you can find the flagged item in the Traceability.

When re-using other requirements from the library, the copied work item will be linked to the original work item via association automatically. When the original requirement is now changed, that will trigger a suspected link, notifying the user that the copied requirement might be obsolete, and it should be reviewed. If a work item is linked to another work item via association, the user can decide whether Retina should propagate a suspected link by marking a checkbox. This means, whenever the associated target item gets modified, the association will be flagged as a suspected link and Retina will trigger this suspected link. Upon clicking the suspected link, the changes from the original can be either accepted or rejected.

4.3.4.3.1 Mass merge of suspected changes

If the two related items have the same tracker type, you can merge the values of one item to another.

By clicking the suspected badge a merge dialog opens. You can merge attributes one-by-one, or use the switch button in the table header to merge all attributes together.

Click on the Save button, and the indicated merges will be applied.

4.3.5 Collaboration on work items

Comments and attachments can be added and/or deleted to each tracker item (only if the user has the right permission).

4.3.5.1 Add comment/attachment

Comment can be added to in three places:

• on the right side of tracker item details page, Timeline panel, or
• on the Comments/attachments tab of tracker item details page or
• on Document view quick comment in the tracker item summary row

Click on the editor in any of these pages and it will be active immediately.

You can add attachment to either description or comment. Use the editor toolbar to browse the item or use drag-and-drop to attach it.

4.3.5.2 Modify comment/attachment

Hover your mouse over an existing comment. A pencil icon will be displayed if you have permission to edit the comment.

Click on it and modify it. After the modifications click on the Save button on editor toolbar to update the comment.

4.3.5.3 Delete comment/attachment

Hover your mouse over an existing comment. A trash can icon will be displayed if you have permission to delete the comment.

Click on it and delete the comment.

Next to the attachment icon you can find a down arrow. Click on it and delete attachment by selecting Delete option.

4.4 Document view

Document View is a special type of view of work items. In Document View you can overview your work items as if they were the paragraphs of a single document: a numbered paragraph is created for each work item (paragraph numbers mirror the hierarchy of the items). You can both read or edit these paragraphs.

4.4.1 Filtering

Users can filter the document view by using the Filter panel on the right side. By click on the icon, filtering criteria(s) could be added in the Standard Filters menu.

When the user defined the criteria, Go button should be chosen to see the filtered work item list.

By using the Traceability filter users can create their Personal or Public views specific to the Tracker. The saved views could be found under the Views dropdown menu on the top of the page. By opening the Views, users can access some predefined views as well to make the filtering easier.

On document view when a tracker item is displayed after filtering, all of its parent items will be displayed as well, even if they don't satisfy the filter conditions.

4.4.1.1 Filter by status

On the filter panel click on Add filter button, and select status field from Default fields section.

You can filter items by status meanings, or by the tracker specified statuses. A status meaning can contain more than one status, it depends on your field configuration.

4.4.1.2 Filter by last modified date

On the filter panel click on Add filter button, and select Modified at field from Default fields section.

You can filter by different settings:

• range: use a predefined date range
• specific dates: set a specific from date and/or a specific to date to filter
• relative ranges: set relative days/workdays/weeks/months/quarters/years before/after today

After setting values and clicking on Go the items modified at the filtered dates will be listed.

4.4.1.3 Filter by suspected alert

On the filter panel click on Add filter button, and select an option from Suspected references section.

You can filter by

• has suspected link: every item with suspected link will be displayed
• has downstream suspected link: every downstream relation that has suspected link will be displayed
• has upstream suspected link: every upstream relation that has suspected link will be displayed

4.4.1.4 Filter by existence of references

On the filter panel click on Add filter button, and select an option from Reference filters section.

You can filter by

• Downstream reference to: displays every s that has downstream reference to a tracker or a specific tracker item
• Upstream reference to: displays every s that has upstream reference to a tracker or a specific tracker item
• Has downstream reference: displays every s that has downstream reference
• Has upstream reference: displays every s that has upstream reference

4.4.2 Navigating in Document Views

The layout of a Document View contains the followings:

There are three panes:

• the left-side one contains the requirement tree
• the middle one contains the generated document itself
• the right panel could be opened up by clicking on the "Show right panel" next to the item's summary. This contains the details of the item, the Editable fields, the Relations and the Timeline

All work items in the tracker (or the ones that match the report query defined in the action bar control) appear in the requirement tree and in the document as well. In the requirement tree they are shown as a parent-child hierarchy, containing the name of the tracker.

Users can navigate in the document by clicking on an item. By choosing one from the tree the document will automatically load to the corresponding paragraph. The properties tab could be opened by clicking on the "Show right panel" next to the item's summary.

The splits between the tree and the generated document can be resized by moving the gray bar between them. The requirement tree can be hidden by clicking on the "Hide left panel" left arrow icon next to the Searching. The right panel can be closed by clicking on the X on the top right of the panel.

4.4.2.1 Collapse and expand left tree

The simplest way to collapse/expand nodes by using the arrow icons on the beginning of the node. Click on the icon of a collapsed parent node, and it will be expanded. Click on the icon again, and it will be collapsed again.

The other way is to click on a tree node with right mouse button. Node's context menu will be displayed.

By the Collapse node and Expand node options you can collapse or expand the current node. Using Expand option from context menu will expand all child item too.

If the item has no child element, these options won't be listed in context menu.

4.4.2.2 Change width of the left tree

You can increase or decrease the width of the left tree by using the split between the tree panel and main panel.

4.4.2.3 Left Tree Configuration

To configure view of left tree click on the gear icon in the tree panel's header.

On the Settings dialog you can configure what is displayed, and what search results are indicated in the tree.

You can enable/disable to show

• Work item IDs
• Numbering
• Mark work items with suspected links
• Show child counts

When you search in the tree you can search in and highlight

• Attachments
• Work item title
• Work item ID
• Work item description

by the predefined colors.

After clicking on Save the document view will be reloaded and the settings will be applied.

4.4.2.3.1 Show item IDs in left tree

To display item ids in left tree check in Work item IDs checkbox in tree settings.

4.4.2.3.2 Show numbering in left tree

To show numbering in the left tree, check the Numbering checkbox in tree settings.

4.4.2.3.3 Show suspected alerts in left tree

To show suspected alerts in left tree check in Mark work items with suspected links in tree settings.

4.4.2.3.4 Show child counts in left tree

To show child counts in left tree check in Show child counts in tree settings.

4.4.2.4 Filter left tree (center panel is not filtered)

To filter left tree start typing into the filter field in the header of the tree panel.

You can set in settings - gear icon next to the filter text area - what fields you want to search in. When the searched text was found in an item, it will be highlighted by the predefined color.

4.4.3 Organizing Items in the Tree

The tree can be used to organize items:

• move elements in the requirement tree
• add new items and
• delete existing ones

4.4.3.1 Create an item with the left tree context menu

Click with right mouse button on a tracker item in the left tree to open item's context menu.

In New... menu you can create

• New item - as last item on the same tree level
• New child - the newly created item will be the child element of the current item
• New item after this - the new item will follow the current item on the same level
• New item before this - the new item will come before the current item on the same level

4.4.3.2 Copy and paste items by left tree context menu

Click with right mouse button on a tracker item in the left tree to open item's context menu.

In Copy/paste menu you can choose these options:

• Cut: to mark the item for move
• Copy: to mark the item for copy
• Copy to...: copying the item directly to the desired place
• Move to...: move the item directly to the desired place

In the case of Cut and Copy the item will be copied to a clipboard. When item(s) are on the clipboard, an information text will be shown on the top of the page.

If you open context menu again on any tree, the Paste options will be displayed in the list:

• Paste as new child: items from clipboard will be pasted as child elements
• Paste above this: items from clipboard will be pasted before the current item on the same level
• Paste below this: items from clipboard will be pasted after the current item on the same level

4.4.3.3 Change item order by drag and drop in left tree

Items order can be changed easily by drag and drop elements in the tree.

After dragging one or more items a green highlight will indicate the possible dropping places. Drop the item to a possible place, page will be reloaded and display item in its new place.

4.4.3.4 Delete item in left tree

To delete item(s) from the left tree select the items in the tree. Click with right mouse button to open context menu, and select Delete option.

4.4.4 Editing and Viewing Items

By clicking on an item's description or the name, the item becomes editable in the middle pane of the page. By double clicking on the item's name in the tree, a detailed editor window pops up.

4.4.4.1 Perform State Transitions via the Status field

If the main panel contains Status fields, you can change the item's status right on the document view.

Click on the down arrow next to the status badge. All available transition will be listed in a panel. Click on a transition, and if there are no empty required fields on the item, the transition will be executed immediately, and the item will be refreshed.

If item has any empty required field, the item details dialog will pop up, and required fields will be marked. After setting these fields Apply button will be active and by clicking on it transition will be executed.

4.4.4.2 Editing summary and description of a Work Item

On main panel summary and description items are editable with the relevant permissions.

Click on the summary, and it will change to edit mode. After the modifications click somewhere outside of the field, and changes will be saved.

Click on the description, and editor will be displayed. You can save your modifications with Save button of editor toolbar.

4.4.4.3 Rename an item in the left tree

To rename item in the left tree click on the item with right mouse button in the tree. In the context menu select Rename option, and the item's name will be editable .

After renaming the item click on the save icon next to the item name, and item will be reloaded.

4.4.4.4 Drag and drop items into main panel to create associations and references

You can add relation to a work item, if you drag and drop another item from a different browser page.

Open page A and page B. Drag the item from page A by grabbing it with the 6-points-icon.

Move it over another item on page B. Three options will be displayed on the second item to drop on.

• Link to this Creates a reference: creates a reference between the two items
• Depends on Creates an association: creates a Depends on association between the two items
• Related to Creates an association: creates a Related to association between the two items

4.4.4.5 Add a quick comment on main panel

Hover your mouse over a tracker item on main panel. An Add comment icon will be displayed on the right side of the item.

Click on it, and you can add a commit to the current item immediately.

4.4.5 Creating References using the Menu

In the references menu you can:

• create new downstream references for a requirement: the potential trackers are listed in the first section of the menu. These are the same tracker that you see when you click on the Create Downstream Reference menu on the item details page
• generate new item in the current tracker: on the bottom of the list you can select Add new item to create a new item in the current tracker

4.4.5.1 Create referring items using the + icon

Hover your mouse over a tracker item on main panel. Some icons will be visible on the left side of the item.

Click on the Add downstream reference or new item icon to display an overlay. Here you can select a tracker to create new downstream reference.

The newly created references will contain the current tracker item as reference automatically.

4.4.5.2 Create new item using the + icon

Hover your mouse over a tracker item on main panel. Some icons will be visible on the left side of the item.

Click on the Add downstream reference or new item icon to display an overlay. Here you can select the New item option to create a new item in the current tracker.

4.4.6 Properties Panel

Work item details can be shown and modified in the properties panel by selecting a work item with a double click in the left tree or by clicking on the "Show right panel" next to the item's summary.

4.4.6.1 Click on the "Show right panel" to display fields in details tab

Hover your mouse over a tracker item on main panel. Some icons will be visible on the left side of the item.

Click on the Show right panel to display right panel.

There are some tabs on this panel:

• All: you can see all the property of the item, and inline edit all editable property
• Editable: you can see and inline edit all editable property of the item
• Relations: to see all references and associations of the item
• Timeline: to see status changes, comments, attachments, worklog and review comments of the items, and write a new comment

Right panel can be closed with the x button on the top-right side. If you click on another item on the main panel, the right panel will be refreshed, and will display the data of the newly selected item.

4.4.6.2 Edit field values in details panel

You can edit the editable items on right panel if you have the permissions and item is in an editable status.

The properties are inline editable, you only need to click on the field and edit it immediately. To save changes click outside of the field.

Wiki fields (e.g. Pre-action, Description, Test parameters) are editable with editor. You can activate edit mode the same, click on the field. But to save your modifications you need to click on the Save button of the editor.

4.4.6.3 View references and associations in the Relations Panel

On the relations panel all of the item's relations are displayed.

They are grouped:

• upstream references
• downstream references
• upstream associations
• downstream associations

4.4.6.4 Add an association on the Relations Panel

On the top of the relations panel you can add new association by clicking on New association button.

On the displayed dialog you can set association type, suspect link, association comment and associated items.

4.4.6.5 View comments, attachments, status changes, worklogs in the Timeline Panel

On timeline panel you can add a new comment and display information about the item.

You can search in timeline with the input field on the top of the panel. By typing the text the timeline items will be filtered immediately.

With Sort button the items can be ordered ascending on descending.

To control displayed item click on Filter button and select the items type to be visible:

• Show comments
• Show attachments
• Show state changes
• Show worklogs
• Show review comments

4.4.7 Document Traceability View

A Document Traceability View could be displayed by using the Traceability Browser filter. This allows the user to display specific upstream and downstream references of the items of a tracker. The upstream and downstream references can be any types of items added from selected trackers in your system. You can add references to items from any tracker within the current workspace or from trackers in any other workspace in the system (including custom trackers).

The view could be saved as public or personal view as well.

4.5 Document view comparison

In Retina, there is an option to visualize differences between specific baselines on document view. By clicking on the three dots on the top right of the page (next to the eye icon) and selecting the "Compare baselines" from the dropdown menu, the differences between two selected baselines appear as a highlighted text.

5 Requirements Management

In Retina requirements are handled in trackers with requirements type. There can be several requirements trackers in the same workspace, or just one. Requirements can be edited in the table view or the documents view.

5.1 MS Office Import, Export, Round-trip

With MS Office such as Word, Excel, MS Project, the user is able to import s into the Retina trackers. Under the “more” menu of the action bar in a tracker, the user can choose the document to import and RETINA shows the general import screen for Word, Excel and MS Project. A document such as e.g. a word or excel file can then be attached by selecting “Attach a file” or the user can drag and drop a file into the upload document area. Retina will automatically recognize and switch to the right document type for the import.

When importing from Word, the word document should be structured using Word styles e.g. with different level of heading styles and normal style for the description. Different heading levels will generate a parent-child relationship between the s. Retina will then show a preview before the actual word import where a tree structure on the left, the content and manual selecting options in the center pane and import rules using different kind of conditions including a statistic area are shown on the right side. Import rules can be defined with specific actions and conditions and any default rule can be added, modified or deleted. The import rule contains of an action selector, filter selector, several types of conditions and logical operator selector between the conditions such as AND OR. Actions for individual s can be overwritten by e.g. using the switch and manually toggle a for the import.

Retina import functionality allows to import data from any excel file as well, whereas the first row should contain the header information like property/field names. During the import wizard, Retina will then automatically pair the header names from the Excel sheet to the closest matching field name in the target Retina tracker. On the next page of the wizard, the user has the option to map the cell-data coming from the Excel sheet to the fields of the Retina tracker. Hierarchies can be imported from Excel when this hierarchy is built from a column, which contains indented data in the sheet. Advanced data conversion is available through Scripts such as JavaScript, Groovy and JEXL. The import can be aborted in the wizard at any time.

Retina allows for exporting the whole tracker or just selected items into MS Office. For Word and Excel, the user can either generate a simple data Word/Excel export document or a Round-trip document.

Exported data via Round-trip documents allows the user to make changes offline or let external users collaborate on this exported document and incorporating the changes back from this document into Retina. Retina will then notify the user of any changes that has been made in the exported round-trip document. The import wizard will then display the changed items only and will highlight the differences to the original work item and the importer can either decide selectively whether to apply and import back those changes one by one or at once into the system.

Customized templates for Word and Excel can be managed and uploaded to a specific directory in the documents management. Word or Excel templates contain certain scripts and special tags that are written into the template file in order to control what content should be exported and how it will look like in the export. In the Export to Office dialog, the customized templates can be used, either by uploading a template file from the local file-system once, or by uploading a template into the specific directory available in the documents management. The Word export template contains Apache velocity scripts and the Excel Export is using a simple yet powerful open-source templating engine, called JETT.

5.1.1 Import from Word

With Microsoft Word import functionality you are able to import work items into your trackers. The Word document should be structured using Word styles: after the import the heading styles will be the summaries of the work items, the paragraphs after the headings with normal styles will be the descriptions. The different levels of heading styles will make the parent-child relation between the work items.

Retina has a general import screen, Import menu item is available in the More functions menu of the action bar of the tracker home page (table view or document view).

By selecting Microsoft Word user can click on Attach a file... or use drag and drop function to put the file into the area to upload document. After the uploading will be finished, and by clicking on Next user can navigate to the Preview screen. The Preview screen where you can see the preview of the work item structure and content and furthermore you can filter and set the work items and define other import rules. You can define Import rules with specific actions and conditions. The rules is for what you would like to do with the work items if the defined conditions are met.

5.1.2 Import from Excel

Retina's Excel import functionality allows you to import data from an Excel file. The major features of this import are:

• You can import data to a Tracker and create new work items there
• Excel 2003 & 2007 (*.xls, *.xlsx) formats are supported
• First Excel row is used as header, 2nd row and below is used as data (customizable)
• Excel columns are mapped to work item fields, mapping is configurable
• Importing work item hierarchies is possible using indented data
• Date, number format is customizable, other detailed data conversion is possible

Before importing some Excel data-file it should conform to following rules:

• Any Excel sheet can be imported, by default the last-selected sheet is imported
• The first row should contain the header information like field names. The headers can contain any descriptive text, but the best approach is to try to use those labels which match (or close) with the Retina tracker columns you want to load the data into. If your data is coming from Retina already then try to keep the header as-is, without any changes.

During the import the wizard will try to automatically pair the header-names in the Excel sheet to the closest matching field name in the target Retina Tracker. So if your names in the sheet match then the configuration will be much easier for you. To start importing to a Tracker go to the Tracker, and from the "More functions" menu choose Import...

The import wizard will start up, and you can walk through the wizard pages and configure the details in there.

Click on "Attach file" to choose and upload the Excel file. You can also drag-drop file from file-system here (some browsers does not support that however).

5.1.3 Simple Export to Word/Excel

Exporting several Work Items (Requirements, Tasks or Bugs) is very easy in Retina. Just open the Tracker which contains the items that will be exported, switch to the "list view", and on the "more" menu which contains an "Export to Office" menu this initia tes the Excel/Word export wizard. This export will contain those fields which are available inside the View and only those items which are matching with the current view.

5.1.4 Roundtrip Export to Word/Excel

With Round-trip editing of Requirements (or other kinds of work items like Tasks / Bugs etc.) in Retina users can:

• Export several work items to a Word document and view, read or print it in Word
• Edit the work items' descriptions or summary in Word. When editing, users can attach pictures or use rich formatting capabilities of Word
• View comments made by other users on the exported work items
• Add new comments to work items
• Finally easily import back all these changes made in the Word document to the original Work Items.
• During import users have the option to review all changes and selectively import only the desired ones

Exporting work items from Retina to Round-trip Word documents starts with navigating to the tracker which contains the ones to be exported. Within the tracker choose the "Export to Office" action in the "more" menu. You can also choose to export "Sel ection" which means that the export document will only contain selected items. Then a dialog appears, where the "Round-trip" option should be chosen. When this menu is selected Retina will build a Word document which contains the work items displayed by the current view and the download of that Word document will start in few seconds automatically. The generated file name will contain the current workspace's and tracker's name, so it is easier to identify later where that export file is originated from.

5.1.5 Re-Import modified Roundtrip file

After finished editing of the Round-trip Word document, it is time to import the changes back to Retina. This can be done with the "Import from Word or Excel" menu in the "More functions" menu of any tracker .

5.1.6 Upload customized template in the documents management

The Word or Excel Templates contain powerful scripts (Groovy or other script languages), which makes these export Templates a very powerful tool, and as such "great power comes great responsibility": the System Administrators must carefully review these Te mplates and their scripts: so they don't cause any malfunctions, malicious attacks or security problems in Retina. You can create and add new and customized Word and Excel templates to Retina, and the Word or Excel export GUI will show such custom templates. These templates can be stored in the following location: by clicking on Export to office in the More Functions menu, a popup window comes up with the details of the export. There is a link, called Manage custom templates where the user can upload his own customized template.

5.1.7 Export Word/Excel using customized templates

For exporting to Word or Excel by using customized templates, the template should be uploaded to the proper place (Manage Custom Templates). By clicking on Export to Office, a popup window comes up with the details of the export. The uploaded template could be selected below the Template section.

5.2 Library

When building a product you may want to reuse the same requirements in multiple versions. A requirement library is a collection of requirement trackers that helps you in this task. When the original work item changes you can rely on the suspected link feature and the diff tool to decide if you have to apply the changes to the copied requirement.

The Library is marked with a book icon, you can access on the right side of the page on the document view, next to the Filter icon.

5.2.1 Expand and collapse the tree

By clicking on the Library configuration in the Library, users can expand or collapse the visible content. From the items listed, the user can select different workspace trackers that they want to list in the Library. By selecting the items and then clicking save, the items become visible in the tree. To remove items from the tree, the check boxes should be inactivated in the Library configuration.

5.2.2 Filter expanded requirements using text filter

In addition to the listing of the requirements in the Library, it is possible to use text filters for filtering the expanded requirements. For using this function, user should use the "Type to filter" section on the top of the Library.

5.2.3 Filter expanded requirements using status filter

To filter the expanded requirements in the Library by using status filter, the "All" dropdown menu should be selected. From this menu it is possible to select the meaning of different statuses, like Open, Resolved/Closed, Closed, Resolved.

5.2.4 Insert item from requirement library

To insert items to a tracker from the requirement Library, the Library should be opened. By selecting the requirements from the Library Configuration, then clicking on save the items appear in the tree. With a drag and drop, the requirements can be re-used in the opened tracker.

5.3 Linking requirements with test cases

On requirement's document view, users can easily link requirements with test cases.

By opening the Library on the top right of the page, with a Library configuration, users have 3 options to make connections between Requirements and test cases:

• link the test case items to a requirement by creating a reference
• set a "depends on" association type which creates an association
• or set a "related to" association type which creates an association

By choosing the proper test case type tracker in the Library, the tracker is loaded to the right side of the page. With an easy drag and drop, users can decide which association type they would use.

6 Traceability Browser

The Traceability Browser offers end-to-end gapless traceability even down to source code, which is a necessity for compliance with regulatory standards. The Traceability Browser is a basically a table which correlated any number of sets of any tracker or tracker types in a desired order with the focus of visualizing dependencies between any particular item corresponding to the neighboring selected tracker or tracker types. A user can navigate to the traceability browser from any tracker in the “more” menu or by selecting the Traceability Browser, which will be the initial tracker. The Traceability Browser can be reached in the Tools menu as well, where in this case firstly the user has to choose an initial tracker. The Traceability Browser shows dependency links for associations, references and the current status of each item. Custom tracker views can be applied for the initial tracker to filter for relevant item dependencies.

Retina's Traceability browser with the selected trackers in the result table can be saved in a permanent link, reloaded and shared with other workspace members. Workspace administrators can store and delete the traceability browser configuration preset, where as, any other role should be able to load this pre-set.

Any time, the Traceability Browser can be exported to Excel for management and stored for audit and regulatory purposes.

6.1 Select trackers and tracker types

In Retina, a Traceability Browser is essentially a table that correlates any number of sets of any trackers or tracker types in a desired order and visualizes the dependencies (downstream and/or upstream associations and/or references) between the items co rresponding the neighboring selected trackers and/or tracker types.

Inside the Initial Tracker(s) section you can:

• add only specific trackers, from the current workspace, and also from other workspaces
• define filters, set and/or logic between filters and predefined order by causes (not possible if show ancestor, descendant is ticked)
• set visibility settings:
  • show ancestor
  • show descendant
• add fields to the traceability view

Inside the Level 1 section you can:

• add only specific trackers, from the current workspace, and also from other workspaces
• define filters, set and/or logic between filters and predefined order by causes
• set visibility settings:
  • Associations: Downstream, Upstream
  • References: Downstream, Upstream
  • Show Folders and Information
• add fields to the traceability view

After setting the desired trackers/tracker types/all of each level, you have to click on Show dependencies to see the result table. The first columns of the result table will belong to the selected initial tracker(s), th e other columns will represent the other Levels.

6.2 Share permanent link and save presets

Once you select some trackers or tracker types into the Current selection section, and the dependencies are shown in the result table, you can make a permanent link of the result table. Click on the "Share with others" button on the top right of the page, then the page will be reloaded with the previous result, the URL will be changed, so you can copy or share the URL with other users/groups/e-mail addresses which will contain the configurations you set.

Workspace admins are able to store configuration presets in workspace level. The presets stores all preset traceability browser configuration.

Click Save Current Settings on the action bar to store current configuration as a preset. You have to type a unique name of the preset and click Save.

6.3 Loading presets

By clicking on Load/Manage Presets on the action bar in the Traceability Browser, user can see the already stored Traceability Browser presets.

6.4 Deleting presets

By clicking on Load/Manage Presets button, user can see the names and the selection list of the stored presets. If you are a Workspace admin, you can also Delete the stored Preset by clicking on Delete Preset, in other cases you are able to load them.

6.5 Export Traceability Browser

There is ability to export the displayed table into MS Office by clicking the Export to Office link above and under the traceability table, so you can work with the traceability data further on.

• Excel export: export the result table into Excel (.xls format). Untick "Merge interconnected cells (long-running operation)." option to speed up the export of larger files
• Word export: Export the result into Word (docx format), building a tree inside the document containing the tracker items of the traceability result with detailed item information. You can specify also templates for the import, so you can configure which data of the tracker item should display

6.6 Work Item Traceability

On the Work Item page there is a Traceability section. This section could be accessed by double clicking on the item, then selecting the Traceability tab. After opening the section, the downstream and the upstream traceability of the single work item will be loaded in 3 levels by default. You have some options to set in Traceability section (once you change one of the options, the Traceability loads automatically), which are:

• Whether to show Associations (not just References), default true
• Number of Levels up to 10 levels
• Whether to show descriptions of the items, default false
• Whether to show SCM commits also as items, default false
• Do not show redundant Items (just like in Traceability Browser), the default value is configurable in general.xml (see below)

7 Risk Management

Retina's risk Management helps to identify, analyze, mitigate and reduce risks during the crucial process for developing safety-critical and complex embedded products and greatly facilitates compliance with ISO 14971. Identifying risks and potential failures in the early development/engineering process lets the user avoid risks while saving development costs and time.

7.1 Risk Management Lifecycle

The Risk Management Lifecycle can be greatly planned and covered, using Retin's BPM. Out-of-the-box, Retina provides standard workflow for identifying, planning, reducing and mitigating risks and standard attributes such as hazard, triggering event, harm, likelihood, severity, risk, planned risk mitigation, likelihood after mitigation, severity after mitigation and risk after mitigation.

7.2 Risk Matrix Diagram

The Risk Matrix Diagram in Retina shows all number of requirement items according to the related risks. The risk property in the risk tracker is a preconfigured computed field and will calculate the risk value automatically as multiplication of their likelihood and severity value. The risk matrix diagram is drawn as a matrix, where out-of-the-box, the Y Axis is for the Likelihood and the X Axis is for the severity values. The diagram can be configured, and the axis can be reversed in Retina.

7.2.1 Configuration inheritance

The matrix has to be configured via special custom fields of the Risk tracker and/or via Risk Management tab of Tracker customization page of the Risk tracker. The newly created risk trackers contain these fields with default values.

Likelihood intervals: custom choice field for configuring Likelihood intervals

Severity intervals: custom choice field for configuring Severity intervals

You can set these intervals and also the background colors of the matrix on the Risk Management tab of the Tracker customization page.

8 Test Management

Retina's advanced quality assurance and testing module enables controlled testing of software, hardware and any kind of product or system while providing compliance with even the most complex of industry standards typically encountered in safety-critical industries.

8.1 Requirements-based Testing

Retina allows for requirements-based testing. Out-of-the-box, testing is done manually in Retina. From a requirements node, the user can derive and link one/multiple Test Cases either recursively for each children requirement or just for this selected node - but only if the “verifies” field is configured. The “verifies” field is a reference field in the test case tracker, which will link to the selected requirement.

8.1.1 Create Test Case from Requirements

When opening the requirements in Document View, user can easily generate test cases for them. By clicking on the + icon (add downstream reference or new item) next to the requirement user can select the target Test Case tracker from the dropdown menu.

This will immediately generate a test case for the requirement in the selected Test Case tracker of the workspace.

8.2 Create Test Step, Test Case, Test Sets

A Test Case is a detailed procedure that fully tests a feature or an aspect of a feature. Test cases consist of detailed descriptions, pre-actions, test steps, and post-actions, test parameters. Technically, Test Case is a tracker item in the "Test Cases" tracker.

Pre-actions should be executed before the actual test steps to initialize the environment, to populate test data and for other types of preparation. Post-actions should be executed after the steps, to close open resources and to clean up the environment. Post-actions should be executed regardless the actual result of the test case, unless documented otherwise.Test Parameterisation is a powerful practice to enhance your testing scenarios. The concept of parameters in testing is simply that your Test cases may define and use some parameters.

A Test Step includes an action, an expected result, an actual result and is one step in a Test Case procedure.

A Test Set is a logical container of related Test Cases and Test Steps. It is associated with a list of releases it is allowed to be executed with, and a list of test configurations that are allowed to be used while executing it. Technically, Test Sets are maintained in the "Test Sets" CMDB category.

A Test Configuration is one possible configuration of the product under testing.
Tests can lead to different results depending on the configuration used, therefore configurations must be recorded for effective testing. Technically, Test Configurations are stored in the "Test Configurations" CMDB category.

A Test Run is an actual execution of a Test Set or a Test Case using one specific Release and one specific Test Configuration. All test cases or test sets that have been executed are maintained in the “Test Runs” tracker.

8.2.1 Modify Test Step, Test Case, Test Sets

To modify a Test Step, Test Case or a Test Set in Retina, the proper Test Case or Test Set tracker should be opened. By double clicking on the item, editor window pops up where the user can modify the item.

8.2.2 Delete Test Step, Test Case, Test Sets

To delete a Test Step, Test Case or a Test Sets in Retina, the proper Test Case or Test Set tracker should be opened. By selecting the item in Document View with a right button on the left side tree, permitted user can delete the item. It is also possible to delete in Table View. By selecting the checkbox next to the deletable item, then clicking on the Actions, permitted user can delete the item.

8.2.3 Test Set creation from selected Test Cases

One of the Test Runs type stored in Test Run trackers are called Test Set Runs: One Test Set Run holds information about a single run of a Test Set on a certain platform and version.

To create a Test Set, the proper Test Set type tracker should be opened. By clicking on "New Item", first of all user should add a name for the test set. On the bottom of the page, Test Cases could be added from the Test Plans library (right side of the page) with an easy drag and drop. After saving the item, the test set becomes ready to run.

8.2.4 Adding Test Cases to a selected Test Set

To add additional s to existing Test Sets, the proper Test Set should be opened. On the bottom of the page, there is a section, called Test cases＆sets. By selecting the Edit button next to this section, user can add other Test Cases by selecting them from the right tree.

8.3 Test Step, Test Case, Test Set Re-Use

Test Sets, Test Cases and Test Steps can be reused through the test case library on the right panel by drag&drop. When re-using e.g. a Test Steps, the user can decide whether to create a copy of this Test Step or if he wants to maintain a reference to the original Test Step. If there is a reference to the original test step and it changes, the copied Test Steps will be updated automatically. The user can break the reference relation by editing the test case.

8.4 Test Parameters

Every test case can be parameterized by using parameters when editing a Test Case’s or a Test Set’s definition. Parameter values can be provided as a Wiki table. A parameter is defined by using the ${parameterName} notation in the wiki text of the Test Case.

Parameters can be used in the following locations:

• Name of the test-case
• Description of the test-case
• Pre- and post- actions of the test-case
• in "Action" and "Expected result" fields of test steps

8.4.1 Providing Parameter values as a Wiki table

Parameters can get values from Wiki tables. Just add a Wiki formatted table to the wiki editor, and the contents of that table will be used as parameter values.

The values are taken from this Wiki table as:

• If there is a header row in the Table, then the text in each header is used as the parameter names
• If no header then the first row is used as parameter names The further rows below the table-header used as values for each parameter in each column

Practically by defining a table you can define a multi-row parameter set. This means that when running a test case it will be run multiple times: once for each value row in this table.

8.5 Test Execution

The user can create new Test Runs out of Test Cases and Test Sets by choosing the specific Release and Test Configuration. When creating a Test Run, the tester can decide how to distribute this run to other users by either creating a shared single Test Run, multiple Test Runs with Roles/Groups where the Roles/Groups will not be expanded to individual users and multiple Test Runs with Users only.

When a Test Case, Test Set or a Test Set which includes Test Cases with Test Parameter, a “Using parameter…” side-bar will appear in the Test Execution. The Test Execution will display:

• The currently resolved parameters with their actual values
• If some parameters' values are missing this will display a warning message with the list of missing parameters
• When multiple rows of parameters available then this will display how many executions of this same test will run to complete all parameter-sets

The tester can also choose a different parameter-set manually by clicking on “Select” and Retina will open up an overlay dialog with the parameter-sets that hasn’t been run yet in order for the user to choose the next parameter. When running Tests with parameters the Tester can decide to skip some of the parameters inside the Test Execution. When Parameters are skipped, that is indicated by a special result “Partly Passed” for the Test Execution. Each Test Execution can be reviewed in the Test Run tab by clicking on the "Show detailed view" for Test Cases and Test Steps.

Once a Test Run has been already completed, the Tester can decide whether to re-run the tests. These are the following options:

• Re-run all tests: will re-run all Test Cases in this Test Set regardless of their results
• Re-run selected tests: user can choose individually which Tests will be re-run
• Re-run failed or blocked tests only: if the user wants to re-run only failed or blocked Tests
• Run the remaining open tests: option appears if some of the Tests were not run at all, because the Test-Set-Run was closed manually. This option will keep all Test results, and run only the missing ones.

8.5.1 Test Runner window

Test Runner is the primary interface to actually do testing.

It helps testers by guiding them through the tests and their test steps to execute. It also records the result of each step (whether passed or failed) and the result the complete test case. Moreover, it makes it convenient to report bugs if the tester faces defects while running tests.

The top part shows the progress within the whole Test Set/Test Case Run (count of the passed and failed tests). It also shows the configuration and release to be used for the current run. Navigation buttons allow testers to jump to the next test, or generally browse through the outstanding test cases. This only works if the Test Set is not marked as Sequential, which forbids random execution order.

The main parts of the page:

• Below that show the name, description and attachments of the actual test case
• Right next to the Test name a Timer is appearing where the Runner is measuring the duration of each test execution. This timer can be paused to get more accurate results in case the Tester has to temporarily suspend the testing. The main goal of the timing that it helps planning future testing cycles, once such temporal data is collected
• Below you may find the files attached to the current test case. Clicking their file names to download them
• This is followed by the previously explained properties of the current test case: Pre-Action, Test Steps and Post-Action. These parts might be hidden if they are not filled for the test case
• Followed by this there are a set of buttons. The first group allows to set the pass step/fail step/block step result for the current step or for the whole test
• By using the Report Bug button you can quickly report a bug in the context of the current run
• The Clear Step will clear the PASSED/FAILED/BLOCKED result from the Step which is focused. This will not however clear the "Actual Result" value
• The Save&Next Test Case button saves the current Test's result and closes it if it already has results
• The Pause Run saves the Test Case's results and closes the dialog, but will leave the Test open so you can continue here next time
• The End Run button will close and complete the whole Test Run: so none of the remaining Test Cases will be run from here

8.5.2 Test Run in Excel

Normally Test Cases and their results (=the Test Runs) are managed completely inside Retina. Retina has a built in Test Runner which is driving the Test-running process: when a set of Test is executed then it will automatically show the next Test and allows the Testers to enter Test Results and close the completed Test Runs.

While the built in Test-Runner is powerful tool, a popular and often appearing request from our customers was that they wanted to execute their Tests without Retina, but somehow later wanted to get back those Tests' results to Retina. (For example if there was no internet connection available at their test site).

• Users will be able to export a Test Run to an Excel document
• The Excel document is prepared for easy filling of the Tests' results
• Once the testing is complete these Excel documents can be imported back to Retina and will look just like if they had been running "inside" Retina

8.6 Bug Reports

Testers can report bugs in context of the current test being executed in Runner at any time during the execution of the test.

By clicking on the "Report Bug" button users can suspend the Test Runner temporarily and display a bug reporting interface.

The user has the option to choose the bug tracker where the bug will be reported. This tracker is remembered and same tracker will be offered next time as default.

The bug to be reported is automatically initialized from the current test run's data. It captures many details:

• including the properties of the test case under execution
• the configuration and release used
• the results of each test step

8.6.1 Bug re-use from Test Runner

When reporting a bug from the test runner, there is a dialog where previously reported bugs can be selected.

8.7 Test Coverage Browser

Test Coverage is a metric to express, which requirements/user story of a product are verified by test cases, by how many of those test cases and what is the overall coverage status. It is also a tool to analyze the result of the latest test runs and of the resulted test coverage of requirements/user stories. The Test Coverage can be accessed in the “Tools” menu by clicking on "Test Coverage".

The main area of the Test Coverage contains three sections, the requirements/user story tree the selected tracker, the test cases assigned to them and the test runs of the test cases. In the grid, there are following information, such as status including color, the coverage, number of test cases verifying this requirement/user story and the coverage analysis.

There are many filtering options in the Test Coverage.

The Test Coverage Statistics section shows the aggregated coverage statistics. This information is computed based on the filters so it matches with the coverage tree. The statistics are grouped by trackers.

The Test Coverage can be exported to Office (Word/Excel). The exported document will contain the same information as the tree, the statistics table and it will respect the filter settings.

9 SCM Repositories

Retina supports GitHub, GitLab and Bitbucket for external Version Control Systems.

Retina allows full traceability and links from requirements and tasks to source code. In the tracker items details, the counter on the “SCM Commits” tab is displayed when an item has associated SCM commits. Each SCM Commit will be stored in the repository itself as well. When e.g. a SCMLoop is installed, the following syntax in the commit message can associate the SCM Commit to any tracker item in Retina #1234 Comment (1234 would be the unique tracker item ID) (Annex D – SCR).

9.1 Connect GitHub repository

There are 2 things to do in Retina:

1. Create user(s) who has the same username as the pusher(s) in the external VCS
2. Add the secret token of the webhook to Retina configuration

To configure secret token in Retina go to the System admin page and open Application Configuration.

• Add "scc" node if it is not existing in your json (json root level)
• Add "github" node if it is not existing in your json under "scc" node
• Add "secretToken":"<secret_token_of_the_webhook>" under "github" node

After that you need to configure GitHub webhook.

9.2 Connect GitLab repository

There are 2 things to do in Retina:

1. Create user(s) who has the same username as the pusher(s) in the external VCS
2. Add the secret token of the webhook to Retina configuration

To configure secret token in Retina go to the System admin page and open Application Configuration.

• Add "scc" node if it is not existing in your json (json root level)
• Add "gitlab" node if it is not existing in your json under "scc" node
• Add "secretToken": "<secret_token_of_the_webhook>" under "gitlab" node

After that you need to configure GitLab webhook.

9.3 Connect Bitbucket repository

There are 2 things to do in Retina:

1. Create user(s) who has the same username as the pusher(s) in the external VCS
2. Add the secret token of the webhook to Retina configuration

To configure secret token in Retina go to the System admin page and open Application Configuration.

• Add "scc" node if it is not existing in your json (json root level)
• Add "bitbucket" node if it is not existing in your json under "scc" node
• Add "baseUrl":"https://bitbucket.org/" under "bitbucket" node
• Add "username": "<bitbucket_username>" under "bitbucket" node
  Where bitbucket_username is a bitbucket username who has access to the repository. It is necessary for Bitbucket API calls
• Add "password": "<bitbucket_password>" under "bitbucket" node
  Where bitbucket_password is the password for the given bitbucket user. It is necessary for Bitbucket API calls. After you save the configuration the password will be encrypted

After that you need to configure Bitbucket webhook.

10 Release Management

Release (Version) Management is about maintaining and tracking different versions of project deliverables, along with their planned and actual release schedule and the issues to be resolved in each different version. Retina allows project management and strongly supports different methodologies for development such as agile. Release Management is not only applicable to software development, but also to any type of project where some milestones need to be reached, managed and reported. Retina can similarly be configured with milestones to support the traditional Waterfall, V-Model, Waterfall with overlapping phases, or the Waterfall/V-Model methodologies with Agile implementation, called Hybrid methodologies.

Releases in Retina are modeled as configuration items in Retina, leveraging the extremely rich CMDB functionality available.

10.1 Definition and Creation of Releases/Milestones

In Retina Releases and Milestones can be created with specific properties directly on the user interface by clicking on the “New Sprint” in the release configuration tracker. In Retina a sprint, which is a time-boxed unit of development used in the Scrum framework, always belongs to a release. Retina shows a release list with all sprints of a release indented under their parent. Sprints contribute their metrics e.g. count of outstanding or finished work items to their parent release so that they show the statistical aggregation from their children. Releases are very powerful entities:

• Releases can be created, updated and deleted by adding, updating or deleting items in the corresponding configuration tracker
• Releases have their own customizable properties
• Releases have their own lifecycles, optionally driven by customizable workflows
• Releases can have children in any depth to break them into sprint or sub- and sub-sub-releases
• Releases can be commented, and they can have attachments
• Releases can have associations to other entities in Retina

10.2 Release Dashboard

The Release Dashboard can be accessed by clicking onto the Releases view for each (sub)release. The Release Dashboard provides a detailed statistical overview of (sub)releases and offers a wide variety to monitor the overall progress of development through releases and sprints in real time.

In order to see the list of work items associated with a particular version, the user can expand the details by clicking on an icon beside the release's name. The work items are color coded to indicate which ones are resolved and which ones are outstanding (green: resolved, white: outstanding). In the Release Dashboard, the user can see overdue items in the progress information as well and can apply various filter such as for status, members, workspace, priority or type for instance. Out-of-the-box, Retina provides (sub)release burn-down charts in the release dashboard to monitor the velocity, which is for a prediction how much a development team can successfully complete during a fix period of time.

10.2.1 Displaying associated Release/Milestone/Sprint

By expanding a release, its (sub)releases, sprints will be displayed.

You can see detailed information under each release/sprint.

On three chart associated sprints, story points, and item number process are indicated. Next to them Status activity and release progress are displayed.

Sub-releases' and sprints' dashboard can be opened by clicking on Show details link besides the sprint name.

From this dashboard you can navigate to Release planner, Release cardboard and Coverage pages.

10.2.2 Burn-Down Chart

Release Dashboard shows the Burn Down Chart for the release right above the filters .

Users can individually configure the chart. Configuration stored for each specific user, does not affect other user's Release Dashboard .

In configuration you can display/hide :

• burn down
• velocity
• new items

The datasource is the items' number, story poi nts or both .

10.2.3 Moving open Items to a Release/Sprint

Click on the down arrow on the top-right corner of a release/sprint summary.

In the context menu you are able to send open items into another sprint, or into the backlog. Open items number are indicated in brackets.

10.2.4 Changing Release status

Ability to change Release status with one click on Release Dashboard.

Click on the down arrow on Release Dashboard besides the status badge, and select the transition to apply.

10.3 Release Planner

The Release Planner can be accessed by clicking onto the Release Planner view for each (sub)release. The Release Planner is the place where the workspaces are actually planned through daily task estimation, daily task, release and sprint management. Work items can be rearranged for prioritization and assigned to a specific (sub)release via drag&drop (e.g. such as from the workspace backlog to a sprint). It is very helpful in balancing workload on a team, especially if the user is adopting agile development methodology with the concept of Story Points. Agile encourages estimating complexity of s expressed in so-called story points. The user can enter the Story Points value for a while editing that in-place in the center panel, or editing that in the overlay. Story Point values will be automatically aggregated in Retina in the right, and by release and sprint in the left panel. There are two ways to assign s with responsibilities to a release:

• Use the Planner or
• Assign s to a specific user/role/group and fill in the release property field in the itself

10.3.1 Work Item assignment to a Release/Sprint/Milestone from Backlog

Open Product backlog on release planner page. To assign s to a specific release or sprint, just drag and dropthem to that (sub)release on the left, possible drop targets will be highlighted.

If you need to move all Work Items form a Sprint or Release to a different one, then it is better to use the specialized functions accessible from the sprint tile's context menu.

Item(s) will be assigned to the selected sprint, and page will be refreshed.

10.3.2 Work Item prioritization

You can manually change the ordering and rearrange s by drag-and-drop in Planner (if you have the proper access rights, of course).

With Send to top, Send to middle and Send to bottom, you are not changing the target (sub)release but move the to the beginning, to the middle or to the end of its list, respectively.

10.3.3 Work assignment and Story Points

Planner is helpful in balancing workload on your team, especially if you use an agile development methodology with the concept of Story Points.

There are two possible ways to set a work item's assignee:

1. Overlay editing: click on the work item in main panel, and edit it's properties on the right panel.
2. Drag-and-drop: drag the item and drop it on a team member option on the left panel under the sprint list.

You can see work item numbers and story point besides each member.

10.3.4 Multiple assignment to sprint or members from grouped Planner

Group work items by a property on Filters panel.

Items will be listed under highlighted group names in the main panel.

On the left side of the highlighted group name grab the whole group with the 6-point icon and drop it on a sprint or member name on the left panel to assign them all at once.

10.3.5 Using table header on Planner

On planner main panel the planner table has a sticky header. Visibility of the columns is easily changeable by using the eye icon on the top-right side of the panel.

Table columns can be reordered with drag-and-drop, and with the context menu of the column headers can be removed or you can reorder the table according to it.

10.3.6 Filter options on Planner

On planner item filter is useable almost the same as in tracker views, but in Planner you can filter by workspaces / trackers using the Workspaces and Trackers selectors. These lists contain the workspaces and trackers which are related to the current release. Furthermore you can filter by any default, reference and custom fields, and some other options just like in tracker views.

To set filter conditions click on the Add filter button, select the field and set its value(s).

By clicking on Go main panel will reload.

10.3.7 Order by options on Planner

On Filter panel you can use order by function. Select one or more fields to order by, set ascending or descending direction, and click on Go. If you select Order by, ordering by drag-and-drop is not possible.

10.3.8 Group by options on Planner

On Filter panel you can use group by function. Select one or more fields to group by.

A highlighted row will be displayed on main panel over the grouped items. By 6-point icon you can drag-and-drop all items from group to execute assigment all at once.

10.3.9 AND/OR logic options on Planner

If you filter by more than two attributes, you can add AND/OR logic to refine filtering. By default the conditions are using AND logic.

Add two conditions on the filter panel. Click on the -/+ icon next to the Add filer to define logic. A mandatory AND/OR logic text input will be displayed, and the given conditions will get numbering. Use this numbering to identify conditions, you can use 1 AND 2, or 1 OR 2 to define a logical phrase.

After you entered a valid logical phrase, Go button will be active again, and by clicking on it the s will be filtered.

10.3.10 Default views on Planner

On the top-left section of the Planner you can select any default view in the Views dropdown.

By selecting a view it will be activated immediately, and main panel will be reloaded.

You can set any view as default view by clicking on the pipe icon next to the view's name, and unset as default by clicking on the x icon next to the view's name.

10.3.11 Create custom public/private view on Planner

Use the filter panel to set up any filter condition.

On the top of the Filter panel click the Save as button to save the filter as own view.

Set its name, whether it's Public or Private, and optionally write a short description.

10.3.12 Modify your own views in "View Manager"

Select an own view from the Views dropdown. Click on the filter icon on the top-right corner of the page.

The settings of the view will be displayed. You can modify these conditions any time, and by clicking on Go button you can see the result of the filter.

If you modify a custom view, you can choose whether you want to modify the current view - click on the Save button - or you want to create a new view based on this custom view - then click on the Save as button on the dropdown menu of the Save button.

You can also change the properties of the current custom view by selecting Properties on the dropdown menu of the Save button.

10.3.13 Delete your own Views

You can delete any custom view; default views are not deletable.

Select the view to delete and click on the filter icon on the top-right corner of the page. Filters panel will be displayed. Open the dropdown menu of the save button and select Delete option. After the confirmation view will be deleted.

10.3.14 Switch View from Planner to Kanban Board

In Release management you can change between Release dashboard, Planner and Cardboard any time.

To change view use the view buttons on the top-right corner, next to the Filter button.

10.3.15 Creating referenced items in Planner

You can create new Downstream References for items by using the context menu next to the Summary field, and selecting a tracker under theDownstream reference menu option .

10.3.16 Use Multiple selection option on Planner

It is possible to select more items at once and manage the selected items in one operation. After you hover your mouse over an item, there will be a checkbox for every item. You can select the items one-by-one, and use drag&drop operations for all of the s elected items. You can assign items to other Release/Sprint, assign to teams/members .

10.3.17 Visibility of Releases and Sprints

If you open a Planner from a specific release/sprint, all of its sub-sprints and the Product backlog will be displayed.

Click on one of the sub-sprint on the left panel to display assigned items on the main panel.

10.4 Cardboard

The Cardboard can be accessed by clicking onto the Cardboard view for each (sub)release. Applying the Kanban methodology helps the users visualize and manage the workflow by letting them track, move work items and trigger status changes along the defined and agreed workflow. The Cardboard in Retina can be used to easily manage the Work Items assigned to the different (sub)releases or simply trackers. The Cardboard also provides a quick overview of the balance between expended resources and WIP (Work in Progress) limits, which is very important to be able to understand the current gaps. Swimlanes, WIP Limits, and various filter options can be configured for usage.

10.4.1 Work in Progress (WIP) Limits

Work-in-process (WIP) at each state in the workflow is limited. New work is “pulled” into a state only when there is available capacity within the local WIP limit .

On Cardboard click on the gear icon on the top-right side, under the filter icon to display Cardboard configuration.

Here you can set WIP minimums and maximums for all potential columns. Save configuration, and setting will be applied immediately.

Free capacity and Overloaded will be indicated at the top of the columns.

10.4.2 Grouping and Filtering options on the Cardboard

On the Cardboard you can find a Swimlane dropdown on the top-right corner of the page. If you select an option in this field, the cards will be grouped regarding to this selected field. These groups are the swimlanes, and they are expandable / collapsible.

After you selected an option for swimlanes three new element will be displayed next to the dropdown field. By Swimlane order by you can define cards' order in swimlanes, and the switch button controls if the empty swimlanes are visible or not. By clicking on the button with arrow you can expand or collapse every swimlane at once.

Besides that you can filter with the Filters panel as usual.

10.4.3 Managing views in the Cardboard

On the top-left section of the tracker view you can select any default view in the Views dropdown.

By selecting a view it will be activated immediately, and page will be reloaded.

You can set any view as default view by clicking on the pipe icon next to the view's name, and unset as default by clicking on the x icon next to the view's name.

Select a view from the Views dropdown. Click on the filter icon on the top-right corner of the page.

The settings of the view will be displayed. You can modify these conditions any time, and by clicking on Go button you can see the result of the filter.

If you modify a default view, then you can click on Save as to save a custom view based on the modified default view. The default view itself won't be changed.

If you modify a custom view, you can choose whether you want to modify the current view - click on the Save button - or you want to create a new view based on this custom view - then click on the Save as button on the dropdown menu of the Save button.

You can also change the properties of the current custom view by selecting Properties on the dropdown menu of the Save button.

You can delete any custom view, default views are not deletable.

Select the view to delete and click on the filter icon on the top-right corner of the page. Filters panel will be displayed. Open the dropdown menu of the save button and select Delete option. After the confirmation view will be deleted.

10.5 Working with Backlogs

The Backlog in Retina is an ordered list of open s that need to be done at some point. There are multiple types of backlogs:

Product Backlog is composed of the open s that are not scheduled to any release or sprint yet. The items exist, but it is not defined when to address them. In every (Sub)Release Planner, you may find a Product Backlog tab in the bottom of the left pane.

Release Backlog is composed of the open s that are scheduled to a specific release, but not to a sprint yet. These should be addressed in that release, but it is not defined in which sprint. Prioritizing Work Items in the backlog can be done via drag&drop.

Sprint Backlog is composed of the open s that are scheduled to a specific sprint, but have not been done yet.

10.6 Support for Large Scale Scrum (LeSS)

Teams and Areas tracker types can be used to better align with the needs of LeSS teams. You can cross-assign Areas, Teams, and team members in the system, while the new @team/@area mention feature enhances collaboration across teams.

11 Baselines

A baseline is essentially a snapshot of a workspace at a particular point in time, which carries all your digital content: requirements, tracker items, wiki pages, documents, comments, or attachments. It not only saves the content, but also the configuration, even across workspaces. A baseline lets you go back in time, and browse an earlier “version” of your workspace. You also have the ability to compare baselines and get statistics on what has changed over time . Baselines can be signed with a unique (to each user) electronic signature. Retina shows a diff for each item, highlighting the changes according to the when-who-what approach.

Baselines can be also created for specific trackers and documents directories in Retina, letting them compare in detailed as well. Retina's powerful BPM Workflow Engine can automatically enforce to create a new baseline for either a tracker or a workspace scope by selecting the default workflow action.

11.1 Contents of a baseline

Baselines in Retina capture the state of your digital content in a moment, pretty much like tags mark a particular state of the source code in a Version Control System.

When you create a new named baseline, a snapshot of your requirements, tracker items, wiki pages, documents, comments and attachments is saved. In the future, you can "go back in time" and browse any earlier baseline, to see how that content looked in that snapshot. Baselines can also be compared to find out what content has been changed between two snapshots, when exactly and by whom.

Baselines are useful for audit purposes, including deviation against a previous baseline, certification for an approval, comparison to another baseline, maintaining wiki pages for multiple product releases, or all of these.

A baseline is a lightweight read-only directory/index of all documents and their respective revision (at the time of baseline creation) in a document tree branch, including the document hierarchy/structure.

11.1.1 Wiki pages

If a baseline contains Wiki documents, it also stores references to all documents and their respective revision (at the time of baseline creation) referenced/included by the contained Wiki documents, and also recursively to documents referenced/included by the referenced documents.

As a result, when browsing Wiki documents from a Retina baseline, all references and inclusion are consistently resolved to the respective revision at the time of baseline creation, even if the target documents have been modified or even deleted in the meantime.

11.1.2 Documents

A baseline is lightweight because it only stores references to specific document revisions which already exist; it does not copy any document data.

The same revision of a document can be referenced by any number of baselines at the same time.

Document revisions referenced in baselines will not be deleted unless all baselines holding references are deleted, even if you delete the document, the document tree branch where the document resides, or the workspace containing the document.

Baselines are immutable: you cannot add, edit or remove items after baseline creation.

Read permission to all items (document revisions) in a baseline is solely controlled via the baseline. You cannot define permissions for individual items.

11.1.3 Trackers

To create a new baseline on the Tracker of the item, that is subject/source of the triggering event.

11.1.4 Tracker items

When you create a new named baseline, a snapshot of the requirements, tracker items are saved.

11.1.4.1 Comments and attachments

When you create a new named baseline, a snapshot of the comments and attachments is saved.

11.1.4.2 Associations

When you create a new named baseline, a snapshot of the associations is saved.

11.1.4.3 Suspected alerts

When opening a baseline, suspected alerts are activated but the user cannot clear suspected .

11.2 Create new Baseline without electronic signature

When creating a new baseline, it is possible to decide if the user would like to create it with or without electronic signature. If the user wouldn't like to sign it, the Signature textbox should be empty.

11.3 Create new Baseline with electronic signature

When creating a new baseline the baseline can be signed by the current user if the user's password is given in the Signature textbox. After saving the newly created baseline, the username and the signature's date become visible.

11.4 Create workspace level Baseline

When creating a new workspace level baseline a snapshot of the whole workspace is saved.

11.5 Create tracker level Baseline

To create a new tracker level Baseline, the selected tracker should be opened. By clicking on the "More functions" menu the "Create baseline" option can be selected which enables the user to create a new tracker level Baseline.

11.6 Browsing a Baseline

By clicking on the selected baseline's name on the baseline list the baseline's content shown in a new window.

11.7 Comparing Baselines

To compare baselines the two "SELECT BUTTON TO COMPARE" buttons should be used at the top of the Baselines page. Then select the baseline by clicking its name in the overlay and press the "Compare Selected Baselines" button. The opened view shows the differences between the two baselines. The differences between the selected baselines are separated into categories. Every category has a tab in the result view. The detailed modifications can be viewed by opening the category tabs.

11.8 Deleting Baselines

To delete a baseline the selected baseline's "Delete Baseline" button should be used on the Baseline page.

12 Reports and Queries

In Retina, the reporting mechanism allows for cross-workspace-reporting in a workspace. Workspaces can be chosen and from the chosen workspaces, subsequently, the available trackers. Once a workspace is configured it can be run again an unlimited number of times. For each tracker, conditions, fields, criteria etc. can be customized. Reports can be exported to various formats such as Excel, PDF, XML, etc.

Queries are a workspace independent ad-hoc search/filter mechanism across multiple workspaces using cbQL. The user can filter the tracker items firstly by workspaces and then by trackers with certain conditions such as text, number fields or reference conditions. But the query widget with the conditions is just for helping define the most useful queries without learning and typing cbQL query language. It doesn’t contain all of the functionalities what cbQL language knows. There is an advanced mode the user can define cbQL expression. New queries can be saved and existing ones can be found upon the user interface. When creating a new query the user needs to give it a name and optionally you can add roles from workspaces that to share the query with and a description. Furthermore, queries can be exported to Excel.

12.1 Creating Reports and Queries

In Retina report and queries can be created through Analytics/Reports/New Report. A report can be created as Simple reports, using the options provided on the graphical user interface, or as Advanced reports, using the cbQL query language.

12.1.1 Simple reports

The Simple report option enables report creation on the graphical user interface without having to enter their query in cbQL language to build the report. The Simple report builder however still builds a cbQL query in the background, but the report is built on the graphical user interface. To reveal the underlying cbQL query switch to Advanced mode.

Simple reports allow cross-workspace-reporting. From the workspace selector, multiples workspaces can be selected. Any workspace can be selected where the user is a workspace member.

From the tracker selector, based on the workspace selection, the user can select multiple trackers from the list of trackers and any trackers can be selected where the user has read permissions based on his/her user role and the tracker permissions associated to the role.

By default, no workspaces and trackers are selected.

To create a simple report at least one condition has to defined.

By clicking on Go with no workspaces and trackers selected and at least one condition defined all s on the Retina instance will be displayed in the preview where the user has read permission and the item matches the condition.

By clicking on Go with workspaces and trackers selected with no condition all s within the selected workspace tracker(s) where the user has read permission will be displayed in the preview.

In the Fields section, the Default fields and Common Reference fields are displayed. Based on the workspace and tracker selection the selected tracker's custom fields are displayed here as well as the bottom of the list. Searching for fields is available by typing the field title in the Search field in the Fields section.

With drag and drop fields can be added as:

• A condition with drag and drop action
• 'Group by' criteria with drag and drop action
• 'Order by' criteria
• with drag and drop action
• A visible column in the report by dragging the field in the displayed preview's header section and releasing it where the indicator shows the placement of the new columns

Conditions can be added by clicking on the '+' icon. Multiple conditions are applied with 'AND' logic. User-defined AND or OR logic can be applied by clicking on the 'Add AND/OR' option in the Conditions section. If AND/OR logic is enabled, a valid logic string must be defined. Valid phrases: numbers that represent the filter conditions, AND, OR logical operators. E.g. 1 AND (2 OR 3).

Newly added conditions will be applied to the preview by clicking on Go. Newly added conditions will be applied to a previously saved report by clicking on Save.

Report results can be grouped through user-selected conditions. To apply such a condition click on '+' in the 'Group by' section. Newly added conditions apply by clicking on Go.

Newly added 'group by' conditions will be applied to the preview by clicking on Go. Newly added 'group by' conditions will be applied to a previously saved report by clicking on Save.

Report results can be ordered through user-selected conditions. To apply such a condition click on '+' in the 'Order by' section. Newly added conditions apply by clicking on Go.

Newly added 'order by' conditions will be applied to the preview by clicking on Go. Newly added 'order by' conditions will be applied to a previously saved report by clicking on Save.

12.1.2 Advanced reports

Switching to the Advanced reporting option enables users to enter their queries that are a workspace independent ad-hoc search/filter mechanism across multiple workspaces using cbQL query language.

The cbQL is a query language in Intland Retina, with which it is possible to create reusable queries. The syntax of the cbQL is similar to the SQL.

There are four different parts of a cbQL.

• SELECT keyword and projection. This part is optional. If we would like to see additional information about a group of tracker items, then it is possible to add aggregation functions and filters or their alias names
• WHERE keyword and a condition list. The WHERE keyword is required if the cbQL contains SELECT keyword otherwise doesn't
• GROUP BY keyword and a field or an alias list. This part is optional. It is possible to make groups from the result of the conditions based on the definition. After the GROUP BY keyword
• ORDER BY keyword and field list and direction. This part is optional. If we would like to order the result, then we can add the necessary fields and the direction of the order

Switching from Simple to Advanced mode in a report where workspaces, trackers, conditions, etc. are already defined reveals the underlying cbQL query.

12.1.3 Editing item details in the result table.

Users can edit details in the result table according to their permissions by clicking on the in the result table. This action opens the right panel with the selected item's details. The item details can be edited with inline edit. Only those attributes can be edited that are editable based the users role's tracker, workflow and field permissions.

12.2 Saving Reports

Users can save the configured reports by clicking on the 'Save As' button once they are done editing the current report.

Mandatory attribute(s):

• Name

Optional attribute(s):

• Description
• Permissions

12.2.1 Shared Reports

Reports can be saved as private or shared reports. To share a report the creator of the report has to define READ or WRITE permissions for user roles defined in workspaces.

To do this first the workspace has to be selected, then the available roles with the workspace.

Multiple roles in multiple workspaces can have permissions to read or edit the report.

The creator user can define the access level (READ/WRITE) for each role.

By default all selected roles have READ access.

12.3 Modify Reports and Queries

Previously saved reports and queries can be modified by the creator user or any users who have WRITE access if their workspace role(s) has this access level configured in the report.

To edit a report the user first has to Find/Load the report.

On the report's result page the user with WRITE access has to click on the 'Edit report' button to open the report in the report editor.

Once the user is done editing the report she/he can save the modifications overwriting the existing report configuration.

12.4 Delete Reports and Queries

Previously saved reports and queries can be deleted by the creator user or any users who have WRITE access if their workspace role(s) has this access level configured in the report.

To delete a report the user first has to Find/Load the report.

On the report's result page the user with WRITE access has to click open the dropdown menu next to the 'Edit report' button and select the 'Delete report' option. The system prompts the user to confirm the deletion of the report.

12.5 Find/load Reports

Previously saved reports can be found and opened from the 'Analytics/Reports/Find reports' menu.

The user can search based on Name.

The user can order the list of reports based on Name, Description, Modified By and Modified At attributes.

The user can filter based on report type:

• Own reports
• Shared reports
• Own and share reports

To open a report the user has to click on the report's name.

12.6 Exporting Reports

Previously saved reports and queries can be exported by the creator user or any users who have READ or WRITE access if their workspace role(s) has this access level configured in the report.

To export a report the user first has to Find/Load the report.

On the report's result page the user has to click on the 'More options' button and select 'Excel export' option.

The user can decide whether to download the exported report or to store it in Retina as a Document type object.

12.7 Working with Report Jobs

Users can define report jobs to send out reports to a predefined list of recipients through automation.

To define a reporting job the user has to open the previously saved report (see 'Find/load reports')

To add a new reporting job the user has to click on '+Add job'.

The user has to define the job's name, the recipients, the frequency of the job. The user can define if the report has to be sent only if the number of items is more than a user-defined integer value.

Recipients:

• The report can be sent out only to those roles that have at least READ access to the report The user can select multiple roles. Emails will be sent only to 40 users per role

Report frequency:

• Daily
  • Once per day
    • User-defined start time (1-hour iterations)
• Weekly
  • Reoccurrence: days, multiple-selection option
  • How many times on these days: once per day, every 4 hours
    • User-defined start time (1-hour iterations)

The user can manage (edit, disable, stop or delete) previously saved reporting jobs:

• In the 'Analytics/Reports/Find reports' menu by clicking on Manage jobs
  • The user can edit the job by clicking on the job's name
  • The user can disable/stop the job
  • The user can delete the job
• By opening an existing report, if there is already a reporting defined the user can edit the job by clicking on 'Edit job'
  • The user can edit the job by clicking on the job's name
  • The user can edit the recipients
  • The user can edit the frequency of job
• By opening an existing report, the user can select the Manage jobs next to the 'Edit job' or 'Add job' button (depending if the open report has a reporting job already)
  • The user can edit the job by clicking on the job's name
  • The user can disable/stop the job
  • The user can delete the job

13 Integration and data exchange with existing tools

Retina resources can be accessed, and data can be exchanged with other tools via the REST API and various formats. For the Retina tool qualification according to ISO 26262, the integration possibilities to any further third party tools such as to MS Office products or LDAP are not included. The end user has to evaluate the usage of any third party tools to Retina within the safety lifecycle themselves.

13.1 Import Processes

Retina does support importing of various data formats.

The user must evaluate the product generating the imported file in context of the usage within the safety lifecycle themselves.

13.1.1 Tracker import

User can import tracker items in tracker page by clicking on More functions besides the view selector and selecting Import option.

Items can be imported from

• Microsoft Word
• Microsoft Excel
• CSV file.

The Word document should be structured using Word st yles: after the import the heading styles will be the summaries of the work items, the paragraphs after the headings with normal styles will be the descriptions. The different levels of heading styles will make the parent-child relation between the work it ems.

Retina Excel import functionality allows you to import data from an Excel file. The major features of this import is:

• You can import data to a Tracker and create new work items there
• Excel 2007 (*.xlsx) format is supported
• First Excel row is used as header, 2nd row and below is used as data (customizable)
• Excel columns are mapped to work item fields, mapping is configurable
• Importing work item hierarchies is possible using indented data
• Date, number format is customizable, other detailed data conversion is possible

Retina import functionality allows you to import data from a CSV file. This import is practically same as importing data from Excel, except the minimal differences caused by the constraints of the CSV file format.

CSV format related constraints of this import is:

• Two quotes escape character ("" escapes "), no other characters are escaped
• Compatible with Microsoft Excel and many other programs that have adopted the format for data import and export
• Leading and trailing white space on an unquoted field is significant
• Specified by RFC4180

13.1.2 Wiki import

To import wiki document from Microsoft Word click on the More options in the top of the Wiki page. Select Import from Word option to display dialog.

You can upload Word document and select an import method:

• overwrite the page with the imported content
• append the imported content to the end of the page

13.1.3 User import

Users can be imported from Excel with the appropriate permission.

On System admin / User accounts page click on the Import from Excel button, and Import wizard will appear in dialog.

13.2 Export processes

Exporting to various formats is supported by Retina.

The user must evaluate the products used to open the exports in context of the usage within the safety lifecycle themselves.

13.2.1 Item export

To export one single item open the tracker item details page.

Under the tabs you can find a hamburger icon, and an Export to Office option. By clicking on this option export dialog will be displayed. You can export item to Microsoft Word and Microsoft Excel formats.

13.2.2 Tracker Audit Export

Open Tracker Audit from the tracker's Configuration page.

On the top of the page you can find an Export to Word button, which will export audit information from all of the tabs to Microsoft Word.

13.2.3 Export to PDF

When selecting the More Functions menu there is an Export to Office option. By clicking on this option export dialog will be displayed. Export to PDF option can be chosen below the "Export with" section.

13.2.4 Tracker export

Exporting several Work Items (Requirements, Tasks or Bugs) or a whole Tracker is very easy, just open the Tracker which contains the items that will be exported and on the More functions menu which contains an Export to Office menu this initiates the Excel /Word export dialog .

This export will contain those fields which are available inside the View and only those items which are matching with the current view.

However if you want to export or view the Work Items of a tracker somehow differently, like change which fields are exported or the order of fields then you can create a custom view for the tracker.

If you need to export some specified items, use the Export selection to Office of the More functions menu. This will export only the previously selected items.

13.2.5 Workspace export

To export a workspace configuration file to use as a project template, Workspace settings should be selected below the Admin menu. By clicking on the Export tab in the pop-up window, user can select the artifacts which should be included in the template file. When clicking on the Export button the workspace configuration file is exported as a template. It is possible to export only a subset of the trackers in the workspace. For this process the trackers checkbox should be unchecked, and the user will get a list where it is possible to select the trackers manually to export.

13.2.6 Wiki export

To export a wiki page in Retina, More Options should be selected on the wiki page, then by clicking on "Export to Word" user can decide if the export should be downloaded or the document should be stored in a document tracker.

13.2.7 User export

To export users in Retina, System Admin page should be opened. By selecting the User accounts the users can be exported to an Excel file.

13.2.8 Round-trip export and import

Exporting work items from Retina to Round-trip Word documents starts with navigating to the tracker which contains the ones to be exported. Within the tracker choose the "Export to Office" action in the "more" menu. You can also choose to export "Selection " which means that the export document will only contain selected items. A popup window appears, where the "Round-trip" option should be chosen.

When this menu is selected Retina will build a Word document which contains the work items displayed by the current view and the download of that Word document will start in few seconds automatically. The generated file name will contain the current workspace's and tracker's name, so it is easier to identify later where that export file is originated from.

After finished editing of the Round-trip Word document, it is time to import the changes back to Retina. This can be done with the "Import from Word or Excel" menu in the "more" menu of any tracker.

The first page of the import wizard will appear. Here the round-trip docx document can be selected and uploaded. This is the same wizard that is used for normal - i.e. non Round-trip- import, but the importer will automatically recognize the Round-trip documents, and will display the specialized import page for them.

The importer will read the Round-trip document and scan it for changes. The import wizard will display the changed work items only, and will also show the differences to the original work item.

After reviewing the import data the user can save and apply the changes, whereafter a summary of changes is displayed.

13.2.9 Template-based Word export

For exporting to Word or Excel by using customized templates, the template should be uploaded to the proper place (Manage Custom Templates). By clicking on Export to Office, a popup window comes up with the details of the export. The uploaded template could be selected below the Template section.

13.2.9.1 Traceability Browser Word export

There is ability to export the displayed traceability table into MS Office by clicking the Export to Office link above and under the traceability table, so you can work with the traceability data further on.

• Excel export: Export the result table into Excel (xls format). untick "Merge interconnected cells (long-running operation)." option to speed up huge excels export.
• Word export: Export the result into Word (docx format), building a tree inside the document containing the tracker items of the traceability result with detailed item information. You can specify also templates for the import, so you can configure which data of the tracker item should display.

13.2.9.2 Review Word Export

To export a review in Review Hub open the review that you want to export, then on the review page, select the Export icon. When the Exporting items window opens, user can select the template that he wants to use for exporting the review. The file can be converted to PDF format by selecting the Convert to PDF checkbox. When the user is ready with specifying the export settings, Export button should be selected to start exporting the review content.

13.2.9.3 Coverage Browser Word export

To open the Test Coverage page, the Tools tab should be selected on the top of the page. By clicking on Test Coverage, there is an ability to export it into MS Office by clicking the Export to Office link above coverage table.

• Excel export:Export the coverage table into Excel (xls format).
• Word export:Export the result into Word (docx format)building a tree inside the document containing the tracker items of the test coverage with detailed item information.

13.2.9.4 Risk Matrix Word export

In Retina it is possible to Export all the risk matrixes into MS Word or MS Excel. By opening the proper tracker's Risk matrix diagram from the More functions menu, user can Export the matrix to Word.

13.2.9.5 Test Run Word export

The Test Run's Report can be exported to Microsoft Word by using the dropdown menu of the top of the test run's editor and selecting the Export to Office option. This produces a Word file which contains the same information in a more Word-friendly format t han the Test Results Report which appears on the web page.

13.2.9.6 Test Case Word export

The created test cases can be imported to Microsoft Word by opening the proper test case type tracker, then selecting the More functions on the top of the page. When clicking on Export to Office, Exporting items window opens, where user can select the template that he wants to use for exporting the review. The file can be converted to PDF format by selecting the Convert to PDF checkbox. When the user is ready with specifying the export settings, Export button should be selected to start exporting the review content.

13.3 Jira Connector

Retina offers a bidirectional synchronization to Atlassian JIRA. Projects can be imported from a JIRA server into Retina by creating a new workspace in Retina and providing the URL of the JIRA server, username and password for this instance. The specified user retrieves a list of available projects on this JIRA server and can import a JIRA project including the roles and members, project versions, components and work items into Retina. If the user wants to continue using JIRA and on the other hand, also wants to refer to/extend selected data from JIRA in Retina, a manual or automatic (periodic) JIRA to Retina workspace replication can be setup. The default synchronization replication from JIRA to Retina is one-way, but the user can change the synchronization to bi-directional. A synchronization interval can be set up in the job interval whereas the smallest allowed value is 10 minutes and an empty interval disables the automatic/periodic execution. The job can be executed manually any time by clicking on the run job symbol.

The user must evaluate JIRA in context of the usage within the safety lifecycle themselves.

13.3.1 Connect to Jira instance on the tracker level

To connect to Jira instance in tracker level open the tracker page in Retina. In more functions select the Synchronize with Jira option.

Configure Jira server on Jira Connector Settings dialog. If Jira server is available, the project list will be displayed, after you click on pencil icon at the bottom of the dialog.

Select the Jira project and work item type you want to synchronize.

13.3.1.1 Connect to Jira instance on the tracker level - Import direction

Select Import Data option for Direction on Jira Connector Settings dialog.

In this case only the modifications from Jira server will be imported to Retina, no modifications from Retina will be uploaded to Jira.

13.3.1.2 Connect to Jira instance on the tracker level - Export direction

Select Export Data option for Direction on Jira Connector Settings dialog.

In this case only the modifications from Retina will be exported to Jira server, no modification from Jira server will be imported to Retina.

13.3.1.3 Connect to Jira instance on the tracker level - bi-directional

Select Synchronize Data option for Direction on Jira Connector Settings dialog.

In this case both the modifications from Retina and Jira server will be updated in the other system.

13.3.2 Import users from Jira on the workspace level

On Jira connector settings page check in Users in References section to display Jira user even if he/she has no Retina user.

13.3.3 Jira credential validation

The first step of Jira connector setting is to set up Jira connection.

You need to set:

• server IP address
• username
• password

13.3.4 Jira permission validation through the Connector

Jira synchronization is permitted for some references for regular user.

Open Jira connector settings dialog with a regular user, and verify References section: Users, Groups, Epics and Teams are disabled.

13.3.5 Storing historical entries for Synchronization/Import/Export date/time/user/changes

On Jira connector settings dialog bottom you can set how many synchronizations should be kept in the synchronization history.

After every successful synchronization you can see history from the Jira Connector dialog history icon.

13.3.6 Workflow synchronization from Jira into Retina

If the Jira user, that you have configured for the Jira synchronization, has "Administer projects" permissions on the Jira project, then Retina can do the necessary Jira workflow synchronization automatically.

Otherwise you will be asked to do the workflow synchronization manually. You can:

• change the user
• sync as admin
• sync from file
• don't sync

13.3.7 Disabling Jira synchronization

To disable synchronization open Jira connector settings dialog, and click on the Remove button on the footer of the dialog.

13.3.8 Synchronize/Import/Export periodically

On the Jira connector settings dialog bottom you can set a running period for synchronization/import/export. The minimum value is 10 seconds.

After setting this value you need to start a manual sync. After that synchronization time will be calculated, and sync will be executed automatically after every x minutes.

13.3.9 Save/load synchronization setup

Map all desired fields on Jira connector Settings dialog.

On the bottom of the dialog click on Save as link. Your settings will be downloaded in a json file.

If you want to reuse this setting, you can load it with the Load from link. Just select your saved json setting file, and the mappings will be loaded immediately.

13.4 User Authentication with LDAP

Retina enables to manage user authentication against an existing LDAP/Active Directory server in addition or instead of maintaining own user accounts and to import and update user account information from an LDAP/Active Directory service. LDAP/Active Directory can be configured via System Admin - User Authentication.

When a user logs in to Retina for the first time and the LDAP authentication is successful, a Retina account will be created automatically with LDAP attributes such as e-mail address, name, phone number, etc. and they will be stored and mapped into the Retina account database. These attributes will be synchronized with the LDAP server after each successful login into Retina.

The user must evaluate Active Directory / LDAP in context of the usage within the safety lifecycle themselves.

14 Review Hub

A Review in Retina is a snapshot of the items of a Tracker, Release or Report at a specific point in time. When a set of items (for example, tasks or requirements) is ready for approval, you can initiate a review in Retina. You can invite contributors (reviewers and moderators) to decide if a review item can be approved or if it needs more work. If an item is updated while under review, you have the option to receive a notification about the change. You can then decide if the review needs to be restarted because of the item that was modified. You can restart the review for all the review items or for those items only that have been modified since the review started.

General Concepts

A review in Retina is a set of items. A review always contains a specific version of the items (depending on when the review was created). The contributors of the review can discuss the items that are being reviewed. After the discussion, they have the following two options for each item:

• Approve the item: the item is fine and fully developed: the reviewer found no issues.
• Mark it as 'Needs More Work': the item is not fully developed, or the reviewer found some issues with the item.

The Review page makes the discussion and the approval or rejection of an item easy.

There are two types of contributors for each review:

• Moderator: a moderator can edit, close, and restart the review and can also add or remove contributors to/from the review.
• Reviewer: a reviewer can approve or reject the items in the review and can add comments, but cannot edit the review.

14.1 Starting and Editing a Review

You have the following options to initiate a review:

• In the Review Hub
• From a tracker: you can initiate a review for a specific tracker using the More functions menu of the tracker. Select one of the following options:
  • Send to Review: this option creates a review for all items of the selected tracker. When creating a review for all items of a tracker, the review reflects the child-parent hierarchy of the original items. However, this hierarchy is not updated in case the review is restarted
  • Send Selection to Review: this option creates a review for the selected items in the tracker
• From a report: you can initiate a review for all the items returned by a specific report
• From a release: you can initiate a review for all the items which are currently assigned to a specific sprint or release.

14.1.1 Tracker Review

A Tracker Review in Retina is a snapshot of the items of a Tracker at a specific point in time. When a set of items (for example, tasks or requirements) is ready for approval, you can initiate a review in Retina. You can invite contributors (reviewers and moderators) to decide if a review item can be approved or if it needs more work.

14.1.1.1 Selecting multiple workspaces

When creating a new review in Review hub, multiple workspaces can be selected from the dropdown menu.

14.1.1.2 Selecting multiple trackers

When creating a new review in Review hub, multiple trackers can be selected from the dropdown menu.

14.1.1.3 Work item hierarchy

In case of sending a single tracker for a review in Review hub, the hierarchy of the work item is maintained.

14.1.2 Report Review

User can initiate a review for all the items returned by a specific report by opening the report and selecting the "Send to review " option from the More options menu. The other option for creating a report review is to go to the Review hub, then select the Report review from the review types. The proper report should be selected to create the review .

14.1.3 Release Review

Users can initiate a review for all the items which are currently assigned to a specific sprint or release. To do that, go to the Review Hub, then select the Release review from the review types. The proper workspace and the specific release should be sele cted to create the review .

14.1.4 Send to Review

Send to Review option creates a review for all/selected items of the selected tracker, a specific report or a release .

14.1.4.1 Send all items of a single tracker to review

When creating a review for all items of a tracker, the review reflects the child-parent hierarchy of the original items. However, this hierarchy is not updated in case the review is restarted .

14.1.4.2 Send selected items of a single tracker to review

Send Selection to Review option creates a review for the selected items in the tracker (you need to select the items before initiating the review). This option is available in List view and Document View).

14.1.5 Baselines

When creating a new baseline for the whole workspace, then creating a new review in Review hub, the created baseline can be selected. If the user change some of the items, the baselined versions will be visible in the review.

14.1.6 Participants of a Review

There are two types of contributors for each review:

Moderator: a moderator can edit, close, and restart the review and can also add or remove contributors to/from the review.

Reviewer: a reviewer can approve or reject the items in the review and can add comments, but cannot edit the review.

A review can be closed and restarted by the moderator. A closed review is always read only, which means that none of the reviewers can accept or reject the items of the review any more. A moderator can restart a closed review. Depending on the options set when restarting the review, some items in the review can still be read only. The purpose of restarting the review is to incorporate any possible modifications (made after the original review was initiated) to the review. For this reason, the restarted review refers to the versions of the items at the time of the restart.

14.1.6.1 Multiple Reviewers

When creating a new review in Review hub, users can invite contributors to decide if a review item can be approved or if it needs more work. On the "Select reviews" page of the Review hub, creator can select multiple reviewers to the current review. Reviewers can review the items but cannot update the review and need the Review permission.

14.1.6.2 Mandatory Electronic Signatures

When creating a new review in Review hub, electronic signatures can be set as mandatory for all users or a number of users. By selecting the "Requires signature to finish the review"/"Requires signature from reviewers” checkbox, the user will be asked to sign the review with his password in the Signature field of the Review hub. It is possible to set the minimum number of signatures on an item, by defining it on the review creation dialog. In addition to the password-based signature, username can also be set as signature criteria if the "Sign with Username and Password" checkbox is selected in the review configuration.

14.1.6.3 Set up User Groups and Workspace Roles as Reviewers

When creating a new review in Review Hub, it is possible to choose members, roles, or groups as reviewers.

14.1.6.4 Replacing Individual Review Participants

It is often the case that review participants are unable to participate in the review activity due to their absence. In Review Hub, review creator can replace the individual review participants by opening the Editor and adding new reviewers to the review. Reviewers who are unable to participate in the review process should be removed.

14.1.7 How to Edit a Review

In Retina user can modify the review's properties in a matter of seconds. To edit a review, go to the Review Hub and open the review that you want to modify. On the review page, click the Edit icon on the top of the page then the review editor page opens.

14.1.7.1 Editing the Name of a Review

In Review hub, it is possible to rename an existing review by the moderator. By opening the review, then clicking on Edit, the name of the review can be modified.

14.1.7.2 Adding Reviewers to an existing review

In Review hub, it is possible to edit the reviewers of an existing review by the moderator. By opening the review, then clicking on Edit, the list of the Reviewers can be modified.

14.1.7.3 Adding Moderators to the existing Review

In Review hub, it is possible to edit the moderators of an existing review by the moderator. By opening the review, then clicking on Edit, the list of the Moderators can be modified.

14.1.7.4 Changing the Deadline of an existing review

In Review hub, it is possible to edit the deadline of an existing review by the moderator. By opening the review, then clicking on Edit, the deadline can be modified.

14.1.7.5 Editing the Signature requirement of an existing review

In Review hub, it is possible to edit the signature requirement of an existing review by the moderator. By opening the review, then clicking on Edit, the list of the " Requires signature to finish the review" and the " Requires signature from reviewers" can be unchecked.

14.2 Finding Reviews

The Review hub contains all the reviews to which the current user has access, that is, all reviews where the user is included as a reviewer or moderator.

From the dropdown menu on the top of the Review hub page, you can select if you want Retina to display all reviews in the system or only the open reviews. You also have the option to group reviews by workspace or by workspace and tracker.

14.2.1 Set "Open Reviews" as default view

When opening the Review hub page in Retina, the default view of the page is the "Open Reviews".

14.2.2 All Reviews

By clicking on the "Open Reviews" dropdown menu on the top of the Review hub page, all reviews can be displayed by selecting the "All Reviews" option from the dropdown menu.

14.2.3 Grouping Reviews by workspace and tracker

By opening the Grouping dropdown menu on the top of the Review hub page, reviews can be grouped in three ways:

• No grouping
• Group by workspace
• Group by workspace and tracker

14.3 How to Restart Review

A moderator can restart a finished review. Depending on the options set when restarting the review, some items in the review can still be read only. The purpose of restarting the review is to incorporate any possible modifications (made after the original review was initiated) to the review. For this reason, the restarted review refers to the versions of the items at the time of the restart.

By clicking on restart icon on the top menu bar a Restart review dialog will be opened.

Here you can select multiple options to restarted review:

• only not reviewed
• only items that were updated or became suspected after starting the last review
  - consider all items with updated downstream references as updated
  - consider all items with updated upstream references as updated
• all items that need more work
• all items in the current review
  - set all items as 'Not reviewed'
• set as 'Needs more work' all items not reviewed in the current review

You can change Reviewers, Moderators and Viewers, the notifications as well.

You can add new items to the review or remove items one-by-one if needed.

14.3.1 Restarting review for not reviewed items only

On the Restart review dialog you can select Only not reviewed checkbox.

In this case the new review will contain only those items, which was not reviewed in the previous review.

14.3.2 Restarting review for items that were updated after starting the last review only

On the Restart review dialog you can select Only items that were updated or became suspected after starting the last review option.

In this case the new review will contain only those items, which were updated after starting the last review, or their reference became suspected since.

14.3.3 Restarting Review for all items that need more work

On the Restart review dialog you can select All items that need more work checkbox.

In this case the new review will contain all item, that were marked as Needs more work in the previous release.

14.3.4 Restarting Review for all Items

On the Restart review dialog you can select All items in the current review checkbox.

In this case the new review will contain all items from the previous review, with their current versions.

14.3.5 Restarting Review with more than one Options

The review can be restarted with multiple options, the conditions will be merged.

14.4 Review Items

To review (accept or reject) items in the Review Hub, follow the steps below:

1. Go to the Review Hub and open a review. Each user will see only those reviews in the Review Hub to which they have access, that is, the reviews in which the user is included either as a reviewer, viewer or as a moderator.
   If a user is included in a review (depending on the review settings), the system will send an email notification to the user about the review. The notification contains a link to the review. You can also open a review by clicking the review link in the notification.
   The selected review opens.
2. On the review page, accept or reject items using the check or x icons. In case you want to reject an item, it is mandatory to add a comment to the item. When you reject an item, a pop-up window opens where you can add your comment. Click on Save button to save your comment.
   You can also add a comment to any item by clicking the comment icon next to a review item. Note that comments will be added to an item within the review not to the original tracker item.
3. To accept or reject all review items at the same time, click the check or x icon in the top menu bar.

14.4.1 Review items are displayed as "Summary not readable" without read permission

If user has no permission to read review item, it will be indicated by a "[Summary not readable]" text.

14.4.2 Filtering Review Items

On the top-left corner of the page you can find a dropdown filter.

You can filter review items by:

• all items (default)
• items I have approved
• items need more work
• items I have reviewed
• items I have not reviewed
• items with my comments
• items with comments
• items updated since the review was created

14.4.3 Approval or Review Items

To approve a review item you need to click on the Approve icon next to the review item on the main panel. Item approval can be withdrawn any time before finishing review.

14.4.4 Rejection of Review Items.

To reject a review item you need to click on the x icon (This item needs more work) next to the review item on the main panel. In case you want to reject an item, it is mandatory to add a comment to the item. When you reject an item, a pop-up window opens where you can add your comment. Click on Save button to save your comment.

Item rejection can be withdrawn any time before fin ishing review .

14.4.5 Different types of comments on Review Items

Click on the comment icon next to the review item on main panel to display Comments panel on the right side of the page.

Here you can add any type of comment to the review item.

Select a feedback type:

• Comment (default)
• Question
• Problem
• Change

After typing feedback in editor click on Save icon and save your comment.

14.4.6 Version-related Review

When you create review item by head version, review item will contain the current version of regarding to the creation of review.

If you select a baseline during review creation the items' version will be correspond to the selected baseline.

14.4.7 Relations and References on Review Items

On main panel below the item description reference items are displayed.

You can open the accordion to see reference details.

14.4.8 Badges display if content has been changed after the start of the review

If has newer version than the version in review item, it will be indicated by a NEW VERSION AVAILABLE badge under the item summary on main panel.

If you click on the badge, the changes will be displayed on a dialog.

14.4.9 Review details on the right panel

Click on the Show right panel icon next to the review item summary on main panel.

It will open the right panel, where you can see all the details regarding to the version of the .

Properties are not editable, only visible.

Relations are listed on this right panel too, just click on the Relations tab on the top of the panel.

Click on the x icon on the top right corner to close this panel.

14.4.10 Approving all review items at the same time

If you click on the check icon on the top menu bar, all review items will be approved at the same time. Item approval can be withdrawn any time before finishing review.

14.4.11 Rejecting all review items at the same time

If you click on the x icon on the top menu bar, all review items will be rejected at the same time. Item rejection can be withdrawn any time before finishing review.

In case you want to reject all items in the review, a pop-up window will open where you can add your comment about rejecting the review items. In this case, your comment will apply to all review items as a general comment.

14.4.12 Entering the mandatory reject comment

If you reject an item, pop-up window opens to save your comment about this rejection.

This is mandatory, you cannot reject any item without comment.

14.5 Finishing a Review

To finish a review, follow the steps below:

1. Go to the Review Hub and open the review that you want to close
2. On the review page, click the Finish icon in the header of main panel. The Finish Review window opens
3. To set (or modify) the status of review items, click Set Statuses button. The Status Mapping window opens
4. If applicable, select a status for approved, rejected, or mixed/not reviewed items
5. Retina has provided a status mapping for all review items based on the review settings. If necessary, change the default mapping for any of the items as applicable
6. When you are finished setting the status for review items, click Finish Review to close the review. If necessary, you can click Back to go back to the Finish Review window. You can also close the review in this window by clicking Finish Review

14.5.1 Changing work item status upon finishing the review

On Finish review dialog click on Set statuses button. If applicable, select a status for approved, rejected, or mixed/not reviewed items.

The status options available in finishing review depend on the tracker configuration. If you select, for example, "Completed" for approved items, the status of all approved items in the review will automatically be changed into "Completed".

14.5.2 Valid state transitions can be forced after finishing a review

If you click the "Execute only valid transitions" checkbox, the status of a review item will only be changed if the tracker's workflow configuration allows for a transition from the items’ original status to the status specified in this step.

14.6 View Review

The review feedback page

You can access the Feedback page by clicking the Feedback icon above the main panel.

The Feedback page lists all the comments that have been added to the review items on the Review page and those that were added to the items before the review started (for example, if the same items are part of another review or if a finished review was restarted). On the Feedback page, you can add new comments to the review or reply to previous comments.

The following types of comments can be added to the review:

• Comment
• Question
• Problem
• Proposed change

Comments and their replies are listed in a hierarchical order with the latest comment appearing at the top.

The review statistics page

You can access the review Statistics page by clicking the Statistics icon above the main panel.

The top section of the Statistics page provides general information about the review (who started the review and when, the deadline, if the review is signed/finished already, and the baseline from which the review was created). The Overall reviewer statistics chart provides an overview of all the votes of all reviewers.

The Review result section shows the progress of each reviewer.

The Items section provides a summary of how many reviewers have approved, rejected or not yet reviewed each item.

The history page

You can access the History page by clicking the History icon above the main panel.

The History page provides a summary of the review's life cycle: when the review started, who were the reviewers/moderators, and when the review was closed.

14.6.1 Feedback page

You can access the Feedback page by clicking the Feedback icon above the main panel.

The Feedback page lists all the comments that have been added to the review items on the Review page and those that were added to the items before the review started (for example, if the same items are part of another review or if a finished review was restarted). On the Feedback page, you can add new comments to the review or reply to previous comments.

The following types of comments can be added to the review:

• Comment
• Question
• Problem
• Proposed change

Comments and their replies are listed in a hierarchical order with the latest comment appearing at the top.

14.6.1.1 Different types of comments can be added to the review

On the top of the review's feedback page you can find a split button named Add comment by default.

Click on the down arrow to display all the options. You can select:

• Add comment (default)
• Add question
• Add problem
• Add proposed change

Click on any of these options, and editor will be opened to write your feedback to the current review.

14.6.1.2 Filtering by comment type

On the top of the review's feedback page you can find a Filter dropdown.

You can filter displayed feedbacks by:

• All comments (default)
• My comments
• Question
• Proposed change
• Comment
• Problem

By selecting an option feedback table will be reloaded immediately.

14.6.1.3 Feedback page: displays comments of original items

If item has comments added before the review started, they will be displayed on feedback page as well.

14.6.1.4 Feedback page: displays comments added in previous reviews

If item has comments added in a previous review, they will be displayed on feedback page as well.

14.6.2 Displaying overall reviewer statistics as a pie chart on the Statistics page

The Overall reviewer statistics chart provides an overview of all the votes of all reviewers.

You can see the number of items which are

• approved
• needs more work
• not reviewed

14.6.3 Statistics page displays links and photos of the user who started-, finished-, or signed the review

On the top of the review's statistics page main review data is displayed.

The started, finished and signed rows contains the user's name, photo and a link to user's details page if user is given.

14.6.4 Statistics page displays progress bars per reviewer user

In Review result section progress is displayed by each and every user.

In the table you can see the reviewer user's name and photo, his/her signature date, and the progress on the review items per rows.

14.6.5 The Statistics Page

Review items are listed in Items section.

The columns are:

• Name: item's name, version, id and link directly to the item
• Needs more work: how many reviewers marked this item as needs more work
• Approved: how many reviewers marked this item as approved
• Not reviewed: how many reviewers need to review this item
• Comments: how many comments was written on this item

14.6.6 Understanding the "Review History" page

On this page you can see all changes regarding to the whole review.

Columns:

• Summary: review name and id with direct link
• Started: review start date and time
• Deadline: review deadline date and time
• Reviewers: all the reviewer users
• Moderators: all the moderator users
• Viewers: all the viewer users
• Finished: review finish date and time

14.6.7 Using comments stream for reviews

By sending an item for a review in Review hub, participants have the possibility to use the comments stream on the right side of the review page. Only review comments show up by default, but using the "Show work item comments" on the top, work item comments can be displayed as well.

In addition to the commenting, user can filter for different review comment types (eg.: comment, question, etc.) and accepted, rejected or open comments.

By using the comment review function, some important rules should be considered:

• accept and reject can only be applied for review comments, only by the owner of the comment
• accepted / rejected comments cannot be edited, replied, or re-accepted / re-rejected

When mentioning a workspace member in a comment who is not involved in the review in any role, Retina offers to invite the user to in a specific "Viewer" role. Moreover, the invited user(s) will get a notification with the content of the proper review's link. Users in Viewer role have the permission to comment or reply on the review, so it effectively helps to build up a transparent collaboration before approving or rejecting the whole review.

The review comments can be also visualized in the item's comment section by selecting the "Show review comments" option from the Filters.

14.7 Exporting a Review

To export a review, follow the steps below:

1. Go to the Review Hub and open the review that you want to export
2. On the review page, click the Export icon on the top of the main panel. The Exporting review window opens
3. In the Use template field, select the template that you want to use for exporting the review
4. If you want the exported file to be converted to PDF format, select the Export to PDF checkbox
5. If you want the review to be exported to an Excel file, click the MS Excel option
6. When you are finished specifying the export settings, click Export to start exporting the review content

Exporting the review will take a few seconds. When the procedure is finished, the exported file will automatically be available as a downloaded document.

14.7.1 Review items can be exported to excel

To export review items to MS Excel select MS Excel option in Exporting review dialog.

Another selectable options:

• Export comments
• Export to PDF
• Generate absolute links (to Retina)

14.7.2 Review items can be exported to Word

To export review items to MS Word select MS Word option in Exporting review dialog.

Another selectable options:

• Export comments
• Export to PDF
• Generate absolute links (to Retina)
• Use template

15 Basic Functionality

Retina operates with user accounts. A user must have an account before logging in and participating in a workspace. When creating an account the user's name, password and e-mail address are required and other optional data may also be entered. The e-mail address will be used by the notification service and will not be visible to other users in the notification, except if the particular other users have certain ('member view') privileges. The optional data that can be entered includes telephone number, mobile numbe r, organization name, time-zone and location. These personal data fields are visible to other registered users with the appropriate permissions .

15.1 Licensing

Retina offers three licensing options for the users: ALM, Reviewer and Viewer. With these license types, the user has different capabilities in the system. To set a selected license type for specified a user, the User Accounts page should be opened on the System Admin page. By clicking on the user's name, the system administrator can edit the License type. By default, when creating a new user in the system the ALM license will be selected automatically. It is possible to check the number of free and used licenses as well by selecting the "Licenses" tab on the System Admin page.

15.2 Authentication

Users are required to authenticate to be able to access Retina.

To create an account:

1. Click on the Register now button
2. Fill in the registration form
3. Click on the Registration button

You can access Retina with an activated user account from the Login page.

15.2.1 Login with valid credentials

To login, enter your username and password and click onLogin . To log in with a different username you need to log out first and then log in with the new username.

Upon a successful login, you are taken to the default dashboard site.

15.2.2 Login with invalid credentials

If either your username or your password is invalid, an "Invalid user credentials!" error message will be displayed.

If you have forgotten your password, click on the Forgot password? link to open Lost password page, and request a password reset with your user name or email address.

15.2.3 Login with LDAP/AD credential

If there is an LDAP/Active Directory server configured on Retina, then any user from the AD can login to Retina without registering.

15.3 Email notifications

Retina can generate notification Emails on accessing (read/write) artifacts such as work items, documents, wiki pages and also on workflow transition state changes.

15.3.1 Work item notifications

Email notification subscriptions to the whole tracker result in e-mail notification when any work item is submitted to or modified in the tracker. Select email notifications for the whole tracker on Notifications tab in Configuration menu.

In Any notifications section you can add or delete members by name or by role or nofify the participants.

In Status c hange notifications section the subscribed members will get notifications only if a status changed on any of the items.

In the last section, Notificatons by Tracker statuses you can subscribe only for items in selected status.

15.4 Full-text Search

Using full text search you can search tasks, bugs, Wiki pages, users, attachments and workspaces. The search is based on indexing, which takes place in the background and the new artifacts are searchable within seconds. Once indexing is complete, Retina's search automatically synchronizes with any changes you make. You can search and then place tags or labels on the relevant items you found, and share just about everything with your team.

Full-text search is provided for:

• documents - including Microsoft Word, Microsoft Excel, RTF, PDF, HTML, wiki and text document contents
• workspaces - the content of the name, description and category fields
• tracker items - including all fields, comments and attachments. For attachments the same file formats are supported as for document search
• report - the content of the name and description fields

15.4.1 Simple Search

A simple syntax is used for word based searches. The simple search field is found in the upper right corner of almost every Retina screen. By default Retina executes a prefix search. This means that when for example you search for org the result will contain work items containing org and also organization.

If you know the ID of the artifact you want to find you can use a shortcut. For example if the work item id is 2000 just type #2000 to the search box and hit enter. The only element in the result will be the work item with that id.

15.5 System Audit Trail

Retina Audit is a tool for System Administrators to analyze and finally export the following user interactions:

• User logins, logouts (including system logouts)
• Work Item or Artifact modification actions (create, update, delete)
• Permission changes (Trackers, Tracker fields, Roles, User Groups)

15.5.1 Logins

We can find login/logout time of users on the Logins tab.

15.5.1.1 Displaying Logins

Set filter values and click on GO button to display login/logout information.

Result is displayed in a table with three columns:

• User: link to the user's account
• Event type: user login / user logout/ user system logout
• Created at: time of the event

15.5.1.2 Logins Filtering

Logins can be filtered by:

• Users: select on or more users
• Event types: the three options can be combined as desired
  • user login
  • user logout
  • user system logout
• Range: date range can be defined by predefined constants or by custom dates

15.5.2 Artifacts

We can find create, update or delete actions for artifacts and work items.

15.5.2.1 Displaying Actions

Set filter values and click on GO button to display work item/artifact information.

Result is displayed in a table with seven columns:

• User: link to the user's account
• Artifact: link to the artifact
• Event type: type of the current action
• Workspace: name of the corresponding workspace, if it is possible
• Tracker: name of the corresponding tracker, if it is possible
• Message: contains a link to the diff viewer if it is available. Diff viewer can be available for work items
• Created at: time of the event

15.5.2.2 Filtering Actions

Actions can be filtered by:

• Users: select on or more users
• Event types: the ten options can be combined as desired
  • artifact create
  • artifact delete
  • artifact remove
  • artifact restore
  • artifact update
  • create
  • delete
  • remove
  • restore
  • update
• Workspaces: select one or more workspace
• Trackers: select one or more trackers of the selected workspaces
• Range: date range can be defined by predefined constants or by custom dates

15.5.3 Permissions

We can find create, update or delete permissions for trackers, tracker fields, roles or user groups .

15.5.3.1 Display Permissions

Set filter values and click on GO button to display permission information.

Result is displayed in a table with seven columns:

• User: link to the user's account
• Artifact: link to the artifact
• Event type: type of the current action
• Workspace: name of the corresponding workspace, if it is possible
• Tracker: name of the corresponding tracker, if it is possible
• Message: contains a link to the diff viewer if it is available. Diff viewer can be available for work items
• Created at: time of the event

15.5.3.2 Filtering Permissions

Permissions can be filtered by:

• Users: select on or more users
• Event types: the three options can be combined as desired
  • artifact permission create
  • artifact permission delete
  • artifact permission update
• Workspaces: select one or more workspace
• Trackers: select one or more trackers of the selected workspaces
• Range: date range can be defined by predefined constants or by custom dates

15.5.4 Audit Configuration

In audit configuration we can control which event we want to log.

Login event types:

• user login
• user logout
• user system logout

Work item event types:

• work item update
• work item create
• work item remove
• work item restore
• work item delete

Artifact event types:

• artifact update
• artifact create
• artifact remove
• artifact restore
• artifact delete.

Permission event types:

• artifact permission create
• artifact permission delete
• artifact permission update.