administration guide - stages process management · pdf file1 terminology administration guide...

AdministrationGuide

Contact:

Method ParkWetterkreuz 19a91058 ErlangenGermany

Phone+49-9131-97206-550

Fax+49-9131-97206-200

[email protected]

Internetwww.methodpark.de

Version: 6.4

Date: 6.5.2015

Contents

1 Terminology..........................................................................................................52 Literature...............................................................................................................63 General information.............................................................................................84 Installation and customization of Stages..........................................................9

4.1 Installation of Stages................................................................................................................. 94.1.1 General installation information...........................................................................................94.1.2 File structure of the Stages components............................................................................94.1.3 Installation prerequisites......................................................................................................94.1.4 Installation procedure.......................................................................................................... 94.1.5 Licenses............................................................................................................................ 10

4.2 Customization of Stages..........................................................................................................104.2.1 General configuration of Stages....................................................................................... 104.2.2 Java garbage collection strategies....................................................................................114.2.3 Local message customization........................................................................................... 114.2.4 Local style customization.................................................................................................. 124.2.5 Local news application categories.................................................................................... 134.2.6 CMS configuration.............................................................................................................134.2.7 CMS prefetch configuration...............................................................................................154.2.8 Network configuration........................................................................................................174.2.9 Database configuration..................................................................................................... 184.2.10 E-mail notification............................................................................................................ 194.2.11 E-mail authentication.......................................................................................................194.2.12 E-mail feedback mechanism........................................................................................... 204.2.13 LDAP Synchronization.................................................................................................... 204.2.14 Project state.................................................................................................................... 204.2.15 Document lifecycles........................................................................................................ 214.2.16 Search in Stages.............................................................................................................224.2.17 People application........................................................................................................... 22

5 Administration of Workspaces.........................................................................235.1 The workspace structure of Stages.........................................................................................235.2 Creation of a New Workspace................................................................................................ 235.3 Modification and deletion of a workspace............................................................................... 25

6 Permissions, roles and user administration...................................................266.1 Creation of permissions...........................................................................................................26

6.1.1 The operation attribute......................................................................................................276.1.2 The workspace attribute....................................................................................................286.1.3 The domain attribute......................................................................................................... 286.1.4 The mode attribute............................................................................................................286.1.5 The transitive attribute...................................................................................................... 286.1.6 The precedence attribute.................................................................................................. 296.1.7 The level attribute............................................................................................................. 296.1.8 Security labels (optional)...................................................................................................30

6.2 Permissions for the project start..............................................................................................316.3 System roles and system users.............................................................................................. 34

6.3.1 System roles..................................................................................................................... 346.3.2 System users.....................................................................................................................34

6.4 User license types................................................................................................................... 356.5 User administration..................................................................................................................36

6.5.1 Creation of new users.......................................................................................................366.5.2 Modify user settings.......................................................................................................... 376.5.3 Assignment of roles to users............................................................................................ 376.5.4 Administrative user information.........................................................................................396.5.5 The Stages maintenance mode........................................................................................39

6.6 Examples................................................................................................................................. 41

6.6.1 Permissions of a quality manager.................................................................................... 416.6.2 Permissions of a project manager.................................................................................... 426.6.3 Permissions of a developer.............................................................................................. 426.6.4 Permission of the company employee..............................................................................436.6.5 Permission of an external role.......................................................................................... 436.6.6 Assignment of roles.......................................................................................................... 446.6.7 License types and assignment of roles............................................................................ 44

7 Running Stages..................................................................................................457.1 Direct links to stages process data......................................................................................... 457.2 Document access.................................................................................................................... 45

7.2.1 Export all configuration managed documents...................................................................457.2.2 Document access via WebDAV........................................................................................46

7.3 Importing data from external source....................................................................................... 467.4 Process export.........................................................................................................................46

7.4.1 General notes....................................................................................................................467.4.2 Exporting project tree into XML........................................................................................ 47

7.5 Stages Logging........................................................................................................................477.5.1 Stages runtime log............................................................................................................ 477.5.2 Stages audit log................................................................................................................ 477.5.3 Stages download log.........................................................................................................477.5.4 Stages e-mail log.............................................................................................................. 487.5.5 Stages license log.............................................................................................................48

7.6 Backup..................................................................................................................................... 488 Stages upgrade..................................................................................................49

8.1 Upgrade Installation.................................................................................................................498.2 Data preserved during upgrade...............................................................................................49

9 Contact information...........................................................................................50

1 Terminology Administration Guide

© 2015 Method Park Software AG

1 Terminology

Instructions, warnings and other important notes are marked in the Guide by the following symbols:

Notice: Shows an additional information

Warning: Indicates that a problem can happen

Important: Indicates an important aspect.

Danger: Indicates that in special cases data loss may happen.

Instructions

Used to show steps to perform

Example

Shows an example

Related links for each chapter are shown with this icon:

Related LinksTerminology on page 5

2 Literature Administration Guide


2 Literature

The following documents provide you with information on working with Stages:

User Documentation

Name Description

Editor Guide The Editor Guide describes the handling of theStages Web Editor.

Stages User Guide The User Guide describes typical work processeswhich quality managers, project managers anddevelopers carry out on a day-to-day basis usingStages.

Metric Guide The Metric Guide describes how Stages Metricreports can be created.

Script Reference Guide The Script Reference Guide describes how theStages scripting API (metrics) is working.

Process Versioning Guide The Guide Process Versioning describes howprocesses can be versioned (baselined).

Configuration/Administration

Name Description

Upgrade Guide The Upgrade Guide describes the required steps forupgrading to Stages V6.

System Requirements Describes the system requirements of the StagesSystem.

Metamodeling Guide The Metamodeling Guide will provide you withassistance in defining an appropriate metamodel.

Administration Guide The Administration Guide gives you guidance inthe administration of Stages. Starting with theinstallation and customization to your company’srequirements, chapter two helps you to prepareStages for the usage.

Issue Tracking Guide The Issue Tracking Guide provides informationabout the definition of your specific issue trackingconfiguration.

PDF Printing Guide The PDF Printing Guide describes how PDFdocuments can be created from different processelements.

People Application Guide The People Application Guide provides informationabout activating your People Application and how tohandle it.

Permissions Guide The Permissions Guide describes in detail all thedifferent permission settings.

Release Notes The Release Notes describes the majorenhancements and changes of the Stages version.

2 Literature Administration Guide


Name Description

Last Changes The Last Changes document is a change log withdetailed information about all changes made in thisversion.

System Integration

Name Description

Autologin Guide The Autologin Guide describes the Single Sign Onfeature of Stages.

ARIS Integration Guide The ARIS Integration Guide describes how ARISprocess models can be imported into Stages.

CMS Prefetch Guide The CMS Prefetch Guide describes the cachingconfiguration of the CMS status informations.

ClearCase Integration Guide The ClearCase Integration Guide describes theintegration with Rational ClearCase.

PTC Integrity Integration Guide The PTC Integrity Integration Guide describes theintegration with PTC Integrity.

SVN Integration Guide The SVN Integration Guide describes the integrationwith Subversion.

Sharepoint Integration Guide The Sharepoint Integration Guide describes theintegration with Microsoft Sharepoint.

Serena Dimensions Integration Guide The Serena Dimensions Integration Guide describesthe integration with Serena Dimensions.

LDAP Integration Guide The LDAP Integration Guide describes how LDAPinformations can be imported into Stages.

These documents are delivered with Stages. They can also be accessed by the Stages Info page.

3 General information Administration Guide


3 General information

This document gives you guidance in the administration of Stages. Stages Administrators will find all neededinformation to install and maintain Stages.

4 Installation and customization of Stages Administration Guide


4 Installation and customization of Stages

4.1 Installation of Stages

4.1.1 General installation informationYou can install Stages into every destination. The destination chosen by default is

• C:\methodpark\stages on Windows and• /opt/projectkit on Linux/UNIX systems.

Note: The installation path on Windows systems must not contain any space characters.

Note: The JDK used by Stages needs to be installed in the default installation path for that JDK.

4.1.2 File structure of the Stages componentsThe important components of the system are located in the

• tomcat\webapps\pkit or

• tomcat/webapps/pkit

folder and referred in the following as <PKITHOME>. The tomcat application server used by Stages is locatedin the tomcat subdirectory of the installation path, referred in the following as <TOMCATHOME>

For example, if you choose the standard path on Windows, then <PKITHOME> would be C:\methodpark\stages\tomcat\webapps\pkit, the default <PKITHOME> for Linux or UNIX is /opt/projectkit/tomcat/webapps/pkit. For the rest of the document, the pathnames are shown with slashes. Usebackslashes for the Windows names.

