Getting Started > Choosing Your Work Environment > Windchill RV&S Client Graphical User Interface > Windchill RV&S Client URL Links
  
Windchill RV&S Client URL Links
You can send Windchill RV&S client URL links in client-generated e-mail notifications allowing recipients to click the links and open the associated items in various Windchill 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 Start > Run menu.
* 
Windchill RV&S client URL links are supported on all Windows platforms supported by the Windchill RV&S client. For the most current product platform support information, see the PTC Release Advisor.
Key Considerations
• Windchill 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 Windchill RV&S client.
If there are multiple installations of the Windchill RV&S client installed on a single machine, by default, the protocol is registered with last client installed and is used for opening Windchill 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 Windchill RV&S client will respond to Windchill RV&S URL links. option. For more information, see “General Preferences”.
* 
By default, e-mail notifications generated by the Windchill RV&S client and Windchill RV&S server include Windchill RV&S client URLs, which are controlled in the Windchill RV&S administration client by the mksis.includeIntegrityGUILinks property. For more information, see the topic on e-mail notifications or contact your administrator.
• Windchill RV&S client URLs use a custom protocol that Microsoft Outlook does not recognize. As a result, each time you click on a Windchill 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 Windchill 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 Windchill RV&S client URLs in rich text fields, the URL prefix integrity must be added to the mksis.im.validURLPrefixes property on the Windchill RV&S server.
• When installing a client service pack, the Windchill 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 Windchill RV&S protocol uninstalls automatically and its registry entries are removed when you uninstall the Windchill 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.
Windchill RV&S Client URL Syntax
The syntax of the Windchill RV&S client URL is as follows:
integrity://<server>:<port>/<app>/<command>?selection=<id>
&<option1>=<value1>&<option2>=<value2>
where:
• integrity:// is the Windchill RV&S URL protocol registered with Windows
• server is the hostname of the machine where the Windchill 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 Windchill RV&S server is installed
• app is the abbreviation for the domain-specific Windchill 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 Windchill 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 Windchill RV&S Client URL Links
You can create e-mail notifications with Windchill 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 Windchill RV&S Web interface, and the second hyperlink will open the same item in the Windchill 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: http://jriley.abcfinancial.com:7001/im/issues?selection=1234
GUI: url:integrity://jriley.abcfinancial.com:7001/im/viewissue?selection=1234
* 
Depending on your e-mail application, the Windchill 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 4:15:25 PM EST to generate an e-mail notification that contains the following links:
WEB: http://jriley.abcfinancial.com:7001/im/issues?selection=1234&asOf=20120709T211525Z
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 Windchill RV&S client URL links, note the following:
• In Microsoft Outlook e-mail clients, the Windchill 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 Windchill RV&S client URL appears as plain text that is not clickable. You can copy the text into a browser or the Windows Start > Run dialog box to open the same view as if it was clicked from a link in a Microsoft Outlook client.
Windchill RV&S Item Revision Information in Client-generated E-mail
If item revisioning is enabled, Windchill RV&S also provides enhanced summary information in e-mails that are generated from the Windchill 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 Windchill 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 Windchill 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, Windchill RV&S creates the standard format for the generated e-mail.
Supported Views, Commands, and Command Options
The following table describes the Windchill RV&S client GUI views, and corresponding CLI commands and command options supported in Windchill RV&S client URLs:
Windchill 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 Windchill 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 inWindchill RV&S client GUI in Item Detail view:
integrity://localhost:9001/im/viewissue? selection=1234
To open item in Windchill 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 Windchill 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 Windchill 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 Windchill 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 Windchill 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 Windchill RV&S client GUI in Change Package view:
integrity://localhost:9001/si/viewcp?selection=1234%3A1
Dashboard
im rundashboard--fieldFilter
To open Windchill RV&S client GUI and run a specified dashboard:
integrity://localhost:9001/im/rundashboard?selection=%22My%20Dashboard%22
* 
Dashboard names that contain spaces must be URL encoded with quotation marks.
Report
im runreport--fieldFilter--asOf--issues--query--param--[no]substituteParams
To open Windchill RV&S client GUI and run a specified report:
integrity://localhost:9001/im/runreport?selection=%22My%20Report%22
* 
Report names that contain spaces must be URL encoded with quotation marks.
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 Windchill 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 Windchill 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 Windchill 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 Windchill RV&S client URLs, encoding is required for the values of the command options only (do not encode the entire URL).
Windchill RV&S assumes all incoming Windchill 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 Windchill 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 Windchill 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 Windchill RV&S client URL will be properly decoded by the Windchill 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 Windchill 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);
}
The following table describes the requirements and considerations for encoding the values of command options in Windchill 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.