PTC Windchill RVS

Common Integration Patterns

• Providing Developers with Early Visibility into Requirements
• Associating Planning Items to Implementation Artifacts
• Escalating Help Desk Problems to Developers
• Sharing Customer Feature Requests with Product
• Reporting Known Defects to the Help Desk
• Aligning Testing Teams across Testing Tools
• Populating Requirements into PLM Tools 

Demo Videos

The following demo video demonstrates an integration between Jama, a requirements management tool, and PTC Windchill RV&S, used here by developers for Agile planning and defect tracking. This integration serves to improve collaboration between the product team and the developers, eliminate duplicate data entry between systems, and improve product quality and traceability. 

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 user permissions:

• User must have 'Login' and 'ViewAdmin' permissions enabled in the mks:im permissions section.

• User must have necessary permissions to access desired projects and artifact types to be synchronized.

• User must be able to transition the state of work items.

Connecting to the PTC Windchill RV&S Repository

Standard Authentication

Required Fields: 

• Location/Connection URL 
  • in Hub versions earlier than 19.1.11/19.2.1: URL format must begin with HTTPS
  • Example Format: https://abc-ptc123:9999/
• Username
• Password

Optional Fields: 

• Attachment Field Name: The name (not the display name) of the Attachment field. This field must exist on the artifact type that requires attachment support.
  • Note: If an integration has been created before this field is populated, the user must navigate to the PTC Windchill RV&S collection and refresh the fields available for that collection.
• Comment Field Name: The name (not the display name) of the field that will be used for comments. This must be a long text field with logging enabled.
  • Note: If an integration has been created before this field is populated, the user must navigate to the PTC Windchill RV&S collection and refresh the fields available for that collection.
• 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.

SSO Authentication

Additionally, PTC Windchill RV&S supports the following SSO implementations:

• Script (HTTP cookies)
• X.509 Certificate

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

Rich Text

Supported rich text elements are as follows:

Block Types:

• Headings
• Paragraph
• Preformatted
• Table
• Block
• Ordered List
• Unordered List
• Quote

Span Types: 

• Anchor
• Bold
• Italic
• Font Size
• Underline
• Deleted
• Subscript
• Superscript
• Code

Comments 

To flow comments in PTC Windchill RV&S, enter the name (not the display name) of the field you are using for comments in 'Comment Field Name' in the repository settings. This must be a long text field with logging enabled.

Only one field can be used as the comment field.

If the field that is used as the comment field is changed, you must update the Comment Field Name on the repository settings, and refresh the projects in your collection. To do this, click "Manage Projects" in your Hub collection and then click 'refresh.' Turning Hub off and on again will also work.

If you fill out the Comment Field Name on the repository settings, but receive a message stating that your collection does not support comments on the Comment Flow screen upon configuring your integration, the field you have chosen may not be a long text field with logging enabled, or you may have entered the name of the field incorrectly. 

There is not a strict upper limit to the number of comments that can be posted, but there is a character limit associated with the field.

This limit is set by the user when they create the field; the default is 32000 characters. This limit counts the characters in all of the comments, plus the comment headers, plus the line breaks separating the comments.

Upon creating comments in PTC Windchill RV&S, the configuration requirements shown below must be observed for comments to flow correctly in your integrations. You can customize your comment flow on the Comment Flow screen. 

Note: In PTC Windchill RV&S integrations, comment flow is also supported in Japanese locales; however, it is not guaranteed that comments will flow as expected if using other non-English locales.

Attachments 

Attachments are supported as read-only and can be enabled by specifying the attachment field name (not the display name) in the repository settings. This field refers to the name of the attachment field on PTC Windchill RV&S Server. Only one field can be used as the Attachment field.

The PTC Windchill RV&S connector can retrieve the following metadata when flowing attachments out of PTC Windchill RV&S:

• File Name
• Size
• ID
• Content Type
• Creator (Username)

Learn more about how to configure attachment flow in Planview Hub here.

State Transitions 

Self Transitions

In order to update a PTC Windchill RV&S artifact without moving it to a new workflow state, a self transition was must be configured for the current state of that artifact. See PTC documentation here. If a self transition is not configured for the artifact's current state, the PTC Windchill RV&S server will reject attempts by the connector to update it.

Mandatory Fields per State

PTC Windchill RV&S enables an administrator to specify 'mandatory fields' that are required to have a value before an artifact can move to a new state. The PTC Windchill RV&S connector fetches the mandatory fields of the current artifact state (source state) and the mandatory fields of the target state.

Any mandatory fields that are configured for the target state, but not the source state, must be filled in with a value by the state transition extension or as parameters of the state transition graph.

It is possible for the comments field to be mandatory in the target state but not in the source state.

• If so, the state transition extension or state transition graph must specify a value for the comment (e.g. a transition comment).
• Otherwise, the state transition extension or state transition graph may optionally provide a value for the comment.

Unsupported Mandatory Fields

The PTC Windchill RV&S connector does not support the following mandatory field types:

• Relationship fields
• Attachments field

Permissions

PTC Windchill RV&S allows the administrator to configure fine-grained permissions for each state transition (including self transitions). The user configured for the PTC Windchill RV&S artifact repository in Hub must have sufficient permissions to transition the artifact between any of the available workflow states.

State Transition Names

Each state transition is named consistently according to this format: "source-state-name -> target-state-name".

For example, if the PTC Windchill RV&S server administrator defined a transition between a state named "New" and a state named "Accepted", the unique name of the transition would be "New -> Accepted".

This format was chosen because it matches with the format of transition names returned by the "im viewtype <artifact-type>" command.

The transition names are important when defining the state transition graph in Hub.

Person Reconciliation

For person reconciliation, the following fields are available:

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

Full Scan

Due to third party API limitations, changes 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:

• FVA fields

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

Special Features Supported

Supported Work Items

Note: Artifacts in PTC Windchill RV&S that are marked as 'test suites,' 'test cases,' or 'test sessions' are not currently supported.

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

Supported Containers

Learn more about containment in Planview Hub here.