GR:Gravity/Xref/Setup

Setup

Setting the Xref preferences

Before you can start configuring Xref locations the required fields of the Xref preference page must be set (this can change if you switch between Xref servers). You can get the required fields pre-filled by first opening the Xref configuration UI. The Xref configuration will set missing or inconsistent fields based on the Gravity server you are currently logged into, the only thing not done is setting the Xref user's password.

The preference page consists of the following properties:

• Xref Server Url, this is the URL of the Gravity Xref web application.

• Username (Gravity), this must be a valid Gravity user.

• Password, the password belonging to the Gravity user.

The preference page has also the following properties that can be set:

• Maximum results, refers to the maximum number of hits that will be returned for an Xref query.

• On double click hit, download and open the Xref source file in the IDE, enabling this option will download the source file of the selected hit and open it in an editor. If not enabled the source will be opened in the browser. The default behavior is to open in an editor.

• Match Xref source file to workspace file ..., when checked an attempt will be made to match the file name of an Xref hit to a same-named workspace file. If a match is found then the displayed location in the Xref view will be the workspace project (the location name is also black instead of blue). If this option is enabled then it overrides the 'on double click' open in the editor or browser.

• On multiple matches use first else don't match, if checked and there are multiple workspace files that match the Xref file then the first workspace file will be used to match else no matching will take place.

• Download source file only if connection is secure ..., if checked then an Xref source file that needs to be downloaded for viewing (or other purposes) can only be downloaded if the connection to the Xref server is secure. This means that the Xref server URL must be configured with the https protocol. A secure connection ensures that sensitive information cannot be intercepted or viewed by a 3rd party when the source file is being downloaded. If the sensitivity of data is an issue then the Gravity Xref server should be configured to accept secure requests only see Setup HTTPS for Gravity server on how to do this.

Below is an example of how the preferences can look like:

Basic Configuration

Example configuration:

• The Xref Server URL points to the Gravity server installation hosting Xref. The URL is used for configuring Xref clients like TD/OMS. The URL is synchronized with the Web server URL (set in the Web configuration). If the host/IP address or port of the Xref server is not correct then check the Web server URL.
• File ignore patterns is a comma-separated list of patterns of which the files are to be excluded from indexing. Allowed regex characters are '*' and '?', for example '*.sh' (matching is case sensitive, i.e. *.sh will not match script.SH). By default most Unix library types and Windows binaries (.a, .so, .exe, .dll ...) are ignored. This is a global setting and applies to all defined locations.
• Dir. ignore patterns is a comma-separated list of sub/directory names to be excluded from indexing. For example 'archive' or 'src/test' (matching is case sensitive). By default repository meta-data directories such as '.git' and '.svn' are ignored.
• Checkout Interval is the interval in minutes on which the Xref locations will be checked out and optionally indexed if any repository changes were detected.
• Parallel Checkout is the number of checkout jobs that may run parallel during Xref maintenance. The minimum is 1 and maximum is 10, setting 0 will disable checkouts but not the maintenance of a location if it is removed as an Xref location.
• Last Indexing time is the time Xref has run a cross-reference against the provided locations. A cross-reference indexing is automatically run when the Xref configuration is updated (location added, removed, updated). Cross-reference indexing will also run on a fixed period so that remote repository information is refreshed in the Xref projects, by default the period is set at 60 minutes.
• The 'Reschedule Indexing' button can be used to force the re-indexing to run even if no changes to the configuration have been made.

Note that re-indexing can take a few minutes (at most around 5-7 minutes) before it starts on the server, see the xref.log, accessible through the Gravity web, to view indexing progress.

When opening the Xref configuration a check will be done of the server URL in the configuration and the server URL in the Xref preferences. If a difference is detected then it is being assumed that a configuration switch has taken place and the following message is displayed:

When this message is displayed then the Xref Server URL and currently logged in Gravity user will have been set in the Xref preferences. It is usually sufficient to update the password to correct the preferences setting.

Xref license

To be able to set up a Gravity Xref environment the Gravity Xref license must be installed. Without the license, you will not be able to configure Xref and the Gravity server will not process Xref locations (extract & index) or reply to Xref search queries. Note that when you add an Xref license to Gravity then the server will need to be restarted to activate the Gravity Xref processing and Xref web application.