Broadcom Clarity

Last updated
Save as PDF

Overview

Organizations need to improve portfolio management by ensuring that artifacts managed by the PMO (Project Management Office) are available to other members of the extended development team and that the PMO has visibility to progress being made on its initiatives and projects. By connecting Broadcom Clarity (formerly CA PPM) software to the tools used by other stakeholders, Hub extends the value of the information managed within Broadcom Clarity and provides access to information from other tools. This creates a deeply integrated lifecycle that increases visibility and collaboration across system boundaries while enabling centralized governance.

Portfolio Managers need to make informed decisions in real time. By connecting Clarity software to the artifact bus provided by Tasktop Sync, Clarity users can make the right decisions and collaborate more effectively across the portfolio.

For example, members of the PMO may use Clarity to articulate and manage high-level initiatives. However these initiatives have to translated into a series of requirements for the development team. By integrating Clarity software with requirements management tools creates a fluid flow of communication between the PMO and the business analysts tasked with crafting the program requirements. This is an example of the Project Portfolio Management – Requirements Management Alignment Software Lifecycle Integration Pattern, other integration patterns that involve Clarity are listed in the Common Integration Patterns section below.

Key Features and Benefits

Synchronizes artifacts across the lifecycle, allowing information to flow freely between Clarity and other tools
Improves collaboration between the PMO, development, test, the service desk and more
Support cross-tool traceability and reporting, removing the need for manual processes and spreadsheets.
Synchronize time worked on tasks from development tools directly into timesheets in Clarity
Enables centralized planning and control

Common Integration Patterns

Demo Videos

Connector Setup Details

This section describes the basic steps needed to prepare your Clarity instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization.

In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'

List of minimal permissions:

Create a Clarity user account to be used by Hub and ensure that it has sufficient permissions to create and update artifacts in the Clarity projects to be synchronized (including XOG and NSQL API access).

Connecting to the Broadcom Clarity Repository

Prior to connecting to the repository, follow the instructions for Clarity NSQL script installation. The connector relies on custom NSQL scripts that must be installed on the Clarity server.

Standard Authentication

Required Fields:

Location/Connection URL
- Example Format: https://server.com:81/niku/xog
- The server URL should be the XOG API endpoint. On a standard Clarity server, this URL will be “http://[hostname]:[port]/niku/xog”, but the “/niku/xog” path may be customized on some servers.
Username
Password

Optional Fields:

Tenant ID
- Tenant ID is required in a multi-tenant-enabled server set-up.
Timesheet Cutoff: Setting this value makes the connector not retrieve timesheet information before the specified date.
- To use this feature, select a date from the date picker. You must ensure that the date selected is at the first day of a time period. For example, if you set your time sheet periods in Clarity to 'monthly,' you must enter a date such as "2021-08-01" (August 1st).
- Note: While Planview Hub does not currently support synchronizing timesheet data, we still recommend setting this field to allow for a short time window. This will prevent the connector from attempting to retrieve worklog data that is associated with artifacts which are being synchronized, and improve system performance.
Timesheet Flow Precision: This field should only be used in Tasktop Sync, as Planview Hub does not currently support timesheet synchronization.
- Setting this to a value makes the connector not submit amounts of time that would not be visible in the Clarity Time Sheet UI. To set this, select the precision that matches the settings on your server from the drop down menu. Timesheet data will only synchronize if the difference between the old and new value in Clarity is greater than zero when that difference is rounded to the selected unit, using the selected number of decimal points. This will default to 1 hour, 5 decimals.
Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Screenshot 2023-09-11 at 11.34.39 AM.png

Learn more about how to set up your repository in Planview Hub here.

Creating a Proxy Association Attribute (Tasktop Sync)

What is Proxy Association Attribute?

A custom string attribute is recommended to be used as the proxy association storage. Tasktop Sync needs to keep track of the association between a task and its proxy task. The association is persisted in a proxy store allowing the synchronization to be restored if there is any catastrophic failure of Tasktop Sync.

A proxy association attribute must be created for each artifact type to be synchronized.

The Proxy Association Attribute field must be a text/string type field in your ALM repository. We recommend creating this field with the name "Tasktop Sync Proxy."

It is recommended that a Clarity custom attribute is set up to store Tasktop Sync proxy association information. Follow these instructions (for the Task object) to create this attribute:

Log in to the Broadcom Clarity web UI as an administrator
Select Objects from the Administration menu
Select the Task object from the list
Navigate to the Attributes tab
Select New from the bottom toolbar
Set Attribute Name to TasktopSync_ProxyAssociation
Set Attribute ID to ttsync_proxyassn
Set Data Type to String
Set Maximum Size to 100 (or greater)
Set Attribute Name (and Description, if desired) to an appropriate value to allow easy identification of the purpose of the attribute
Select Save and Return
Navigate to Custom Objects -> Administration -> Studio -> Queries.
Open the query whose Query ID matches Tasktop_GetTask
Add the newly created ttsync_proxyassn attribute as a select field in the NSQL tab. See instructions for adding custom field to your artifacts

Equivalent steps are required for any other supported object type.

The new attribute will not be visible in the web interface by default and does not need to be exposed for Tasktop Sync for Clarity to work correctly.

Initialization and Change Queries (Tasktop Sync)

Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.

The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.

The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope.

The Broadcom Clarity connector supports the following query types:

The Search Tasks by Project query returns all supported tasks in the selected projects that have been modified within a specified time span.
The Search Incidents by Category query returns all incidents in the selected categories that have been modified within a specified time span.
The Search Sub-Objects by Type query returns all the instances of the selected artifact type’s custom sub-objects that have been modified within a specified time span.
The Search by Type query returns all artifacts of the selected artifact type.
The Search by Type and Date query returns all artifacts of the selected artifact type that have been modified within a specified time span.

Query	Instruction
Initialization Query	For initializations query you can choose to use any of the above queries to limit the number of artifacts retrieved from the server
Changes Query	For changes query you can use the same query as above, but specify the "Last Changed On" filter to retrieve only a subset of artifacts.

NSQL Scripts

NSQL Script Installation

The Broadcom Clarity Connector uses custom NSQL scripts that must be installed on the Clarity server. NSQL queries are SQL-like scripts that the Clarity server can expose via SOAP API. The Studio Developer’s Guide contains further information on NSQL.

For each of the scripts in the NSQL Scripts section:

In the Broadcom Clarity web interface, navigate to Custom Objects -> Administration -> Studio -> Queries.
Click New.
Set the Query ID to match the selected script from NSQL Scripts below (e.g., Tasktop_GetTask)
Set the other properties ( Available for user portlets, Content Source)
Click Save and Continue.
Copy the source of the selected script to the NSQL section of the web interface
Click the Save And Return button.

