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>
&<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
• 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 user name 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 user name link. When you click a user name 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 user name 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
|
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
|
||
|
Item Detail view
|
im viewissue--asof
|
To open item inPTC 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
|
||
|
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
|
||
|
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
|
||
|
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
|
||
|
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
|
||
|
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
|
||
|
Change Package
|
si viewcp
|
To open PTC RV&S client GUI in Change Package view:
integrity://localhost:9001/si/viewcp?selection=1234%3A1
|
||
|
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
|
||
|
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
|
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.
URL Encoding Requirements and Considerations
When constructing PTC RV&S client URLs, encoding is required for the values of the command options only (do not encode the entire URL).
PTC RV&S assumes all incoming PTC RV&S client URLs are encoded as per RFC 1738 to ensure all URL data can be converted to and from UTF-8. All encoding and decoding uses the UTF-8 encoding scheme for maximum compatibility, as per the WWW Consortium recommendations. For example, a space character will be encoded as %20. For more information, browse to http://docs.oracle.com/javase/8/docs/api/java/net/URLEncoder.html.
All illegal characters are encoded with a percent (%) character followed by the two-digit hexadecimal representation of the ISO-Latin code point for the character.
The following are examples of PTC RV&S client URLs with encoded options:
• integrity://localhost:9001/im/viewissue?selection=12345&asof=%222012-01-01%2014%3a01%3a00%20z%22
where 2012-01-01 12:01:00 z is encoded
• integrity://localhost:9001/si/viewproject?project=%2FTestProject%2Fproject.pj
where /TestProject/project.pj is encoded
• integrity://localhost:9001/im/viewissue?selection=12345&asof=jwWiki%20%e3%82%a2%e3%83%bc%e3%83%86%e3%82%a3%e3
• %82%af%e3%83%ab
where asof=jwWiki アーティクル is encoded
When writing custom trigger scripts or custom actions that generate PTC RV&S client URLs, PTC recommends that you use standard libraries like java.net.Encoder to encode the values of command options in the URL. For example, you can encode by calling the java encoder class
java.net.URLEncoder.encode(some_URL, "UTF-8")
This encoder class conforms to RFC 1738 (the URL specification) and guarantees the PTC RV&S client URL will be properly decoded by the PTC RV&S client when launched. For more information, browse to http://www.rfc-editor.org/rfc/rfc1738.txt.
The trigger script file changePackageNotification.js uses this java class to encode the command options in its PTC RV&S client URLs, as shown in the following example:
/**
* Return a URL-encoded string version of the argument passed in.
*/
function urlEncode(arg)
{
try {
return java.net.URLEncoder.encode(arg,"UTF-8");
} catch (err) {
// Fall-through
}
// If UTF-8 failed, just use the default encoding.
return java.net.URLEncoder.encode(arg);
}
* Return a URL-encoded string version of the argument passed in.
*/
function urlEncode(arg)
{
try {
return java.net.URLEncoder.encode(arg,"UTF-8");
} catch (err) {
// Fall-through
}
// If UTF-8 failed, just use the default encoding.
return java.net.URLEncoder.encode(arg);
}
The following table describes the requirements and considerations for encoding the values of command options in PTC RV&S client URLs:
|
Character Types
|
Coding Requirements/Considerations
|
|---|---|
|
ASCII Control Characters
|
All characters within the range 00-1F and 7F must be encoded.
|
|
Reserved Characters
|
The following special characters are reserved:
• dollar sign ($) encode %24
• ampersand (\&) encode %26
• plus sign (+) encode %2B
• comma (,) encode %2C
• forward slash mark (/) encode %2F
• colon (:) encode %3A
• semi-colon (\;) encode %3B
• equal sign (=) encode %3D
• question mark (?) encode %3F
• at sign (@) encode %40
|
|
Unsafe Characters
|
Some special characters present the possibility of being misunderstood within URLs, for example, they could be incompatible or unreliable. PTC recommends encoding the following characters:
• blank space ( ) encode %20 (especially multiple spaces)
• quotation marks (“”) encode %22
• less than sign (\<) encode %3C
• greater than sign (\>) encode %3E
• number sign (#) encode %23
• percent (%) encode %25
• left brace ({) encode %7B
• right brace (}) encode %7D
• vertical bar/pipe (|) encode %7C
• backslash (\) encode %5C
• caret (^) encode %5E
• tilde (~) encode %7E
• left bracket ([) encode %5B
• right bracket (]) encode %5D
• grave accent (`) encode %60
|
|
Non-ASCII Characters
|
All non-ASCII characters must be encoded. This includes the entire top half of the ISO-Latin set 80-FF hexadecimal.
|
|
Unicode Characters
|
All unicode characters must be encoded. This includes everything above FF.
|