Configuring Resource Traceability

Resource Traceability gives Polarion users the power to link source code assets semantically. (Link Work Items directly to the source code function, method or variable that implements them.)

This gives managers and auditors a traceable record of all implemented changes and developers a link to who and what prompted a task, in case further clarification is required.

Developers simply add a custom comment to the source code they’re developing and it is automatically parsed to any Work Item (Requirement, Change Request, Improvement, Bug Fix etc.) that the code implements.

Administrators can configure how and when this information is parsed in multiple configurations, using multiple parsers, to satisfy all of their technical and time constraints.

Resource Traceability Configuration Checklist

Table 15.1. Checklist

 Before Using Resource Traceability

Add Resource Traceability properties. to the polarion.properties file for either a Single Server or Cluster Setup.

Configure Repositories.

(Supports SVN, GIT or Polarion's default repository.)

Add Linked Resources to Work Items.

Add <extension id="linkedResources" label="Linked Resources"/> to each Work Item type that Resource Traceability will be used with.

Configure resource-traceability.xml

Configure Where, When and How Resource Traceability parses data to Work Items.

Check logs for errors.

For Administrators: Check the new log4j-rt log regularly for parsing results and errors.

Learn the source code syntax.

For Developers: The source code syntax used to link where they implemented a source code change to the Work Item that requested it.

Important!

If planning to use Resource Traceability with large or multiple repositories, increase Polarion’s memory allocation.

Add Resource Traceability Properties

For a Resource Traceability server embedded inside Polarion - The Default configuration

The Resource Traceability server is set to start by default. Administrators that do not wish to use the Resource Traceability feature can disable it by adding the following property to the polarion.properties file.

com.siemens.polarion.rt.startRtServer=false
            

Customize the following Properties to use a different PostgreSQL instance for storing links.:

(By default com.polarion.platform.internalPG is used to fetch database properties.)

com.siemens.polarion.rt.db.jdbcUrl
com.siemens.polarion.rt.db.username
com.siemens.polarion.rt.db.password
            

Using Resource Traceability in a Cluster

Important!

To ensure that a cluster setup installs correctly, the property below was added to the shared polarion.properties file. This property should be removed before setting up a Resource Traceability server.

            com.siemens.polarion.rt.startRtServer=false
          
Standalone Resource Traceability Server

To configure a Cluster or Standalone Resource Traceability installation connected to a Polarion Cluster:

This configuration is recommended to ensure high-availability of the Resource Traceability server.

(If the RT node goes down, it can be quickly restarted without having to restart the Polarion application itself.)

Adjust Database:
  1. Shutdown Polarion and PostgreSQL.

  2. Go to the[POLARION_DATA]/postgres-data folder.

  3. For Windows or Linux installations, open postgreql.conf, comment out the following properties and uncomment the entry (for the same property) exactly below them:

    • max_connections

    • shared_buffers

    • work_mem

    • maintenance_work_mem

    • fsync

    • synchronous_commit

    • full_page_writes

    • wal_buffers

    • checkpoint_segments

    • effective_cache_size

    • max_locks_per_transaction

  4. Restart PostgreSQL

To create a database on a new location on a shared storage, please contact Polarion support.

Note

To connect a Resource Traceability Server to an external database, the following should be used:

com.siemens.polarion.rt.db.jdbcUrl=jdbc:postgresql://<databaseLocation>:5433/polarion
com.siemens.polarion.rt.db.username=<username> (e.g polarion)
com.siemens.polarion.rt.db.password=<password>
            
Adjust the Resource Traceability server's polarion.properties file

When connecting the Resource Traceability server to a Polarion Cluster.

  1. Mount the shared storage to the Resource Traceability node. (Required to share the polarion.properties file.)

  2. Make a copy of your polarion.properties file for Resource Traceability.

  3. After making the copy, replace the content with the content below and adjust the properties if needed:

    com.siemens.polarion.rt.polarionUrl=http://polarion-cluster
    com.polarion.application=polarion.rt
    #Shared folder between the machines that make up the cluster
    #default Linux: com.polarion.shared=/opt/polarion/shared
    #default Windows: com.polarion.shared=\\\\<shared_services_host>\\Polarion
    com.polarion.shared=/opt/polarion/shared
    TomcatService.ajp13-port=8889
    base.url=http://rt-hostname
    #Control port and host name for shutdown requests
    controlPort=8887
    controlHostname=rt-hostname
    com.polarion.platform.internalPG=polarion:polarion@localhost:5433
                                    

    Note

    The com.siemens.polarion.rt.polarion URL should point to the cluster address that goes through the load balancer.

Adjust the Virtual Memory Settings

  1. Adjust the Virtual Memory properties so that they fall into the -Xms500m -Xmx2g range.

    (These values will vary depending on the number of external repositories, their size and scheduling.)

    • For Windows: in the [POLARION_HOME]/polarion.ini

    • For Linux: in [POLARION_HOME]/etc/config.sh

  2. Restart Polarion

Adjust the Polarion Server

Adjust the Polarion server to work with the standalone Resource Traceability server.

When connecting a Polarion cluster to a Standalone Resource Traceability Server, add the following properties to each node:

com.siemens.polarion.rt.startRtServer=false
com.siemens.polarion.rt.url=http://rt-hostname

Note

com.siemens.polarion.rt.url should point to the base.url of the standalone Resource Traceability server.

(For both cluster and single installations.)

Https setup is done like any other Polarion instance. Certificates must also be imported into the truststores of both the Polarion and Resource Traceability servers.

Embedded Resource Traceability Server in Cluster Nodes

To ensure a high-availability setup, use the "Standalone Resource Traceability Server" setup above.

Important!

To ensure that a cluster setup installs correctly, the property below was added to the shared polarion.properties file. This property should be removed before setting up a Resource Traceability server.

			    com.siemens.polarion.rt.startRtServer=false
			  

To correctly configure a Resource Traceability cluster, setup " Reader" and " Writer" nodes.

  • Reader Node: Can only return links that are stored in the Resource Traceability database for a specified Work Item.

    (There is no limit to the number of Reader nodes located in the cluster.)

  • Writer Node: enables configuration updates, collects information from the repositories and stores data, (files, configurations and links), in the database.

    (Only a single Writer node is allowed in the cluster.)

Note

Writer node settings can be left as is, because a Polarion instance starts the Resource Traceability (RT) server by default as a Writer instance.

Configure Reader Nodes

Customize the following Properties to use a different PostgreSQL instance for storing links:

(A database on a different node acts like a separate PostgreSQL instance and the properties below should also be provided on the node or instance pointing to the database.)

e.g. com.siemens.polarion.rt.db.jdbcUrl=jdbc:postgresql://someurl (e.g. node2):5433/polarion where the URL points to a different server.

By default com.polarion.platform.internalPG is used to fetch database properties.

com.siemens.polarion.rt.db.jdbcUrl
com.siemens.polarion.rt.db.username
com.siemens.polarion.rt.db.password
            

All Reader nodes should be configured to send different "write"-requests to the Writer node.

They should also all be marked as Reader nodes by setting the following property to 'false'.

com.siemens.polarion.rt.dataCollectingEnabled=false
            

The following property should be linked to the Writer node's base URL.

com.siemens.polarion.rt.writerNodeUrl=
            

Define the same database properties in the following properties for every Reader node.

They should be linked to the Database that is used by the Writer node.

This enables the Polarion located on a Reader node to send a request to fetch Work Item links for its local RT Server instance along will all other requests (e.g. configuration changes) to the Writer node.

com.siemens.polarion.rt.db.jdbcUrl
com.siemens.polarion.rt.db.username
com.siemens.polarion.rt.db.password
            

Configure Repositories

Things to consider when configuring a Resource Traceability compatible repository:

  • Currently only a single branch per GIT <repositoryConfiguration> is supported. The local repository must be switched to the branch defined in the configuration.

  • To collect resources from different branches in GIT, create a clone of the repository in the desired branch and set it up as another repository in External Repository Configuration and the resource-traceability.xml file.

  • To use an External Repository, configure the repository before configuring the resource-traceability.xml file.

    ( Administration RepositoriesConfiguration ) See Configuring External Repositories for details.

Changes to a Repository

When considering change to an existing repository, it is essential to understand the potential impact on resource traceability.

  • If the root URL of the external repository is changed, no recollecting of resources is processed: no old records are removed, and no new ones are processed.

  • If the ID of the external repository is changed, then old records are removed and new ones are processed.

For example, if a user changes the URL of the repository without changing the actual repository (e.g. replaces http:// with https://, or the changed URL points to the same repository with same structure as old one, then there is no problem with not recollecting anything. However, if a user changes theURL of the repository and the new repository has different structure, then the administrator should change the ID of the current repository configuration and also change it in resource-traceability.xml in order for everything to be recollected.

Configure the Resource-Traceability.xml file

  1. Select the target Project.

  2. Click on on the top left of the navigation bar.

  3. Click on the Repository Topic Resource Traceability

    (The Resource Configuration screen appears.)

  4. Customize the XML in the provided field using the parameters below:

    Sample resource-traceability.xml

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <resource-traceability>
       <categories>
         <category id="first_category" name="Codebase">
            <repositories>
               <repositoryConfiguration id="default" repository="default">
                  <branches>
                     <branch id="Release 1.0" path="Demo Projects/elibrary/branches/1.0"/>
                     <branch id="Release 1.1" path="Demo Projects/elibrary/branches/1.1"/>
                  </branches>
                      <paths>
                         <path dir="java_folder"/>
                      </paths>
               </repositoryConfiguration>
            </repositories>
            <schedulers>
                <scheduler cron="0 */60 * * * *"/>
            </schedulers>
            <fileParsers>
                <fileParser extensions=".java" id="javaParser" name="com.siemens.polarion.rt.parsers.java">
                </fileParser>
            </fileParsers>
          </category>
       </categories>
    </resource-traceability>
                

    Use the sample xml file above as a structure guide and customize it using the tags below:

    Warning

    If a configuration is deleted, all the links associated with it will also be removed!

    Note

    See the <scheduler cron="0 0/60 * * * *" /> tag below for details on how to stop a parser from running a <RepositoryConfiguration> without deleting existing links

    <categories>

    The wrapper tag used for the <category id="first_category" name="Codebase"> tag.

    For Resource Traceability, a category lets administrators organize one or more <RepositoryConfiguration> tags by similar criteria (e.g. Codebase, Marketing Material etc.).

    The configuration file must contain one <categories> tag with one or multiple <category> tags defined for each project.

    The resource-tracability.xml file must contain at least one category but multiple <categories> can be defined for each project.

    <category id="first_category" name="Codebase">

    The <category> tag lets administrators create multiple configurations, based on different criteria, within the single resource-traceability.xml file.

    If parser and/or scheduler are set on the category level then it will apply to all repositories inside that category, unless explicitly set on the <RepositoryConfiguration> level.

    Multiple <repositories> can be configured on this level by creating a <RepositoryConfiguration> for each.

    Define a unique system id and common name.

    The system id is used by Polarion to identify the category and the name is what appears in the Linked Resources section of a configured Work Item.

    <repositories>

    The wrapper tag used for the <repositoryConfiguration> tag.

    This tag must be used inside a category. Here you can define one or more <repositoryConfiguration>.

    <repositoryConfiguration>

    Where Resource Traceability searches for, and processes data.

    One or more <repositoryConfiguration> tag can be defined per <category> tag. (At least one must be defined for each.)

    <repositoryConfiguration id="default" repository="default">

    Use this tag to define multiple configurations for a single repository by entering a unique name for each configuration in id= and use the id of the repository defined on the Repositories Administration page ( Administration Repositories) as the repository=value.

    <branches>

    The wrapper tag used for the <branch id="Version 0.9" path="Demo Projects/elibrary/branches/0.9"/> tag.

    <branch id="Version 0.9" path="Demo Projects/elibrary/branches/0.9"/>

    A duplication of resources for version variants or testing.

    The behaviour of this tag differs, depending on the Repository type. (Git or SVN)

    - For SVN, multiple branches can be defined or none at all.

    (If none is specified the default "Trunk" repository is used.)

    - GIT , requires that only a single branch be defined, and currently does not support multiple branches.

    (If no branch is specified for a GIT repository then the "Master" branch will be used by default.)

    Branch id= The branch id that appears in the Linked Resources section of a configured Work Item.

    path= The absolute location of the branch starting from the root of the repository. (Can include the Project and/or Project Group.)

    <paths>

    The wrapper tag for the <path dir="elibrary/trunk/src/main/java"/> tag.

    <path dir="elibrary/trunk/src/main/java"/>

    The file and folder locations processed by the parser.

    One or more <paths> can be defined per Repository.

    If branches are used, specify, if needed, the specific path location(s) inside the branches that should be processed by the parser.

    If not specified the whole branch directory will be processed.

    If branches are not used, set the absolute location of the path starting from the root of the repository, including the "Project" and/or "Project Group".

    <fileParser>

    The wrapper tag used for the <fileParser id="javaParser" name="com.siemens.polarion.rt.parsers.java" extensions=".java"> tag.

    <fileParser id="javaParser" name="com.siemens.polarion.rt.parsers.java"extensions=".java">

    The parser (Java, C etc.) used to extract the traced content and populate the links that appear in the Linked Resources section of a configured Work Item.

    One or more <fileParser> can be defined per <RepositoryConfiguration> or <category> tag..

    Define a unique parser system id, the parser's name, and the file Extension it should search for.

    Available Parsers:

    For Java - <fileParser id="javaParser" name="com.siemens.polarion.rt.parsers.java" extensions=".java">

    For C - <fileParser id="cParser" name="com.siemens.polarion.rt.parsers.c" extensions=".c">

    For XML - <fileParser id="xmlParser" name="com.siemens.polarion.rt.parsers.xml" extensions=".xml">

    <schedulers>

    The wrapper tag for the <scheduler cron="0 */60 * * * *"/> tag.

    One or more <schedulers> can be defined per <category> or <RepositoryConfiguration> tag.

    <scheduler cron="0 */60 * * * *" />

    When or if the associated parser is executed.

    TIP

    To keep existing links but stop the further processing of new links, remove the <scheduler cron="0 */60 * * * *"/> tag from the target <category> or <repositoryConfiguration>.

    Note

    Use Cron syntax to define the parsing schedule. See the Examples of cron Expressions section in help for details.

    (See Cron Trigger Tutorial to view an online tutorial.)

  5. Click Save once XML configuration is complete.

  6. The configured Repositories can be run at any time by clicking the Run Config... button on the Resource Traceability Administration page.

    (This is a great way to test a new configuration, or bypass the scheduled wait time.)

Check Logs Regularly

Administrators should regularly check the log4j-rt-(time stamp) logs in the Polarion\data\logs\main\ directory to stay on top of the following:

  • What collections occurred,

  • What repositories were collected,

  • What errors, if any, occurred.

Java and C Parser Behaviour

If the Java or C parsers encounter something that they cannot process, e.g. incorrect comment syntax, they will skip the offending code, log an error and continue parsing the rest of the file.

The Java Parser is optimized for Java 8.

The C Parser is optimized for the C11 Standard.

Java and C Parser Encoding

Use UTF-8 encoding for the Java and C Parsers.

XML Parser Behaviour

If the XML parser encounters something that it cannot process, then it will stop processing the rest of the file, and log an error.

XML Parser Encoding

The XML parser automatically detects encoding tags (e.g. <?xml version="1.0" encoding="ISO-8859-1"?> but if no heading exists it will use UTF-8.

(If it does and the encoding is not UTF-8 a parsing error will occur.)

Add "Linked Resources" to Work Items

  1. To add Resource Traceability's " Linked Resources section to selected Work Items.

    Go to ( Administration Work Items Form Configuration.)

  2. Scroll down to the Form Layouts section.

  3. Select a Work Item type to add the Resource Traceability feature to and click Edit .

  4. Insert the following line where the new "Linked Resources" section should appear in the Work Item.

    <extension id="linkedResources" label="Linked Resources"/>

    (label="Linked Resources" is the section title that appears in the Work Items.)

  5. Click Save.

  6. Repeat this for any Work Item type that you wish to have Resource Traceability configured for.

  7. Configured Work Items will now include a "Linked Resources" section.

    Note

    This Section always shows information from the "Head" (most recent) revision. (Even in Baseline and Historical Views.)

Enable "Linked Resources" READ Permissions

Make sure that the right users have permission to view "Linked Resources" in a Work Item.

Read rights can be assigned to individual user names By Permission, By Role or through Custom Sets

By Permission

  1. Select the target Project.

  2. Go to ( Administration User Management Permissions Management.)

  3. Click the By Permission tab.

  4. Expand the Work Items section and then the Fields section within it.

  5. Click on Permission to READ field “Linked Resources” and click Edit .

  6. Make sure that the applicable users have a Check mark in the box in the Granted column beside their username(s).

  7. Click Save .

By Role

  1. Select the target Project.

  2. Go to ( Administration User Management Permissions Management.)

  3. Click the By Role tab.

  4. Select a Role from the Role drop-down list, expand the Work Items section and then the Fields section within it.

  5. Make sure that there's a check mark beside Permission to READ field “Linked Resources” .

  6. Click Save .

Note

Permissions can also be granted via Work Item Custom Sets.

Link a Resource

Developers add a source code comment using the syntax below to customize what information is included with the linked resource.

Linked Resource Example

To add a linked resource like the example above (for Java or C parsers), add the following commented code where the change was implemented.

/**
* @wi.implements elibrary/EL-115:164 Returns author of this book
*/
public String getAuthor() {
return this.author;
}  
            

Multi-Line Message

There is no limit to the number of commented lines for a developer message.

Just start the message with a "{" and end it with "}".

/**
* {@wi.implements elibrary_alm/EL-122 messages can take up 
* several lines in the code. Just surround the whole parsing syntax 
* with {}  
* Anything commented after will not be included.
*/ 
            

Supported Elements

Developers can add the Resource Traceability feature to comments for the following elements:

For Java: (.java is the supported extension.)

  • method

  • constructor

  • field

  • class

  • interface

  • enum

  • static block

For C: (Supported extensions - .c, .h and additional custom extensions depending on how the parser and project preferences are configured.)

  • function

  • function prototype

  • global variable

  • struct

  • union

  • enum

Where to Place the Comment

Where the comment should be placed, varies depending on the parser used.

For Java and C

If using a Java or C parser, the Resource Traceability syntax links the element that directly follows it in the source code.

(public String getAuthor() in the example above.)

For XML

For XML, add the comment inside the target element as in the example below.

The second example will link to the Plugin instead of the groupId.

Search for Work Items with Linked Resources

Users can search for Work Items with or without Linked Resources.

Figure 15.1. Work Items WITH Linked Resources

Work Items WITH Linked Resources

Figure 15.2. Work Items WITHOUT Linked Resources

Work Items WITHOUT Linked Resources