Micro Focus Pulse 19.1

What is Pulse?

Dimensions CM Pulse enables development teams to continuously examine the health and quality of their changes and decide if they are ready to be merged or released. You can:

• Use experts to:
  • Continuously build, inspect, and deploy code.
  • Report back findings.
  • Review the health and quality of changes.
  • Capture built artefacts.
• Use pull requests to review and merge a set of changes, typically in a topic stream.
• Visualize changes on the changeset graph.
• Use Agile request management to organize and execute the team's work using requests, backlogs, and iterations.
• Collaborate with team members to conduct peer reviews of code changes.
• View recent activity in products, streams, and projects.
• Run reports to display statistics and trends.
• Browse the code in a CM repository.

What's New in Pulse 19.1?

• Pull requests enable you to review and merge sets of changes.
• New build expert plugins:
  • Ant
  • Gradle
  • MSBuild
  • VisualStudio Build
  • Makefile
• Other expert plugins have been updated.
• Pulse now follows Dimensions CM product visibility rules.
• New agent architecture for continuous integration and inspection.
• You can now set variables, used by experts, on agents and chains.
• Various usability enhancements including a tabbed review page.
• Better visibility of chain runs in reviews and changeset pages.

Quick Tour

Watch an online quick tour to learn more about Pulse.

Navigate

Top Navigation

The top navigation contains:

• Links to My Work, Suites, and Administration.
• A search field.
• A link to the online help.

Sidebar

The sidebar contains links that are relevant to your current location in Pulse.

Breadcrumbs

Breadcrumbs display your current location in Pulse.

My Work

My Work displays useful information for the user who is currently logged into Pulse, including:

• The number of reviews that require the user's attention.
• The number of reviews owned by the user.
• The number of requests in the user's Inbox.
• Streams and products that the user has recently delivered to.
• Backlogs and iterations the user has recently used.
• Recent activity by the user such, as the results of chains for deliveries they have made, and reviews they have commented on.

The sidebar has links to information related to the current user, such as a list of reviews, changeset history, email subscriptions, and user preferences.

To open My Work for the current user, on the top navigation click My Work.

Inbox

The inbox displays the requests assigned to the current user.

Search

You can search in:

• Activity feeds
• History tabs when you are browsing the contents of streams
• Backlog and iteration lists
• Request catalogs

Examples:

• A review label: Q234
• A request label: QLARIUS_CR_44
• A backlog title: "Performance backlog"

Search for Requests and Reviews

You can search for requests and reviews wherever you are located in Pulse.

1. (Optional) To restrict the scope of the search, select a suite, product, or a stream.
2. Click Search on the top navigation.
3. From the list select Reviews or Requests.
4. Enter a search filter (you can enter part of a name, label, or title). You can search for:
   • Labels
   • Requests
   • Owners
   • Individual words in titles
   • Phrases (in double quotes, for example: "Fix API error")
5. Click Search or press Return. The results are displayed below. Click a result to view more details.
6. To refine your search, do one of the following:
• Select a filter from one of the results lists. The filter appears in the Refined by box:



• Control-click to select multiple filters from the lists. In the Refined by box click Apply. The box is updated:



The Search Results window is updated. You can further refine your search by removing filters from the Refined by box.

Click Clear to remove all filters.

Keyword Search

You can also use keywords in a search.

Activity Feed Keywords

Code History Keywords

Request Keywords

Review Keywords

Keyboard Shortcuts

On Review and Changeset pages you can use these keyboard shortcuts:

Dimensions CM Documentation

The full set of Dimensions CM documentation, including user guides and release notes, is available online in the Documentation Center.

User Preferences

Email Notifications

You can select the review and pull request email notifications to which you are subscribed. Notifications are sent when an event takes place on a review, for example:

• A review or pull request that you own changes state.
• You become the owner of a review or pull request, or are added as a reviewer.
• A review or pull request that you own is voted on.
• A review or pull request that you own is commented on.

1. On the top navigation click My Work.
2. On the sidebar select Email Subscriptions.
3. Select, or unselect, notifications.
4. Click Save.

View Defaults

You can set defaults for how views are displayed. Views include Reports, the Changeset Graph, Changeset History, Contributors, and Punch Card.

1. On the top navigation click My Work.
2. On the sidebar click Preferences.
3. In the Default Time Period for Views section select the default Start Date and End Date range for the data that is displayed.
4. Click Save.

Changeset Graph Defaults

You can set defaults for how the changeset graph is displayed.

1. On the top navigation click My Work.
2. On the sidebar click Preferences.
3. In the Changeset Graph Defaults section, from the Display Scale list select one of the following:
   • Changeset: display individual changesets.
   • Daily: groups changesets by days.
   • Week: groups changesets by weeks.
4. Select a Zoom Level.
5. Click Save.

Suites, Products, and Streams

Administrators can organize work into suites and register CM products.

• A suite is a collection of related software products, for example, Insurance. A suite can contain one or more Dimensions CM products, for example, Life Insurance and Health Insurance. You can register CM products in Pulse so that they respond to events produced from those products.
• A product is the same as a Dimensions CM product and is a major unit of software development. A product is a collection of CM streams, for example, the product Life Insurance contains these streams:
  • LIFE
  • DISCOUNTS
  • PROMOTION
• A stream is the same as a Dimensions CM stream or project and represents a branch or feature of development.

Use the following workflow to create a suite, add products, and configure streams:

1. Create a suite.
2. Register one or more products to the suite.
3. Configure settings and defaults for each product.
4. Optional:
• Register one or more streams with each product (streams are normally registered automatically).
• Automatically create reviews and run chains for each stream.

View Activity

When you select a suite, product, stream, review, or changeset its latest events are displayed in the Activity feed, including:

• Deliveries of changesets to streams that create reviews
• Reviewers added to a review
• Changes to reviews' states
• Review comments
• The results of chains and experts than ran on changesets

You can filter the information that is displayed in an activity feed.

1. (Optional) From the Activities list select an event type, for example, Comments. By default All Activities is selected.
2. (Optional) In the Filter box enter one or more keywords in the format <keyword>:<value>.
3. Click Apply.

Create Suites and Register Products

Administrators can create new suites and register Dimensions CM products.

Create a New Suite

1. On the top navigation click Suites.
2. Click New Suite.
3. Enter a title for the new suite.
4. Optionally enter a description for the suite. Use the tools to format, and preview, the description.
5. Click Save.

Register a Product to a Suite

1. Select the suite where you want to register the product.
2. Click Register and select Single Product.
3. Enter a title for the product. A Pulse product is the same as a Dimensions CM product but the titles can be different.
4. Optionally enter a description for the Pulse product. Use the tools to format, and preview, the description.
5. From the Repository Name list do one of the following:
   • Select an existing Dimensions CM repository.
   • Select Create new repository.
6. If you are creating a new repository do the following:
   1. Enter a title for the Dimensions CM repository.
   2. Enter the network address of the Dimensions CM server, for example: dmcm-server.example.com
   3. Enter the CM base database name and connection string, for example: CM_TYPICAL@DIM14
   4. For SCM Credentials, select or deselect the option Always use the following credentials. Click here for information about using this option.
   5. Enter a Dimensions CM account username and password.
7. From the Product in Repository list select a CM product.
8. Click Register.

Register Multiple Products to a Suite

1. Select the suite where you want to register the products.
2. Click Register and select Multiple Products.
3. From the Repository Name list do one of the following:
   • Select an existing Dimensions CM repository.
   • Select Create new repository.
4. If you are creating a new repository do the following:
   1. Enter a title for the Dimensions CM repository.
   2. Enter the network address of the Dimensions CM server, for example: dmcm-server.example.com
   3. Enter the CM base database name and connection string, for example: CM_TYPICAL@DIM14
   4. For SCM Credentials, select or deselect the option Always use the following credentials. Click here for information about using this option.
   5. Enter a Dimensions CM account username and password.
5. From the Products in Repository list shift-click to select multiple CM products.
6. Click Register. The new Pulse products have the same titles as the CM products. You can edit the titles later.

Register a Stream to a Product

Streams are registered automatically in a Pulse product when anyone makes a delivery to that stream in Dimensions CM. However, administrators can manually register a stream, for example, to add a chain before the next delivery to that stream.

1. Select the product where you want register a stream.
2. Click Register Stream.
3. In the Stream Name box start typing the name of a stream. Pulse automatically displays a list of all the streams that match the string (not case sensitive).
   TIP Use wildcards to help you find a stream:

   • Type '*' at the end of a string to match specific names, for example: DEV:STREAM_A*
   • Type '*' to display all the streams in a Dimensions CM product.
4. Select a stream.
5. Click Save. The stream is registered with the product and you can now:
   • Configure the stream to automatically create reviews and run chains.
   • Add experts to chains.

Delete Suites, Products, and Streams

Administrators can delete suites and products and unregister streams.

1. On the top navigation click Suites.
2. Do one of the following:
   • Select one or more suites.
   • Select a suite and then select one or more products.
   • Select a suite, a product, and then select one or more streams.
3. Click Delete and confirm.

Modify a Suite or Product

Administrators can modify the title and description of suites and products.

1. Open a suite or product.
2. Click Edit.
3. Modify the title and/or description.
4. Click Save.

Set Favorite Streams

You can add, or remove, a stream from your list of favorite, active streams. Favorite streams are marked with a star and are always displayed at the top of the streams list.

1. Open a stream.
2. To the right of the stream name toggle the star to add, or remove, it from your favorites.

Move a Product to another Suite

Administrators can move a product to another suite.

1. Open a product.
2. Click Move.
3. Select a suite from the list.
4. Click Move.

Filter the List of Streams

On a product page you can filter the list of streams that is displayed.

1. Open a product's home page.
2. In the Streams section, in the search box type a filter. Pulse automatically displays a list of all the streams that match the string (not case sensitive).

Product and Stream Settings

Administrators can set defaults for the all the streams in a product. For example, you might want different products to show different check lists when users vote to approve reviews or request changes. You can override these settings for each stream.

Create New Reviews

Set options for how new reviews are created.

1. Select a product or stream.
2. On the sidebar select Settings and then the Reviews tab.
3. From the Creation of Reviews in Stream list select an option for creating reviews:
• Automatic
• Manual
• No allowed
4. From the Review Rules To Use list select a rule. Rules control how reviews move from one state to another (for example, whether all reviewers must approve a review, or just one reviewer).
5. From the Review Check List To Use list select a review check list to be used with new reviews. You can also select the option not use a review check list.
6. Click Save.

Pull Request Settings

See Configure Pull Request Settings.

Chain Runs

Configure how chains are executed on streams.

1. Select a product or stream.
2. On the sidebar select Settings and then the Chain Excution tab.
3. From the Run chains list select one of the following:
   • Run chains on this stream
   • Disable chains on this stream
4. Click Save.

New Stream Defaults

When you create a new stream you can copy the settings from the source stream.

1. Select a product.
2. On the sidebar select Settings and then the New Streams tab.
3. Select Copy settings from source stream.
4. Click Save.

Delivery Filter Defaults

Administrators can set the default delivery filter for a product, which automatically assigns it to any streams that do not have a filter. A product can only have one default delivery filter. Delivery filters determine which changesets create reviews and run chains. For example, you could exclude deliveries of built artefacts made on behalf of your automated CI system in those products where CI was configured.

1. Select a product.
2. On the sidebar select Delivery Filters.
3. Select a delivery filter. If there are no filters you create new ones.
4. Click Set As Default and click Make Delivery Filter Default.
5. To apply a different delivery filter to a stream:
   1. Select the stream.
   2. On the sidebar select Settings.
   3. On the Changesets tab select a filter from the list.
6. Click Save.

Agents

About Agents

Agents are small applications that Pulse can use to run chains:

• Each agent is associated with a specific instance of Pulse.
• Each instance of Pulse includes an embedded agent, so you do not need to install an agent on the same machine.
• To distribute the processing load of chains, install multiple agents on different machines on a network.
• Agents only include the code required to run chains and automatically download the required plugins from the Pulse master. You do not need to manually install plugins on agents.
• Agents can be configured to run specific chains by adding capabilities and variables.

Approve Agents

When an agent is associated with an instance of Pulse it is automatically displayed in the Agents administration page. To license an agent, an administrator can approve it. You can see if an agent is licensed, or if there are licensing issues, on the Agents page.

• When an agent is added to Pulse, by default it is unapproved and cannot be used to run chains. If an agent can be trusted, you can approve it.
• Unapproving or deleting an agent releases the license that it holds.
• Taking an approved agent offline or online does not effect licensing.
• Pulse includes three free agent licenses.

1. On the top navigation click Administration.
2. Select Agents.
3. Select one or more agents.
4. From the Mark As list select Approved.
5. To unapprove agents and release licences, from the Mark As list select Unapproved.

Manage Agents

View Agent Information

The Agent page lists all the agents registered for your instance of Pulse. Each agent displays the following information:

• Agent name (same as the host machine, which you cannot change in Pulse), for example: suse4130-buildagent
• Title (an optional description of the agent), for example: Windows compilers
• Status: Embedded, Offline, Unapproved
• Universal unique identifier (UUID)
• Operating system of the host machine
• Connection status, for example: Started 2 weeks ago
• Heartbeat (when the agent last communicated with Pulse)
• Agent version
• Capabilities tags
• Memory usage of the host machine
• Workspace remaining on the host machine. A workspace is an area on disk that an agent can populate with code to run a chain.

1. On the top navigation click Administration.
2. Select Agents.
3. To restrict the list of agents that are displayed, select an option from the filter list. For example, you can display all agents or only agents that are online.
4. To enable or disable memory and workspace monitoring, click Agent Monitoring.
5. To modify an agent's title, select the agent from the list, click Edit, on the General tab enter a new title, and click Save.

View Agent Chains

You can view the chains that are running on an agent and the history of previous chain runs including the last run, last failure, last success, and the total number of runs.

1. On the top navigation click Administration.
2. Select Agents and select an agent.
3. The Running tab displays the chain that is currently running.
4. The Chains tab displays the history of previous chain runs. Each chain is on a separate row.

Take Agents Offline or Online

You can take an agent offline, for example, the host machine is being updated and you want to temporarily prevent it from running chains.

1. On the top navigation click Administration.
2. Select Agents.
3. Select one or more agents.
4. From the Mark As list select Offline.
5. To take agents back online, from the Mark As list select Online.

Upgrade and Restart Agents

If an agent is not responding you can restart it. If you have updated the version of a Pulse master you should update the Pulse slaves that are connected to it. When you upgrade a slave it downloads the agent code from the master and installs it.

1. On the top navigation click Administration.
2. Select Agents and select an agent.
3. Click Upgrade or Restart.

Delete Agents