4.1.3 Installation prerequisitesInformations about the prerequisites and requirements can be found in the Upgrade Guide.

4.1.4 Installation procedure

4.1.4.1 Installation with a MySQL DatabaseIn order to install Stages together with a MySQL database, the following steps are necessary. For the usageof another database than MySQL, please contact the Stages support team.

Please contact the Methodpark Stages Support for a download link to the latest Stages release and therequired JAVA SDK Version. Retrieve the appropriate JAVA Version either from your IT Support or theOracle JAVA download pages. Install the JAVA SDK first and then start the Stages installation. A wizard willguide you through the different installation steps.

The installation file also installs a MySQL database system.

Stages is installed as a Windows system service that is automatically started at boot time. The service is alsostarted after a successful installation process, so no reboot is required after installing Stages.

Stages can be accessed via the URL http://<servername>:8080/ after a short startup delay. It is, ofcourse, also possible to use a different port or to use HTTPS as access protocol. The respective configurationis described in Network configuration on page 17.

Note: If you use an anti-virus-program on your database server, you have to make sure that thevirus scanner is not scanning the database directory as this might lead to database inconsistencies.This problem is a known MySQL error and Sun Microsystems is advising the described proceeding.



A scan-exclusion is also recommended for the whole Stages directory (recursively) as this willsignificantly improve the Stages performance.

4.1.4.2 Operating systemsSupported operating systems are Windows 2000/XP/Vista/Windows7. Recommended is a Windows Server2003 and a Windows Server 2008. Support for other operating systems, e.g. Linux, Solaris, is available onrequest.

For any further information about system requirements, please refer to Stages "System Requirements".

4.1.5 LicensesStages comes preconfigured with a temporary license that allows running Stages on any machine.

Running Stages with a permanent license requires the Stages server machine to have a fixed IP address. Torequest a permanent license for running Stages on a specific server, please follow these steps:

• Install Stages on the server• Log in as root (see System users on page 34)• Switch to the info page by selecting

• Activate "Show parameters for license request"• Send the parameters shown on this page to the Stages support by clicking on the e-mail address

A Stages license is delivered in an installer, two files will be installed:

• a license file: <PKITHOME>/WEB-INF/conf/PKitLicense.xml• a signature file: <PKITHOME>/WEB-INF/conf/PKitSignature.xml

Note: Both files must not be modified. Otherwise Stages will detect a signature mismatch andrefuse to start.

Important: Changing the hostname or the IP address of your Stages server or using a differentTCP/IP port usually invalidates your license. Please inform the Stages support about the changewhich will grant you an updated license.

4.2 Customization of Stages

4.2.1 General configuration of Stages

4.2.1.1 Configuration FileStages can be configured in the <StagesInstallDir>/tomcat/webapps/pkit/WEB-INF/conf/PKitConfig.xml configuration file. In its properties section some parameters can be configured byintroducing name-value pairs. For information about existing configuration parameters and their effect pleasecontact the Stages support.

The following code configures a value of "value.of.property" for the configuration property"name.of.property":

<properties> <property name="name.of.property" value="value.of.property"/></properties>



4.2.1.2 Configuration of Stages service parameterStages service can be configured in the tomcat service configuration GUI <StagesInstallDir>\tomcat\bin\tomcatw.exe. To start the tomcat GUI please run the following command in MS-DOS shell:

bin>tomcatw.exe //ES//projectkit

In the Java tab you can configure additional Java start parameter for Stages that are listed below:

• Xmx (Max memory pool): 1024 MB

• Xms (Initial memory pool): 512 MB

• Remote monitoring of Stages application via JConsole or SVisualVM

• Dcom.sun.management.jmxremote.port=8055

• Dcom.sun.management.jmxremote.authenticate=false

• Dcom.sun.management.jmxremote.ssl=false

• Set Option for not garbage collected Java heap size, the so called permanent generation:

• XX:MaxPermSize=256m

• XX:PermSize=256m

Note: More JavaVM options can be found directly on the Oracle home page http://java.sun.com/javase/technologies/hotspot/vmoptions.jsp. Other JavaVM configurations should be done only afterconsultation of the Stages support.

4.2.2 Java garbage collection strategiesThe JavaVM provides a variety of different garbage collection strategies (algorithms). These differentalgorithms can have a huge impact on the performance of Java applications. Our internal tests have shownthat for most customer scenarios the default garbage collector gives the best results. Therefore we adviceour customers to leave the garbage collector settings for Stages unchanged.

4.2.3 Local message customizationThe messages shown on the Stages Graphical User Interface (GUI) can be customized to the terminologyused within an organization. This also applies to the textual representations for the configured newsapplication categories.

Each message possesses a standard definition which can be overwritten by local definitions. These localmessages can be configured in the file <PKITHOME>/WEB-INF/classes/ LocalPKit.properties andits localized versions (e.g. <PKITHOME>/WEB-INF/classes/ LocalPKit_de.properties). At systemstartup, your messages will be automatically merged into the message pool of Stages.



The format of the message files conforms to the Java property files standard ("name = value"). Detailedinformation concerning the definition of messages can be found in the Stages Metamodeling Guidedocument.

Use the standard messages files <PKITHOME>/WEB-INF/classes/PKit.properties and<PKITHOME>/WEB-INF/classes/PKit_de.properties to lookup the keys of the respective messages.

Note: Do not change the <PKITHOME>/WEB-INF/classes/PKit.properties filesthemselves, because upgrades would overwrite the changes.

4.2.4 Local style customizationThe appearance of the Stages GUI can be customized via CSS (Cascading Style Sheet) statements. Addyour local style definitions therefore to the file <PKITHOME>/custom.css.

The style names used by Stages can be found in the file <PKITHOME>/standard.css. This file can beused as a template for the customization of the local Stages style.

Similar to the above structure, the CSS files <PKITHOME>/notifystyle.css and <PKITHOME>/notifystandard.css contain the CSS definitions for the e-mail notification service via HTML E-Mails (seeE-mail notification on page 19). Add your own definitions to the <PKITHOME>/notifystyle.css fileand use the <PKITHOME>/notifystandard.css as a template.

Note: Do not change the <PKITHOME>/standard.css and <PKITHOME>/notifystandard.css files themselves, because upgrades would overwrite the changes.

The icons and headlines shown in the Stages header can also be changed. This customization happens viamodification of the local property files

• <PKITHOME>/WEB-INF/classes/LocalPKit.properties and accordingly• <PKITHOME>/WEB-INF/classes/LocalPKit_de.properties

Both, the left and the right header side can be configured to show either an icon or a headline text. Toconfigure a headline to the left, use the following properties in a local property file:

• logo.left.mode = text

• logo.left.text.message = <Your Headline>

• logo.left.text.style = heading

To configure a logo to the right, use the following properties in a local property file:

• logo.right.mode = image

• logo.right.src = /local/img/<Your logo file>

• logo.right.width = <Logo image width in pixel>

• logo.right.height = <Logo image height in pixel>

• logo.right.altkey = logo.right.text.message

• logo.right.link = http://<Your HTTP link>/

• logo.right.text.message = <Your message to be shown as tip>

The logo image file (GIF, PNG or JPG format) should be stored in a <PKITHOME>/local/img folder.The folder needs to be created if it does not exist yet. All files within the <PKITHOME>/local folder will bepreserved across Stages updates.

4.2.4.1 Print style customizationThe style used for printing process elements can be customized in the file <PKITHOME>/printout.css.

Note: Do not change the <PKITHOME>/printbase.css, because upgrades would overwrite thechanges.



4.2.4.2 Individual service areaYou can personalize the service area in the left navigation frame. Edit <PKITHOME>/local/service.jspfor this purpose. There you can change the webmasters e-mail address and link to your homepage. Inaddition to that you are able to insert any further HTML-Code.

4.2.5 Local news application categoriesThe Stages news application categories can also be configured individually. That means, categoriescan be removed or new categories can be added. This is done in the Stages configuration file named<PKITHOME>/WEB-INF/conf/PKitConfig.xml. In contrast to the license and signature files, thisconfiguration file can be changed arbitrarily.

4.2.5.1 Individual categoriesPlease see the configuration file <PKITHOME>/WEB-INF/conf/PKitConfig.xml that comes with Stagesfor a very detailed description of the category configuration specification.

4.2.5.2 Type conversionsWhen the type of a category attribute is changed (e.g. from a text field to a date field), Stages must convertthe old data into the new type. The following table shows how types are automatically converted:

Table 1: Attribute type conversions

new type

original type

string text date selection

string X conversionwithout loss

conversion if stringcontains validdate, else DEL

