Getting Started > Choosing Your Work Environment > Integrity Lifecycle Manager Client Graphical User Interface > Integrity Lifecycle Manager Client URL Links
 
Integrity Lifecycle Manager Client URL Links
You can send Integrity Lifecycle Manager client URL links in client-generated e-mail notifications allowing recipients to click the links and open the associated items in various Integrity Lifecycle Manager 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.
* 
Integrity Lifecycle Manager client URL links are supported on all Windows platforms supported by the Integrity Lifecycle Manager client. For the most current product platform support information, browse to:
Key Considerations
• Integrity Lifecycle Manager 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 Integrity Lifecycle Manager client.
If there are multiple installations of the Integrity Lifecycle Manager client installed on a single machine, by default, the protocol is registered with last client installed and is used for opening Integrity Lifecycle Manager 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 Integrity client will respond to Integrity URL links. option. For more information, see “General Preferences”.
* 
By default, e-mail notifications generated by the Integrity Lifecycle Manager client and Integrity Lifecycle Manager server include Integrity Lifecycle Manager client URLs, which are controlled in the Integrity Lifecycle Manager administration client by the mksis.includeIntegrityGUILinks property. For more information, see the Integrity Lifecycle Manager Server Administration Guide or your administrator.
• Integrity Lifecycle Manager client URLs use a custom protocol that Microsoft Outlook does not recognize. As a result, each time you click on a Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity eSupport portal.
• To use Integrity Lifecycle Manager client URLs in rich text fields, the URL prefix integrity must be added to the mksis.im.validURLPrefixes property on the Integrity Lifecycle Manager server. For more information, see the Integrity Lifecycle Manager Server Administration Guide or your administrator.
• When installing a client service pack, the Integrity Lifecycle Manager 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 Integrity Lifecycle Manager protocol uninstalls automatically and its registry entries are removed when you uninstall the Integrity Lifecycle Manager 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.
Integrity Lifecycle Manager Client URL Syntax
The syntax of the Integrity Lifecycle Manager client URL is as follows:
integrity://<server>:<port>/<app>/<command>?selection=<id>
&<option1>=<value1>&<option2>=<value2>
where:
• integrity:// is the Integrity Lifecycle Manager URL protocol registered with Windows
• server is the hostname of the machine where the Integrity Lifecycle Manager server is installed
* 
The hostname may be determined based on values defined by your administrator. For more information, see your administrator or the Integrity Lifecycle Manager Server Administration Guide.
• port is the port number of the machine where the Integrity Lifecycle Manager server is installed
• app is the abbreviation for the domain-specific Integrity Lifecycle Manager 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 Integrity 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 Integrity Lifecycle Manager Client URL Links
You can create e-mail notifications with Integrity Lifecycle Manager 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 Integrity Web interface, and the second hyperlink will open the same item in the Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager client URL links, note the following:
• In Microsoft Outlook e-mail clients, the Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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.
Integrity Lifecycle Manager Item Revision Information in Client-generated E-mail
If item revisioning is enabled, Integrity Lifecycle Manager also provides enhanced summary information in e-mails that are generated from the Integrity Lifecycle Manager 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 an Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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, Integrity Lifecycle Manager creates the standard format for the generated e-mail.
Supported Views, Commands, and Command Options
The following table describes the Integrity Lifecycle Manager client GUI views, and corresponding CLI commands and command options supported in Integrity Lifecycle Manager client URLs:
Integrity Lifecycle Manager client GUI View
CLI Command/Supported Options
URL Examples
Items view
im issues--query--queryDefinition--fields--sortField--sortAscending--nosortAscending
To open item in Integrity Lifecycle Manager 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 inIntegrity Lifecycle Manager client GUI in Item Detail view:
integrity://localhost:9001/im/viewissue? selection=1234
To open item in Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager client GUI in Change Package view:
integrity://localhost:9001/si/viewcp?selection=1234%3A1
Dashboard
im rundashboard--fieldFilter
To open Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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. For more information, see the Integrity Lifecycle Manager Server Administration Guide or your administrator.
URL Encoding Requirements and Considerations
When constructing Integrity Lifecycle Manager client URLs, encoding is required for the values of the command options only (do not encode the entire URL).
Integrity Lifecycle Manager assumes all incoming Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager client URL will be properly decoded by the Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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 Integrity Lifecycle Manager 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.