Administrators can delete an agent that is registered with Pulse. Deleting an agent release any licenses held by that agent.

1. Stop the agent on the host machine.
2. In Pulse, on the top navigation click Administration.
3. Select Agents.
4. Select the agent and click Delete.
5. Confirm that you want to delete the agent.

Add Variables to Agents

You can add variable defintions to agents. A variable provides information about agents that can be used by chain runs. For example:

• The location of a specific compiler on an agent’s host machine.
• The configuration settings used by an expert.

Variables enable you to add steps to chains without needing to know the installation details of applications and tools on your agents.

1. On the top navigation click Administration.
2. Select Agents and select an agent.
3. Click Edit and select the Variables tab.
4. Enter a name and value pair, for example: MAVEN_HOME=/home/autobuild/maven3
5. Click Save.

Add Capabilities to Agents

You can add capabilities to agents. Capabilities describe a host machine's environment, for example:

• A specific operating system
• High memory
• A specific network location

You can add multiple capabilities to agents, use them to match agents to chains, and restrict the agents that can execute chains. For example, assume you have multiple agents running Windows. If a chain requires Windows Server 2016 and 64GB of memory you can:

• Add the capabilities WindowsServer2016 and 64gbMemory to the appropriate agent.
• Add WindowsServer2016 and 64gbMemory as required capabilities on the chain.

When the chain runs it matches its required capabilities with the capabilities of the agents; the chain only runs on the agent that is running Windows Server 2016 and has 64GB of memory.

1. On the top navigation click Administration.
2. Select Agents and select an agent.
3. Click Edit and select the Capabilities tab.
4. To add capabilities enter one or more tags. Tags cannot contain spaces.
5. Click Save.

Health and Quality

Pulse enables you to inspect the health and quality of your code changes. You can:

• Visualize streams, branches, merges, and changesets.
• Run chains of experts to check the health and quality of source code and builds.
• Review code changes to determine if they are ready to be merged or released.
• Use pull requests to evaluate a well-defined set of changes.

Changesets

About Changesets

Pulse uses changesets to visualize information about changes. A changeset is a logical grouping of changes that is automatically created every time you deliver changes in a stream or project to a repository. A changeset enables you to identify, work with, and track, sets of changes. Every changeset that you deliver creates a new version of a stream or project.

Video: Introduction to Changesets

There are multiple ways that you can view the information in changesets:

• Changeset Graph: visualizes your changesets and streams of development.
• Changeset History: displays the history of changes in chronological order.

You can view changeset information for suites, products, and streams. My Work displays changeset information specific to the user who is currently logged in.

You can filter the changeset graph, or any information view, to:

• Limit the data that is displayed.
• Focus on a specific feature or set of streams and projects.
• Focus on a specific period of time.

1. Select a suite, product, or stream.
2. Open the changeset graph or one of the information views.
3. At top right click the date filter.
4. In the Stream Name box enter a wildcard to match stream and project names, for example: QLARIUS:JAV*
TIP
• You can enter multiple wildcard strings; separate each wildcard with a comma.
• To hide specific streams, add a minus '-' character at the start of the string, for example: -*JAV*
• To only display streams that you have marked as favorites, select Show favourites only.
5. From the Start Date and End Date lists do one of the following:
• Select a predefined date range.
• Select Since or Until and use the date picker to manually select a date range.
TIP
• Start Date displays all data that matches the wildcard from the date that you specify.
• End Date displays all data that matches the wildcard up to and including the date that you specify.
6. Click Apply. The graph or view refreshes and only displays data that matches the filters that you specified.

View Changesets

Overview

A changeset graph visualizes streams and their change history across multiple releases. The graph provides development teams and release managers with a visual understanding of what changes are being worked on, where, and why. Experts provide an opinion on the health of changes and an indication of release readiness. A changeset graph enables you to:

• Visualize all your streams and projects in one place including branches and merges. Each circle or group represents a changeset or a group of changesets.
• Review the health and readiness of your changesets and determine if they are ready to be merged or released.
• Watch in real time as streams are branched, merged, and moved through the lifecycle.

Changeset Health

Changeset health is displayed visually using a combination of the expert opinions of the changes and the review state:

The changeset is currently healthy and the review was successful

The changeset is not healthy or the review failed

The changeset is unstable

Experts are running on the changeset

Experts are scheduled to run on the changeset

No experts were run on the changeset and no review is available

The changeset was aborted

When the review and experts are completed, a changeset icon has a solid border, for example:

When the review or any experts are in progress, a changeset icon has a border that is not solid, for example:

Display a Changeset Graph

1. Select a suite, product, or stream. The graph is scoped to the suite, product, or stream that you select.
2. On the sidebar select Changeset Graph.
3. (Optional) Filter the information that is displayed.
4. Use the following methods to display the information on a changeset graph:
   • Mouse over a stream's label to display its changeset history.

   

   • Click a stream's label to display an overview.
   • Mouse over, or select, a changeset to highlight all the merge lines that connect it to other changesets.
   • Control-click changesets to highlight multiple merges.
   • Mouse over a changeset to display a summary.

     

   • Mouse over a changeset group to display the stream version range, and the result of the chains that ran on the most recent changeset.

     

View Changeset Details

Click a changeset to view its details. A pane at the bottom displays information including:

• The changeset number and description.
• The stream or project version that owns the changeset.
• The user whose delivery created the changeset.
• The date and time the changeset was created.
• The review created by the delivery. Mouse over to display its current state.
• The result of the chain that ran on the changeset.

Group Changesets

You can view changesets individually or grouped by days or weeks. Groups take up less space on the graph and look like this: The number of changesets contained in a group is displayed at the top right.

1. Open the changeset graph.
2. From the Changesets Graph list select one of the following:
   • Individual Changesets
   • Grouped by Days
   • Grouped by Weeks

Sort Streams on Changeset Graphs

On the changeset graph you can sort streams by:

• Stream name
• Create date
• Last activity

You can also sort streams in ascending or descending order.

1. Open the changeset graph.
2. From the Streams sorted by list, select a sort option and a sort order.

View Changeset History

The changeset history view displays changes to suites, products, and streams in chronological descending order. For each changeset the following information is displayed:

• The changeset number and description. Click to open the changeset page.
• The stream or project version that owns the changeset.
• The user whose delivery created the changeset.
• The date and time the changeset was created.
• The review created by the delivery. Click a review to view its details.
• The health of the changeset.

1. Select a suite, product, or stream. The view is scoped to the suite, product, or stream that you select.
2. On the sidebar, select Changeset History.
3. (Optional) Filter the information that is displayed.
4. Select a changeset to view its details.

View Changeset Pages

A changeset page displays information about a specific changeset including:

• The changeset ID and title
• The associated stream or project
• Recent activity, such as experts that ran on the changeset
• Related requests
• The associated reviews
• The results of chains that ran on the changeset including findings and measurements
• A list of all the files in the changeset
• The contents of the files and comments.

1. Select a suite, product, or stream.
2. On the sidebar, select Changeset History.
3. Select a changeset to view its details.

Customize Changeset Pages

You can customize if the following elements are displayed by default on a changeset page:

• Comments made by reviewers
• Findings on files made by experts
• Entire files (not only the lines that have changed)
• Previous versions of files
• Combine the previous and current differences of files

You can also select a white space option for viewing file differences, for example, Ignore White Space.

1. Open a changeset page.
2. Click Action and select Display Defaults.
3. From the Show by Default select options.
4. From the White Spaces list select an option.
5. Click OK.

Pull Requests

Introduction to Pull Requests

The topics below introduce you to pull requests and how they work with topic streams to help you review and merge changes.

About Pull Requests

A pull request is a special type of review that you use to evaluate and merge a set of defined changes, typically in a topic stream. Pull requests are a collaborative process that allows a team to:

• Review the proposed code changes.
• Add review comments and contribute to a discussion.
• Protect your mainline stream from unwanted changes, bad merges, and broken builds.
• Approve changes and merge them into a mainline.

Key facts about pull requests:

• Are related to two streams: the source stream, where the pull request changes are made and reviewed, typically a topic stream; and the target stream, where the pull request changes will be merged to, typically a mainline stream.
• Can be related to a request, which is used to merge the changes in the pull request.
• Enable you to merge changes into a target stream without using a work area.
• Can run chains to help you decide if the changes in a stream are healthy.

Pulse administrators can configure a new pull request to be automatically created when a topic stream is created. The new pull request is automatically linked to the topic stream.

About Topic Streams

Topic streams are temporary streams that you use for a set of defined changes, for example, to fix a defect or develop a small feature. Topic streams enable you to isolate changes from a mainline stream. Topic streams have some limitations compared to normal streams but advantage is they are very quick to create.

How do Pull Requests and Topic Streams Work Together?

A topic stream and its related pull request work together to help you review and merge changes:

• A topic stream is created from a parent stream, which creates a pull request. You can create topic streams in the Dimensions CM clients.
• Changes are delivered to the topic stream and related to the pull request.
• The pull request is reviewed, approved, and merged into the topic stream’s parent stream.

Key facts:

• Reviewers use the pull request to review the changes in the topic stream.
• The pull request contains the changes in the related topic stream.
• The request related to the pull request is used to merge the changes in the topic stream into its parent stream.

Reviewing Pull Requests

You can assign reviewers to a pull request before you publish it. Reviewers can add comments to the changes, identify issues, make suggestions, and answer questions. When a comment is made, the pull request author and all the reviewers receive an email with a snippet of the code and the review comments.

Merging Changes in Pull Requests

If the parent product or stream has been configured to automatically merge pull requests, when a review moves to the Approved state, the pull request is automatically merged into its parent stream.

If automatic merge is not enabled, when changes have been reviewed and approved, and if there are no conflicts between the topic stream and its parent, you can manually merge the pull request. If there are conflicts, you must resolve them in a work area before you can merge the pull request.

If the merge is successful the pull request is automatically closed. If the merge fails a warning is displayed at the top of the pull request.

Using Pull Requests

The topics below describe how to use pull requests to review and merge changes.

Configure how Pull Requests are Created

Administrators can select the following options to configure how pull requests are created for topic streams:

• Do not allow: pull requests are disabled for topic streams.
• Allow manual: pull requests can be created manually between pairs of streams.
• Automatic for Topic Streams: pull requests can be created manually between pairs of streams; child topic streams automatically create pull requests.
• (Streams only) Use the product's default settings for creating pull requests: applies the option selected for the stream's product.

The default naming scheme for pull requests is: PR<nn> :<title>

1. Select a product or stream.
2. On the sidebar click Settings.
3. Select the Pull Requests tab.
4. From the Creation of Pull Requests from Child Stream list select an option.
5. Click Save.

Create Pull Requests Manually

If pull requests are not configured to be created automatically for a topic stream, you can create one manually. You cannot create a pull request in a non-topic stream.

1. Select the topic stream where you want to create a pull request.
2. Click New Pull Request.
3. In the New Pull Request dialog select the following:
   • The product where you want to create the pull request. Default: the product to which the stream belongs.
   • A source stream. Default: the topic stream.
   • The target stream the pull request will be merged into when development is complete. Default: the topic stream’s parent.
4. Enter a title and description.
5. Add lead and optional reviewers who can vote to approve or request changes. Choose developers who you think are most suitable to review these changes.
6. Select a request that describes the changes to be made. This request will be used to merge the changes into the parent stream. If the topic stream is already related to a request, it is automatically selected. To relate a different request, click Relate and select a request from the Relate Requests dialog box. To unrelate a request, click Unrelate.
7. Click Create. The new pull request is now at the Draft state.

Open and Modify Pull Requests

You can open and view a pull request. If you are the pull request author you can also:

• Edit the title and description
• Change the author
• Add and remove reviewers
• Change the related request
• Change the display defaults

1. Select a product. To restrict the scope of the search, select a stream.
2. On the sidebar click Reviews.
3. From the Reviews list select a filter, for example, Active.
4. Select the pull request that you want to view or modify. On the Conversation tab you can modify the:
   • Description
   • Author (the owner of the pull request)
   • Reviewers
   • Related request
   Any changes that you make are saved automatically.
5. To edit the title or display defaults, select an option from the Actions menu.

Publish Pull Requests

If you are the author of a pull request, when you have finished delivering your changes you can publish it for review. When you publish a pull request:

• It moves to the In Review state.
• The reviewers are notified.

1. Open a pull request.
2. Click Publish.
3. Click Publish Review. Depending on your review rules, you may want to action the related request to its In Review state.

Run Chains on Pull Requests

You can run chains on pull requests to help you decide if the changes in the related stream are healthy.

1. Open the pull request where you want to run chains.
2. From the Actions menu click Run Chains.
3. Select one or more chains that have been defined for the related stream.
4. Click Run Chains. The selected chains are queued. After the chain has run you can view the results on the Chain Runs tab.

Review and Approve Pull Requests

If you are the reviewer of a pull request you can:

• View the associated code changes.
• Add review comments and collaborate with team members.
• View the results of chains that have run on the pull request.
• Vote to approve changes to the pull request.

1. Open a pull request.
2. To view the code changes, click the Changes tab. The Contents section list all the files in the review. To review a specific file, select it from the list, or scroll down. The list of files is also displayed on the sidebar.
3. To add comments to a file:
   • Click and drag to select the lines where you want to add a comment.
   • In the Comment box enter your comments. Optionally, format the comment using the toolbar or markdown syntax.
   • Click Comment. Your comments are now visible to your team and their responses will be displayed in the same comment box. Each reviewer receives an email with a snippet of the code and the review comments.
4. To vote to approve a pull request click Approve. Enter the reasons for your approval and click Approve.

Request Changes to Pull Requests

If you are the reviewer of a pull request you can ask for changes to be made to the code. Depending on your review rules, the pull request can be sent back to its author for rework. The author can make additional changes and republish the pull request.

1. Open a pull request.
2. To vote for changes to be made, click Request Changes.
3. Enter comments and click Request Changes.

Merge Pull Requests Automatically

Administrators can enable approved pull requests to merge automatically into the target stream. Automatic merging only works if there are no conflicts when the pull request moves to the Approved state. If a pull request fails to merge automatically you can try and merge it manually.

1. Select a product or stream.
2. On the sidebar click Settings.
3. On the Pull Requests tab, from the Merge Policy list select a policy that enables automatic merges.
4. Click Save.

Merge Pull Requests Manually

If the parent product or stream has not been configured to automatically merge approved pull requests, you can do a manual merge if there are no conflicts between the contents of the topic stream and its target stream.

1. Open the pull request that you want to merge into the target stream.
2. Click Merge Pull Request.
3. Add a merge comment and click Merge. If the merge is successful the pull request is automatically closed. If the merge fails a warning is displayed at the top of the pull request.

Abandon Pull Requests