DEL

text use the firstline of text

X conversion iftext contains

valid date in firstline, else DEL

DEL

date conversionwithout loss

conversionwithout loss

X DEL

selection DEL DEL DEL X

DEL: old attributes are deleted automatically

Attributes are only converted when the delete attribute of the categories element is set to true, e.g.<categories delete="true">. If the attribute is not true and categories were deleted from theconfiguration file, Stages prints warnings to the log file (see Stages Logging on page 47) and refuses tostart.

4.2.6 CMS configurationStages Process Workbench can interact with a configuration management system (CMS) to access storedfiles. Currently, following CMS are supported:

• Concurrent Versions System (CVS)• Subversion (SVN)• IBM Rational ClearCase• PTC Integrity• Microsoft Sharepoint• Stages internal CMS



4.2.6.1 CVSFor CVS integration, a CVS client package must also be installed on the Stages server system.

To integrate Stages with a CVS client, the location of the CVS command line client cvs.exe must beconfigured in the file <PKITHOME>/WEB-INF/conf/PKitConfig.xml with the following statements:

<cms>

<cms-type name="CVS">

<cms-property name="client" value="C:\Programme\GNU\WinCvs 2.0\cvs.exe"/>

...other properties should not be changed...

</cms-type>

</cms>

Stages comes preconfigured with these values. If your cvs.exe is installed at a different location, theproperty must be changed accordingly.

The CMS property sandboxLocation specifies a directory where Stages places its internal CVSsandboxes to access the CVS repositories. Please note, that the CVS sandbox directory must be located onthe same logical drive as the repositories when Stages runs on a Windows server system. This is due to alimitation of the external CVS command.

The individual CVS configuration (repository location, module name, branch tag) must be configured for eachproject via the Stages Processes Application. The CVS repository must already exist and be initialized (cvsinit command). The CVS module must also exist. If a branch tag is specified, the tag must exist in the givenmodule. If no tag is specified, the HEAD branch (main version) is used.

Please note that all locations must be valid and accessible on the Stages server. For example, if the Stagesserver runs on a Linux host, the repository path must be specified in UNIX style (e.g. /dir1/dir2/REPOSITORY).

4.2.6.2 SubversionPlease check the SVN Integration Guide for information about Subversion integration.

4.2.6.3 IBM Rational ClearCaseFor accessing ClearCase documents, the Stages server must be installed as a ClearCase client. Allinteractions are done via the cleartool command. Its location and the location of the view storage isconfigured in the Stages configuration file similar to the CVS configuration (see CVS on page 14).

The CMS property sandboxLocation specifies a directory where Stages stores static views of theClearCase VOBs that need to be accessed.

The individual ClearCase configuration (VOB tag, branch type) must be configured for each project viathe Stages Processes Application. The ClearCase VOB must already exist. If no specific branch type isconfigured via the GUI, the /main/LATEST branch type is used.

Please check the ClearCase Integration Guide for information about ClearCase integration.

Note: Do not move an existing Stages installation with a ClearCase connection to a new servermachine without contacting Stages support as this requires a special procedure.

4.2.6.4 Other configuration management systemsStages also supports the following configuration management systems:

• PTC Integrity (See PTC Integrity Integration Guide)• Microsoft Sharepoint (See Sharepoint Integration Guide)



For configuration of these systems, please contact Stages support.

4.2.6.5 Stages internal CMSFor the usage of the Stages internal CMS no extra configuration is required.

4.2.7 CMS prefetch configuration

4.2.7.1 IntroductionThe CMS prefetch is a Stages system service. It ensures that Stages displays up to date information ofdocuments that are managed by an external configuration management system (CMS). Therefore theCMS prefetch is scheduled periodically to retrieve the latest revision information for all documents of activeprojects.

Note: All changes of the configuration described in this document require a restart of the Stagesservice.

4.2.7.2 Configuration of the CMS prefetchThe default configuration of the CMS prefetch is found in <PKITHOME>/WEB-INF/conf/PKitConfig.xmlfile:

<pkit-config>

<properties> <property name="cms.prefetch.activated" value="true"/>

<property name="cms.cache.refreshIntervalInMinutes" value="60"/>

<property name="cms.prefetch.sleepMillisBetweenDocuments" value="0"/>

<property name="cms.prefetch.workersCount" value="1"/>

<property name="cms.prefetch.strategy.class" value="de.methodpark.pkit.cms.prefetch.ClassicAllDocumentsStrategy"/>

</properties>

<cms> ... </cms>

</pkit-config>

A more detailed description of these properties can be found in the following table:

Property Description

cms.prefetch.activated In case no configuration management system isconfigured the prefetch service can be completelydeactivated.

Default: true

cms.cache.refreshIntervalInMinutes A new prefetch run will be started after this period oftime. (In case of a too short interval it will be delayeduntil the previous run has finished)

Default: 60

cms.cache.lastAccessIntervalForActiveProjectsInDays

The prefetch will only update documents that arereferenced by projects that were used (browsed)within the specified time frame.

Default: 4



Property Description

cms.prefetch.sleepMillisBetweenDocuments In case the prefetch service produces too muchCPU load on the Stages server or on the CMS, itcan be forced to pause for some time. This will ofcourse lead to longer running prefetches.

Default: 0

cms.prefetch.workersCount In case the prefetch does not finish its work withinthe specified referesh interval, the amount of workerthreads utilized by the prefetch can be increased.This will lead to additional CPU load and load on theCMS.

Default: 1

cms.prefetch.strategy.class Specifies the strategy implementation to use toupdate the document revision information.

Default: de.methodpark.pkit.cms.prefetch.ClassicAllDocumentsStrategy

cms.prefetch.maxParallelTasks.<CMSType> Where <CMSType> is the name of one of theCMS types specified by the cms-type Tag in thecms Section of PKitConfig.xml. It will only beused by some of the available Strategies. E.g.PrefetchByCMSTypeStrategy. It can be used torestrict the amount of parallel tasks that work on thesame type of CMS.

Default: 1

cms.prefetch.initialStart.hourOfDay In case this property exists in PKitConfig.xml,scheduling of the initial prefetch run will be delayeduntil the configured hour of the day. Valid valuesare (0-23). E.g. for 22 the first prefetch run will bedelayed to 22:00. It has to be ensured that theStages service is up and running at this timepoint.If this property does not exist the prefetch will startdirectly after starting the Stages service.

Default: <not set; start immediatly>

4.2.7.2.1 StrategiesThe following prefetch strategies are currently available.

4.2.7.2.1.1 Classic all documents strategy

class=de.methodpark.pkit.cms.prefetch.ClassicAllDocumentsStrategy

This strategy ignores the maxParallelTasks properties. (cms.prefetch.maxParallelTasks.<CMSType>) It isthe default strategy. In case of a single worker thread the documents are prefetched sequentially. In case ofmultiple worker threads the prefetch of single documents is arbitrarily distributed among all workers.

4.2.7.2.1.2 Prefetch by CMS type strategy

class=de.methodpark.pkit.cms.prefetch.PrefetchByCMSTypeStrategy

This strategy allows more detailed configuration on the distribution of prefetches dependent on the type ofCMS the document is hosted.

cms.prefetch.maxParallelTasks.<CMSType> allows to specify the maximum number of workers that areallowed to process documents of that CMS type. This is useful in case different CMS types are used by

one Stages deployment and the CM systems have very different performance characteristics. So it is e.g.possible to specify that there is only one worker for SVN and all other workers should be used for Integrity.This example would need the following configuration:

<pkit-config>

<properties>

<property name="cms.prefetch.workersCount" value="8"/>

<property name="cms.prefetch.strategy.class" value="de.methodpark.pkit.cms.prefetch.PrefetchByCMSTypeStrategy"/>

<property name="cms.prefetch.maxParallelTasks.SVN" value="1"/>

 <property name="cms.prefetch.maxParallelTasks.Integrity" value="0"/>

</properties> <cms> ... </cms>

</pkit-config>

4.2.7.3 Cache PersistenceStages caches two different levels of information regarding files in external configuration managementsystems. It collects infomation about the folder structure of a CMS and the files contained within thesefolders. This information is then used for displaying document information such as the version or state of afile.

These caches are - by default - persisted in the file system on the application server that runs Stages.However the administrator may configure these caches to be stored within a relational Database. Thisincreases cache performance significantly.

The configuration of this is done in the Stages configuration file <PKITHOME>/WEB-INF/conf/PKitCaching-customer.xml

Each cache requires its own configuration and its own database. An example configuration for both MySQLand Oracle database servers can be found within the file.