The queries are automatically available through web services after saving.

Adding Custom Attributes to your Artifacts

All custom attributes (fields) on supported object types that will be synchronized must be added to the NSQL scripts matching the object type (See Tasktop_GetTask, Tasktop_GetIncident, Tasktop_GetAsset, or Tasktop_R_[sub-object id] below).

Note: If a custom attribute is missing from the corresponding NSQL, the value will be cleared when the Clarity Connector updates the object.

In the Broadcom Clarity web interface, navigate to Custom Objects -> Administration -> Studio -> Objects -> [Object Type].
Select the Attributes tab.
Select the custom attribute to synchronize and identify its Attribute ID.

Replace both CUSTOM_ATTRIBUTE_ID in the below line with the Attribute ID identified in the last step.

, Select:DIM_PROP:USER_DEF:IMPLIED:TASK:CUSTOM.CUSTOM_ATTRIBUTE_ID:CUSTOM_ATTRIBUTE_ID

For example:

, Select:DIM_PROP:USER_DEF:IMPLIED:TASK:CUSTOM.projectlead:projectlead

Navigate to Custom Objects -> Administration -> Studio -> Queries.
Select the query for fetching the desired object type: Tasktop_GetTask, Tasktop_GetIncident, Tasktop_GetAsset, or Tasktop_R_[sub-object id]
Navigate to the NSQL tab.
Insert the custom attribute line from step 4 underneath the last “@Select” line. For example:
Repeat the above steps for all custom attributes.
Click the Save And Return button when all custom attributes have been added.

Adding Dynamic Lookup Attributes to your Artifacts

Some Clarity object attributes have a “Lookup” type and a reference to a Lookup list of available values. If the type of the lookup list is ‘Static List’ then the Clarity connector supports all attributes of this type automatically. However, if the lookup type is ‘Dynamic Query’ the connector is unable to execute the associated query and such attributes are excluded by default.

To enable a dynamic lookup attribute in the connector create an NSQL script with the following conditions:

The NSQL script id matches the following pattern: Tasktop_L_<Attribute Id>
The NSQL script maps two fields, one to "id" and one to "label":
- The select clause for the unique id of the queried object maps the value to an “id” attribute name. (e.g., @SELECT:DIM_PROP:USER_DEF:IMPLIED:CHG:PRID:id@)
- The select clause for the visible label of the queried object maps the value to a “label” attribute name. (e.g., @SELECT:DIM_PROP:USER_DEF:IMPLIED:CHG:PRNAME:label@)

Examples:

Example 1: Using Company lookup as dynamic lookup attribute

SELECT  @SELECT:c.id:id@,
      @SELECT:c.company_id:company_id@,
      @SELECT:c.company_id:UNIQUE_CODE@,      
      @SELECT:c.company_name:company_name@                
      FROM    srm_companies c,
                    cmn_lookups s                
      WHERE   c.status = s.id
      AND @FILTER@         
      @BROWSE-ONLY:
          AND     s.lookup_code IN ('ACTIVE')
        :BROWSE-ONLY@