If you are an administrator you can abandon reviews if they are no longer required. This stops further review activity and cannot be reversed.

1. Open the pull request that you want to abandon.
2. From the Actions menu select Abandon Review.
3. Click Abandon Review.

Update Pull Requests

The latest changesets in a topic stream are automatically attached to pull requests. However, to check that the pull request is current, you can scan for the latest changes.

1. Open the pull request that you want to update.
2. From the Actions menu select Scan for New Changesets.
3. Click Scan.

Change Ownership of Pull Requests

If you are an administrator you change the author (ownership) of pull requests.

1. Open the pull request.
2. On the Conversation tab, in the Author section, click Change.
3. Select the user who will be the new author.
4. Click Change Author.

Mark Pull Requests as Approved

If you are an administrator you can bypass the review of pull requests and mark them as approved. If the parent product or stream has been configured to automatically merge, the pull request is merged into its parent stream.

1. Open the pull request.
2. From the Actions menu select Mark as Approved.
3. Click Approve Review.

Send Pull Requests for Rework

If you are an administrator you can bypass the review of pull requests and send them to the author for rework.

1. Open the pull request.
2. From the Actions menu select Send for Rework.
3. Click Send for Rework.

Configure Pull Request Settings

The topics below explain how to configure pull requests settings such as merge policies.

Manage Merge Policies

Administrators can manage the policies that control who can merge pull requests. You create a new merge policy or modify an existing one.

1. On the top navigation click Administration.
2. Select Merge Policies.
3. Click New Merge Policy or select the policy that you want to modify.
4. Enter, or modify, the merge policy title.
5. To enable pull requests to be merged automatically, select Automatically merge pull requests when they are approved. The automatic merge is performed by the repository’s system user in the background.
6. To display the Merge button in pull requests, in Who can Merge select the author and/or reviewers. The privilege to perform a merge is controlled by Dimensions CM privileges, which the users must have.
7. To add other users who can see the Merge button, click Add and add merge gatekeepers. These users also require the correct Dimensions CM privileges.
8. Click Save.

Set Pull Request Rules

Administrators can set the default review rules used by pull requests. Rules control how reviews move from one state to another (for example, whether all reviewers must approve a review, or just one reviewer).

1. Select a product or stream.
2. On the sidebar select Settings.
3. Select the Pull Requests tab.
4. From the Review Rules To Use list select a rule.
5. Click Save.

Set Default Check Lists

Administrators can set the default review check lists used by pull requests. You can also specify no check list.

1. Select a product or stream.
2. On the sidebar select Settings.
3. Select the Pull Requests tab.
4. From the Check List To Use list select a rule.
5. Click Save.

Set Display Defaults

You can set the display defaults for your pull requests.

Map Pull Requests States to CM Request States

Administrators can map the following Pulse pull request states to Dimensions CM request states:

• In Review: a comma separated list of CM request states that can add reviewers to pull requests.
• Rework: when a pull request is sent for rework, action the associated request to the specified CM state.
• Approved: when a pull request is approved and ready to be merged, action the associated request to the specified CM state.
• Completed: when a pull request is merged successfully, action the associated request to the specified CM state.

1. On the top navigation click Administration.
2. Select Repositories and then a CM repository
3. Select Defaults and then the Pull Requests tab.
4. In the state name in CM fields, enter CM states.

Set the Dimensions CM Reviewer Role

Administrators can set the default Dimensions CM role for pull requests. Users that hold this role can be selected as reviewers for pull requests. Default role: REVIEWER

1. On the top navigation click Administration.
2. Select Repositories and a CM repository
3. Select Defaults and then the Pull Requests tab.
4. In the Reviewer role name in CM section, enter a Dimensions CM role.

Code Review

About Reviews

Overview

Video: Introduction to Peer Review

You can use peer review to:

• Comment on, and review, the changes in your development projects.
• Collaborate with team members.
• Get insight into the health of changes in your changesets and streams, such as the results of chain runs.
• Promote team work and development best practices.
• Vote to approve reviews or ask for changes, which may cause reviews to be marked as approved or sent for rework.

If you are a user with administrator rights you can also:

• Change a review's owner.
• Send a review for rework back to its owner.
• Change a review's state.
• Abandon a review.

The review list displays all the reviews that have been created for the selected user, suite, product or stream. A review page displays information about a specific change. You can control how a review's state is changed with the configurable review rules.

Reviews are also displayed on the activity feed for suites, products, streams, and My Work.

Create Reviews

If you are an administrator you can configure changesets to automatically create reviews.

Review States

Pulse's review states and state changes are:

Reviewers vote to approve, send for rework, and abstain from a review. Depending on the configurable rules their votes may cause a state change, or contribute to a state change in the future. By default, the first reviewer to vote on a review changes its state but different rules may be configured in your environment.

The review states are:

• Draft: the review is being modified by the user who is the owner.
• In Review: the review has been published. Reviewers can add comments and vote on the review.
• Approved: the review's changes have been accepted.
• Rework: the review has been sent back to its owner with suggestions for improvement.
• Completed: if there are no issues the Approved review is normally marked as Completed by the owner.
• Abandoned: a review can be changed to Abandoned at any time by an administrator. The review is closed and removed from circulation.

Review Roles

A user can hold one of the following roles on a review:

• Owner: normally the user that delivered the changeset that created the review. The owner can be changed by an administrator to any valid user.
• Lead reviewer: can be assigned automatically from the changeset and modified manually. The valid lead reviewers are derived from the real role assignments on the design parts in Dimensions CM that own the items being reviewed. A lead reviewer can add optional reviewers.
• Optional reviewer: normally assigned manually. The valid optional reviewers are derived from the candidate role assignments on the design parts in Dimensions CM that own the items being reviewed. Optional reviewers cannot assign other reviewers.

Delivery filters control which changesets automatically create reviews. Dimensions CM role assignments on the items in the changeset determine which users are automatically assigned as lead reviewers or are available to be assigned as optional reviewers.

Review Rules

A change in a review's state is triggered by one of the following:

• A user with the appropriate role (Owner or Administrator) changes the review state manually.
• A decision made by a review rule that has run automatically.

The review rules are codified as a script that runs when one of the following significant events occur:

• A new changeset is associated with a review, which may automatically assign reviewers to the review.
• A user manually changes the state of a review.
• A reviewer votes to approve, request changes, or abstain with no opinion on a review that is at the In Review state.
• The owner of a review is changed.
• The reviewers assigned to a review are changed manually.
• A request associated with a review is actioned to the In Review state in Dimensions CM. This may automatically assign reviewers.

A rule script uses the votes of the lead and optional reviewers, and additional information, to decide whether to change a review's state. You can create, or modify, scripts and set the default rule script for each stream.

If you are using the built-in defaultRule.js rule script the default behavior automatically changes the review state from:

• Draft to In Review when a reviewer is assigned.
• In Review to Approved or Rework after the first vote has been cast by any reviewer.
• Rework to In Review when the request's state changes to In Review in Dimensions CM.

The Review List

A review list displays the following:

• Suites: reviews for all products and streams
• Products: reviews for all streams
• Streams: reviews for the current stream

To open a review list:

1. Select a suite, product, or stream.
2. On the sidebar select Reviews.

Each row in a review list is a separate review and includes the following information:

• An icon that indicates the review's current state, for example, In Review or Approved
• The review's label (number and title)
• The date the review was created
• The stream associated with the review
• The user who created the review
• The users who are reviewing the review

You can select a filter to modify the type of reviews that are displayed.

1. Open a review list.
2. From the Reviews list select a filter.

You can also sort the reviews by category, and in ascending or descending order.

1. Open a review list.
2. Click Sort by.
3. Select a category.
4. Optionally select, or unselect, Sort descending.

Review Pages

Each review page displays the following information:

• An icon that indicates the review's current state, for example, In Review or Approved.
• The review's ID and title.
• The associated stream or project.
• A summary of the review's health, for example, The chains indicated this change is good.
• Reviewer votes.
• The review owner and the lead and optional reviewers.
• Recent activity on the review.
• Related requests.
• The results of chains that ran on the changesets.
• The changesets associated with the review.
• The files and folders associated with the changesets.
• The contents of the files in the review.

Activity

The recent activity on the review is displayed in the Activity section, for example:

• The delivery that created the review
• Chains that ran on the review

You can filter the information that is displayed:

• Discussions & Deliveries: only displays user generated events (such as Review sent for rework) and comments added by reviewers.
• Grouped: also displays the results of chains and experts that ran on the changesets associated with the review.
• All: displays both of the above.

Requests

Related requests are displayed in the Requests section and a summary of the first one is expanded. Click the title of any review to view its details.

The results of any chains that have run on the changesets associated with the review are displayed in the Chain Runs section. Expand a chain run to view the measurements and findings of each expert.

Changesets

The changesets associated with the review are displayed in the Changesets section. Multiple changesets are associated with a review if users have made several deliveries to a stream using the same request.

If a review is associated with multiple changesets you can filter the files that are displayed.

1. In the Changesets section select two changesets to compare with each other.
2. Click View. The contents section and the sidebar are updated and only files that have changed between the selected changesets are now displayed.

Contents

The Contents section, and the sidebar, display all the files and folders in a review. You can view the contents of any file and add comments.

Publish a Review

When a review is created its initial state is Draft. If you are the review owner, or a user with administration privileges, you can publish the review so that it is available to your team. The owner is normally the user that delivered the changeset that created the review.

1. On the review list page select the review you want to publish.
2. Click Publish.
3. Click Publish Review. The review is now at the In Review state.

Add and Remove Reviewers

Each review can have reviewers with these roles:

• A review owner; normally the user who delivered the changeset that created the review.
• One or more lead and/or optional reviewers.

To add reviewers to a review:

1. Open a review.
2. In the Reviewers section click Add and then Lead Reviewer or Optional Reviewer.
3. Select more or more reviewers.
TIP
• Control click to select multiple users.
• Use Search to find users.
4. Click Add Reviewers.

To remove reviewers from a review:

1. Open a review.
2. In the Reviewers section select more or more reviewers.
3. Click Remove and confirm.

Browse the Contents of Files in a Review

The Contents section, and the sidebar, display all the files and folders in a review. Changes to files and folders, and to lines and characters in files, are displayed with these colors:

	File added
	Line and/or characters added
	File deleted
	Line and/or characters deleted
	Line and/or characters deleted
	File renamed

The sidebar displays the total number of files in the review.

The Contents section displays the number of files and folders that have been added, modified, renamed, and deleted.

Click a file to view its contents. Use the Show menu to control how the file contents are displayed.

Add Comments to Files in Reviews

You can add comments to files in a review and collaborate with team members. Each reviewer receives an email with a snippet of the code and the review comments. This is different to adding a comment to an entire review.

1. On a review page find a file.
2. In the line number column, click and drag to select the lines where you want to add a comment.



3. In the Comment box enter your comments. Optionally, format the comment using the toolbar or markdown syntax.
TIP

You can also email comments to users who are not included in a review, for example, you want the opinions of other developers.

a. On the toolbar click Mention or enter the @ character in the comment box.

b. Start typing the name of a registered user, Pulse automatically displays the names of users that match.

c. Select a user.

d. Repeat to add additional users.



4. To display how your comment will look, click Preview. To continue editing click Edit.
5. To add the comment click Comment. Your comments are now visible to your team and their responses will be displayed in the same comment box.

Vote on a Review

You can vote to approve a review or request changes. Depending on how the rules script for this stream is configured, your vote may trigger the rule script to move the review to its next state.

1. At the top of a review click Approve or Request Changes.
2. Enter the reasons why you are voting to approve the review or requesting changes.
3. Optionally format your comment (see the markdown reference).
4. To display how your comment will look click Preview. To continue editing click Edit.
5. If a check list is presented, select items that have influenced your voting decision.
6. Click Approve or Request Changes.

You can also abstain from voting. This useful if there is a rule that mandates that all reviewers must vote, but you have no opinion.

1. Open a review.
2. Click Action and select Abstain with No Opinion.
3. Enter a reason for abstaining and click Abstain.

Mark a Review as Approved

If you are a user with administrator privileges you can bypass reviewer voting and mark a review as Approved.

1. Open a review.
2. Click Action and select Mark as Approved.
3. Click Approve Review.

Change a Review’s Owner

If you are a user with administrator privileges you can change a review's owner.

1. Open a review.
2. Click Change Owner.
3. Select a user.
4. Click Change Owner.

Send a Review for Rework

If you are a review owner, or a user with administrator privileges, you can send a review back to its owner for rework with suggestions for improvement, and bypass reviewer voting.

1. Open a review.
2. Click Action and select Send for Rework.
3. Click Send for Rework.

Abandon a Review

If you are a review owner, or a user with administrator privileges, you can abandon a review. Abandoning a review indicates that it is no longer active and stops further review activity. This action cannot be reversed.

1. Open a review.
2. Click Action and select Abandon Review.
3. Click Abandon Review.

Close a Review

If you are a review owner, or a user with administrator privileges, you can close a review. Closing a review prevents further changes being made to it. Only close a review if you are sure that no further work is required.

1. Open a review.
2. Click Close Review and confirm.

Add Comment to an Entire Review

You can add comments to an entire review when it is at specific states. Comments appear in a review's activity feed. This is different to adding comments to a specific file in a review.

1. Open a review.
2. Click Action and select Comment on Review.
3. Optionally format your comment. To display how your comment will look click Preview. To continue editing click Edit.
4. When you have finished click Add Comments.

Edit a Review's Title

You can edit a review's title.

1. Open a review.
2. Click Action and select Edit Title.
3. Enter a new title and click Save.

Set Review Page and Pull Request Defaults

You can set the display defaults for the files in your reviews and pull requests:

• Display comments made by reviewers
• Display the findings made by chain runs inline inside files. If you switch this off, mouse over the margin to display findings.
• Display the entire contents of each file
• Display the previous version of each file
• Unify the previous and current differences of each file

You can also select a white space options, for example, Ignore White Space.

1. Open a review or a pull request.
2. Click Action and select Display Defaults.
3. Select options.
4. Click OK.

Manage Review Check Lists

When a user votes to approve a review or request changes they are typically required to select items from a check list. Administrators can create different types of check lists to satisfy different levels of severity. For example:

• Secure: a complex check list with high levels of tightly controlled compliance, for example, for licensing.
• Minimum: a small list with low levels of compliance, for example, for in-house testing.

For each stream the same check list is used for approvals and changes, however, you can associate a different review check list with each stream.

To create a review check list:

1. On the top navigation click Administration.
2. Select Review Check Lists.
3. Click New Check List.
4. Enter a name for the check list.
5. Enter items that you want your reviewers to select when voting to approve reviews or request changes. Review check lists may contain up to ten items. For example:
   • Coding standards
   • Export compliance regulations
   • Software complexity rules
