PTC RV&S Client URL Links
You can send PTC RV&S client URL links in client-generated e-mail notifications allowing recipients to click the links and open the associated items in various PTC RV&S client GUI views. You can also include the URL links in reports and launch them from other URL locations, such as Web pages, Internet Explorer, and the Windows > menu.
 |
PTC RV&S client URL links are supported on all Windows platforms supported by the PTC RV&S client. For the most current product platform support information, see the PTC Release Advisor.
|
Key Considerations
• PTC RV&S client URLs contain the protocol name integrity://, which must be registered with the Windows operating system on each client machine. The registration occurs automatically when you install the PTC RV&S client.
If there are multiple installations of the PTC RV&S client installed on a single machine, by default, the protocol is registered with last client installed and is used for opening PTC RV&S client URLs. You can register the protocol with a different client on the same machine (or disable the option) in the General pane of the client’s Preferences Configuration dialog box by toggling the This PTC RV&S client will respond to PTC RV&S URL links. option. For more information, see General Preferences.
|
|
By default, e-mail notifications generated by the PTC RV&S client and PTC RV&S server include PTC RV&S client URLs, which are controlled in the PTC RV&S Administration Client by the mksis.includeIntegrityGUILinks property. For more information, see the topic on e-mail notifications or contact your administrator.
|
• PTC RV&S client URLs use a custom protocol that Microsoft Outlook does not recognize. As a result, each time you click on a PTC RV&S client URL link, the standard Microsoft Office Outlook Security Notice prompts asking if you want to continue. Click Yes in the dialog box to invoke the PTC RV&S client URL. Alternatively, you can completely disable the dialog box for the integrity:// protocol by creating a registry entry in the operating system. For more information, see article CS121955 on the PTC eSupport Portal.
• To use PTC RV&S client URLs in rich text fields, the URL prefix integrity must be added to the mksis.im.validURLPrefixes property on the PTC RV&S server.
• When installing a client service pack, the PTC RV&S protocol installs automatically only if it is not currently registered on that client. Consequently, if you disable the protocol for a client and later apply a service pack to the same client, as a result the protocol could become re-enabled on that client.
• The PTC RV&S protocol uninstalls automatically and its registry entries are removed when you uninstall the PTC RV&S client. However, if the protocol is registered with a different client (in the case of multiple clients on a single machine), then the registry entries are not removed.
PTC RV&S Client URL Syntax
The syntax of the PTC RV&S client URL is as follows:
integrity://<server>:<port>/<app>/<command>?selection=<id>
&<option1>=<value1>&<option2>=<value2>
where:
• integrity:// is the PTC RV&S URL protocol registered with Windows
• server is the hostname of the machine where the PTC RV&S server is installed
|
|
The hostname may be determined based on values defined by your administrator.
|
• port is the port number of the machine where the PTC RV&S server is installed
• app is the abbreviation for the domain-specific PTC RV&S application, for example, im=Workflows and Documents, si=Configuration Management, extended-web-ui=Refreshed Web Interface.
• command is the name of the CLI command and corresponding view to invoke, for example, viewissue (for more information, see Supported Views, Commands, and Command Options)
• selection=id is the PTC RV&S item ID required by the command (can be a comma- or space-separated list of values, where spaces are URL-encoded to %20, for example, selection=12345%2023456%203456)
• option=value is an arbitrary number of additional settings (corresponds to CLI command options (define multiple values options as a comma-separated list))
|
|
Encoding is required for the values of the command options. For more information, see URL Encoding Requirements and Considerations.
|
Sending and Receiving E-mail Notifications With PTC RV&S Client URL Links
You can create e-mail notifications with PTC RV&S client URLs by clicking a highlighted username in any visible field in the GUI or Web. This opens the default e-mail application with a new message addressed to the user you selected.
The e-mail subject is a brief description of the item and the body contains two hyperlinks. The first hyperlink will open the respective item in the PTC RV&S Web interface, and the second hyperlink will open the same item in the PTC RV&S client GUI. For example, click user jriley in the header of the Item Detail view of item 1234 to generate an e-mail that contains the following links:
WEB: https://jriley.abcfinancial.com:7001/im/issues?selection=1234
REFRESHED WEB: https://jriley.abcfinancial.com:7001/extended-web-ui/items/item/1234
GUI: url:integrity://jriley.abcfinancial.com:7001/im/viewissue?selection=1234
|
|
Depending on your e-mail application, the PTC RV&S client URL link may not be active or clickable until the recipient receives the e-mail notification.
|
When you generate e-mail from a historical view, the e-mail subject and body are annotated with the as of date and time that correspond to the historical view. For example, in the History tab of item 1234, click user jriley on July 9, 2012 9:15:25 PM EST to generate an e-mail notification that contains the following links:
WEB: https://jriley.abcfinancial.com:7001/im/issues?selection=1234&asOf=20120709T211525Z
REFRESHED WEB: https://jriley.abcfinancial.com:7001/extended-web-ui/items/item/1234?asof=2012-07-09T21:15:25Z
GUI: url:integrity://jriley.abcfinancial.com:7001/im/viewissue?selection=1234&asOf=20120709T211525Z
The as of date and time stamp is basic ISO 8601 format in Coordinated Universal Time (UTC) and specified as a full date and time with a time zone designator, for example:
YYYYMMddThhmmssZ
where:
• YYYYMMdd are numerical 4-digit year, 2-digit month and day, respectively (single-digit months and days require a leading 0)
• T separates the date from the time
• hhmmss are numerical 2-digit hour, minutes, and seconds, respectively (single-digit hours, minutes, and seconds require a leading 0)
• Z is the time zone designator for zero UTC offset
|
|
Time is specified from 00:00:00 to 23:59:59 inclusive in 24-hour format, for example, a URL that refers to a time of 13:56:45 is the same as 1:56:45 PM.
In addition, time is specified based on the local time of the sender. If the recipient is in a different time zone from the sender, when the link is clicked and the item opens, it displays in the local time zone.
|
When receiving e-mail notifications containing PTC RV&S client URL links, note the following:
• In Microsoft Outlook e-mail clients, the PTC RV&S client URL appears as a clickable link.
• In Microsoft Outlook Web, clickable GUI links are not supported in any browser.
• In Lotus Notes e-mail clients, the PTC RV&S client URL appears as plain text that is not clickable. You can copy the text into a browser or the Windows > dialog box to open the same view as if it was clicked from a link in a Microsoft Outlook client.
PTC RV&S Item Revision Information in Client-generated E-mail
If item revisioning is enabled, PTC RV&S also provides enhanced summary information in e-mails that are generated from the PTC RV&S client when you click a username link. When you click a username link in a historical item, the subject field of the client-generated e-mail will include item revision information in the following format:
Type<Item ID>: Item summary[revision information] as of asof date
In addition, when item revisioning is enabled, the body text of the client-generated e-mail includes:
As of: [revision information] asof date
To view the historical context for a PTC RV&S item, navigate to the History tab and click the timestamp link for the required date to open the historical item. You can then launch an e-mail message from the historical PTC RV&S item by clicking a username link (such as the Assigned User, Modified By user, or Created By user).
|
|
Item revision information is not included in the client-generated e-mail when you click from a link in the item history, or if you are working from an item where the first revision has not been set.
|
If item revisioning is not enabled, PTC RV&S creates the standard format for the generated e-mail.
Supported Views, Commands, and Command Options
The following table describes the PTC RV&S client GUI views, and corresponding CLI commands and command options supported in PTC RV&S client URLs:
|
PTC RV&S client GUI View
|
CLI Command/Supported Options
|
First Generation Web Interface URL Examples
|
Refreshed Web Interface URL Examples
|
||||
|---|---|---|---|---|---|---|---|
|
Items view
|
im issues--query--queryDefinition--fields--sortField--sortAscending--nosortAscending
|
To open item in PTC RV&S client GUI in Items view:
integrity://localhost:9001/im/issues?query=MyQuery&fields=Summary%2cPriority&sortField=Priority&sortAscending
|
To open item in Refreshed Web Interface Items view:
integrity://localhost:9001/extended-web-ui/items?query=MyQuery&fields=Summary%2cPriority&sortField=Priority&sortAscending
The following special characters are not supported in query definition:
• plus sign (+)
• equal sign (=)
• colon (:)
• semi-colon (;)
• at sign (@)
• ampersand (&)
• question mark (?)
• dollar sign ($)
• comma (,)
• forward slash mark (/)
• star (*)
• exclamation (!)
• single quote (‘)
• left square bracket ([)
• right square bracket (])
• left bracket (
• right bracket )
• left curly bracket ({)
• right curly bracket (})
|
||||
|
Item Detail view
|
im viewissue--asof
|
To open item in PTC RV&S client GUI in Item Detail view:
integrity://localhost:9001/im/viewissue? selection=1234
To open item in PTC RV&S client GUI in historic Item Detail view:
integrity://localhost:9001/im/viewissue?selection=1234&asOf=20120730T190323Z
|
To open item in Refreshed Web Interface Item Detail view:
integrity://localhost:9001/extended-web-ui/items/item/1234
To open item in Refreshed Web Interface historic Item Detail view:
integrity://localhost:9001/extended-web-ui/items/item/1234?asOf=20120730T190323Z
|
||||
|
Document view
|
im viewsegment--asof--fields--outlineColumns
|
To open document in PTC RV&S client GUI in Document view:
integrity://localhost:9001/im/viewsegment?selection=1234&fields=Category%2cText
|
To open document in the Refreshed Web Interface DocStudio view:
integrity://localhost:9001/extended-web-ui/doc-workspace/doc/1234?fields=Category%2cText
|
||||
|
Relationships view
|
im relationships--asof--fields
|
To open document in PTC RV&S client GUI in Relationships view:
integrity://localhost:9001/im/relationships?selection=1234&fields=ID%2cType%2cState%2cSummary
|
To open document in the Refreshed Web Interface Relationships view:
integrity://localhost:9001/extended-web-ui/relationships/item/1234?fields=ID,Type,State,Summary
|
||||
|
Source Trace Viewer
|
im viewsourcetraces--project--asof--devpath--scmHost--scmPort--fields--projectrevision--revision--sortField--sortAscending--nosortAscending
|
To open Source Trace Viewer for member in normal project/subproject:
integrity://localhost:9001/im/viewsourcetraces?selection=code.java&project=c%3a%2fproject.pj& revision=1.0
To open Source Trace Viewer for member in variant subproject:
integrity://localhost:9001/im/viewsourcetraces?selection=code.java&project=c%3A%2Fproject.pj&devpath=TestDevPath&revision=1.0
or
integrity://localhost:9001/im/viewsourcetraces?selection=code.java&project=%23c%3A%2F%23d%3DTestDevPath&revision=1.0
To open Source Trace Viewer for member in build project/subproject:
integrity://localhost:9001/im/viewsourcetraces?selection=code.java&project=c%3A%2Fproject.pj&projectrevision=1.0&revision=1.0
or
integrity://localhost:9001/si/viewsourcetraces?selection=code.java&project=%23c%3A%2F%23b%3D1.0&revision=1.0
|
The Configuration Management feature is not supported in the Refreshed Web Interface
|
||||
|
Source Project
|
si viewproject--project--devpath--projectrevision--filtersubs--nofiltersubs
|
To open PTC RV&S client GUI in Source Project view with empty subprojects filtered out:
integrity://localhost:9001/si/viewproject?project=%2FTestProject%2Fproject.pj&filtersubs
|
The Configuration Management feature is not supported in the Refreshed Web Interface
|
||||
|
Source Member History
|
si viewhistory--project--devpath--projectrevision
|
To open PTC RV&S client GUI in Source Member History view:
integrity://localhost:9001/si/viewhistory?selection=source.java&project=%2FTestProject%2Fproject.pj
|
The Configuration Management feature is not supported in the Refreshed Web Interface
|
||||
|
Change Package
|
si viewcp
|
To open PTC RV&S client GUI in Change Package view:
integrity://localhost:9001/si/viewcp?selection=1234%3A1
|
The Configuration Management feature is not supported in the Refreshed Web Interface
|
||||
|
Dashboard
|
im rundashboard--fieldFilter
|
To open PTC RV&S client GUI and run a specified dashboard:
integrity://localhost:9001/im/rundashboard?selection=%22My%20Dashboard%22
|
To run a specified dashboard in the Refreshed Web Interface:
https://ppuwsv-alm18t.ptcnet.ptc.com:1340/extended-web-ui/dashboards/run?selection=__id121
|
||||
|
Report
|
im runreport--fieldFilter--asOf--issues--query--param--[no]substituteParams
|
To open PTC RV&S client GUI and run a specified report:
integrity://localhost:9001/im/runreport?selection=%22My%20Report%22
|
To run a specified report in the Refreshed Web Interface:
https://ppuwsv-alm18t.ptcnet.ptc.com:1340/extended-web-ui/reports/run?selection=12345
|
||||
|
Chart
|
im runchart--fieldFilter--query
|
To open PTC RV&S client GUI and run a specified chart:
integrity://localhost:9001/im/runchart?selection=%22My%20Chart%22
|
To run a specified chart in the Refreshed Web Interface:
https://ppuwsv-alm18t.ptcnet.ptc.com:1340/extended-web-ui/charts/run?selection=__id158
|
|
|
If the mksis.im.enableautomaticredirectiontoRWI property is set to true, all the URLs pointing to the First Generation Web interface are redirected to the Refreshed Web Interface.
|
In addition, note the following about the command options --project, --tvigui, and --notvigui:
• The option --project supports the Source Configuration Path and Flat Path syntaxes. By using the source configuration path syntax with the --project option, you can specify variant projects and build projects without using the --devpath and --projectrevision options.
For example, instead of specifying the two options
project=c%3A%2Fproject.pj&devpath=TestDevPath
you could specify the single option
project=%23c%3A%2F%23d%3DTestDevPath
For detailed information on these syntaxes, see “Specifying Configuration Management Projects” in the options man page of the CLI man pages.
• The options --tvigui and --notvigui are available for all supported commands. These options control whether the PTC RV&S client URL launches the specified command within the Tabbed View Interface (TVI), which is the client view with full support for ViewSets, or the floating view.
◦ If --tvigui is not specified, then the command launches in the TVI GUI. In other words, the PTC RV&S client GUI opens using the user’s current ViewSet, and the ViewSet configuration controls whether the command opens in a floating view or docked view.
◦ If --notvigui is specified, then the command launches in the floating view, (the TVI GUI is not launched).
|
|
For more information on ViewSets, see Understanding ViewSets (GUI).
|
All PTC RV&S client URLs generated by the system are set to --tvigui. Integrity can be modified to generate standalone URLs (--notvigui); however, your administrator must customize the trigger scripts that generate e-mail notifications.