Note: After changing the cache persistence settings, the Stages configuration has to be updated(<PKITHOME>/bin/updateConfig.bat) and Stages has to be restarted.

4.2.8 Network configurationStages is started on TCP/IP port 8080 and uses HTTP by default. Thus, it can be accessed via the URLhttp://<servername>:8080/. To use a different port or to use HTTPS as access protocol, change therespective lines in the Tomcat configuration file named <TOMCATHOME>/conf/server.xml.

Important: Changing the TCP/IP port or moving the Stages server to a new server machineusually invalidates your license. Please inform Stages support about the change which will grantyou an updated license.

To change the HTTP port, change the port number within the following statement:

<Connector port="8080" maxHttpHeaderSize="8192" maxThreads="100"minSpareThreads="5" maxSpareTHreads="75" enableLookups="true"redirectPort="8443" acceptCount="100" debug"0" connectionTimeout="60000"/>



For example, to use HTTPS on port 8443, comment out the statement above and enable the statementbelow:

<Connector port="8443" maxHttpHeaderSize="8192"maxThreads="150"minSpareThreads="25" maxSpareThreads="75" enableLookups="false"disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true"clientAuth="false" sslProtocol="TLS" SSLEnabled="true"keystoreFile="<path to keystore file>" keystorePass="<password>"/>

Additionally, a JSSE Java library must be installed (which is included in JDK 6.0) and a server certificatemust be created. A more detailed description for these tasks can also be found in the tomcat server.xmlconfiguration file.

4.2.9 Database configuration

4.2.9.1 MySQL database configurationStages uses per default a local MySQL database. To use a different configuration – either a differentdatabase type or a different database host – modify the configuration file <PKITHOME>/WEB-INF/conf/Database.properties. As this file contains the database password in cleartext, protect it fromunauthorized access with appropriate permissions.

The default configuration is connected to a MySQL database server running on the same server like theStages application. The database name is pkit. Stages connects to the database with the username/password pair specified in the configuration file. The database administrator account is called root and hasthe same password as the user in the configuration file.

It is sufficient to change the following four lines in the configuration file:

torque.database.default.driver=org.gjt.mm.mysql.Driver

torque.database.default.url=jdbc:mysql://localhost/pkit

torque.database.default.username=<DATABASEUSER>

torque.database.default.password=<PASSWORD>

Important: The rest of the configuration file should not be changed.

The MySQL configuration can be found in the configuration file C:\windows\my.ini or C:\winnt\my.ini, resp., if using a Linux OS at /opt/projectkit/mysql/data/my.cnf. Detailed informationabout MySQL configuration and tuning can be found under http://www.mysql.com/documentation/.

4.2.9.2 Oracle database configurationIn addition to MySQL, Stages is also able to interact with an Oracle database system. The configurationof an Oracle based Stages installation is similar to the setup described in section MySQL databaseconfiguration on page 18, but usually the Oracle database system resides on a different host.

To enable the connection to the Oracle database you need to modify the file <PKITHOME>/WEB-INF/conf/Database.properties and set the parameters DB_HOST, DB_PORT, SID,ORACLE_USERNAME and PASSWORD appropriately. The parameter DB_HOST identifies the name of theOracle server and DB_PORT the port number on which the Oracle server listens for incoming connections(port 1521 per default). The parameter SID is a unique name for your Oracle system. Please ask your Oracledatabase administrator to provide the necessary information.

torque.database.default.driver=oracle.jdbc.driver.OracleDriver

torque.database.default.url=jdbc:oracle:thin:@<DB_HOST>:<PORT>:<SID>

torque.database.default.username=<ORACLE_USERNAME>

http://www.mysql.com/documentation/

torque.database.default.password=<PASSWORD>

Note: Please notice that in contrast to a MSySQL based Stages installation the setup of thedatabase has to be performed manually, you can find more informations in the Upgrade Guide.

To be able to use Stages with an Oracle database it is necessary to send the "tablespace name"as well as Oracle "user name" to the Stages support to receive an appropriate dump of an emptyStages database.

4.2.10 E-mail notificationThe Stages e-mail notification service informs Stages users about new news application entries and theassignment of new roles. Also Stages can schedule certain tasks such as the creation of a process version,if a notification server has been configured. The task will then be queued and the user will be informed onceit is finished.

Before using this notification service, a few configuration parameters must be set in the <PKITHOME>/WEB-INF/conf/PKitConfig.xml configuration file.

The following section describes an example for such a configuration:

<notification>

 <serverurl>http://stages.example.com:8080</serverurl>

 <mailserver>mail.example.com</mailserver>



<replyto>[email protected]</replyto>



<sender>Stages Notification Service < [email protected]></sender>



<minimumInterval>120</minimumInterval>

</notification>

All configuration parameters (URLs, host names, e-mail addresses) need to be adjusted to your localenvironment.

The tag <replyto> can be filled with a comma separated list of e-mail addresses. Administrator notices,e.g. LDAP synchronization warnings, will be sent to the addresses specified within this tag.

4.2.11 E-mail authenticationIf the specified notification e-mail server requires user authentication, additional tags have to be inserted.The following example describes such an authentication configuration:

<!—- username that should be used for authentication -->

<mailuser>John Doe</mailuser>

<!—- password to authenticate mailuser -->

<mailpassword>pass</mailpassword >

<!—- name of the SASL realm -->



<saslrealm>SASL.METHODPARK.COM</saslrealm>

<!—- configuration parameters for notification follow here -->

Note: All authentication parameters are optional.

4.2.12 E-mail feedback mechanismStages contains a feature for user feedback via e-mail. The users can then write feedback mails by simplyusing the predefined mail addresses. The feedback can thereby be given for a configurable number ofcategories. These categories must be configured in the <PKITHOME>/WEB-INF/conf/PKitConfig.xmlconfiguration file.

The following example describes such a configuration:

<feedback address="[email protected]">

<categories> <category ident="process" address="[email protected]"/>

<category ident="misc"/>

</categories>

</feedback>

In this configuration, two categories "process" and "misc" are defined. The feedback for the "process"category will be sent to "[email protected]", all other feedback will be sent to the defaultaddress "[email protected]" defined directly at the "feedback" element.

For every category, a cleartext message must be configured that will be shown to the user on the GUI andthat will also be used as the e-mail subject. This messages are defined via properties (see Local messagecustomization on page 11) and must be named

feedback.category.CATEGORY-IDENT = CLEARTEXT MESSAGE

For example, to define a user message and e-mail subject for the "process" category,"feedback.category.process = Process" would be used.

Note: E-mail notification (see E-mail notification on page 19) has to be defined properly in orderto enable the feedback mechanism. The corresponding feedback link is shown in the service area.

4.2.13 LDAP SynchronizationThe Stages user database can be synchronized with various LDAP directory servers (e.g. OpenLDAP,Windows Active Directory). This allows password sharing among different systems. Detailed informationabout LDAP synchronization can be found in the Stages LDAP Guide, available from Stages support.

4.2.14 Project stateWith Stages you have the possibility to assign specific states to your projects. Of course, the assignmentand in particular the change of the project state should only be done by authorized users (the definition ofpermissions is described in Creation of permissions on page 26).

Before using the project state feature, the available states have to be defined. Therefore they have to beentered into the <PKITHOME>/WEB-INF/conf/PKitConfig.xml configuration file. The following exampledescribes such a configuration.

<quickview>

<projectstate name=""/>



<projectstate name="red"/>

<projectstate name="yellow"/>

<projectstate name="green"/>

</quickview>

To support an international view of the states, you have to add one line for every available project state in<PKITHOME>/WEB-INF/classes/LocalPKit*.properties (see Local message customization onpage 11). For your convenience, the preceding project states are already preconfigured in <PKITHOME>/WEB-INF/classes/PKit*.properties. You can use them as templates for new project states:

quickview.main.state. = Undefinedquickview.main.state.red = Redquickview.main.state.yellow = Yellowquickview.main.state.green = Green

After the assignment of a state, the project names are shown in a specific color in the project navigation tree.Therefore each project state is associated to one color. These colors can be configured in <PKITHOME>/custom.css (see Local style customization on page 12). Again the preceding states are alreadypreconfigured in <PKITHOME>/standard.css

.projectstate_{}