6. Click Save.

To delete review check lists:

1. Select Administration | Review Check Lists.
2. Select one or more check lists.
3. Select Delete and confirm.

You can also select the default check list for a product.

Watch a Review

You can optionally watch a review when it is at specific states. When changes are made to the review you will be notified by email. You can select the notifications that you receive.

• To watch a review click Watch.
• To stop watching a review click Unwatch.

Administrators can configure changesets to automatically create reviews and run chains of experts. The first delivery of a changeset to Dimensions CM creates a new Pulse review whose title is the same as the delivery change comment. If the review is related to a specific request, subsequent deliveries that use the same request are grouped under the same review.

To create reviews and run chains you need to:

• Create delivery filters
• Configure which changesets automatically create reviews and run chains

Create Delivery Filters

Delivery filters enable administrators to control how reviews are created, and chains are triggered, for each stream. Every path in a changeset is matched against the patterns in a stream's delivery filter. If one or more paths pass through the filters, the changeset delivery creates reviews and runs chains. The default delivery filter for a product is used by any streams in that product that do not have an assigned delivery filter.

1. Select the product where you want to create a delivery filter.
2. On the sidebar select Delivery Filters.
3. Select New Delivery Filter.
4. In the Title box enter a name for the new delivery filter.
5. In the Note box optionally enter information about the filter.
6. Use the Changeset Path Filtering section to control which paths create reviews and run chains.
   In the Include these paths box do one of the following:
   • To only create reviews and run chains for specific paths, enter Ant style patterns (one pattern per line), for example:
     **/*.java
**/*.jsp
   • To create reviews and run chains for all changesets, leave blank.
   In the Exclude these paths box do one of the following:
   • To prevent specific paths from creating reviews and running chains, enter Ant style patterns (one pattern per line), for example:
     **/.DS_Store