The above lookup code can easily be transferred into the following Tasktop_L_company (where "company" will be what the field is call in the artifact type's Get NSQL):

SELECT  @SELECT:c.id:id@,   
        @SELECT:c.company_name:label@                
        FROM    srm_companies c, cmn_lookups s                
        WHERE   c.status = s.id
        AND @FILTER@

Example 2: Enabling the “Charge Code” field on Task objects

Create the following NSQL script with the Query ID Tasktop_L_prchargecodeid:

SELECT  @SELECT:DIM:USER_DEF:IMPLIED:CHG:PRID:id@
,       @SELECT:DIM_PROP:USER_DEF:IMPLIED:CHG:PRNAME:label@
,       @SELECT:DIM_PROP:USER_DEF:IMPLIED:CHG:PREXTERNALID:externalId@
FROM    PRChargeCode
WHERE   @FILTER@
        @BROWSE-ONLY:
AND     prIsOpen  != 0
AND prprojectid is null
        :BROWSE-ONLY@

The above script was adapted from the “Active Charge Codes” lookup query provided by the Clarity web interface.
That original script is here:

SELECT  @SELECT:prID:prID@,
        @SELECT:PRUID:UNIQUE_CODE@,
        @SELECT:prName:prName@,
        @SELECT:prExternalID:prExternalID@,
        @SELECT:prModTime:prModTime@
FROM    PRChargeCode
WHERE   @FILTER@
        @BROWSE-ONLY:
AND     prIsOpen  != 0
AND     prprojectid is null
        :BROWSE-ONLY@

Enabling Partitions

In order for the connector to support partitions, the Tasktop_L_partition_code script must be added. For each object that has partitions, add the following to the respective Get {object-type} NSQL. Replace [object-type] and [odf-object-table] with appropriate object type values. For example:

For Task, add to Tasktop_GetTask NSQL: Replace [object-type] with TASK and [odf-object-table] with ODF_CA_TASK
For Incident, add to Tasktop_GetIncident: Replace [object-type] with INCIDENT and [odf-object-table] with ODF_CA_INCIDENT

, @SELECT:DIM_PROP:USER_DEF:IMPLIED:[object-type]:[odf-object-table].partition_code:partition_code@

The Clarity user account must be added to all relevant partitions.

NSQL Scripts

Below, you will find a table outlining the required and optional scripts to flow each supported artifact type in Clarity. Below the table is an index containing the scripts that are compatible with each supported version of Hub. Open the PDF file to view and copy the scripts needed for your desired artifact type.

Required Scripts by Artifact Type

Artifact

Required Scripts

Optional Scripts

Asset

Tasktop_GetResources
Tasktop_GetAsset
Tasktop_SearchAssets

For Charge Code:

Tasktop_L_prchargecodeid
See additional configuration details here

For Currency Code:

Tasktop_L_currency_code

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here

For Portfolios:

Tasktop_GetPortInvestments
Tasktop_GetPortfolio
Tasktop_SearchPortfolios
Tasktop_L_currency_code

Change Request

Tasktop_GetResources
Tasktop_GetChangeRequest
Tasktop_SearchChangeRequests
Tasktop_GetProject
Tasktop_SearchProjects

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

Incident

Tasktop_GetResources
Tasktop_GetIncident
Tasktop_SearchIncidents
Tasktop_GetIncidentCategories

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Investment:

Tasktop_L_invemstmentId

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

For Worklogs:

Tasktop_GetIncidentEffort
Tasktop_GetTimeperiods
Tasktop_L_investmentId

Issue

Tasktop_GetResources
Tasktop_GetIssue
Tasktop_SearchIssues
Tasktop_GetProject
Tasktop_SearchProjects

For Associated Tasks:

Tasktop_GetTask
Tasktop_SearchTasks
Tasktop_GetRiskIssueTasks

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

Portfolio

Tasktop_GetResources
Tasktop_GetPortfolio
Tasktop_SearchPortfolios
Tasktop_L_currency_code

Note: To flow a container in Hub (Portfolio or Project), at least one work item's queries should also be present. Hub won't list a container if there are no available children within it.

For Department:

Tasktop_L_department

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Investments:

Tasktop_GetPortInvestments

For Managers:

Tasktop_GetPortfolioUsers
Tasktop_GetMultiSelectValues

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

For Stakeholders:

Tasktop_GetPortfolioUsers
Tasktop_GetMultiSelectValues

Project

Tasktop_GetResources
Tasktop_GetProject
Tasktop_SearchProjects

Note: To flow a container in Hub (Portfolio or Project), at least one work item's queries should also be present. Hub won't list a container if there are no avaiable children within it.

For Charge Code:

Tasktop_L_prchargecodeid
See additional configuration details here

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

For Portfolios:

Tasktop_GetPortInvestments
Tasktop_GetPortfolio
Tasktop_SearchPortfolios
Tasktop_L_currency_code

For Tasks:

Tasktop_GetTask
Tasktop_SearchTasks

Resource (Labor)

Tasktop_GetResources
Tasktop_GetResource
Tasktop_SearchResources
Tasktop_L_inputTypeCode

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

Risk

Tasktop_GetResources
Tasktop_GetRisk
Tasktop_SearchRisks
Tasktop_GetProject
Tasktop_SearchProjects

For Associated Issues:

Tasktop_GetIssue
Tasktop_SearchIssues
Tasktop_GetRiskIssueLinks

For Associated Risks

Tasktop_GetRiskIssueLinks

For Associated Tasks:

Tasktop_GetTask
Tasktop_SearchTasks
Tasktop_GetRiskIssueTasks

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

For Residual Risks:

Tasktop_GetRiskIssueLinks

SubObject

Tasktop_GetResources
Tasktop_R_{Object ID}
Tasktop_S_{Object ID}

All required queries of master object.

For example, for the following sub-object

Object Name	Object ID	Master Object
objName	objID	Incident

The required queries will be named:

Tasktop_GetResources
Tasktop_R_objID,
Tasktop_S_objID,
Tasktop_GetIncident, Tasktop_SearchIncidents, Tasktop_GetIncidentCategories.

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

Task

Tasktop_GetResources
Tasktop_GetTask
Tasktop_SearchTasks
Tasktop_GetProject
Tasktop_SearchProjects

For Assignees:

Tasktop_GetAssignments
Tasktop_GetMultiSelectValues

For Charge Code:

Tasktop_L_prchargecodeid
See additional configuration details here

For Dynamic Lookup Fields:

Tasktop_L_{Attribute Id}
See additional configuration details here

For Multi-Select and Multi-Person Fields:

Tasktop_GetMultiSelectValues

To support Partitions:

Tasktop_L_partition_code
See additional configuration details here.

For Worklogs:

Tasktop_GetTaskEffort
Tasktop_GetTimeperiods
Tasktop_GetAssignments
Tasktop_GetMultiSelectValues

Script Index

Broadcom Clarity Script Index

Other Configuration Settings

Task ID Field

When creating a new task with the Clarity connector, the task must have a unique ID. Although Clarity marks the external ID field as unique, it allows multiple projects to have tasks with the same external ID, which can cause Hub to locate the wrong artifact when attempting to make updates.

If the task’s ID field is empty or matches the ID of an existing task in the project, creation will fail. After the task is created, however, the Clarity connector will treat its ID field as read-only.

The recommended way to handle the Clarity ID field in Hub is to create a one-way, upon-creation-only mapping from the ID field of the other system to the Clarity ID field.

Note: You can also have the Clarity server auto-generate an ID to populate this field, without having to map it. This can be configured under Custom Objects -> Administration → Studio -> Objects -> Task -> ID -> Auto-numbering tab. This will automatically generate an ID for a new Task which can have a counter to increment with (thus unique).

Person Reconciliation

Note: Because Oracle does case-sensitive string comparisons, person searching on a Clarity instance with an Oracle database will be case-sensitive.

For person reconciliation, the following fields are available:

Fields Used for Hub’s Default Person Reconciliation Algorithm	Field Names for Person Reconciliation Extensions (Note that these are case sensitive)	Label in Clarity
ID	id	ID (also referred to as “Resource ID” in the UI)
Username	userName	User Name
Email	email	Email Address
N/A	name	Display Name
N/A	firstName	First Name
N/A	lastName	Last Name
N/A	uniqueName	Unique Name
N/A	userId	User ID

In the resource view URL below, you can find both the ID (listed as 'resourceID' in the URL) and the User ID (listed as 'ID' in the URL - we know, it's a little counterintuitive!). Sometimes these two values are identical, but in other circumstances they can be two separate values: ID vs User ID

Learn more about how to configure person reconciliation in Planview Hub here.

Person Fields

In Tasktop Sync, Clarity person fields are identified by the numerical (internal) ID, thus any synchronization feature using people (i.e., person/multi-person fields, time-worked) requires a person mapping, even in LDAP environments.

Person mappings may be generated using the following Ruby script:

require "net/http"
require "highline/import"
require "uri"
require "nokogiri"
require "rexml/document"

include REXML

def get_people_xml(server, user, pass)
  uri = URI.parse(server)
  http = Net::HTTP.new(uri.host, uri.port)
  request = Net::HTTP::Post.new(uri.request_uri)
  request.add_field('Content-Type', 'text/xml;charset=UTF-8')
  request.add_field('SOAPAction', "http://www.niku.com/xog/Query/Tasktop_GetResources")
  request.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:quer="http://www.niku.com/xog/Query">
  <soapenv:Header>
  <quer:Auth>
  <quer:Username>' + user +'</quer:Username>
  <!--Optional:-->
  <quer:Password>' + pass + '</quer:Password>
  </quer:Auth>
  </soapenv:Header>
  <soapenv:Body>
  <quer:Query>
  <!--Optional:-->
  </quer:Query>
  </soapenv:Body>
  </soapenv:Envelope>'
  response = http.request(request)
  return response.body
end

def get_records(xml)
  doc = Nokogiri::XML(xml)
  return doc.xpath('//nsp:Record', {"nsp" => "http://www.niku.com/xog/Query"})
end

def get_person(record)
  person = {}
  record.children.each do |child|
    if child.name == "internalresourceid"
      person[:internalresourceid] = child.text
    elsif child.name == "username"
      person[:username] = child.text
    elsif child.name == "resourceid"
      person[:resourceid] = child.text
    elsif child.name == "fullname"
      person[:fullname] = child.text
    end
  end
  return person
end

def create_person_elt(person_id)
  person = Element.new("person")
  person.add_attribute("id", person_id)
  return person
end

#person1_id is internalresourceid, person2_id will be the LDAP username
def create_person_mapping_elt(person1_id, person2_id)
  person_mapping = Element.new("person-mapping")
  person_mapping << create_person_elt(person1_id)
  person_mapping << create_person_elt(person2_id)
  return person_mapping
end

def create_repo_elt(repo_url)
  repository = Element.new("repository")
  repository.add_attributes( {"url"=>repo_url, "default-person-id"=>"TODO"} )
  return repository
end

def start_person_mappings(base_url)
  person_mappings = Element.new("person-mappings")
  person_mappings.add_attribute("xmlns", "http://tasktop.com/xml/ns/sync/person-mapping-model")
  person_mappings << create_repo_elt(base_url)
  person_mappings << create_repo_elt("TODO")
  person_mappings << create_person_mapping_elt("","")
  return person_mappings
end

def print_doc(person_mappings)
  doc = Document.new
  doc << XMLDecl.new("1.0", "UTF-8")
  doc << person_mappings
  doc.write($stdout, 3)
  doc.write(File.new("personMapping.xml", "w"), 3)
end

base_url = ask("Enter server URL: ")
user = ask("Enter username: ")
pass = ask("Enter password: ") { |q| q.echo = false }

xml = get_people_xml(base_url, user, pass)
records = get_records(xml)

person_mappings = start_person_mappings(base_url)
records.each do |record|
  person = get_person(record)
  #If the second repository uses something other than the username that exists in the first repository
  #then you can change this by changing create_person_mapping_elt(person[:internalresourceid], person[:username])
  #to create_person_mapping_elt(person[:internalresourceid], person[:fullname]). If this entry
  #is not one of username, fullname, or resourceid then the script will need to be further modified
  #to extract this data.
  person_mapping = create_person_mapping_elt(person[:internalresourceid], person[:username])
  person_mapping << Comment.new("PPM person: #{person[:fullname]}, Username: #{person[:username]}, internalResourceId: #{person[:internalresourceid]}, resourceId: #{person[:resourceid]}")
  person_mappings << person_mapping
end
print_doc(person_mappings)

See the following instructions for using the Ruby script:

Instructions

All Windows users and some Linux users will need to install Ruby. (Mac OSx comes with Ruby preinstalled, as do many versions of Linux.) Directions for all systems are available here.
1. For Windows, RubyInstaller provides easy one-click installation. When prompted for “Installation Destination and Optional Tasks“, check the box beside ‘’Associate .rb and .rbw files with this Ruby installation.’
Open a console/command line interface.
1. For Mac and Linux users, this will be Terminal.
2. For Windows users, choose “Start command prompt with Ruby."
From the command line, run the person mapping script by referencing its file path. For instance, if the script is located on the desktop, enter the following:
```
> ruby Desktop/ppm_person_mapping.rb
```
At this point, if you see “cannot load such file — highline/import (LoadError)”, you need to first install highline. Enter the following:
```
> gem install highline 

> gem install nokogiri 
```
1. For Mac/Linux users, if you now get a Gem::FilePermissionsError, you’ll need to use the following:
```
> sudo gem install highline

> sudo gem install nokogiri 
```
After successfully installing highline and nokogiri, go back and re-enter the command in step 3.
The script will now prompt you to enter your Clarity server URL, username, and password. After entering this information, a person mapping will be generated in XML format. This mapping will appear both in the console and as a file in the directory you ran the script from.
1. On a Mac, if you ran the script from /Users/EdithWharton, there will now be a person mapping in /Users/EdithWharton/personMapping.xml.
2. On Windows, if you ran the script from C:\Users\WilliamStyron, the mapping will be in C:\Users\WilliamStyron\personMapping.xml.
You will need to complete the mapping by entering the URL for the server you are synchronizing to as well as the default-person-id for both the Clarity Server and system synchronized to.

See the Functional Limitations table below for limitations.

Full Scan

Due to third party API limitations, updates to the following fields may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:

Relationships (i.e., multi-link) fields on Projects and Portfolios, such as portfolios, investments, or tasks
'Cost Type' field on Tasks
Custom Fields
- Hub can detect changes to custom fields when those changes are made from the UI, but cannot detect changes to custom fields when those changes are made via API (for example, if a Hub integration updates a custom field, it does not trigger change detection)
Worklogs (Note: Worklogs are only supported on Tasktop Sync)

Learn more about how to configure change detection and full scan intervals in Planview Hub here.

Time Tracking Integration

Note: Time Tracking is not currently available on Planview Hub. Instructions below apply to Tasktop Sync, only.

To prepare your instance for time tracking integration, make sure that the following settings have been configured:

Note that this may already be done if you have time tracking enabled and working in your environment.

For Projects:

Navigate to "Home" -> "Portfolio Management" -> "Projects", and select the project you want to edit
Navigate to "Properties" -> "Properties" -> "Schedule"
Under the "Tracking" section, turn on "Time Entry" and set "Track Mode" to "Clarity"

For Users:

Navigate to "Home" -> "Resource Management" -> "Resources", and select the user you want to edit
Navigate to "Properties" -> "Properties" -> "Settings" (this step only necessary for Clarity On-Demand, and newer versions of Clarity on-site)
Set "Track Mode" to "Clarity", and turn on "Open for Time Entry"
Navigate to "Properties" -> "Access to this Resource" -> "Resource"
Click "Add" at the bottom
Select "Resource - Approve Time" and "Resource - Enter Time", and click "Add and Continue"
Select the person that this resource should be able to enter and approve time for (such as a project manager, resource manager, or yourself) and click "Add."

Ensure that the users configured for time tracking are members of the project team.

For Time Reporting Periods (if you do not have time reporting periods yet):

Navigate to "Administration" -> "Project Management" -> "Time Reporting Periods"
Click the "New" button at the bottom
Set "Scale" to anything but "Weekly", set "Start Date" and "Finish Date" to any dates
click "Save and Return"

Repeat the above steps to create at least two time reporting periods of two or more days in length.

Note: When creating a time reporting period, the span between "Start Date" and "Finish Date" will be split into time reporting periods of the size of the "Scale" option. So if you set "Scale" to "Daily" and set the start and finish dates to 7 days apart, you'll actually create 7 single-day time reporting periods.

Additional Notes:

Time entered manually in Clarity timesheets will get overwritten / removed when a worklog synchronization is set up (and the same time doesn't exist in the source system of worklogs).

Incident Time Tracking:

When a user wants to log work on an Incident in Clarity, she has to select an Investment as well. In a synchronization scenario, no other system currently supported has a field similar to investment, so the Tasktop Sync Clarity Incident Time-Worked synchronization makes the following assumptions:

Whenever Time-Worked is written for a given Clarity Incident, the investment being used is the investment set on the actual Incident
In a synchronization, you can choose to either map the Clarity Incident Investment field to a semantically matching (custom) field on the other system, or use a static, literal value mapping so the Investment is always the same. Or, as a third option, only allow Clarity to change the investment, so synchronization will never write it, only use the value during time-worked writing.
If the Investment on the Incident is empty, writing Time-Worked will fail. If no Time-Worked is to be written though, the field can of course remain empty and other fields can be synchronized.
Should the Investment field be changed, the time-worked entries from the secondary system (existing and new ones) will be written to Clarity using the new Investment. No existing time-worked entries for the old Investment will be touched on the Clarity timesheets.
Any time-worked entries for Investments not matching the Incident investment will be ignored (neither written to nor used in calculations).
The assumption for this Incident time-worked use case is that after an Incident has it's first time-worked written, the Investment field will only change in rare, exceptional cases

Repository Fields Specific to Time Tracking

Time sheet cutoff date: Setting this value makes the connector not retrieve or sync worklogs before the specified date. To use this feature select a date from the date picker. You must ensure that the date selected is at the first day of a time period.
Time sheet display precision: Setting this to a value makes the connector not submit amounts of time that would not be visible in the Clarity Time Sheet UI. To set this, select the precision that matches the settings on your server from the drop down menu. If no value is selected the connector defaults to 'hours' and 5 decimal places.

Frequently Asked Questions

See Broadcom Clarity connector FAQs here.

Supported Features

Special Features Supported

You can learn more about special features in Planview Hub here.

Feature	Custom Type Supported?	Applicable Hub Version	Applicable Repository Versions
Time Worked (Worklogs) Impersonation	N/A	Tasktop Sync: 4.2 and later	Any supported repository version: Tasktop Sync
Comments Impersonation Public/Private			Any supported repository version: Planview Hub Tasktop Sync
Attachments Impersonation			Any supported repository version: Planview Hub Tasktop Sync
State Transitions Supported for Asset and Project (State Transitions are not needed in Clarity for other artifact types. Therefore status can flow out of or into Clarity as a single select)	N/A	Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	Any supported repository version: Planview Hub Tasktop Sync

Supported Artifacts

Supported Work Items

Learn about the difference between containers and work items in Planview Hub here.

Supported Work Item Type	Applicable Hub Versions	Applicable Repository Version	Unique URL?
Task	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Incident	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Incident Sub-object	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Asset	Planview Hub: All Tasktop Sync: 4.5 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Project Sub-Object	Planview Hub: All Tasktop Sync: 4.7 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Labor Resources	Planview Hub: 18.4.0.20180829 and later Tasktop Sync: 4.16 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Risk	Planview Hub: 19.1.0.20181203 and later Tasktop Sync: 4.17 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Change Request	Planview Hub: 19.1.0.20181203 and later Tasktop Sync: 4.17 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Issue	Planview Hub: 19.1.0.20181203 and later Tasktop Sync: 4.17 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Project (Note: treated as a container beginning with Planview Hub 18.2)	Planview Hub: 17.1 - 18.1 Tasktop Sync: 4.5 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes

Supported Containers

Learn more about containment in Planview Hub here.

Containers used to define the boundary of a collection (by clicking 'Manage Projects' on the collection)
Containers that can synchronize between repositories	Applicable Hub Versions	Applicable Repository Versions	Unique URL?
Project Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here.	Planview Hub: 17.2 and later	Any supported repository version: Planview Hub	Yes
Program Since programs are technically the same as projects, these can by synchronized utilizing the 'project' artifact type, and artifact filtering utilizing the 'program' boolean field (program = Y) Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here.	Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Portfolio Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here.	Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
N/A (entire repository selected as container)	Planview Hub: All	Any supported repository version: Planview Hub
Containers used for artifact routing
Projects (for Tasks only) N/A - entire repository is routed (for all other artifacts)	Planview Hub: All	Any supported repository version: Planview Hub

Supported Field Types

Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.

Standard Field Type	Does Hub support custom fields of this type?	How is field type referenced in the repository?	Sample Repository Fields Supported	Particular Repository Fields NOT Supported
String		String	ID Category Gantt Outline Level Short Name Name
Single Select		Lookup: Number String	Cost Type EV Calculation Method	Primary Role
Multi Select		Multi-valued lookup: Number String
Boolean		Boolean	Critical Fixed Duration Key Task Locked Open for Time Entry Program (to differentiate between programs and projects)
Date		Date	Early Finish Early Start Late Finish Late Start
Date Time			Start Finish Created Date Last Updated Date
Duration
Double		Percent Number (with decimal places)	Duration % Complete
Long		Number	Priority
Person	N/A	Person Lookup: Number	Assigned Project Manager Assigned To Created By Last Updated By
Persons		Resource	Assignees
Relationship(s) Learn how to configure relationships in Planview Hub here.	N/A		Parent Task Related Project Portfolios (Read Only) Investments (Read Only)	Plans Plan of Record
Rich Text
Web Links		URL
Other

Functional Limitations

Category	Limitation	Applicable Hub Versions	Applicable Repository Versions
Third Party Functional Limitation	Projects Customers may notice the following behaviors when using Hub: Collections will contain artifacts from the entire repository and cannot be restricted by project.	Planview Hub: All	Any supported repository version: Planview Hub
Third Party API Limitation	Risks, Issues, and Change Requests Relationships and Multi-Relationships of and to Risk, Issue, and Change Request are read-only in the connector.	Planview Hub: 19.1.0.20181203 and later Tasktop Sync: 4.17 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Portfolios Due to a bug in Clarity, custom fields on Portfolios that are marked as 'required' will only allow creation if there is a default value set. If no default value is set, creation will always fail, even if the required value is included in the payload the connector sends to Clarity.	Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	Any supported repository version prior to 15.4: Planview Hub Tasktop Sync
Third Party API Limitation	Unicode Characters Resources with unicode characters in their 'User Name' field cannot be written using XOG. The Clarity server will fail and cannot accept those value. If such a user is set in the webUI, however, Hub can correctly retrieve its value, and can also update it to a different value or update other fields.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	Configuration When creating a new connection to Clarity, the repository URL should be the XOG API endpoint. On a standard Clarity server, this URL will be "http://[hostname]:[port]/niku/xog", but the "/niku/xog" path may be customized on some servers.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	ID Field Clarity objects (task, incident, incident sub-objects) must have a non-empty ID for the Clarity connector to be able to update or delete them. In Clarity, the ID field of a task is editable and optional. So it is possible to have a task with an empty ID. However, the API used by the Clarity connector uses this ID field to identify tasks to be updated or deleted.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	ID Field If users change the ID of tasks/sub-objects, or change the ID or name of projects/incidents, the connector may create a duplicate task, create a duplicate project, or rename a project. If a user changes the ID of a task or the ID of a project, and the connector uses the old ID in an API call, a new task or project will be created. If a user changes the name of a project, and the connector uses the old name in an API call, the project will be renamed to its old name. Hub minimizes the chances of this occurring by fetching the latest task ID, project ID, and project name before making API calls. However, there is still a small window (of a couple seconds at most) in which, if a task ID, project ID, or project name is changed, this may occur.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Date, Date/Time Fields Once a date or date time field's value is set, the connector cannot remove the value. The values can be modified but not removed.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	URL Fields Hub treats all fields of URL type as strings.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Dynamic Lookup Single-Select Fields Hub supports "Dynamic" lookup single-select fields but special per-field setup steps are required. See manual for instructions on enabling dynamic lookups with NSQL scripts.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Charge Code Field The Charge Code field (single-select) on a task is read-only. Note that this field is a also a "Dynamic Lookup" single-select and requires special steps to be enabled. An example is in the NSQL Script section, above.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Assignees Clarity assignees become read only as soon as a time sheet with a time entry for that assignee becomes read only. If assignee synchronization is set up, removing such read-only assignee from the proxy artifact will result in the Clarity connector to silently ignore this removal, the assignee will remain. No error will be reported.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Performance Under load, the Clarity server might return "Success" on an update operation when in fact no update is written to the task.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Multi-Select Fields Hub cannot clear multi-select fields once one or more values are selected. Hub requests to clear multi-select fields are ignored. The API allows adding and removing one or more values but does not work when removing all values.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Singe Select Fields Single-select stock (not custom) fields like Task.Cost_Type cannot be cleared once they have value. Hub requests to clear these fields are ignored.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Relationships Task parent relationships cannot be removed. Hub can change a task's parent but cannot move from a child task to a root task. The API doesn't reliably allow removing such relationships (without updating every single task in the entire project).	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	Person Fields Clarity person fields are identified by the numerical (internal) ID, thus any synchronization feature using people (i.e. person/multi-person fields, time-worked) requires a person mapping, even in LDAP environments. See more details above.	Tasktop Sync: 4.1 and later	Any supported repository version: Tasktop Sync
Known Issue	Date Fields Unlike all other date fields, Clarity provides Creation Date and Last Update Date fields in the server's time zone instead of in UTC. Hub currently handles these dates like all others and so incorrectly assumes they are UTC. This means that these date values will be incorrect in all time zones that are not UTC.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Best Practice	Date Fields We recommend setting up Clarity task sync to only set start and finish dates on initialization. Task start and finish dates cannot be updated through the XOG API if the task's ETC value is greater than 0.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Known Issue	Person Fields Person fields in the connector are backed by an NSQL script that simply fetches all Resources. In Clarity, those fields use custom dynamic lookup queries that further restrict the available options depending on the field's context. This means that Hub may provide resource values that Clarity then rejects on write. In practice this shouldn't be an issue for Hub since the resources are driven by person mapping anyway. At present the only fields affected by this are writable Person fields on Incident (Assign To, Assigned Project Manager, and Reported By) and Task Assignees.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Person Fields Custom person fields are not supported. See known issue above. Because a Clarity Person field is just another lookup, Hub has no way of knowing if the associated lookup query is for Person data or not.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Person Fields Once a Person value is set, Hub cannot remove the value. It can only change the value.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Best Practice	Incidents By default, writing to the Incident artifact's Priority field is ignored. A system-calculated priority is assigned based on the Urgency and Impact fields. To override this with a user-defined Priority, one has to enable the "Override Priority Calculation" flag (boolean field). Therefore Hub mappings that intend to write the Incident Priority field need to also map the "Override Priority Calculation" field, likely to a Literal castor with the value "true". Once written, the flag stays set unless changed from the Clarity UI, so you can configure the attribute mapping to only sync on creation. Do this if you don't want to step-over users that have deliberately disabled the override post-creation.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Best Practices	% Complete Calculation Method Every project has a "% Complete Calculation Method" setting. When it's set to "Manual", % complete could be written to. All other settings could result in the value being overwritten by the server. Also, % complete depends on the status field. If status is set to "not started", % complete is automatically set to 0%. If status is set to "completed", % complete is automatically set to 100%. Clarity silently fails all attempts to write to % complete unless the project's "% Complete Calculation Method" is set to manual and the task's status is "Started". This is the only state the connector can guarantee the value of % complete.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Known Defects	Errors Deadlock errors from the Clarity server result in an error, rather than pending state.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	Custom Number Fields Custom Number fields need to have the "Decimals" field set in the Object / Attribute configuration on the Clarity server. If that field remains empty, the Clarity connector will ignore this custom field.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Tasks Tasks with empty External IDs can only be one-way synced out of Clarity.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Tasks Tasks that have sub-tasks are not synced. The sub-tasks are synced, but not the parent of those tasks. This is due to these Parent tasks being summary tasks and not real tasks.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Projects The Project field "Department Name" cannot be written to with the Clarity connector, as the XOG API does not include this field.	Planview Hub: All Tasktop Sync: 4.5 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Projects Clarity Project has a multi-link field Tasks, which links to all the tasks on the project. This field is read only and does not have change detection. Manually refresh the artifact to receive changes.	Planview Hub: All Tasktop Sync: 4.5 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party Functional Limitation	Tasks Clarity Task has a single-link field Project, which links to its project. The field is only writable when the task is created. Hub does not support moving a task to a different project.	Planview Hub: All Tasktop Sync: 4.5 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	Partitions The repository user must be added to all partitions being accessed. Failing to so will result in Clarity writing partial data. A debug message will be logged in this instance.	Planview Hub: All Tasktop Sync: 4.7 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	Custom Fields All custom fields of artifacts the connector writes to must be added to the corresponding Hub R(retrieve) NSQL. Failing to do so will cause the connector to clear the field value.	Planview Hub: All Tasktop Sync: 4.1 and later	Any supported repository version: Planview Hub Tasktop Sync
Feature Unsupported	Status Fields To configure state transitions in Planview Hub, the following possible transitions can be used in the graph: Approve (from state Unapproved to state Approved) Unapprove (from states Approved or Rejected to state Unapproved) Reject (from state Unapproved to state Rejected) Cancel Resumed (from state Resumed to state Cancelled) Cancel Approved (from state Approved to state Cancelled) Resume (from state Cancelled to state Resumed)	Planview Hub: 18.2 and later	Any supported repository version: Planview Hub
Third Party Functional Limitation	Status Fields Investments (e.g. Project, Program, Asset) have a workflow around the Status field. Due to limitations in the XOG API, some status transformations cannot be performed (i.e.: Rejected -> Approved, Cancelled -> Approved, Approved -> Rejected). All other transformations can be performed	Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	Any supported repository version: Planview Hub Tasktop Sync
Configuration Requirement	Time Tracking The "Do not synchronize time worked before" setting (Clarity Repository Settings Page, Advanced section) must be set to a day that matches the start date of a time period on the Clarity server (or it can be blank). The "Do not synchronize time worked before" feature has undefined behavior when the date specified does not fall on the start date of a Clarity time period.	Tasktop Sync: 4.4 and later	Any supported repository version: Tasktop Sync
Best Practices	Time Tracking If the timesheet entry rounding repository setting is changed to a finer precision, there is a potential that previously equivalent worklogs are now considered non-equivalent and thus will get synchronized. This could cause errors if that happens to be on read-only timesheets. If users use a customized precision though, there is still a potential for synchronization errors.	Tasktop Sync: 4.4 and later	Any supported repository version: Tasktop Sync
Known Defect	Time Tracking Tasktop Sync cannot add multiple worklogs to a Time Period that currently has no time logged for the user.	Tasktop Sync: 4.1 and later	Any supported repository version: Tasktop Sync
Best Practices	Time Tracking Retrieving timesheets causes high I/O and CPU load on the data base server of Clarity. Besides ensuring proper sizing of that server, Tasktop Sync and Broadcom strongly recommend performing regular data base maintenance listed here.	Tasktop Sync: 4.1 and later	Any supported repository version: Tasktop Sync
Third Party API Limitation	Time Tracking Split time sheet entries are not supported. They are ignored when reading in time sheet data, and an error happens when attempting to write to a split entry.	Tasktop Sync: 4.1 and later	Any supported repository version: Tasktop Sync

Category

Limitation

Applicable Hub Versions

Applicable Repository Versions

Third Party Functional Limitation

Projects

Customers may notice the following behaviors when using Hub:

Collections will contain artifacts from the entire repository and cannot be restricted by project.

Planview Hub: All

Any supported repository version:

Planview Hub

Third Party API Limitation

Risks, Issues, and Change Requests

Relationships and Multi-Relationships of and to Risk, Issue, and Change Request are read-only in the connector.

Planview Hub: 19.1.0.20181203 and later

Tasktop Sync: 4.17 and later

Any supported repository version:

Third Party API Limitation

Portfolios

Due to a bug in Clarity, custom fields on Portfolios that are marked as 'required' will only allow creation if there is a default value set. If no default value is set, creation will always fail, even if the required value is included in the payload the connector sends to Clarity.

Planview Hub: 18.2 and later

Tasktop Sync: 4.14 and later

Any supported repository version prior to 15.4:

Third Party API Limitation

Unicode Characters

Resources with unicode characters in their 'User Name' field cannot be written using XOG. The Clarity server will fail and cannot accept those value. If such a user is set in the webUI, however, Hub can correctly retrieve its value, and can also update it to a different value or update other fields.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Configuration Requirement

Configuration

When creating a new connection to Clarity, the repository URL should be the XOG API endpoint.

On a standard Clarity server, this URL will be "http://[hostname]:[port]/niku/xog", but the "/niku/xog" path may be customized on some servers.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Configuration Requirement

ID Field

Clarity objects (task, incident, incident sub-objects) must have a non-empty ID for the Clarity connector to be able to update or delete them.

In Clarity, the ID field of a task is editable and optional. So it is possible to have a task with an empty ID. However, the API used by the Clarity connector uses this ID field to identify tasks to be updated or deleted.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

ID Field

If users change the ID of tasks/sub-objects, or change the ID or name of projects/incidents, the connector may create a duplicate task, create a duplicate project, or rename a project.

If a user changes the ID of a task or the ID of a project, and the connector uses the old ID in an API call, a new task or project will be created.

If a user changes the name of a project, and the connector uses the old name in an API call, the project will be renamed to its old name.

Hub minimizes the chances of this occurring by fetching the latest task ID, project ID, and project name before making API calls. However, there is still a small window (of a couple seconds at most) in which, if a task ID, project ID, or project name is changed, this may occur.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Date, Date/Time Fields

Once a date or date time field's value is set, the connector cannot remove the value.

The values can be modified but not removed.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

URL Fields

Hub treats all fields of URL type as strings.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Dynamic Lookup Single-Select Fields

Hub supports "Dynamic" lookup single-select fields but special per-field setup steps are required. See manual for instructions on enabling dynamic lookups with NSQL scripts.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Charge Code Field

The Charge Code field (single-select) on a task is read-only. Note that this field is a also a "Dynamic Lookup" single-select and requires special steps to be enabled. An example is in the NSQL Script section, above.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Assignees

Clarity assignees become read only as soon as a time sheet with a time entry for that assignee becomes read only. If assignee synchronization is set up, removing such read-only assignee from the proxy artifact will result in the Clarity connector to silently ignore this removal, the assignee will remain. No error will be reported.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Performance

Under load, the Clarity server might return "Success" on an update operation when in fact no update is written to the task.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Multi-Select Fields

Hub cannot clear multi-select fields once one or more values are selected. Hub requests to clear multi-select fields are ignored.

The API allows adding and removing one or more values but does not work when removing all values.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Singe Select Fields

Single-select stock (not custom) fields like Task.Cost_Type cannot be cleared once they have value. Hub requests to clear these fields are ignored.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Relationships

Task parent relationships cannot be removed. Hub can change a task's parent but cannot move from a child task to a root task.

The API doesn't reliably allow removing such relationships (without updating every single task in the entire project).

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Configuration Requirement

Person Fields

Clarity person fields are identified by the numerical (internal) ID, thus any synchronization feature using people (i.e. person/multi-person fields, time-worked) requires a person mapping, even in LDAP environments.

See more details above.

Tasktop Sync: 4.1 and later

Any supported repository version:

Tasktop Sync

Known Issue

Date Fields

Unlike all other date fields, Clarity provides Creation Date and Last Update Date fields in the server's time zone instead of in UTC. Hub currently handles these dates like all others and so incorrectly assumes they are UTC. This means that these date values will be incorrect in all time zones that are not UTC.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Best Practice

Date Fields

We recommend setting up Clarity task sync to only set start and finish dates on initialization.

Task start and finish dates cannot be updated through the XOG API if the task's ETC value is greater than 0.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Known Issue

Person Fields

Person fields in the connector are backed by an NSQL script that simply fetches all Resources. In Clarity, those fields use custom dynamic lookup queries that further restrict the available options depending on the field's context. This means that Hub may provide resource values that Clarity then rejects on write. In practice this shouldn't be an issue for Hub since the resources are driven by person mapping anyway. At present the only fields affected by this are writable Person fields on Incident (Assign To, Assigned Project Manager, and Reported By) and Task Assignees.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Person Fields

Custom person fields are not supported. See known issue above. Because a Clarity Person field is just another lookup, Hub has no way of knowing if the associated lookup query is for Person data or not.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Person Fields

Once a Person value is set, Hub cannot remove the value. It can only change the value.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Best Practice

Incidents

By default, writing to the Incident artifact's Priority field is ignored. A system-calculated priority is assigned based on the Urgency and Impact fields. To override this with a user-defined Priority, one has to enable the "Override Priority Calculation" flag (boolean field). Therefore Hub mappings that intend to write the Incident Priority field need to also map the "Override Priority Calculation" field, likely to a Literal castor with the value "true". Once written, the flag stays set unless changed from the Clarity UI, so you can configure the attribute mapping to only sync on creation. Do this if you don't want to step-over users that have deliberately disabled the override post-creation.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Best Practices

% Complete Calculation Method

Every project has a "% Complete Calculation Method" setting. When it's set to "Manual", % complete could be written to. All other settings could result in the value being overwritten by the server. Also, % complete depends on the status field. If status is set to "not started", % complete is automatically set to 0%. If status is set to "completed", % complete is automatically set to 100%.

Clarity silently fails all attempts to write to % complete unless the project's "% Complete Calculation Method" is set to manual and the task's status is "Started". This is the only state the connector can guarantee the value of % complete.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Known Defects

Errors

Deadlock errors from the Clarity server result in an error, rather than pending state.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Configuration Requirement

Custom Number Fields

Custom Number fields need to have the "Decimals" field set in the Object / Attribute configuration on the Clarity server. If that field remains empty, the Clarity connector will ignore this custom field.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Tasks

Tasks with empty External IDs can only be one-way synced out of Clarity.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Third Party API Limitation

Tasks

Tasks that have sub-tasks are not synced. The sub-tasks are synced, but not the parent of those tasks. This is due to these Parent tasks being summary tasks and not real tasks.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Projects

The Project field "Department Name" cannot be written to with the Clarity connector, as the XOG API does not include this field.

Planview Hub: All

Tasktop Sync: 4.5 and later

Any supported repository version:

Third Party API Limitation

Projects

Clarity Project has a multi-link field Tasks, which links to all the tasks on the project. This field is read only and does not have change detection. Manually refresh the artifact to receive changes.

Planview Hub: All

Tasktop Sync: 4.5 and later

Any supported repository version:

Third Party Functional Limitation

Tasks

Clarity Task has a single-link field Project, which links to its project. The field is only writable when the task is created. Hub does not support moving a task to a different project.

Planview Hub: All

Tasktop Sync: 4.5 and later

Any supported repository version:

Configuration Requirement

Partitions

The repository user must be added to all partitions being accessed. Failing to so will result in Clarity writing partial data. A debug message will be logged in this instance.

Planview Hub: All

Tasktop Sync: 4.7 and later

Any supported repository version:

Configuration Requirement

Custom Fields

All custom fields of artifacts the connector writes to must be added to the corresponding Hub R(retrieve) NSQL. Failing to do so will cause the connector to clear the field value.

Planview Hub: All

Tasktop Sync: 4.1 and later

Any supported repository version:

Feature Unsupported

Status Fields

To configure state transitions in Planview Hub, the following possible transitions can be used in the graph:

Approve (from state Unapproved to state Approved)
Unapprove (from states Approved or Rejected to state Unapproved)
Reject (from state Unapproved to state Rejected)
Cancel Resumed (from state Resumed to state Cancelled)
Cancel Approved (from state Approved to state Cancelled)
Resume (from state Cancelled to state Resumed)

Planview Hub: 18.2 and later

Any supported repository version:

Planview Hub

Third Party Functional Limitation

Status Fields

Investments (e.g. Project, Program, Asset) have a workflow around the Status field. Due to limitations in the XOG API, some status transformations cannot be performed (i.e.: Rejected -> Approved, Cancelled -> Approved, Approved -> Rejected). All other transformations can be performed

Planview Hub: 18.2 and later

Tasktop Sync: 4.14 and later

Any supported repository version:

Configuration Requirement

Time Tracking

The "Do not synchronize time worked before" setting (Clarity Repository Settings Page, Advanced section) must be set to a day that matches the start date of a time period on the Clarity server (or it can be blank).

The "Do not synchronize time worked before" feature has undefined behavior when the date specified does not fall on the start date of a Clarity time period.

Tasktop Sync: 4.4 and later

Any supported repository version:

Tasktop Sync

Best Practices

Time Tracking

If the timesheet entry rounding repository setting is changed to a finer precision, there is a potential that previously equivalent worklogs are now considered non-equivalent and thus will get synchronized. This could cause errors if that happens to be on read-only timesheets.

If users use a customized precision though, there is still a potential for synchronization errors.

Tasktop Sync: 4.4 and later

Any supported repository version:

Tasktop Sync

Known Defect

Time Tracking

Tasktop Sync cannot add multiple worklogs to a Time Period that currently has no time logged for the user.

Tasktop Sync: 4.1 and later

Any supported repository version:

Tasktop Sync

Best Practices

Time Tracking

Retrieving timesheets causes high I/O and CPU load on the data base server of Clarity. Besides ensuring proper sizing of that server, Tasktop Sync and Broadcom strongly recommend performing regular data base maintenance listed here.

Tasktop Sync: 4.1 and later

Any supported repository version:

Tasktop Sync

Third Party API Limitation

Time Tracking

Split time sheet entries are not supported. They are ignored when reading in time sheet data, and an error happens when attempting to write to a split entry.

Tasktop Sync: 4.1 and later

Any supported repository version:

Tasktop Sync