.projectstate_red{ background-color:#ff7070 }

.projectstate_yellow{ background-color:#ffff70 }

.projectstate_green{ background-color:#70ff70 }

.

4.2.15 Document lifecyclesStages supports the application of document lifecycles on document instances. These lifecycles areconfigured in the process metamodel (see Stages Metamodeling Guide). For each document lifecycle,certain document states are defined, which can be illustrated by a color / style. The following is a sectionfrom the process metamodel (See Metamodeling Guide). It specifies the usage of the color "green" for thedocument state "released":

<state ident="released" style="green">

If you want to use another color than the predefined colors red, orange, yellow and green, or you wantto overwrite the color value of one of these predefined colors you have to add an additional line to thestylesheet custom.css. Please use the following examples as templates for the definition of new documentstate colors:

Example 1 – Overriding the predefined document state color green:

.documentstate_green { background-color:# 00f100 }

Example 2 – Creating a new document state color:

.documentstate_blue: { background-color:# 012af6 }

Note:

PTC Integrity stores an attribute named "State" for every version in the system. Stages uses thisattribute to store the lifecycle-status for a document. Therefore every lifecycle-status defined inStages must be recognized by PTC Integrity as a valid value for the "State"-attribute.

In order to use PVCS with document lifecycles you have to use PVCS Version 8.0 or higher.Stages uses PVCS promotion groups for storing document status. Therefore you have to define apromotion group in the PVCS promotion model for every document-state.

-->

4.2.16 Search in StagesWith the search in Stages it is possible to find "words" or "elements" in all workspaces and applications.Some configuration parameters can be set in the <PKITHOME>/WEB-INF/conf/PKitConfig.xmlconfiguration file.

The following describes an example for such a configuration:

<search>

<index-optimize>0 0 23 ? * *</index-optimize>

 <max-result-size>100</max-result-size> 

<index-sync-interval>5</index-sync-interval>

</search>

You can define maximal number of search hits and interval for index synchronization to your localenvironment, if you want to change the first parameter, please contact your consultant for more details.

4.2.17 People applicationIf you want to use this feature a special license is required. This license is free and you will get it from theStages support together with an additional people application metamodel. You need to add this metamodelto your PKitProcess.xml file. Furthermore you need to add permissions to your roles to access thisfeature, please refer to the Permissions Guide .

5 Administration of Workspaces Administration Guide


5 Administration of Workspaces

5.1 The workspace structure of StagesThe Stages structure is a hierarchical structure similar to those of a file system. This structure is composedof nodes, the so called workspaces. Workspaces must thereby not be equated with development projects.They can also be process models or organizational elements like the company's divisions, etc. The nextfigure shows an exemplary hierarchical Stages structure which serves as an example in the followingchapters.

Figure 1: Stages structure

In our example there is a company "Company" at the top level of the hierarchy. On the next level there is anarea for the company executive board, one where development projects are stored and one where processmodels are stored. There already exist two different development projects ("Project A" and "Project B"), aswell as two process models ("V-Model" and "Agile Model").

5.2 Creation of a New WorkspaceNew workspaces can be created within the Workspaces application of Stages:

Instructions

1. First you have to determine where the new workspace should be inserted into the hierarchical structure.Therefore, navigate in the workspace navigation to the respective place. Select "Actions➜Newworkspace"



The following dialog box will be opened:

2. Enter a workspace name, a description (it will be displayed in the overview application), the processowner (this is the user, who will have permission to create or instantiate the process; default: user whocreates the workspace) and the workspace language (default:english). Furthermore you can define, ifthe workspace has a news application, a central downloads application and if it is part of a workspacegroup (a workspace group consists of the workspaces and its subworkspaces. When importing data,assignments of elements from other processes are only created within such a group). Moreover youcan determine if the workspace provides common elements and supports workspace variables (Thesevariables allow you the definition of the arbitrary name value pairs that can be referenced by syntax"%variableName%" in workspace and process descriptions, file paths and file names.

3. If you activate the news application, you can choose the categories which should be available:



Here you can choose between a list of categories, which are defined in the <PKITHOME>/WEB-INF/conf/PKitConfig.xml file, as describe in Local news application categories on page 13.

4. Select Save to confirm and you receive an empty workspace which does not contain any process. Howthe process can be created and filled with content is described in the Stages User Guide.

5.3 Modification and deletion of a workspaceThe modification and deletion of workspaces also takes part within the workspaces application in Stages.Similar to the creation of a new workspace.

Instructions

1. Navigate to the respective workspace in the workspace navigation. Select "Actions➜Edit workspace/Move workspace/Delete workspace"

2. Choose one of the following options:

• Modification of the workspace

A once created workspace can be changed or moved to another place in the workspace hierarchy.Modification means thereby the change of the workspace data described in Creation of a NewWorkspace on page 23 (workspace name, type, description, assigned news categories, etc.).

• Deletion of a project

Workspaces can be deleted. That means that the whole workspace content including the process, thenews entries, etc. are deleted.

6 Permissions, roles and user administration Administration Guide


6 Permissions, roles and user administration

Stages uses a role-based access control, where the permissions are linked to roles instead of users.

One role can thereby be assigned to several users and vice versa. Every role possesses one or morepermissions.

Note: The roles to which permissions are assigned are equivalent to the roles defined in theprocess.

Example

There is a role "Project manager" defined in the process. Specific permissions, like reading and writingpermission for the processes application, are created and linked to this role. Then, the role is assigned toone ore more users, like the project manager of "Project A" or the project manager of "Project B".

6.1 Creation of permissionsAs described before, permissions are linked to roles. That means, permissions can be assigned to each roleof the process.

Instructions

1. Choose a role in the Processes application and select "Actions➜Edit users/permissions"

2. In the opened dialog box you can see the assigned persons to this role



3. You have the following choices:

• Select "Actions➜Add new permission" to add a new permission• Or select "Change" or "Delete" next to the permission to modify permissions.

4. You can assign new users to this role or change existing assignments by selecting "Actions➜Edit userassignments"

5. For the creation of permissions, a set of eight attributes is available:

These attributes are explained as a tuple (P). This tuple is composed as follows: P(Op, Proj, Dom, Mode,Prec, Tran, Lev).

6.1.1 The operation attributeThe attribute Operations defines the types of operations, which a role is allowed to perform. There existfour operation types:

• Read• Modify• Create• Delete



6.1.2 The workspace attributeWith the second attribute Project a workspace in Stages is defined, to which a role receives certainpermissions.

Note: Permissions are always given for a specific node in the hierarchical tree.

Example

The role "Project manager" of "Project A" receives permissions for the node "Project A". Combined withthe first permission attribute "operations", the project manager of "Project A" can receive the right to read,modify, create and delete within the node "Project A". For this example, the tuple P looks as follows:P("RMCD", "Company X>Project A", Dom, Mode, Prec, Tran, Lev)

6.1.3 The domain attributePermissions can be defined more precisely than just for a specific node in the hierarchical tree. They alsocan be defined for a specific application (= domain) of Stages. The different permissions are described in apermission matrix.

6.1.4 The mode attributeThere are two different permission modes:

• permit• deny

This differentiation makes it possible to either permit or deny access to certain domains. Thereby thefollowing rules have to be considered:

1. Denial > Permission2. Everything, which is not explicitly permitted,is denied

Rule 1 means that if to a user two roles are assigned, one which permits the access to a specific domain andone which denies the access to that specific domain, the user has no access to that domain.

Rule 2 means that if a specific role has the permission to a specific domain of a node X, the role hasno access to all other domains of that node as well as to all other nodes in the Stages tree and thecorresponding domains.

6.1.5 The transitive attributeWith the permission attribute Transitive a permission can be set, which is not only valid for a certainmode, but for all other subsequent nodes.

Example

There is a role "Employee" who has reading access to the news application of Company X as well asto the news application of all subsequent nodes, except the "Executive board" news application and allpossible subsequent nodes. The permission of the "Employee" can look as follows:

P ("R", "Company X", "News", "permit", Prec, "Tran=Yes", Lev)

P ("RMCD", "Company X > Executive board", "News", "deny", Prec, "Tran=Yes",Lev)



6.1.6 The precedence attributeWith the attribute Precedence, the precedence of permissions can be set. That makes it possible to definea more specific priority between permissions:

• high permission• low permission• high denial• low denial

The priority is thereby as following:

high deny > high permit > low deny > low permit

Example

The role "Employee" which has no access to the news application of the "Executive board". Additionallythere is a role "Executive board". A person from the executive board is at the same time an employee ofthe Company X, but in contrast to a usual employee, the executive board member has to have access tothe node "Executive board".

The permission of the role "Executive board" can look as follows:

P ("RMCD", "Company X > Executive Board", "News", "permit", Prec, "Tran=Yes",Lev)

With the permissions defined above, the executive board member has still no access to the "ExecutiveBoard" news application, because the denial of the role "Employee" is higher than the permission of therole "Executive board".

With usage of the Precedence attribute, this problem can be solved as follows:

• Role "Employee"

P ("R", "Company X", "News", "permit", "low", "Tran=Yes", Lev)

P ("RMCD", "Company X > Executive board", "News", "deny", "low","Tran=Yes", Lev)

• Role "Executive board"

P ("RMCD", "Company X > Executive Board", "News", "permit", "high","Tran=Yes", Lev)

With usage of the Precedence attribute, the "Executive board"'s permission is higher than the"Employee" role's deny, with the result that a member of the executive board can now read and createentries to the news application of the node "Executive board".

6.1.7 The level attributeThe configuration of permission levels allows a very specific access on parts of the Processes application.The attribute level only affects the domains "Processes" and "Files". Thus, it also has consequences ondocuments in the configuration management system. In all other domains, the value of the level attribute isirrelevant1.

Note: Permission levels correspond with the security levels of process elements.

1 Notice the following: when using permission mode deny und choosing a permission level differentfrom open on a Stages domain which does not include a security level (i.e. all domains except for"processes" and "Files") the specified operation type will have no effect on the users assigned tothe respective role. This is because the security level open is assigned implicitly for those objects.Therefore, when using permission mode deny in such context you must always choose permission levelopen.



The security level X of a process element means, that a user has at the very least permission level X, inorder to have access to that certain process element. The permission level Y allows the corresponding useraccess on process elements with the security level Y or less.

The permission levels apply thereby top down, whereas security levels apply bottom up. Following examplevisualizes the above rules.

Example

The security level of the document "Risk Analysis" is set on confidential (security level 4). To be able toaccess this document, a role has to have at least the permission level 4 or 5 in order to be able to accessthis document. All other workspace members, who receive the permission level 3 or less, are not able toaccess the document "Risk Analysis".

Table 2: Permission and security level

Permission level Security level

5 5

4 4

3 3

2 2

1 1

P ("RMCD", "Company X > Projects > Project A","Processes", "permit", "high","Tran=Yes", "Lev=4")

As shown in the table above, permission levels are valid top down, whereas security levels are validbottom up. That means, if a process element has the security level X, only those roles with the permissionlevel X or more can access this process element. All roles with the permission level X-1 or less do nothave access.

6.1.8 Security labels (optional)With security labels you have the possibility to define more specific access policies in the Processesapplication. The permission domain "processes" grants access to all process elements (in the defined



workspace and with corresponding security level), a more restrictive policy can be desired. Security labelshave to be defined in the PKitConfig.xml configuration file in an own section:

<pkit-config>

…

<securitylabels> <securitylabel name="Label A"/>

<securitylabel name="Label B"/>

</securitylabels>

…

</pkit-config>

Afterwards, the defined security labels can be assigned to any process element. If a security label is set foran element, only roles which have the same security label permission can access this element.

Note: Option "ANY" grants access to all security labels. This is especially useful when new securitylabels have been defined. A role with this option set will not be affected by any new security label asaccess has become independent of security labels for this role.

6.2 Permissions for the project startThe project manager has to have the permission to instantiate the process model, defined by the qualitymanagement, in his project. Therefore, the project manager needs the corresponding permission. But thispermission can only be given by assigning the project manager, for example M. Miller, to the role "ProjectManager". And this assignment only takes part after instantiating of the process in the corresponding project.

Note: When instantiating a process model M in a project P, the permissions defined in the processmodel are automatically adapted to the project. That means, for all permissions defined in theprocess model where the project attribute is M, the project attribute is set to P.

How can the project manager M. Miller instantiate the process model in his "Project B" before being assignedto the "Project Manager" role? This problem can be solved by defining a process owner.

Note: The process owner is the user/person who has the permission to instantiate a processmodel.



When the project-workspace is created within the workspace administration, the process owner has to bedetermined. Usually this is either the project manager or the quality manager.

After creation of the initial process, the process owner assignment is removed from the workspace and theuser looses its special process setup permission.

Important: From the point in time when the user got the process owner assignment until the initialprocess is created the process owner has the permission to import arbitrary process descriptionsincluding permissions and role assignments. This means he has root like privileges for thistimespan.

As this permission is removed automatically this would mean that after the instantiation in the "Project B",the project manager M. Miller no longer has the permission to access or change information according to hisproject. It would also mean that he can not assign him as a user to the role "Project Manager" of "Project B".

In order to avoid this circumstance, an instantiating role can be defined in the process model, the so calledbootstrap role.



Note: The bootstrap role is the role which is automatically assigned to the person who instantiatesthe process model (=process owner).

This way, after the instantiation in the "Project B", M.Miller is then assigned to the bootstrap role, so that hehas all permissions defined for the bootstrap role "Project Manager".

Not only one role of the process model can be declared as the bootstrap role.

Note: In case two or more roles are defined as bootstrap roles, the instantiating person is assignedto all bootstrap roles.

If no bootstrap role is declared in the process model, an additional role is created after the instantiation.This role is called "Process Owner" and is assigned to the person who instantiated the process. The wholeprocess described above is visualized in following:



6.3 System roles and system users

6.3.1 System rolesThe Stages start-up database contains one standard role: the "default" role. The "default" role is implicitlyassigned to all users. Its permissions control the access to system information. This role also obtainspermissions like reading access to all workspaces:

Important: The "default" role can not be deleted.

6.3.2 System usersStages generates a start-up database that contains two standard accounts (root and default). Both accountshave the password "pass". The passwords for both users should be changed immediately after installation.The new passwords for both accounts should only be known by the system administrators.

The Stages demo version comes with three additional demonstration users: demoqm, demopm, demodev.The password for these accounts is "demo".

6.3.2.1 RootThe root user has superuser privileges. All access controls are disabled when working as root. This is similarto superusers known from UNIX like systems. Use the root account to manage the system and initially set upusers, roles and permissions. The privileges to manage users, roles and permissions can also be delegatedto normal users.

Important: The root account can not be deleted.

6.3.2.2 DefaultThe default user serves two purposes:

• First, it defines the default settings of all users. Every user uses the settings of the default user until he orshe changes his own settings.



Guidelines for the change of settings can be found in the Stages User Guide.

• Second, every new user is automatically assigned to the roles of the default user at creation time. If themajority of your users should be assigned to specific roles, for example to the "Employee" role, assign theroles first to the default user before creating the new users.

6.4 User license typesStages offers three license types:

• Quality Manager (QM) license• Project Manager (PM) license• Developer (Dev) license

Additionally an anonymous access (Anon) to Stages is possible which is independent from the license typeassigned to a user. The license types differ in the permissions that can be granted to them. The followingtable shows which permissions can be granted to each of these types as well as to the anonymous user:

Permission Domain QM PM Dev Anon

Comments X X X

CMS profiles X X X

Compliance X R

Data collectors X X

External source X X X

Files X X X

News X X X

Info page* R R R R

Issues X X X R

Permissions X X R

Process release X

Process tailoring X X R

Process version X R R

Processes X R R R



Permission Domain QM PM Dev Anon

Workspace navigation* R R R R

Project state X X R

Workspaces X X R R

Reports X X R

Role assignment X X R

Users X R R

Wiki (-articles, -cartegories) X X X R

People application (-employee, -departments)

X X X R

Legend:

R=read access, X= full access

* In these permission domains only operation "read" has impact.

QM licenses are floating licenses. That means, there is a license pool from which the user gets his license.When all licenses from the pool are occupied, the user cannot log-in. In contrast to QM licenses, PM andDev licenses are personal licenses. With a personal license the user can log into the Stages system at anytime.

Anonymous access is neither limited to a maximum number of users nor is explicitly assigned to a user.Every user can access Stages as an anonymous user. However, as shown above the anonymous accesscomes with a small number of possible permissions.

The Stages user database can be synchronized with various LDAP directory servers. All specified userentries are then copied into the Stages database. The license type that a newly created user should obtaincan be configured. Have a look at the Stages LDAP Guide to learn more about LDAP synchronization andthe way how to set the license type for newly created users.

6.5 User administration

6.5.1 Creation of new users

Instructions

1. New Users can be created in the Users application, from every node of the Stages structure

2. Select "Actions➜Create user" for the "Project B"

"Create user" is only visible if at least one QM license type is contained in your Stages license or - in caseof personal licenses (PM, Dev) - not all licenses are already in use.

3. Enter the user data in the following dialog box:



Click on "Save" to create a new user.

6.5.2 Modify user settingsA new user must be created, the root user or an administrative role can modify the settings for this user.

Instructions

1. Select the respective user. In the actions menu select "Actions➜Change settings"

2. You can change the settings of this user in the next window:

6.5.3 Assignment of roles to users

Instructions

1. Select the respective role, for example "Project Manager" and choose "Actions➜Edit users/permissions"



2. In the next dialog box you can see the existing permissions and the already assigned users:

3. Select "Actions➜Edit user assignments"

4. In the following dialog box, you can search for users by a built-in function, or select one of the shownusers to assign him to the role "Project Manager"



5. Mark the user and finish the assignment by clicking on "Save".

Same applies when assigning users as stand-in for the given role. Stand-in users have the sameprivileges as normally assigned users, but when their name is shown in a user list, the entry is markedwith (Stand-in).

6.5.4 Administrative user informationThe Stages administrator has access to administrative user information on the Stages info page. That meanshe has the possibility to see how many users are currently logged into the system.

Furthermore, the active users themselves can be listed by clicking on "Show list". All the information abovecan be found on the info page of Stages, you can access the info page by clicking on

6.5.5 The Stages maintenance modeThe superuser "root" is authorized to start the Stages maintenance mode. The link "Start maintenance" canbe found on the "Info" page.

Instructions

1. Select the Stages info page:

2. Select "Start maintenance"



3. After activating the maintenance mode users cannot log into Stages anymore. Logged-in users at thattime receive a notification e-mail. The text of this e-mail can be entered on the maintenance page:

This text is also displayed in red letters on the Stages login page and the Stages "Info" page.

Example

A typical use case of the maintenance mode is the notification about an upcoming Stages restart (forexample because of a Stages upgrade or changes in the metamodel or PKitConfig.xml). By announcingthe time of restart the logged in users can complete and save their workings. The maintenance mode hasto be deactivated by the link "Stop maintenance" on the Info page.



The users can then log in again.

6.6 ExamplesIn this chapter the permission mechanism should be visualized by means of examples. Therefore five typicalroles and their permissions are described:

• Quality manager• Project manager• Developer• Company employee• External role

6.6.1 Permissions of a quality manager

This example role of a quality manager has the permission to

• read, modify, create and delete all CMS profiles of the company• read, modify, create and delete all Compliances of the company• read all files of the company• read all issues of the company• read all Processes applications of the company• read, modify, create and delete all process releases of the company• read, modify, create and delete all process versions of the company• read all project states of the company• read, modify, create and delete all role assignments of the company• modify application of process within the process models node• read, modify, create and delete the processes application within the process models node• read, modify, create and delete the processes application within the reference models node



6.6.2 Permissions of a project manager

The project manager of the "Project A" has the following permissions:

• read and modify the application of process of his project and of all subprojects no matter to which securitylevel the specific elements are set

• read, modify, create and delete the cms profiles of his project and all subprojects• read the compliance of his project and all subprojects• read, modify, create and delete files of his project and all subprojects no matter to which security level the

specific files are set• read, modify, create and delete issues of his project and all subprojects no matter to which security level

the specific issue is set• read and create entries in the news application of his project and all subprojects• Read process elements in the processes application of his project and of all subprojects, no matter to

which security level the specific elements are set• read and modify process releases of his project and all subprojects, if they have the security level "open"• read, modify and create process versions of his project and all subprojects, if the have the security level

"open"• read and modify the project state of his project and all subprojects• read reports of his project and all subprojects• read, modify, create and delete role assignments of his project and all subprojects

6.6.3 Permissions of a developer

The developer in our example has the following permissions:

• read, modify, create and delete cms profiles of the project• read the compliance mappings of the project• read, modify, create and delete files of the project• read the process within the project

The permissions for the domains "Files" and "Processes" are set to the level internal (= level 3). This makesit possible to diversify between the permissions of external and internal roles. For example, if there is anexternal project member who must not have access to a document D, the solution can look as follows:

• the document D receives the security level internal (= level 3)• the external project member receives the permission level project (= level 2) and has therefore no access

to the document D• whereas the internal project member receives the permission level internal

Note: Access to the domain "Workspace" is normally not needed, because the role "default" hasthis permission in delivery state. To each new user the role "default" is assigned automatically.



6.6.4 Permission of the company employee

In every company, a role "Employee" can be created, to which general permissions can be added. Thosecould be:

• read and create entries in all news applications of the company• but at the same time deny the access to certain areas, which are for example designated for the

management.

As all company internal users are assigned to the role "Employee" it has to be possible to deny the access tospecific News (at least the writing access). For that purpose, the precedence is low and it can be suspendedby a high denial, as described in The precedence attribute on page 29.

In the example above, there is furthermore a "Project C", to which the normal company employee has noaccess. In this case, he is not even allowed to see that there is a node "Project C", and therefore he receivesa denial to the "Workspace" domain of the node "Project C". The precedence here is low, because accordingto the rule described in The precedence attribute on page 29 it has to be possible for another person, whois a member of the project C, but at the same time also a company employee, to have access to this area.

6.6.5 Permission of an external role

In some cases, external roles are involved in projects. The example above shows a possible configuration ofthe permissions of a customer that:

• is not allowed to see, which other projects the Company has, but only the project ("Project A") in which heis involved

• therefore a low denial for the domain "Workspaces" is set, which has as a consequence, that thecustomer can not see any node within the "Company"

• a high reading permission for the "Project A" is needed, in order to provide the customer the sight onthe workspace in which he is involved; this permission only enables the customer to see, that there isa node called "Project A"

• additionally, in order to see the "Project A", the reading permission on the workspace domain of allnodes on the way to "Project A" is also required; these nodes are "Company" and "DevelopmentProjects"

• is allowed to read the News of "Project A" and create entries, as a basis for communication



6.6.6 Assignment of rolesAll roles are described within the nodes of the Stages structure, without having any dependency betweeneach other. When a user is created, he has to be assigned to one or more roles. Following picture shows thepossible assignments of a developer, T. Anderson, who is at the same time both employee of the Companyand developer in "Project B".

Implicitly, as defined in System roles on page 34 he is also assigned to the "default" role.

6.6.7 License types and assignment of rolesAs described in User license types on page 35, every user is associated with a certain license type. Thelicense types differ in the set of permissions that can be granted to them. If a user is assigned to a role withpermissions the user is not allowed to receive due to his associated license type, a warning will be shown:

If the user is not allowed to receive permissions for a certain domain at all, the corresponding permissionswill be ignored. If the user is allowed to only receive read access for a certain domain, the permissions forthat domain will be reduced to read access. All other permissions (create, modify, delete) will be ignored.

The user in the example above is associated with the license type "Project Manager". As shown in Userlicense types on page 35 no permission for the domain "Process Release" can be granted to that licensetype at all. In consequence, all permissions for that domain granted to a role the user is assigned to will beignored. On the other hand read access for domain "Process Version" can be granted to the license type"Project Manager". In that case, assigned permissions for that domain are reduced to read access.

7 Running Stages Administration Guide


7 Running Stages

7.1 Direct links to stages process dataStages contains an interface which allows direct references to Stages process data by HTML links fromoutside. To create a direct link to a specific process element, use the following URL syntax:

http://<STAGESSERVER>:<PORT>/pkit/go/process/element.do?elementName=<ELEMENTNAME>&elementType=<ELEMENTTYPE>&projectName=<PROJECTNAME>

Please use the appropriate values for <ELEMENTNAME> and <ELEMENTTYPE> that uniquely address thedesired process element. Examples for valid element types are: phase, artifact, role, activity, subprocess,method, tool, resource, standard, metric, and training. More information can be found in the MetamodelingGuide.

To directly link to an element index page, specify "INDEX" as the element name. To directly link to the mainpage of the process, use the special element name "MAIN". In case of the main page, no element typeneeds to be specified.

Space characters in element or project names can be expressed with the "+" character (e.g."projectName=Project+A"). Ambiguous element or project names can be made unique by specifying thecomplete path to the element separated by "|" characters (e.g. projectName=Company|Projects|Project+A).

An example for the direct link to the document/artifact "Requirements Specification" in workspace "ProjectA":

http://pkit.example.com/pkit/go/process/element.do?elementName=Requirements+Specification&elementType=artifact&projectName=ProjectA

Stages will display a login dialogue if the user is not already authenticated at the system and will switchdirectly to the referenced process element afterwards. If the user is already authenticated, the page willdirectly show the corresponding process element.

To directly reference a specific document i.e. a file (managed within a CMS) use a special <ELEMENTTYPE>named artifactInstance and specify the logical name of the artifact instance as <ELEMENTNAME>. Clicking onthis link will directly start the download of the instance's binary contents. To refer to a specific revision of adocument instance, add the revision identifier with an additional revision attribute. The syntax of the revisionidentifier is CMS-specific.

An example for the direct link to revision 3 of the document/artifact instance "Design-Modul1" in workspace"Project A":

http://pkit.example.com/pkit/go/process/element.do?elementName=Design-Modul1&elementType=artifactInstance&projectName=ProjectA&revision=3

All these external links can also be automatically generated by Stages. Using the link in the respectiveprocess element pages and a popup window will be opend that provides a correctly specified HTML link tothat process element or artifact instance.

7.2 Document access

7.2.1 Export all configuration managed documentsOn the CMS Profiles page you can export the latest revision of all configuration managed project documentsinto one zip-file by clicking on "Export all CM documents" (Fehler! Verweisquelle konnte nicht gefundenwerden.6). You need special permissions to do so (see Table 2 – Domains – CMS Profiles).



7.2.2 Document access via WebDAVStages enables the user to edit documents directly via WebDAV. This only works with the following types ofdocuments:

• MS Word 2000 and higher• MS Excel 2000 and higher• MS PowerPoint 2000 and higher• MS Project 2000 and higher

Document access with WebDAV works with Internet Explorer 5.5 and higher. Further the Stages server mustbe added to the trusted sites in the security configuration of Internet Explorer.

7.3 Importing data from external sourceEvery Stages News category can be configured to be external (see Local news application categories onpage 13). This means, that data from externals sources (e.g. configuration management systems, documentmanagement systems) can be imported into this category via a XML input interface. This requires threesteps:

Instructions

1. Configure an external source with type "XML Import" for this category. This can be done via the StagesGUI. Choose a unique identification (e.g., "<project name> CVS Import") for that source.

2. Create an XML file structured as shown in <PKITHOME>/WEB-INF/conf/input-example.xml. Seethe example file for further detail. The unique identification from Step 1 must be entered into the identattribute of the pkit-data/input element.

3. The XML file must be sent to the server where Stages runs on. The default target port is 8099. If youneed to modify the port, contact Stages support.

If the XML file complies to the Stages data DTD, and all entries conform to their requirements (e.g., nameis set, description is set, required attributes are set and valid), they will be immediately stored into the newsapplication. Another possibility is to choose the external source type "Mailbox" and configure the followinginput fields according to the usual e-mail server parameters. Stages automatically polls the given mailbox ona regular basis and imports new e-mails into the news category.

7.4 Process export

7.4.1 General notesAs described in The domain attribute on page 28 operation R on domain "Processes" is necessary toexport a process. In order to fully export a process, additional permissions may be necessary however. Thefollowing list shows relevant permission domains and their impact on the process export.

• "Reports": Necessary to export metric reports• "Data Collectors": Necessary to export metric data collectors• "Files": Necessary to export files• "Permissions": Necessary to esport the permissions of contained roles• "Role Assignments": Necessary to export user role assignments

In order to export the elements listed above, operation R on the corresponding permission domain has to begranted to the user doing the export. If the concerning process is assigned to one or more reference models,sufficient permissions on these processes have to be granted to the user performing the export, too, in orderto export the assignments made to that reference models.



7.4.2 Exporting project tree into XMLEvery process can be exported to a XML file. The link is located on the "Import/Export" page. The exportcovers all process elements like phases, activities, roles, artifacts etc with their descriptions and theassociations between the elements. For every process element you can find an external link as an attributeto the respective element-XML-Tag.

The exported description of the defined roles also contains information about permissions given to the rolesand the assigned users. For artifacts the artifact instances are listed in the exported file, too. The structure ofthe exported XML-file is defined by a Document Type Definition (DTD) as well as a XML Schema Definition(XSD). Both files can be found in <PKITHOME>/dtds folder named pkit-process-tree_1_0.dtd andpkit-process-tree_1_0.xsd respectively.

7.5 Stages LoggingStages writes noteworthy events (e.g. warning messages, errors) into logfiles. These logfiles are located inthe Stages installation directory on Windows (by default C:\Programme\methodpark\stages) and in<StagesInstallDir>/log on Linux and UNIX-style platforms. All logfiles are automatically archived intothe respective XXX.log.NNN files to prevent overflow.

Logging is performed via the Log4J framework and is configured in the logging configuration file<PKITHOME>/WEB-INF/conf/log4j.conf.

7.5.1 Stages runtime logThe main logfile is pkit.log. Whenever the system refuses to start (i.e., when it can not read its config file)or problems occur during runtime, the relevant messages are written into this logfile. Per default, this logfilecontains all messages. To reduce the logging, set the default logging level to INFO. This can be done bychanging the entry

log4j.rootLogger=DEBUG, StandardAppender

to

log4j.rootLogger=INFO, StandardAppender

in the logging configuration file <PKITHOME>/WEB-INF/conf/log4j.conf.

7.5.2 Stages audit logStages writes security-related events into an audit logfile named audit.log which you can find in theStages installation directory on Windows and in <StagesInstallDir>/log on Linux and UNIX-styleplatforms. These events include

• user logins and logouts• session timeouts

Every event log entry includes an identifier that uniquely identifies the user session.

7.5.3 Stages download logAll binary downloads, accesses to processes application elements and news entries are logged into thelogfile download.log. This logfile can be analysed for statistical purposes. In contrast to the other logfiles,the download log is formatted as a CSV file (Comma Separated Values).

The columns are as follows

1. Date2. Time3. User name4. IP-address5. Project name6. Portal element ( Processes and news application)7. Download type (TEXT, BINARY)



8. Official name of downloaded document (e.g. Requirements Specification")9. Internal name of downloaded document (e.g. "requirementsSpec.doc")10.Document type (MIME-type of document or processes application element type)11.Document size (only for binary downloads)12.Status (OK, FAILED)

7.5.4 Stages e-mail logWhenever an e-mail is sent by Stages – usually via the news notification service – a respective log entry iswritten to the logfile notification.log.

7.5.5 Stages license logEvery successful security related event (see Stages audit log on page 47) creates an entry in thelicense.log which you can find in the Stages installation directory on Windows and in <installationdirectory>/log on Linux and UNIX-style platforms. Every entry comprises information about how manylicenses of which type are currently in use.

7.6 BackupAs Stages is a data-driven application, it is important to integrate Stages into the backup system ofthe server machine. All Stages data is located in the installation directory (usually C:\Programme\methodpark\stages on Windows and /opt/projectkit on Linux). It is sufficient to integrate thisdirectory into the local backup strategy. Before restoring Stages data from a backup, please remove thecontents of this directory to make sure that no outdated files remain in the system.

To assure database integrity, it is recommended to stop the database process before running a backup ofthe database directory and starting the database process again afterwards. The database directory is usuallyC:\Programme\methodpark\stages\mysql\data on Windows. On Linux, the directory dependson your Linux distribution. Stopping and restarting the database process is usually done via "net stopmysql" and "net start mysql" commands on Windows and via the distribution-dependent rc-Scripts onLinux.

On Windows, Stages uses the following registry keys to store its installation location and to announce thesoftware to the system. The following entries should also be integrated into the local backup strategy:

HKEY_LOCAL_MACHINE\SOFTWARE\method park\Stages

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\Stages\DisplayName

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\Stages\UninstallString

8 Stages upgrade Administration Guide


8 Stages upgrade

8.1 Upgrade InstallationStages upgrades are distributed as install files. These install files are either delivered on CD or canbe downloaded from our server after having contacted the Stages support. The installer per defaultautomatically backs up all Stages data before performing a Stages upgrade.

8.2 Data preserved during upgradeThe following data will be preserved during a Stages upgrade:

• Configuration files in the <PKITHOME>/WEB-INF/conf folder:

• PkitConfig.xml

• PkitLicense.xml

• PkitProcess.xml

• PkitRequest.xml

• PkitSignature.xml

• Database.properties

• oldcategories.xml (automatically created by Stages)• Local style definitions for the main system in <PKITHOME>/custom.css• Local style definitions for the online help system in <PKITHOME>/help/en/style.css (for the English

version) and <PKITHOME>/help/de/style.css (for the German version)• Local style definitions for the mail notification service in <PKITHOME>/notifystyle.css• Local data files in <PKITHOME>/local folder and all sub-folders• Local message definitions in <PKITHOME>/WEB-INF/classes/LocalPKit.properties and

<PKITHOME>/WEB-INF/classes/LocalPKit_de.properties

• Tomcat server configuration: <TOMCATHOME>/conf/server.xml• Database installation (configuration <PKITHOME>/WEB-INF/conf/Database.properties and

database content)

Important: Please note, that the Tomcat web.xml configuration file (see Network configuration onpage 17) is not preserved across upgrades due to technical reasons. If you have modified this file,your modifications will be lost after the upgrade.

9 Contact information Administration Guide


9 Contact information

For further information, you may contact the Stages support.

• E-mail: [email protected] (preferred)• Phone: +49 9131 97206 550

[email protected]