**/tmp/**
   • To create reviews and run chains for the included changesets, leave blank.
7. If you have a system that delivers changes using specific user names, for example a build process, you can ignore those changesets. In the Exclude changesets delivered by these users box enter the user names (login IDs) on separate lines. For example, regbuild excludes all deliveries by the user with the login ID regbuild. Leave this box blank to disable it.
8. To ignore changesets with specific text in their delivery comments, in the Exclude changesets with these messages box enter message patterns, where * is a wildcard character and each pattern is on a separate line. For example, *NO_REVIEW* excludes deliveries where the message contains the keyword NO_REVIEW. Leave this box blank to disable it.
9. Click Save.
10. To make this the default delivery filter for this product, on the Delivery Filters page select the filter. Click Set As Default and then Make Delivery Filter Default. A product can have one default delivery filter.

Automatically Create Reviews and Run Chains

Administrators can configure which changesets delivered to streams automatically create reviews and run chains of experts.

1. Select the stream that you want to configure.
2. On the sidebar select Settings.
3. Select the Changesets tab.
4. To control which changesets delivered to this stream create reviews and run chains, from the Filter Changesets using Delivery Filter select a delivery filter.
5. Select the Reviews tab.
6. To specify a review check list to be used with new reviews created in this stream, from the Review Check List To Use list select one of the following:
• The product's default check list
• Any other list that has been defined
• No review check list
7. To specify the review rules for this stream, from the Review Rules To Use list select the product's default rule or any other rule that has been defined.
8. Select the Chain Execution tab.
9. To configure how this stream runs chains, from the Run chains list select one of the following:
• The product's default setting
• Run chains on this stream
• Disable chains on this stream
10. Click Save.

Chains and Experts

About Chains

Pulse includes experts that you can run in a sequence of steps called a chain. Experts enable you to:

• Perform builds
• Capture built artefacts
• Create and build Docker containers
• Deploy assets
• Fetch code from Dimensions CM
• Examine source code and artefacts for security vulnerabilities, report findings, and provide an opinion
• Perform static analysis
• Perform other activities such as fetch sources and send email notifications

Experts

The following experts are included with Pulse:

Build

• CM Build: if your team uses Dimensions Build and you have existing build configurations, you can run the configurations in Pulse.
• Jenkins: a continuous integration server that you can use with Pulse to execute, and report on, builds of changesets as they are delivered.
• Maven: builds and distributes artefacts.
• Script: runs a batch script (Windows) or shell script (Linux).
• Ant: runs an Ant build.
• Gradle: runs a Gradle build.
• Makefile: runs a build using a makefile.
• MSBuild: runs an MSBuild.
• Visual Studio Build: runs a Microsoft Visual Studio Build.

Capture Artefacts

• Capture to DA CodeStation: captures built artefacts to Deployment Automation CodeStation. These artefacts represent deployable items such as files, images, databases, configuration materials, or any other assets associated with a software project.
• Capture to Dimensions CM: captures built artefacts to a Dimensions CM stream.
• Capture to Directory: captures built artefacts to a directory.
• Capture to SCP/SFTP: captures built artefacts to a workspace using secure copy (SCP) or to remote network server using Secure File Transfer Protocol (SFTP).

Container

• Build a Docker Image: builds a Docker image in which you can run applications.
• Run a Docker Container: creates a Docker container in which you can run Docker images.
• Run Script in Docker Container: use a command to execute a script in a Docker container that is running, without logging into that container.

Deployment

• DA Deployment: imports and deploys a component using Deployment Automation.
• DA Generic Process: runs a generic process in Deployment Automation.

SCM

• Fetch from Dimensions CM: fetches sources from a Dimensions CM repository.

Security and Compliance

• Dependency Vulnerabilities: finds third party dependencies in your code that may have known security vulnerabilities.
• Fortify SCA (Static Code Analyzer): analyzes your source code and identifies the root causes of security vulnerabilities.
• WhiteSource: identifies all the open source components and dependencies in your build, reports any known security vulnerabilities, and lists their licenses.

Static Analysis

• Checkstyle: enforces coding standards.
• Kiuwan: measures, analyzes, and verifies the quality of your code.
• PMD: analyzes source code and finds common programming bugs.
• SonarQube: inspects the quality of your code.

Other Experts

• Changeset Summary: counts the number of files added, deleted, and modified in each changeset.
• Halt on Failure: stops a chain if the previous expert in the chain failed.
• Notification: sends notifications if a chain succeeds and/or fails.

For details about each expert and how to configure it see Configure Experts.

Expert Attributes

Experts have these optional attributes:

• Execution state: Success, Failure, Unstable, or Aborted.
• Measurement: A set of single-valued judgments about source code. For example, 24,847 might be a measurement of lines of code, and High might be a measurement of the security risk level.
• Finding: When issues are identified, experts annotate the source code and provide a "severity" level to indicate how serious an issue is. Annotations are displayed in tabular form in the Experts section of a review page and some experts also annotate the files in the Contents section. Some findings may include a link to a web page that provides more details. See Inspect Expert Results.
NOTE The Dependency Vulnerabilities and WhiteSource experts only annotate the Experts section.

Create Chains

Overview

A chain is comprised of a sequence of steps and each step can run one expert. For example, this chain has four steps:

• Step 1: Maven builds the stream.
• Step 2: Halt On Failure stops the chain if the previous step fails.
• Step 3: Capture WAR file captures the targets to the stream.
• Step 4: DA Deployment deploys the application to an environment

Chains are owned by streams. You can configure multiple, independent chains to run on the same stream, for example:

• The first chain runs on every delivery and performs brief static analysis.
• A second chain runs at midnight every day, performs more thorough analysis, and deploys software.

Create Chains

1. Select the stream where you want to create a chain.
2. On the sidebar select Chains.
3. Click New Chain.
4. Enter a title and click Save.
5. On the Configuration tab, optionally add a note that describes the chain.
6. Click Save.

Choose Changesets to Run Chains On

You can choose the changesets that a chain runs on. By the default a chain runs on all the changesets in a stream.

1. Select a stream, on the sidebar select Chains, and select a chain.
2. Click Edit and select the Configuration tab.
3. In the Matching Paths section enter Ant patterns, one pattern per line. To trigger the chain, at least one path in the changeset must match the pattern. Leave blank to run the chain on all changesets in the stream.
4. Click Save.

Schedule Chains

You can set a schedule when a chain will run.

1. Select a stream, on the sidebar select Chains, and select a chain.
2. Click Edit and select the Configuration tab.
3. From the When to Run list select how often the chain will run, for example, when every changeset is delivered to the stream.
4. Click Save.

Add Steps to Chains

1. Select a stream, on the sidebar select Chains, and select a chain.
2. Click Edit and select the Steps tab.
3. From the Add Step list select an expert or action from one of the categories.
4. Add a name for this step.
5. Configure the step. Each expert or action has different parameters, some of which are mandatory. For details see Configure Experts.
6. Click Save.
7. Add more steps as required.
8. To change the running order of steps in the chain, drag and drop them to different positions.
9. To remove a step from a chain, select it, and click Remove.

Add Capabilities to Chains

You can add capabilities to chains. Capabilities describe an agent's environment, for example:

• A specific operating system
• High memory

You can add multiple capabilities to a chain. When the chain runs it matches its required capabilities with the capabilities of the agents. For example, if a chain requires Windows Server 2016 and 64GB of memory, add WindowsServer2016 and 64gbMemory as required capabilities on the chain. The chain only runs on the agents that match these capabilities.

1. Select the chain where you want to add capabilities.
2. Click Edit and select the Configuration tab.
3. In the Required Capabilities field enter a comma-separated list capabilities. Leave blank to run this chain on any agent.
4. Click Save.

Add Variables to Chains

You can use variables in chains to tailor how chains behave on each agent or to provide a way of reusing the same value in multiple steps. For instance, a variable is defined on an agent to describe where a compiler is installed. This allows a chain to reference that location via the variable instead of a fixed value in the step's configuration. When the chain is run on the agent, the references to the variable are replaced with the values that have been defined for the agent.  Similarly, two or more steps may need the same value, in which case you can define a variable on the chain with that value, and reference it on each step. An agent works out what a value should be for a variable in this order:

1. The variable definition on the chain.
2. The agent definition.

If there is no definition for the variable on the agent, it is assumed to be blank.

Example:

• An administrator creates a chain that will use Maven and can run on two agents.
• Maven is installed on different locations on each agent.
• The administrator adds a variable to each agent, MAVEN_HOME, which defines the location of the Maven installation on that agent.
• The administrator adds the variable ${MAVEN_HOME} in the chain step.
• When the chain runs on an agent, the value of the variable is substituted with the value for the Maven location on that agent.

1. Select the chain where you want to add variables.
2. Click Edit and select the Variables tab.
3. Click Add Variable.
4. Enter a variable name and value pair, for example: MAVEN=M2_HOME
5. Click Save.

Specify Stream Content to be Analyzed

When a chain runs you can specify the stream content that will be fetched to the work area and analyzed. By default the entire contents are fetched, which may be a slow operation depending on the size of the stream.

1. Select a chain.
2. Click Edit and select the Configuration tab.
3. In the What to Analyze section:
   • To clean the workspace where the chain will run, select Clean workspace before fetching sources.
   • To fetch no items, unselect Fetch stream content.
   • To analyze the entire stream, select Fetch stream content and leave the content field blank.
   • To analyze part of the stream, select Fetch stream content and in the content field enter Ant patterns (one per line) that match specific paths.
4. Click Save.

View all Chains in a Stream

You can view all the chains that have been added to a stream.

1. Select the stream.
2. On the sidebar select Chains.
3. Select a chain to view its results, configuration, and steps.

Share Chains

You can export chains that you created and share them with your team.

1. Open the chain that you want to export.
2. From the Actions menu select Export Chain.
3. Navigate to a folder and save as a .chain file.

You can import chains from members of your team:

1. Select a stream where you want to import a chain.
2. On the sidebar select Chains,
3. From the Actions menu select Import Chain.
4. Navigate to the folder containing the .chain file, select the file, and click Open.
5. Click Import.

Additional Chain Configurations

You can set these additional configurations:

• Select a policy for retaining the logs created by a chain.
• Stop a chain after the failure of any step. For example, you have a chain with multiple steps and the last step is a build. If any of the previous steps fails, the chain stops, and the build is not executed. You can use this option instead of adding the Halt on Failure expert.
• Only queue one copy of a chain at any time.

1. Open a stream, on the sidebar select Chains, and select a chain.
2. Click Edit and select the Configuration tab.
3. Select Stop chain on first step failure.
4. Select Allow only one queued chain run.
5. In the Retention Policy section select a policy for keeping the logs in this chain. Retention policies are configured by your administrator.
TIP You can override the retention policy for each log in a chain.

Set Retention Policies for Chain Logs

By default chain logs are kept for 30 days. Administrators can create custom retention policies and apply them to chains.

1. On the top navigation click Administration.
2. Select Retention Policies.
3. Click New Retention Policy.
4. Enter a title and description for the retention policy.
5. Specify the number of items to be retained in the log, for example: 100
6. Specify how many days items in the log will be retained, for example: 365 (one year)
7. Specify the maximum size of the log in megabytes, for example: 1024 (a gigabyte). When the log reaches the defined size the oldest items will be purged.
8. Click Save.

Inspect Expert Measurements and Findings

You can inspect expert results and findings in:

• The review where the chain ran
• The associated changeset

Results include:

• Finding for each expert, including Errors, Warnings, Failures, and Information.
• Measurements for each expert. Measurements are a set of single-valued judgments about source code, For example, 24,847 might be a measurement of lines of code, and High might be a measurement of the security risk level.

The state of each chain run is indicated by these icons and colors:

The chain run was successful

The chain run completed but failed

The chain run completed but is unstable

The chain run is in progress

The chain run has not started

The chain run was abandoned

The chain run was aborted or terminated

To inspect expert results and findings:

1. Select a suite, product, or stream.
2. On the sidebar click Reviews or Changeset History. Scroll down to a review or changeset and select it.

The Chain Runs section displays results for all the experts that ran on this review. Expand each expert to view its measurements and findings. Some experts may include a link to a web page that provides more details.

The Contents section of a review displays a list of all the files in the review and the number of expert findings for each file.

1. To view an expert's findings for a specific file, in the Contents section select the file.
2. From the Show menu select Show Entire File.
3. Scroll down the file until you see results that you want to inspect. Each line number with a result has a color that represents one of these categories:
   • Blue: information
   • Dark Orange: error
   • Orange: warning

   A line may have multiple results.

4. Mouse over a line number to display information.

View Chain Run Details

You can examine each chain run in detail and view expert findings.

1. Select a stream.
2. On the sidebar select Chains.
3. Select a chain. A list of the chain's recent runs is displayed. Each run shows:
   • The run's state icon
   • The run ID
   • The changeset where the chain ran
   • The duration of the run
   • The instance of Pulse that ran the chain
4. Click a chain run ID to view more details. Click a tab to view its details:
   • Console: displays the output log for each expert in the chain. Expand an expert to view its logs. Logs are expanded by default if they include failures. Warnings and messages are color coded. To filter the information that is displayed, select a log threshold level. To download a log, from the Actions menu select Download Logs. Log files use LF line separators.
   • Findings: displays the findings for each expert in the chain, including Errors, Warnings, Failures, and Information. Expand each expert to view more details.
   • Measurements: displays the measurements for each expert in the chain. Measurements are a set of single-valued judgments about source code, For example, 24,847 might be a measurement of lines of code, and High might be a measurement of the security risk level. If any items were captured, a report is attached to this tab.
   • Activity: displays the activity for each expert in the chain including: when the expert ran, the changeset where it ran, and the associated review. Some experts include a link to a web page where you can view additional details.
   • Changesets: lists all the changesets consumed by this run.
   • Requests: lists all the requests associated with this run.
   • Contents: lists all the files that have changed since the previous run.
5. To run this chain again on the same changeset, click Re-run.
6. To override the default log retention policy for this chain and keep the log, click Keep Forever.

Edit and Delete Chains

Administrators can edit and delete chains:

1. Select the stream containing the chain that you want to edit or delete.
2. On the sidebar select Chains.
3. To delete one of more chains, select them from the list, click Delete, and confirm.
4. To edit a chain, select it, and click Edit.
5. Edit the chain's configuration, add and remove steps, and change their running order, and add variables.
6. Save the changes.

Diagnose Chains

If you are having issues with a chain you can diagnose it by running it manually.

To diagnose the latest changeset, select the stream that contains the chain that you want to diagnose and do one of the following:

• On the sidebar select Chains, select the chain, and click Run on Latest Changeset.
• On the sidebar select Changeset History, select the latest changeset, and from the Actions menu select Run Chains.

To diagnose a specific changeset:

1. Select the stream that contains the chain that you want to diagnose.
2. On the sidebar select Chains.
3. Select the chain.
4. On the Runs tab select a specific run.
5. Click Re-run.

Repository Browser

You can browse the streams and projects in a CM repository and view the contents of folders and files. You can browse the current (tip) version of a stream or previous versions. Each file or folder that you open displays information about:

• The user who delivered the changes
• The changeset ID and delivery message
• The health of the changes
• The review associated with the changes

Files also display:

• Findings from experts when a chain has run on the stream
• Peer review comments
• Colored code syntax

Folders also display:

• A summary of problems with any associated reviews
• The number of contributors who made changes
• (Optional) A readme file that describes the folder's contents

Browse the Contents of Streams

1. Open a stream.
2. On the sidebar click Code. The Content tab displays the most recent changes to the stream.
3. Navigate to a folder or file to view its contents.

Browse the Previous Versions of Streams

1. Open a stream
2. On the sidebar click Code.
3. Do one of the following:
   • To browse the entire contents of a previous changeset, select the History tab, select a changeset, and click View at Version. On the Content tab browse the files and folders in the changeset.
   • To view a previous version of a file or folder, on the Content tab navigate to the file or folder. Click the History tab, select a version of the file or folder and click View at Version.
4. To revert to the tip of the stream, click View at Tip.

Add Descriptions of Folder Contents

(Optional) In each folder you can create a file that describes its contents. You can write the content in the following formats:

Pulse searches each folder for one of these file types in the order specified in the table above. The first file that is found is rendered and the content displayed at the bottom of the folder page.

Add Comments to Files

You can add comments to files and collaborate with team members. This is similar to adding comments to files in reviews.

Configure Experts

Pulse includes bundled and built-in experts:

• A built-in expert can only be upgraded or replaced when you update Pulse. It is core to the product and is not expected to change without changes to Pulse.
• A bundled expert is a standard expert that is shipped with Pulse. You can overwrite it as long as the newer version is backwards compatible with your version of Pulse.
• Additional and upgraded experts will be made available for download from the Community web site.
• You can write your own expert implementations if you have site-specific requirements or in-house utilities that you want to integrate with Pulse.

Except where specified all experts are either bundled or built-in.

Each expert section below contains some, or all, of the following information:

• Overview: what the expert does and why you would use it.
• Prerequisites: external tools that the expert depends on.
• Configure: global server configuration files that must be set up, the fields that you enter when configuring an expert, and whether the expert needs to be in a chain that uses a workspace.

  A workspace is a directory that is allocated to a chain when it runs. The workspace is populated with the stream content (its files), so that the experts in the chain can analyze the stream content and report findings back to Pulse. Workspaces are limited and a chain may be delayed until one is allocated. Workspace directories are located in the Pulse data directory.

The notation ${dataDir} refers to the Pulse data directory on the Pulse server, for example, C:\ProgramData\Serena\Dimensions CM\Pulse or /opt/serena/dimensions/14.4/cm/pulse_data.

Manage Experts

The Plugins page displays all the experts that are currently installed in your CM environment. The plugins are separated into these categories:

• Build
• Capture artifacts
• Container
• Deployment
• Other
• SCM
• Security and Compliance
• Static Analysis

Administrators can:

• Check what plug-ins are installed
• Enable and disable plug-ins
• View the results of recent expert runs

1. On the top navigation click Administration.
2. Select Plugins.
3. For each plug-in do the following:
   • Enable or disable the plug-in.
   • View the last runs.

For details about installing additional plug-ins see the Dimensions CM Administrator's Guide.

Capture to DA CodeStation

Overview

Captures built artefacts to Deployment Automation CodeStation. These represent deployable items such as files, images, databases, configuration materials, or anything else associated with a software project. For information about configuring and using Deployment Automation (DA) click here.

Prerequisites

• The Deployment Automation server must be installed in a network location where the expert can connect to.
• A working component configured in your Deployment Automation server for the expert to invoke.

This expert supports DA version 6.1.5.

Configure

Configure Expert Settings

Capture to Dimensions CM

Overview

Captures built artefacts to a Dimensions CM stream.

Configure

Capture to Directory

Overview

Captures built artefacts to a directory.

Configure

Capture to SCP/SFTP

Overview

Captures built artefacts to a workspace using secure copy (SCP) or to remote network server using Secure File Transfer Protocol (SFTP).

Configure

Changeset Summary

The Changeset Summary expert is a built-in expert that counts the number of files added, deleted, and modified in each changeset. To track of the number of changes, which indicates the level of code churn, you can configure this expert to run on every changeset.

This expert has no prerequisites or configuration and does not require a workspace because it uses the changeset information.

Checkstyle

Overview

The Checkstyle expert is a bundled expert that uses the Checkstyle development tool to check that Java code adheres to a defined coding standard.

Use Checkstyle to help you comply with Java coding standards by automating code checking. Checkstyle is highly configurable and can support most coding standards, for more information see: http://checkstyle.sourceforge.net

This expert has no prerequisites (the Checkstyle 5.7 libraries are embedded in the expert so there are no external tools to install).

Configure

Create Server Configuration File

To customize the Checkstyle rules to be checked by this expert, create an XML configuration file in ${dataDir}/conf/experts/com.serena.starlight/checkstyle/ on the Pulse server. The default filename is config.xml.

The Checkstyle expert searches for a configuration file in the following sequence:

1. If the field Configuration File Name specifies a filename, looks for that file in ${dataDir}/conf/experts/com.serena.starlight/checkstyle/.
2. If the field Configuration File Name is empty, looks for config.xml in the same directory on the Pulse server.
3. If the field Configuration File Name is empty, and config.xml does not exist, uses a built-in configuration based on Sun Coding Conventions.

Configure Expert Settings

When you add this expert to a chain in Pulse modify the following properties:

Checkstyle operates on source code files so add the Checkstyle expert to a chain that populates a workspace.

CM Build

Overview

If your team uses Dimensions Build and you have existing build configurations, the bundled CM Build expert enables you to run the configurations in Pulse. Dimensions Build is a build management, execution, and monitoring tool that is part of Dimensions CM. For details see the Dimensions CM Build Tools User's Guide.

Prerequisites

A build configuration, created in Dimensions Build, for each stream that you are going to build.

Configure

When you add this expert to a chain configure it as follows:

1. Enter a name for this step in the chain.
2. Select a CM user account to be used to run the build:
   • Service account: use the account and credentials of the user current logged into Pulse. This is the account that was used to populate the work area associated with the stream.
   • Custom account: use a different CM user account. Specify the user name and password.
3. Set Configure using command line to one of the following:
   • Yes: enter a BLD command and specify a poll rate. For details of the BLD command see the Dimensions CM Command-Line Reference.
   • No: configure CM Build using the fields described below.

CM Build manages its own workspaces so you can add it to a chain that does not populate a workspace.

DA Deployment

Overview

The DA Deployment expert is a bundled expert that allows you to integrate Pulse with Deployment Automation (DA) and to publish and deploy artefacts from a Dimensions CM stream.

You can use the DA Deployment expert to automate the path to production for your application. For example, the expert can support continuous delivery by:

• Publishing files from a stream to a Deployment Automation server as a new component version.
• Adding a Deployment Automation status to a new published version.
• Deploying the new published version.

Prerequisites

The Deployment Automation server must be installed on your network, but not necessarily on the Pulse server, where this expert can connect to it. The DA Deployment expert has been tested with Deployment Automation server version 6.1.1.

You will need a working application process configured in your Deployment Automation server for the DA Deployment expert to invoke.

Configure

Create Server Configuration File

The following DA Deployment expert properties file is usually required: ${dataDir}/conf/experts/com.serena.starlight/sdadeploy/sda-pulse-expert.properties

The property below identifies the location of the Deployment Automation server, if the default value shown is correct you do not need to edit it:

Configure Expert Settings

When you add this expert to a chain in Pulse modify the following configuration fields:

Deployment Automation normally operates on binary files so add the DA Deployment expert to a chain that populates a workspace with built artefacts.

DA Generic Process

Overview

The DA Generic Process expert is a bundled expert that allows you to integrate Pulse with Deployment Automation (DA) and run a DA global process on a specific resource. For example, you can use this expert to run a regular, repeated process when updated artefacts are delivered.

Prerequisites

The Deployment Automation server must be installed on your network, but not necessarily on the Pulse server, where this expert can connect to it. The DA Generic Process expert has been tested with Deployment Automation server version 6.1.1.

You will need a working global process configured in your Deployment Automation server for the DA Generic Process expert to invoke.

Configure

Create Server Configuration File

The following DA Generic Process expert properties file is usually required: ${dataDir}/conf/experts/com.serena.starlight/sdaprocessexecutor/sda-pulse-expert.properties

The property below identifies the location of the Deployment Automation server, if the default value shown is correct you do not need to edit it:

Configure Expert Settings

When you add this expert to a chain in Pulse modify the following fields:

Deployment Automation normally operates on binary files so add the DA Generic Process expert to a chain that populates a workspace with built artefacts.

Dependency Vulnerabilities

Overview

The Dependency Vulnerabilities expert is a bundled expert that integrates the Open Web Application Security Project (OWASP) dependency-check tool that can scan Java, .NET, and Python applications and their dependent libraries.

This expert identifies vulnerable dependencies in the analyzed stream and displays the findings in the Experts section of a Pulse Review page. One finding per vulnerability is displayed and there can be multiple vulnerabilities for each dependency. Each finding contains the ID of the vulnerability and the name of the dependency where it was found. A report file can be viewed from the Review page.

Prerequisites

There is no external software to install (the dependency-check 1.3.6 library is embedded in the Dependency Vulnerabilities expert). However, the expert relies on data from the National Vulnerabilities Database (NVD) web site to find vulnerabilities and requires access to the internet to download and update data.

On the first run the expert creates:

• The folder ${dataDir}/conf/experts/com.serena.starlight/dependencyvulnerabilities/data/
• The file cve.2.9.h2.db that is updated from the Common Vulnerabilities and Exposures (CVE) data . Each run automatically updates the CVE data if autoupdate in the properties file is set to true.

Configure

Create Server Configuration File

The properties file is optionally located in ${dataDir}/conf/experts/com.serena.starlight/dependencyvulnerabilities/dependencycheck-pulse-expert.properties. It contains configuration properties for both the Dependency Vulnerabilities expert and its embedded dependency-check library. You only need to create this file if you need to override one of the default values.

Configure Expert Settings

When you add this expert to a chain in Pulse modify the following fields:

For more information about analyzers see this web page.

The Dependency Vulnerabilities expert may report false-positive dependencies. For example, you consume a vulnerable library but you do not use the vulnerable functionality, or the vulnerability only applies in circumstances that does not apply to you. You can suppress any CVE by passing the suppression XML file with CVE suppressions (Suppression file property) or the CVE ID list (CVE suppression list property). For more information about suppression see this web page.

The dependency-check analyzers operates on binary files so add the Dependency Vulnerabilities expert to a chain that populates a workspace with built artefacts.

Run a Docker Container

Overview

Creates a Docker container, which is a runtime instance of a Docker image.

Configure

Build a Docker Image

Overview

Creates a Docker image, which is an ordered collection of root filesystem changes and the corresponding execution parameters that you can use in a container runtime. An image typically contains a union of layered filesystems stacked on top of each other. You can optionally push the image to a Docker repository.

Configure

Run Script in Docker Container

Overview

Enables you to use a command to execute a script in a Docker container that is running, without logging into that container.

Configure

Halt on Failure

This expert does not have any parameters.

Fortify SCA

Overview

The Fortify SCA expert is a bundled expert that analyzes the source code of an application for security issues. Static Code Analyzer (SCA) identifies the root causes of software security vulnerabilities and delivers accurate, risk-ranked results with line-of-code remediation guidance.

Prerequisites

The Fortify SCA expert requires Fortify SCA (and any tools that it will use, such as Microsoft Visual Studio) to be installed and configured correctly for the named user account that Tomcat will run as.

Configure

Create Server Configuration File

The Fortify SCA expert's server configuration file is mandatory and is located in: ${dataDir}/conf/experts/com.serena.starlight/hpfortify/hpfortify-pulse-expert.properties

Example server configuration file:

sourceAnalyzerPath=C:\\Program Files\\HP_Fortify\\HP_Fortify_SCA_and_Apps_4.30\\bin\\sourceanalyzer.exe
reportGeneratorExecutablePath=C:\\ProgramFiles\\HP_Fortify\\HP_Fortify_SCA_and_Apps_4.30\\bin\\ReportGenerator.bat 
visualStudioExecutablePath=C:\\Program Files (x86)\\Microsoft Visual Studio 10.0\\Common7\\IDE\\devenv.exe

Configure Expert Settings

When you add this expert to a chain configure it as follows:

1. Enter a name for this step in the chain.
2. Select a custom translation option:
   • Yes: use a custom translation string. Enter a string in Custom translation options but only include phase options and exclude '-b'.
   • No: select translation options (see the table below).
3. For Analysis phase optionally enter additional rulepack files or folders, one per line. You can specify an absolute path or one that is relative to the root of the stream. Use the sourceanalyzer Ant task rules attribute.
4. To create a PDF of the report select Generate PDF report and enter the path of a report template. You can specify an absolute path or one that is relative to the root of the stream. If you do not specify a report template the default is used. Use the ReportGenerator utility's template option.

Jenkins

Overview

The Jenkins expert is a bundled expert that can invoke a Jenkins job on a remote Jenkins server. For example, use it to run a continuous integration build against each changeset as it is delivered and report the build time.

Prerequisites

The Jenkins server must be installed on your network, but not necessarily on the Pulse server, for this expert to connect to. See the Jenkins web site for more information about installing.

You must define a job on your Jenkins server that the expert will invoke.

Optionally add build parameters to the job so that information about the Dimensions CM stream and changeset are available in your build. Alternatively, allow the Jenkins expert to make any configuration change to the Jenkins job automatically (no manual changes to your Jenkins job are needed).

If you add the build parameters manually, select the option This build is parameterized in your Jenkins job configuration page and add each build parameter as a String Parameter. The values Default Value and Description in Jenkins are not important.

Configure

When you add this expert to a chain in Pulse modify the following properties:

If your Jenkins job requires a build authentication token before it can be triggered (see this Jenkins wiki page for details) add the token to the end of the Jenkins URL, for example: http://hostname:port/jenkins/job/MyProject/?token=buildtoken

The Jenkins expert:

• Uses the parameters after the question mark in the build request URLs that are sent to the Jenkins server.
• Supports freestyle and pipeline jobs.

Jenkins manages its own workspaces so you can add the Jenkins expert to a chain that does not populate a workspace.

Configure the Output Log

By default, the last 100 lines from the Jenkins log are displayed in the output log of a chain run and stored in the database.

To change the number of lines that are displayed and stored:

1. Open the Jenkins property file: ${dataDir}/conf/experts/com.serena.starlight/jenkins/jenkins-pulse-expert.properties
2. Modify the value of this property: jenkins.console.lines.count 

Kiuwan

Overview

The Kiuwan expert is a bundled expert that integrates with Kiuwan Software Analytics in the Cloud, an online code quality and security service. If you are signed up to the Kiuwan service use this expert to:

• Track the quality and security of your changesets.
• Make that information visible in Pulse reviews and reports.

Prerequisites

You must have an active account (username and password) for the Kiuwan service, have logged into the service, and configured an application name for your stream.

You must install the Kiuwan Local Analyzer on the Pulse server.

Configure

Create Server Configuration File

The Kiuwan expert's server configuration file is mandatory and is located in: ${dataDir}/conf/experts/com.serena.starlight/kiuwan/kiuwan-pulse-expert.properties

Configure Expert Settings

When you add this expert to a chain in Pulse modify the following fields:

The properties Username, Password and Application are only optional if they have been configured in the server configuration file.

The Kiuwan Local Analyzer operates on source code files so add the Kiuwan expert to a chain that populates a workspace.

Maven

Overview

The Maven expert is a bundled expert that executes Maven goals.

Prerequisites

Maven must be installed on an executor and added as an environmental variable.

Configure

When you add this expert to a chain in Pulse modify the following properties:

Ant

Overview

The Ant expert is a bundled expert that runs Apache Ant builds. Apache Ant is an open-source build automation tool.

Prerequisites

Ant must be installed on an agent and added as a capability.

Configure

When you add this expert to a chain in Pulse modify the following properties:

Gradle

Overview

The Gradle expert is a bundled expert that runs Gradle builds. Gradle is an open-source build automation tool.

Prerequisites

Gradle must be installed on an agent and added as a capability.

Configure

When you add this expert to a chain in Pulse modify the following properties:

Makefile

Overview

The Makefile expert is a bundled expert that runs GNU Make builds. Make is an open-source build automation tool.

Prerequisites

Makefile must be installed on an agent and added as a capablity.

Configure

When you add this expert to a chain in Pulse modify the following properties:

MSBuild

Overview

The MSBuild expert is a bundled expert that runs the Microsoft Build Engine, a platform for building applications.  

Prerequisites

MSBuild must be installed on an agent and added as a capability.

Configure

When you add this expert to a chain in Pulse modify the following properties:

Visual Studio Build

Overview

The Visual Studio Build expert is a bundled expert that uses Microsoft Visual Studio to build applications and to create assemblies and executable programs. 

Prerequisites

Visual Studio Build must be installed on an agent and added as a capability.

Configure

When you add this expert to a chain in Pulse modify the following properties:

Fetch from Dimensions CM

Overview

A bundled expert that checks out source items from a Dimensions CM repository.

Configure

Notification

Overview

Sends notifications by email if a chain succeeds or fails.

Configure

PMD

Overview

The PMD expert is a bundled expert that scans Java source code (and other languages) and looks for potential problems such as bugs, dead code, suboptimal code, overcomplicated expressions, and duplicate code. You can use it to find common programming flaws during your code review process. PMD is configurable and can find many different issues, for more information see the PMD web site.

This expert has no prerequisites (the PMD 5.3.7 libraries are embedded in the expert so there are no external tools to install).

Configure

When you add this expert to a chain in Pulse modify the following configuration fields:

The PMD command line option column shows how each PMD expert configuration field maps to the PMD command line tool. For details see: http://pmd.sourceforge.net/pmd-5.2.3/usage/running.html.

PMD operates on source code files so add the PMD expert to a chain that populates a workspace.

Script

Overview

The Script expert is a bundled expert that enables you to specify one of the following:

• An operating system command.
• The path to a script, for example, a Windows batch file or Linux shell script.

Configure

When you add this expert to a chain, configure it as follows:

1. Enter a name for this step in the chain.
2. From the Script Type list select one of the following:
   • Use inline command and enter an operating system command in the Command line box.
   • Use file path and enter the path in the File path box.
3. From the Script Language list select Windows Batch or Shell Script.

You can use the following environment variables:

• PULSE_STREAMTITLE: the name of the project or stream.
• PULSE_STREAMVERSIONID: the project or stream version.
• PULSE_SCMCONNECTIONURI: a unique identifier for the Dimensions CM database.
• PULSE_LOGINNAME: the user who made the delivery.
• PULSE_MESSAGE: the commit message for the delivery.
• PULSE_DIRECTORY: the location of the workspace containing the source code.
• CURRENT_DIR: same as PULSE_DIRECTORY (also set as the working directory of the script).

All the variables in the environment.properties file are available to the script as environment variables.

If the script exits with an exit code of 0, it is a SUCCESS. If the script exits with a non-zero exit code, it is a FAILURE.

SonarQube

Overview

The SonarQube expert is a bundled expert that runs static analysis against source code in a repository and reports findings and metrics. You can use it to analyze your source code on every changeset, or on a regular schedule, and optionally record the defects and metrics in your SonarQube server.

Prerequisites

The SonarQube expert requires SonarQube Runner, a command line application, to be installed and configured on the Pulse server. A SonarQube server must be installed on your network (not necessarily on the Pulse server) for this expert to connect to. For details see the SonarQube web site.

SonarQube expert uses the Web Service Java Client to make REST requests to a SonarQube server and has been tested with SonarQube server versions 5.6.x (Long Term Support) and 6.x.

The server configuration file ${dataDir}/conf/experts/com.serena.starlight/sonarqube/sonarqube-pulse-expert.properties must be present and set up correctly before you can use SonarQube expert.

Configure

Create Server Configuration File

The SonarQube expert properties file is mandatory and is located in: ${dataDir}/conf/experts/com.serena.starlight/sonarqube/sonarqube-pulse-expert.properties

If you do not specify an optional property SonarQube Runner uses the default value specified in ${SONAR_RUNNER_HOME}/conf/sonar-runner.properties.

You can configure additional supported parameters in ${SONAR_RUNNER_HOME}/conf/sonar-runner.properties.

Configure Expert Settings

When you add this expert to a chain in Pulse modify the following properties:

The properties Username and Password are optional and are only required in specific security situations, see the SonarQube web site for details.

The SonarQube Runner operates on source code files so add the SonarQube expert to a chain that populates a workspace.

WhiteSource

Overview

The WhiteSource expert is a bundled expert that identifies all the open source components and dependencies in your build, reports any known security vulnerabilities, and lists their licenses.

Prerequisites

• An active organization (and API token) for the WhiteSource SaaS service.
• Access to the WhiteSource administrative site.
• A product and project to report results to.
• The project token.

Configure

Create Server Configuration File

The WhiteSource expert's server configuration file is located in: ${dataDir}\conf\experts\com.serena.starlight\whitesource\whitesource-pulse-expert.properties

Example server configuration file:

whitesourceServerUrl=https://saas.whitesourcesoftware.com

Configure Expert Settings

When you add this expert to a chain in Pulse, specify the following fields:

Reports

Dashboard Reports

Dashboard reports display statistics and trends that are generated from the activity in your streams. Reports are scoped to the suite, product, or stream from where you run them. If you are an administrator you can create and manage reports.

Create Reports

You can create a new report and add multiple panels. Each panel can have one of the following:

	Metric: a chart with a single value, for example, the number of deliveries made.
	Line Chart: an illustration of data points at successive time intervals. Mouse over a time interval to display the data for each value.
	Pie Chart: a circular statistical graphic that is divided into sectors to illustrate numerical proportion. Mouse over a sector to display its value. The value in the middle is the first metric's numeric value as a percentage of the total.
	Bar Chart: a diagram in which the numerical values of variables are represented by the height or length of lines, or rectangles of equal width.
	Table: a set of data arranged in rows and columns.

1. Select the level where you want to create the report (a suite, product, or stream).
2. On the sidebar select Reports.
3. From the Actions menu and select Create View.
4. In the Title box enter a name for the new view.
5. In the Note box optionally enter information about the report.
6. Click Save.
7. To add a panel to the report do the following:
   1. Click Add panel.
   2. Enter a name for the panel.
   3. Select a display type.
   4. Select Report on difference from previous value to show how a value has changed over time. For example, to show a trend such as the number of defects.
   5. Select a width for the display (as a percentage of the width of the main window).
   6. Select one of these metric types:
      • Review Metrics
      • Expert Metrics (only available for streams)
   7. Click Add metric and select one from the list. You can add multiple metrics to these display types: pie charts, bar charts, and tables.
   8. Click Save.
8. To add more panels repeat the previous step.
9. Drag and drop panels to change their positions in the report.

Run Reports

1. Select the level at which you want to run the report (a suite, product, or stream).
2. On the sidebar select Reports.
3. From the Reports list select a pre-defined report.
4. (Optional) Select a time period for the report (start and end dates).
5. To refresh the report click Refresh.

Manage Reports

Administrators can delete and edit reports.

1. Select the suite, product, or stream where the report is located.
2. On the sidebar select Reports.
3. From the Reports list select a report.
4. To delete the report, from the Actions menu select Delete and confirm.
5. To edit the report's title and description, from the Actions menu select Edit Title & Notes.
6. To edit a report panel click Edit in its title bar. Modify the settings and click Save.
7. To remove a panel click Delete in its title bar and confirm.
8. Drag and drop panels to change their position in the report.

Changeset Reports

The Changeset report displays information about changeset creation and health.

1. Select the level where you want to create the report (a suite, product, or stream).
2. On the sidebar select Reports and then Changesets.
3. Select a date range from the filter on the top right. The default is the last 3 months.

The Changesets Delivered section displays:

• A graph of changeset delivery frequency over the date range.
• The total number of users who contributed and their deliveries.

The Changesets by State section displays:

• Colored tiles that indicate changeset health and display the total number of changesets for each state.
• A graph of the health of changeset deliveries over time. You can display this graph:
  • Stacked: displays the changeset states stacked one on top of each other. The pop up label displays the total number of changeset states per day.
  • Stream: displays each changeset state separately and shows the trend. The pop up label displays the total number of changeset states per day.
  • Expanded: similar to Stacked but the graph is expanded to 100%. The pop up label displays the changeset states as a percentage of the total number of deliveries for each day.

The Changesets Details section lists all the changesets delivered over the date range. Click a changeset or review label to view more details.

Request Reports

The Requests report displays information about request creation.

1. Select the level where you want to create the report (a suite, product, or stream).
2. On the sidebar select Reports and then Requests.
3. Select a date range from the filter on the top right. The default is the last 3 months.

The Requests Creation graph displays the creation of requests over time. There is a tab for each request type.

The Requests by state section lists the total number of requests per state. Click a state to display a list of all the associated requests. Click a request to view its details.

Review Reports

The Review report displays information about reviews created by changeset deliveries.

1. Select the level where you want to create the report (a suite, product, or stream).
2. On the sidebar select Reports and then Reviews.
3. Select a date range from the filter on the top right. The default is the last 3 months.

The Reviews tab displays:

• A graph that shows the frequency of review creation for the selected date range.
• A list of all reviews by state. Click a state to display a list of all the associated reviews. Click a review to view its details.

The Top Reviewers tab displays the users who reviewed the most reviews.

The Top Owners tab displays the users who own the most reviews.

The Top Rework tab displays the users who have had the most reviews sent for rework.

Contributor Reports

You can display a list of all the developers that have made deliveries. The tiles display the number of changesets delivered and the health of their chains:

• Green tiles: the chains were successful and are healthy
• Yellow tiles: the chain are unstable and there are health issues
• Red tiles: the chains failed and there are health issues
• Grey tiles: no chains ran on the changesets

Mouse over a colored section of a contributor's bar to display its percentage of the total number of changesets that have been delivered. The contributor's total number of deliveries is displayed to the right of their bar. The total number of contributors and deliveries for all developers is displayed at the top of the page.

1. Select the level where you want to create the report (a suite, product, or stream).
2. On the sidebar select Reports and then Contributors.
3. (Optional) Filter the information that is displayed.

Delivery Activity Reports

You can display the days and hours when deliveries were made. Larger circles indicate higher activity.

1. Select the level where you want to create the report (a suite, product, or stream).
2. On the sidebar select Reports and then Punch Card.
3. (Optional) Filter the information that is displayed.

Agile Request Management

Use requests, backlogs, and iterations, to plan, track, and execute your team's work.

About Requests

Requests are used to track and approve the changes your team is making. A request is a single unit of work, equivalent to a story in Agile planning, that can report a defect, suggest an enhancement, or detail other work for a particular product. You use story points to estimate the size of a request. Each request type has a lifecycle assigned to it that determines which users may work on the request. For information about request lifecycles see the Dimensions CM Process Configuration Guide.

The request catalog displays all the requests in a CM product or stream. You can open any request and view its details.

View the Request Catalog and Open Requests

1. Select a product or stream.
2. On the sidebar click Request Catalog. Each row displays information about a request including its owner, lifecycle state, and any backlogs and iterations to which it belongs.


TIP You can sort the list and search for specific requests.
3. To open a request select it.
   • General tab: displays information about the request, including:
     • A summary of the request
     • The request's acceptance criteria
     • Attachments
     • Related requests
     • Associated reviews
     • Associated changesets
     • Total and remaining story points
     • A burndown chart (if the request is included in an iteration)
     • An external link, for example, the URL of an external web site or the value of an SBM ticket related to the request. If the value is a hyperlink, it opens in a new tab or window. This field only displays a value if it has been mapped to request attributes. An external link may look similar to this:
       
     • The request owners and their capabilities
     • Any iteration, backlog, or epic to which the request belongs
     • The related stream and design part
     NOTE The fields that are displayed can be configured by your Pulse administrator.
   • Attributes tab: each request type has different user defined attributes, which record important information about the request. For example, Estimated completed date, Raised by, and Severity. Some attributes may be required.
   • Action History tab: displays information about when the request was actioned to different states in its lifecycle and the users that performed the action. To filter the action history, select a lifecycle state.

Configure Request Types

Administrators can:

• Disable request types to limit which ones can be used in request planning. At least one type must be enabled. By default, all request types are enabled and their attributes are not mapped.
• Map Pulse attributes to request attributes defined in the process control plan in the Dimensions CM administration console. Select CM attributes that best suit how your team uses request planning. For information about request attributes see the Dimensions CM Process Configuration Guide.

1. Select the product where you want to enable request types.
2. On the sidebar select Product Settings and then Request Types.
3. Select the request type that you want to configure.
4. Select or deselect Enable request type.
   • Enable: existing requests of this type are visible and you can create new requests.
   • Disable: existing requests of this type are visible but you cannot create new requests.
5. In the Attributes Mappings section, map this request type's attributes to request attributes defined in CM (see below).
6. Click Save.

Add External Links to Requests

Administrators can configure request types to display external links, see the next section.

Map Pulse Attributes to CM Request Attributes

To enable Agile planning, Pulse requires additional fields. You can store these fields in Pulse or map them to CM request attributes:

• If you store attributes (unmapped) in the Pulse database you do not need to add them to your process control plan in Dimensions CM. This allows you to evaluate and use Pulse more easily, especially if the fields will always be edited in Pulse.
• If you map attributes to CM they can be viewed and edited in other CM clients.

About Backlogs

Backlogs enable you to organize your team’s work and group requests into a prioritized hierarchy of epics and features. An epic is a large unit of work that is typically broken down into smaller units of features and requests.

About Iterations

An iteration is one development cycle, commonly known as a sprint, which is typically a few weeks. An iteration includes the requests your team are confident they can complete during the sprint. As an iteration progresses, the remaining effort required to complete the requests should decrease. You can view an iteration as a list or a card wall. Iterations are located at the product level in Pulse.

The Content tab displays the content of an iteration in a flat list and includes information such as:

• What requests are being worked on.
• For each request, its rank order in the iteration, title, effort, current state, and owners.
• The progress of the work; the effort, in story points, required to complete each request.

On a Card Wall tab each card displays information about a specific request such as:

• Which team member is working on it.
• The request’s story points.
• If the request is blocked.
• The number of days the request has been in its current state.
• A badge indicating its review state and the health of the changes.

Cards are grouped in rows by request type with a separate column for each lifecycle state. Each request type displays the number of requests that are blocked, hidden, and unassigned.

A card wall also displays metrics about the progress of the current iteration:

• In progress: story points remaining to be completed (as a number and percentage).
• Iteration end: the number of days left until the iteration ends.
• Done: requests completed (as a number and percentage).
• Burndown chart: shows how much work remains to be done in the iteration and helps to predict when the work will be completed.
• Burnup chart: shows how much work has been completed and the total amount of work.

The History tab displays changes made during an iteration, for example, requests that were added.

Create New Requests

1. Do one of the following:
• Open the backlog where you want to add the request. Optionally select the epic or feature that will contain the request. To add the new request at the top level of the backlog, do not select an epic or feature.
• Open the request catalog.
2. Click New and select a request type, for example, ECR.
3. On the General tab do the following:
   • Give the request a title and summarize its purpose.
   • For Acceptance Criteria specify the criteria to be met before the request is considered to be complete.
   • For Story Points estimate the total number of points required to complete the work and the points remaining until will be finished. Story points are an estimation of a request’s relative complexity compared to other requests, and the effort required to complete it.
   • Optionally relate the new request to a stream and design part.
4. On the Attributes tab specify or select values. Each request type has different attributes and some may be mandatory. The attributes are similar to those in the other CM clients.
TIP
• You can hide read-only attributes.
• Only attributes that you have the privilege to edit are displayed.
• The fields that are displayed depend on the request type and how it has been customized by the CM administrator.
5. Click Save.

Creating a New Request Based on an Existing Request

You can also create a new request based on the properties of an existing request. In CM this is known as priming a request. The new request can be:

• In the same or a different product.
• A different request type.
• Related to the request from which it was primed.

1. Open the request catalog.
2. Open the request that you want to prime.
3. Click Prime To and select a request type.
4. Select a relationship type, for example, Duplicate.
5. Click Prime.
6. Complete the form the same as for a new request.

Add an Action Description to a Request

You can add an action description to a request without actioning it.

1. Open the request where you want to add a description.
2. Click Action and select Add Action Description.
3. Enter a description and click Add.

Plan and Manage a Backlog

You typically start backlog planning by:

• Creating a new backlog.
• Adding epics and features.
• Populating the backlog with work (requests).

Create a Request Backlog

If you are an administrator, you can create a new backlog and assign backlog owners. A backlog owner can manage its content, for example: add, remove, and rank items. The backlog owners can be changed by an administrator or another owner.

1. Select the product where you want to create the new backlog.
2. On the sidebar select Backlog.
3. Click New.
4. Give the backlog a name and summarize its purpose.
5. (Optional) To assign one or more owners:
   • Click Add. The Add Owner dialog box is displayed.
   • In the Search box enter a string that matches registered Pulse users.
   • Select one or more users and click Add Owner.
6. Click Save.

Open a Backlog

1. Select the product containing the backlog.
2. On the sidebar select Backlogs.
3. Select a backlog or search for one by title or ID#.

Create an Epic or Feature

1. Open the backlog where you want to create a new epic or feature.
2. (Optional) Click New and select Epic or Feature.
3. Give the epic or feature a title and summarize its purpose.
4. Click Save.
5. Add additional epics and features as required.
6. To change the hierarchy, drag and drop epics and features in the backlog.

Add a Request from the Request Catalog

You can add an existing CM request that originated from inside or outside your team.

1. Open the backlog where you want to add a request.
2. Click to show the right panel and select Request Catalog.
3. Select a request and drag it to a specific place in the backlog hierarchy on the left panel.

Move Epics, Features and Requests between Backlogs

You can move epics, features, and requests between backlogs. An object can only belong to one backlog; if you move one to the target backlog it is removed from the source backlog. When you move a feature its child requests are also moved.

1. Open the backlog where you want to move an object to.
2. Click to show the right panel and select Backlogs.
3. Select a backlog or search for one by title or ID.
4. Select an epic, feature, or request and drag it to a specific place in the backlog hierarchy on the left panel.

Prioritize and Rank Requests in a Backlog

In each backlog, requests are ranked in descending order of priority in their parent epic or feature. You can rank and prioritize requests in the structured or flat view.

1. Open the backlog where you want to prioritize and rank requests.
2. Click to display the flat view.
3. Select a request and drag it to a different position in the hierarchy.

Mark a Request as Blocked

If you cannot continue working on a request you can mark it as blocked.

1. Open the backlog containing the request you want to block.
2. Select the request.
3. Select Mark Blocked. In the backlog the request is now labeled as Blocked.

Delete an Epic, Feature or Request

You can delete an epic, feature, or request from a backlog. If you select an epic that has child features they are also removed. Any requests contained in an epic or feature are removed from the backlog and made available to the team.

1. Open the backlog where you want to delete objects.
2. Select one or more epics, features, or requests. Multiple objects that you select must be at the same level in the backlog hierarchy. For example, you can only select requests and features that are at the same level in an epic.
3. Click Delete.

Plan and Manage an Iteration

Create an Iteration from a Backlog

You can create a new iteration from a backlog if you are an administrator or the backlog owner. The new iteration can only include requests that are not already assigned to another iteration. Requests that you can add have a green circle next to their label . If you select an epic or feature, its child requests are included in the new iteration.

1. Open a backlog.
2. Select one or more epics, features, and requests. Multiple objects that you select must be at the same level in the backlog hierarchy. For example, in an epic you can only select requests and features that are at the same level.
3. Click Create Iteration.
4. In the Create Iteration dialog box do the following:
   • Give the iteration a name and summarize its goals.
   • Specify the duration of the iteration and a start date.
5. Click Save.

Create an Iteration from an Existing Iteration

You can create a new iteration containing requests from an existing iteration if you are its owner or an administrator. This is useful when you have finished a sprint and want to move uncompleted requests to a new iteration. The owner of the source iteration becomes the owner of the new iteration and the selected requests are moved to the new iteration.

1. Select the product where you want to create the new iteration.
2. On the sidebar select Iterations.
3. Select the iteration that will be the source for the new iteration.
4. Select one or more requests.
5. From the Move To menu select New Iteration.
6. In the Create Iteration dialog box do the following:
   • Give the iteration a name and summarize its goals.
   • Specify the duration of the iteration and a start date.
7. Click Start.

Create a New Empty Iteration

If you are an administrator you can create a new, empty iteration.

1. Select the product where you want to create the new iteration.
2. On the sidebar select Iterations.
3. Click New.
4. Give the iteration a name and summarize its goals.
5. Specify the duration of the iteration and a start date.
6. (Optional) To add an owner:
   • Click Add. The Add Owner dialog box is displayed.
   • In the Search box enter a string that matches registered Pulse users.
   • Select one or more users and click Add Owner.
7. Click Save.

Open an Iteration

1. Select the product containing the iteration you want to view.
2. On the sidebar select Iterations.
3. From the list select one of the following: Recent, Owned by me, Current, Future, Previous
4. Select the iteration.

Add a Request from a Backlog

You can add a request from a backlog to an iteration if you are the owner of the iteration or an administrator. You can only add requests that are not already assigned to another iteration. Requests that you can add have a green circle next to their label .

1. Open the iteration where you want to add a request.
2. Click the Content tab.
3. Click to show the right panel.
4. On the right panel select Backlogs.
5. Select a backlog or search for one by title or ID.
6. Select a request and drag it to any position in the iteration on the left.

Move a Request from another Iteration

You can move a request from another iteration if you are the owner of both iterations. The request is removed from the source iteration and added to the target iteration.

1. Open the iteration where you want to add a request.
2. Click the Content tab.
3. Click to show the right panel.
4. On the right panel select Iterations.
5. Select an iteration or search for one by title or ID.
6. Select a request and drag it to any position in the iteration on the left.

Prioritize and Rank Requests

In each iteration, requests are ranked in descending order of priority. To change a request's position, do one of the following:

• Select it and drag to a different position.
• Click the Rank field and enter, or select, a new position.

Move Requests to another Iteration

You can move requests to another iteration if you are the owner of both iterations.

1. Open the iteration from where you want to remove requests.
2. Click the Content tab.
3. Click to show the right panel.
4. On the right panel select Iterations.
5. Select a target iteration or search for one by title or ID.
6. In the source iteration on the left select the requests that you want to move.
7. Select Move To and then Iteration on Right <iteration ID>.

Move Requests to a New Iteration

You can move requests from an existing iteration to a new iteration.

1. Open the iteration from where you want to remove requests.
2. Click the Content tab.
3. Select the requests that you want to move.
4. Select Move To and then New Iteration.
5. Give the new iteration a name and specify its duration and start date.
6. Click Start.

Edit an Iteration

You can edit an iteration if you are the owner or an administrator.

1. Open the iteration that you want to edit.
2. Click Edit.
3. Edit the iteration.
4. Click Save.

Remove Requests from an Iteration

You can remove requests from an iteration if you are the owner or an administrator. After you remove a request it can be added to other iteration.

1. Open the iteration from where you want to remove requests.
2. Select one or more requests.
3. Click Remove and confirm.

Delete Iterations

You can delete one or more iterations if you are the owner or an administrator.

1. Select the product containing the iterations.
2. On the sidebar select Iteration.
3. Select one of these tabs: Current, Future, Previous
4. Select iterations.
5. Click Delete and confirm.

View Request Details on a Card Wall

When the card wall is displayed you can view a request's details.

1. Open an iteration and display the card wall.
2. Select a card. The request's details are displayed on the right.

Create Space on a Card Wall

You can create space on a card wall and only display the information that you require by:

• Collapsing request types
• Collapsing lifecycle states
• Using compact cards
• Hiding the merics and burndown/burnup charts

Compact card wall example

1. Open an iteration and display the card wall.
2. To collapse a request type, toggle the arrow on the left.
3. To collapse a lifecycle state, hover over the column title and click
4. At the bottom of the card wall, click Show charts and/or Show compact cards.

Group Requests on a Card Wall

You can group requests on the card wall by users. This enables you to:

• See how many requests and story points are allocated to each user
• Identify users who may be struggling to complete their work

1. Open an iteration and display the card wall.
2. At the bottom of the card wall, click Group by user.

Display Off-Normal Request States

Off-normal request lifecycle states are not displayed by default.

1. Open an iteration and display the card wall.
2. At the bottom of the card wall select Show off normal states. If an off-normal state column is collapsed, click to expand it.

Action Requests

You can action a request to a new lifecycle state if it is in your Inbox or you are a Dimensions CM administrator.

Action a Request from a Backlog or Iteration

1. Open the request that you want to action.
2. Click Action To and select a lifecycle state from the list. The Action Request dialog box is displayed.
3. On the General tab optionally modify the total and remaining story points.
4. Click the Owners tab and optionally add users who will own the request after it is actioned:
   1. Click Add. A dialog box displays a list of all the users that can be added as owners.
   2. From the Role to assign list, select the role with which to assign the new owners, for example, Developer.
   3. From the Capability of users list, select a capability for the new owners. For more information see the Dimensions CM Process Configuration Guide.
   4. Select one or more users and click Add.
5. When you action a request you may need to provide additional information on the Attributes tab, some of which might be required.
6. Click Action.

Action a Request from a Card Wall

1. Open the iteration containing the request that you want to action.
2. Click the Card Wall tab.
3. Drag a request to another lifecycle column. The Action Request dialog box is displayed.
4. When you action a request you may need to provide additional information on the Attributes tab, some of which might be required.
5. On the Owners tab, optionally select the user who will become the request owner after it is actioned.
6. Click Action. The request’s state is changed and it moves to the next lifecycle column on the card wall.

Delegate a Request

Delegate a request when you want to assign it to other users. When you delegate a request you can change the role assignments for it, for example, Developer. You can also select a Dimensions CM capability, for example:

• Leader: sole responsibility for the request.
• Primary: primary responsibility for the request.
• Secondary: acts as a backup to the primary role.

1. Open the request catalog and select the request.
2. On the General tab, in the Owners section click Add.
3. From the Role to assign list, select the role to be delegated to the users.
4. From the Capability of users list, select a capability for the users.
5. From the Users to assign section select one or more users.
6. Click Delegate.

Edit Requests

You can edit a request's details if it is in your Inbox or you are a Dimensions CM administrator. After you edit a request its new values are displayed in all CM clients.

1. Open the backlog or iteration containing the request that you want to edit.
2. Select the request and click Edit.
3. On the General tab do the following:
   • Edit the title, summary, and acceptance criteria
   • Edit the story points
   • Add and remove attachments
   • Add and remove relationships to other requests
   • Relate the request to a different stream or project
   • Add and remove relationships to design parts
4. Select the Attributes tab and edit the values. The attributes vary between request types but are the same as in the other CM clients. Each request type has different attributes. Attributes that are required for the next state are indicated.
TIP
• You can hide read-only attributes.
• Only attributes that you have the privilege to edit are displayed.
5. Click Save.

Add Owners to Requests

You can add owners to a request if the request is in your Inbox or you are a Dimensions CM administrator.

1. Open the request from the request catalog, a backlog, or an iteration.
2. On the General tab, in the Owners, section click Add.
3. From the Role to assign list select a role, for example, Developer.
4. From the Capability of users list select a capability, for example, Secondary.
5. In the Users to assign box search for, and select, one or more users.
6. Click Add and then Save.

You can also remove owners from requests if their role was not inherited.

1. Open the request from the request catalog, a backlog, or an iteration.
2. On the General tab, in the Owners, select one or more owners.
3. Click Remove and then Save.

Administer Pulse

To administer Pulse you must be logged in as a user with administrator privileges.

Configure the Avatar Server

Administrators can configure where Pulse obtains user avatar images.

1. On the top navigation click Administration.
2. Select Avatars.
3. Select one of the following sources for avatar images and user information:
   • Disabled: all avatars display the default user picture.
   • Solutions Business Manager: use an SBM server to find avatar images and full names. Set the SBM server.
   • LDAP Server: use the LDAP settings, see below.
   • Gravatar: use an email address suffix. Set the suffix.
4. If you selected LDAP, specify the following information:
   • Server URL
     The URL of the LPAP server, for example:
     ldap://domain-controller.example.com:389
   • Username
     The bind user to perform searches as, for example:
     cn=binduser,ou=Organizational Unit 1,ou=Organizational Unit 2,dc=example,dc=com
   • Password
     The password of the LDAP bind user.
   • Base DN for search
     The base DN to search from, for example:
     dc=example,dc=com
   • Avatar image attribute
     The LDAP attribute containing avatar image data, for example:
     thumbnailPhoto
   • Follow LDAP referrals
     To enable searches to follow LDAP referrals, toggle Follow LDAP referrals to Yes.
   • Search filter
     The LDAP search filter to match objects, for example:
     (&(objectClass=person)(sAMAccountName={0}))

Configure Special Services

Administrators can configure the servers that provide specialized services to Pulse, such as Solutions Business Manager.

1. On the top navigation click Administration.
2. Select Servers.
3. In the Solutions Business Manager URL box enter the URL for the SBM user workspace, for example:
   http://sbm-server.example.com/tmtrack/tmtrack.dll?
4. In the Email Address Domain Suffix box enter the suffix that is automatically appended to user names to form email addresses, for example:
   @example.com.
5. Click Save.

Administer Email Notifications

Administrators can manage the review email notifications that users can subscribe to, and unsubscribe from. If a notification is disabled, users will not see the notification listed in their subscription preferences. If a notification is available, users can choose to subscribe to it.

1. On the top navigation click Administration.
2. Select Notifications.
3. For each notification type select one of the following:
   • Disabled: the notification is not available for users to subscribe to.
   • Send notification: the notification is sent to users by default though they can unsubscribe from it.
   • Do not send notification: the notification is not sent to users by default though they can subscribe to it.
4. If you do not want users to receive code fragments in email notifications, unselect the option Include code fragments.
5. Click Save.

Manage Users

A user can be one of the following:

• Standard: can use peer reviews, changeset views, and request management.
• Administrator: can change a user's type and administer the system. There can be multiple administrators.

1. On the top navigation click Administration.
2. Select Users. A list of all the currently registered users is displayed including their user name, full name, email address, and user type.
3. Select one or more standard users. From the Actions menu select Add administrator privilege.
4. Select one or more administrators. From the Actions menu select Remove administrator privilege.

Configure Connections to Repositories

Administrators can add and modify connections to multiple repositories (Dimensions CM base databases).

1. On the top navigation click Administration.
2. Select Repositories.
3. Do one of the following:
   • To add a new repository select New Repository.
   • To edit the connections for an existing repository, select it from the list. Click Connection Details.
4. In the Title box enter, or modify, the name of the Dimensions CM repository.
5. In the Server box enter, or modify, the network name of the Dimensions CM server, for example: dm-server.example.com
6. In the Dimensions CM base database name box enter, or modify, the database connection, for example: CM_TYPICAL@DIM14 These two values, separated by the @ symbol, are the same information that you enter in the DB name and DB connection boxes when you log into a Dimensions CM client.
7. For SCM Credentials, select or deselect the option Always use the following credentials. For details about using this option see below.
8. Enter a Dimensions CM account username and password.
9. Click Save.

Configure Access to Repositories

When Pulse accesses a Dimensions CM repository it presents a set of credentials. The credentials used for each repository depend on how you set the option Always use the following credentials in the repository connection:

• Selected: the CM account that you specify (see above) is used to connect to the Dimensions CM repository, which allows connections and caches to be pooled across users. Audit trail and user access control is the same as for the CM user. This option uses less disk space and fewer system resources.
• Unselected: the credentials of the user currently logged in Pulse are used to connect to the Dimensions CM repository. Audit trail and user access control is the same as for the Pulse user. The CM account that you specified is used for non-interactive connections to that repository when a logged in Pulse user is not available. This option provides better audit trail and access control.

Set Repository Defaults

Administrators can set repository defaults, such as integrations with Dimensions CM requests.

1. On the top navigation click Administration.
2. Select Repositories.
3. Select a CM repository.
4. Select Defaults.
5. In the Reviewer Role in CM section enter a Dimensions CM role. Users that hold this role can be selected as reviewers in Pulse. If you do not specify a role the default REVIEWER is used.
6. In the Integrating with CM Requests section do the following:
   • In the In Review state name in CM box enter a comma separated list of CM request states that can add reviewers to associated Pulse reviews. Pulse listens for Action Request notifications from Dimensions CM. When a request enters one of these named states in CM, its Reviewer role assignment is copied to Pulse, and its review rules are executed.
   • In the Rework state name in CM box enter the CM state to which requests are actioned when any associated Pulse review is sent for rework.
   • In the Approved state name in CM box enter the CM state to which requests are actioned when any associated Pulse review is sent for rework or marked as approved.
   NOTE
   • Actioning a request to In Review causes the review rules to run and will typically change the review's state to In Review.
   • These integrations are optional. Leave blank to disable an integration.
   • Leave all boxes blank unless your CM request lifecycle includes an In Review state.
   • If you do not want to automatically copy role assignments to Pulse, or push states from Pulse, do not use this integration. Users can make changes manually in Pulse and Dimensions CM without this integration.
   • Leave the boxes blank to disable the integration between Pulse reviews and Dimensions CM requests.
7. Click Save.

Clear Pulse Caches

If you have made a configuration change and it is not visible, try clearing the relevant cache.

1. On the top navigation click Administration.
2. On the sidebar select Caches.
3. Click Clear to empty a cache.
4. To clear all caches click Clear All.

Other Administrative Tasks

For information about the following Pulse administration tasks see the Dimensions CM Administrator's Guide:

• Customizing rule scripts
• Setting the JDBC URL
• Location of common tools and Pulse data folders

Markdown Syntax Reference

Markdown is a syntax used to format information in plain text. You can use Markdown in any external text editor and copy the contents to Pulse, retaining a consistent look for all comments. The formatting is created with special sequences of punctuation characters in plain text.

Character Formatting

Inline Code and Code Blocks

Some code line 1
Some code line 2

Line Breaks and Paragraphs

Simple Lists

Links

Headers and Rules

Troubleshoot

Administration Issues

See also the Pulse troubleshooting chapter in the Dimensions CM Administrator's Guide.

Database not Accessible

If Pulse fails to start because it cannot connect to its database, a detailed exception message is displayed instead of the login page. A common reason is a missing or inaccessible database at application start up time. The logs in the Pulse data directory on the server contain more information. For information about configuring the JDBC URL, see the Pulse chapters in the Dimensions CM Administrator's Guide.

Reviews not Created Automatically

Reviews are not created automatically when deliveries are made to CM:

• If your Dimensions CM server is correctly configured to emit ALF events when a delivery is made, check that your repository connection has been setup properly and that Pulse can connect to it.
• In the stream's settings check that:
  • The delivery filter is not set to exclude the changeset.
  • Create/Attach to a Review is selected.
• If a delivery references a Dimensions CM request, or has a review label in the format [Q100] in the delivery message, the changeset may be associated with an existing review at the Draft or Rework state and will not create a new review.

User Avatar Images not Displayed

Try the following:

• Check that the avatar server is configured properly.
• Go to Administration | Caches and clear the avatar images cache.
• Clear your local browser cache.

Chains do Not Start

If chains do not start when deliveries are made to CM check:

• The stream is configured to automatically run chains.
• The chain is configured to run on a schedule rather than every delivery.
• The Pulse server logs described in the Dimensions CM Administrator's Guide.

Chain Results Not Displayed

If chains run successfully but results are not displayed, check that the parameters in Jenkins are configured correctly. Builds will run in Jenkins even if parameters are not configured correctly, but the results will not be sent to Pulse. You can also view chain logs.

For more information about configuring Jenkins see the Dimensions CM Build Tool User's Guide.

Other Issues

See also the Pulse troubleshooting chapter in the Dimensions CM Administrator's Guide.

Reviewers Not as Expected

If the reviewers assigned to a new review are not as expected:

• Check that the design parts that own the files being reviewed are correct.
• Check who holds the Reviewer role on those design parts.

If item content is not displayed correctly in reviews, in the Dimensions CM administration console check that:

• The item's data format is set correctly.
• The data format has an appropriate MIME type. Items that have a data format with a MIME type beginning text/ are displayed as inline text, MIME types beginning with image/ are displayed as images.
NOTE When you change an item's data format, or the data format's MIME type, the change may not display immediately in Pulse. The file content part of the review page is cached at the server and may take a few minutes to cycle.

Requests are Actioned but Pulse Reviews do Not Change State

If CM requests are actioned but the corresponding Pulse reviews do not change state, try the following:

1. On the top navigation click Administration.
2. Select Repositories.
3. Select the review's repository and click Defaults.
4. In the Reviewer role name in CM field see what CM role that has been specified. Users that hold this role can be selected as reviewers in Pulse.
   • If the CM request does not have a user that holds this CM role, no changes are made in Pulse.
   • If the CM request does have a user hold this CM role, the role assignment should have been copied to the review. However, the review rule script for the stream also determines if the review changes its state.
   All reviews at the Draft and Rework states that are associated with the actioned request will have their reviewers updated. Reviews not at Draft or Rework are not affected by the request.

Check the ALF event configurations and Pulse server logs, see the Dimensions CM Administrator's Guide for details.

Pulse Reviews Change State but Requests are Not Actioned

If Pulse reviews change state but the corresponding CM requests are not actioned, try the following:

1. On the top navigation click Administration.
2. Select Repositories.
3. Select the review's repository and click Defaults.
4. In the Approved state name in CM and Rework state name in CM boxes check the state names are correct.
5. Click Cancel.
6. On the sidebar click Connection Details.
7. In the Credentials section check that the specified user can log into Dimensions CM and that the user account has privileges in Dimensions CM to action requests to the necessary states.

Unexpected Formatting in Review Comments

• Pulse uses Markdown syntax for formatting user comments. If you are expecting a new line in your comment, try ending the previous line with two spaces or using an extra blank line.
• For security reasons the following are removed:
  • Links or images that do not point to an URL of the type http:// or https://
  • Unsafe or unbalanced HTML tags

IIS 403 Error

If you have configured IIS using AJP and are getting an IIS 403 error page instead of the Pulse login page when you open http://<server-name>/pulse/, do the following:

1. Open IIS Manager.
2. In the Connections pane, expand Default Web Site, and select the /jakarta folder.
3. In the Management section of the Features view, double click Configuration Editor.
4. In the From list select Default Web Site/jakarta Web.config.
5. In the Section list select system.webServer/httpErrors from the tree.
6. Change the value of the property existingResponse from Auto to PassThrough.
7. In the Actions panel click Apply.

PMD Expert

If the compilation unit (*.java file):

• Is not syntactically correct PMD does not report any findings therefore sources must be compiled successfully.
• Is very large, for example 10,000 lines, and there are multiple bugs PMD may take a long time to complete.

SonarQube Expert

If you have problems with SonarQube Runner see the web site.

If you receive the state Aborted check that:

• The expert property file is in: ${dataDir}/conf/experts/com.serena.starlight/sonarqube/sonarqube-pulse-expert.properties
• All required properties are specified in the property file.
• The SonarQube server and database are up and running.
• The connection details to the SonarQube server and SonarQube database are configured correct in the property file.
• The path to the SonarQube Runner command line tool is correct in the property file.

Check the Pulse log file.

Deployment Automation Experts

Check the following:

• The configuration is set up properly, for example, the correct Deployment Automation object names are specified.
• If the property file is not found or is not set up correctly, the wrong Deployment Automation server URL may be specified.
• The Deployment Automation server version is supported.
• The Deployment Automation agent or resource is online.

Dependency Vulnerabilities Expert

Check the following:

• If autoupdate in the properties file is set to false, CVE data is not updated and the expert will not report any findings.
• The OWASP Dependency Check tool does not always work correctly with analyzer options and you may have to disable them. To exclude specific paths use the Exclude patterns field.

Support

Contact support