Software AG Designer Installing Plug-ins and Fixes Offline

/1.2.0/

Contents
PRELUDE..................................................................................................................................................... 2 INSTRUCTIONS.......................................................................................................................................... 3 1. SETTING UP THE MIRROR APPLICATION .................................................................................................. 3 2. CREATING THE LOCAL COPY OF THE UPDATE SITE (PARTIAL OR COMPLETE) ........................................ 3 2.1 Windows........................................................................................................................................... 3 2.2 Linux ................................................................................................................................................ 3 2.3 Notes ................................................................................................................................................ 4 3. LIST THE CONTENTS OF AN UPDATE SITE (OPTIONAL)............................................................................ 5 3.1 Notes ................................................................................................................................................ 6 4. DISPLAY AND VERIFY THE CONTENTS OF THE REMOTE UPDATE SITE (OPTIONAL) ................................ 6 4.1 Notes ................................................................................................................................................ 6 5. COMPARE THE CONTENTS OF THE LOCAL COPY (OPTIONAL).................................................................. 6 5.1 Notes ................................................................................................................................................ 7 6. PINGING THE UPDATE SITE (OPTIONAL) ................................................................................................. 7 6.1 Notes ................................................................................................................................................ 7 7. PROXY SETTINGS (OPTIONAL)................................................................................................................. 7 7.1 Notes ................................................................................................................................................ 8 8. INSTALLING FEATURES FROM THE LOCAL COPY ..................................................................................... 8 8.1 From the Designer UI...................................................................................................................... 8 8.2 From the Command Line ................................................................................................................. 8
8.2.1 Notes ......................................................................................................................................................... 9

9. MISCELLANEOUS .................................................................................................................................... 9
9.1. Virtual machine system properties: ............................................................................................................. 9

Prelude
This document covers how to install features into Software AG Designer 8.2 for users without direct access to the update site. It is achieved by a special Software AG Eclipse package which deals with mirroring of secured update sites. With this package, a user with access to Empower creates a partial or complete local copy (mirror) of the update site. The location of this copy is communicated to users without access, who install into their Designer from there. The standard Eclipse SDK already provides a mechanism to mirror update sites. Unfortunately, the p2 implementation doesnt support access from the command line to an update site that protects its content by requiring credentials. The Software AG update site (https://empower.softwareag.com/eclipse/updatesite82) is a secure one and requires authentication with Empower account credentials. For the command-line case, Software AG provides a plug-in called com.softwareag.common.eclipse.p2 which deals with the mirroring of secure update sites. There are two possibilities to use this plug-in: The pre-packaged Software AG Mirror application. The tool as archived update site (sag.common.tools.updateSite.zip) and an Eclipse SDK (3.6 or above) into which you install the plug-in.

Instructions
1. Setting up the Mirror Application
When using the pre-packaged application, ensure it is the correct one for your platform, and unpack the archive into an empty folder. This will result in a complete Eclipse installation. However it requires a Java runtime in the path to execute. Alternatively, you can specify a specific Java executable to Eclipse with the -vm argument. When using the archived update site, unpack the zip into the dropins folder of the Eclipse SDK you intend to use, or start the Eclipse SDK and use Help> Install New Software to install from the unpacked archive.

2. Creating the Local Copy of the Update Site (Partial or Complete)

Running Eclipse as command line application is different on Windows and Linux. In both cases, open the command prompt and navigate to the folder containing the Eclipse installation. The full command to create the mirror is as follows (all on one line, even if for readability we show the arguments on several lines here). Optional arguments are enclosed in brackets.

2.1 Windows
Command on Windows:
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.mirror -source <URL of update site> -destination <destination folder> [-username <user name>] [-pass <password>] [-filter <filter pattern>] [-iu <comma-separated IDs of features or plug-ins>] [<proxy settings>] [<VM arguments>]

2.2 Linux
To execute on Linux, you may need to make the eclipse program executable first:
chmod +x eclipse

To run it, include the path:

./eclipse -nosplash -application com.softwareag.common.eclipse.p2.mirror -source <URL of update site> -destination <destination folder> [-username <user name>]

[-pass <password>] [-filter <filter pattern>] [-iu <comma-separated IDs of features or plug-ins>] [<proxy settings>] .[<VM arguments>]

In the following, only the Windows variants of the command lines are shown; Linux users are trusted to infer the appropriate syntax for their platform.

2.3 Notes
If the destination folder does not exist, it will be created; otherwise it must already be an Eclipse repository, e.g. created by a previous mirror command. It is this location that needs to be communicated to users as the (network) path they will use to install from. If desired, it can be hosted in a straightforward manner as file system through any web server. In case of non-HTTP access, use 'file:' to precede any directory source or destination locations. Avoid whitespace or non-standard characters in the paths of the folders involved, as these might cause problems (even when enclosed in quotes). If user name or password are not specified, you will be prompted. In case you are not prompted for user name and password make sure you use secure storage applicable to your version of the Eclipse platform. By default any Eclipse based installation is using:
<user_home>/.eclipse/org.eclipse.equinox.security/secure_storage

If you have previously run a different Eclipse installation, this might lead to impossibility to read the designated source repository. A possible workaround is to (temporarily) rename the secure storage file for example to secure_storage.bak. The -iu argument is applicable for mirroring an individual item or comma separated set of items. The ID format is <id>[/<version>]. The version is optional; if unspecified, the latest version is taken. For a feature, you need to append .feature.group to the feature ID. You find an example below. Without a -iu argument, the complete source update site is mirrored. The -filter argument is applicable for filtering out the installable units from the update site. It uses the standard P2 query language in order to create a string match expression. The last has to be enclosed in double quotes. A sample example to get a wildcard id in a specific version range could be: -filter "id ~= $0 && version ~= $1;org.eclipse.*;[1.0,2.0]"

The application depends on the Eclipse proxy settings. These can be set on the applications command line, a separate call to the proxy command (see below), or in the Eclipse UI. By default, Eclipse uses settings derived from the system environment. Depending on the connection and the update site content, the operation can take a while. If successful, the destination folder will contain a (partial or complete) copy of the update site. Any diagnostic messages are logged into a file named mirror.log in the Eclipse folder. Use the -help argument in order to list the application command syntax. It's available for mirror, verify, ping and proxy applications. The Software AG update site requires an SSL connection, so you need to use a Java runtime with proper SSL root certificates installed. (For example, the one coming with the Software AG products.) For mirroring contents of non-Software AG update sites, the procedure is the same; it is recommended however to specify a different local location for storing the copies.

A complete command on Windows might look as follows:

eclipsec -nosplash -application com.softwareag.common.eclipse.p2.mirror -source https://empower.softwareag.com/eclipse/updatesite82 -destination file:c:/mirror/ -iu com.centrasite.gui.feature.group/8.2.1.0006-0523, com.centrasite.reporting.datasource.ui/8.2.1.0006-0523 -username fred@example.com -pass FredsPassword

3. List the Contents of an Update Site (Optional)

Execute the following command in order to list the contents of the remote or local update site:
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.list -source <URL of update site> -save <destination file> [-username <user name>] [-pass <password>] [-filter <filter pattern>] [<proxy settings>] [<VM arguments>]

A complete example on Windows might look as follows:

eclipsec -nosplash -application com.softwareag.common.eclipse.p2.list -source https://empower.softwareag.com/eclipse/updatesite82

-save c:/list.log -username fred@example.com -pass FredsPassword

3.1 Notes
In case of non-HTTP/S access, use 'file:' to precede any directory source location. Use file path for -save without 'file:'

4. Display and Verify the Contents of the Remote Update Site (Optional)
Execute the following command in order to verify the content of the remote update site for any issue prior to mirroring:
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.verify -source <URL of update site> [-username <user name>] [-pass <password>] [-filter <filter pattern>] [-iu <comma-separated IDs of features or plug-ins>] [<proxy settings>] [<VM arguments>]

A complete example on Windows might look as follows:

eclipsec -nosplash -application com.softwareag.common.eclipse.p2.verify -source https://empower.softwareag.com/eclipse/updatesite82 -iu com.centrasite.gui.feature.group/8.2.1.0006-0523, com.centrasite.reporting.datasource.ui/8.2.1.0006-0523 -username fred@example.com -pass FredsPassword

4.1 Notes
When the Software AG update site is accessed, you will be prompted for username and password in case there are not explicitly specified. Verification actively uses the proxy configuration set either on the command line, separate call to the proxy command (6) or in Eclipse UI. Verification success/failure with 0/n issues detected is the outcome of the command execution in the positive/negative use case.

5. Compare the Contents of the Local Copy (Optional)

Execute the following command in order to compare the contents of two update sites.
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.compare -source1 <URL of first update site>

-source2 <URL of second update site> -save <destination file> [-username1 <first user name>] [-username2 <second user name>] [-pass1 <first password>] [-pass2 <second password>] [-filter <filter pattern>] [<proxy settings>]

5.1 Notes
For local mirror of the update site prefix the location with 'file:' directive. Use file path for -save without 'file:'

6. Pinging the Update Site (Optional)

Execute the following command in order to ping the location of the update site and check for any connectivity issues. Optional arguments are enclosed in brackets.
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.ping -source <URL of update site> -username <user name> -pass <password> [<VM arguments>]

6.1 Notes
When the Software AG update site is accessed, you will be prompted for username and password. Pinging actively uses the proxy configuration set either by the proxy command (6) or in Eclipse UI.

A complete example on Windows might look as follows:

eclipsec -nosplash -application com.softwareag.common.eclipse.p2.ping -source https://empower.softwareag.com/eclipse/updatesite82 -username fred@example.com -pass FredsPassword

7. Proxy settings (Optional)

As noted above, the application depends on the Eclipse proxy settings. Execute the following command in order to establish proxy settings for use in the Designer platform. Optional arguments are enclosed in brackets.
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.proxy [-proxyhost <proxy host w/o http://>

[-proxyuser <proxy user>] [-proxypass <proxy password>] -proxyhostssl <ssl proxy host w/o https://> [-proxyuserssl <ssl proxy user>] [-proxypassssl <ssl proxy password>]] [-proxybypass <comma separated bypassed hosts>] [-proxyclean]

Execute the following command in order to display the current proxy configuration setup.
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.proxydisplay

7.1 Notes
The proxy arguments are used to filter the traffic to the designated source location through a company proxy server. The command line arguments mimic the behavior in Eclipse Window->Preferences->General->Network Connections section. The proxy host location should not be prefixed with any of the available protocols (http:// or https://). Please see the example below. The proxy port is separated by colon from the proxy host. Parameter -proxyclean can be used to reset Eclipse proxy settings to its default state. The proxy settings are persisted in: <Eclipse root>/configuration/.settings/org.eclipse.core.net.prefs Example on Windows might look as follows:
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.proxy -proxyhost proxy:8080 -proxyuser FredUser -proxypass FredPass -proxyhostssl proxyssl:443 -proxyuserssl FredUserSSl -proxypassssl FredPassSSL -proxybypass localhost,127.0.0.1 -proxyclean

8. Installing Features from the Local Copy 8.1 From the Designer UI
Start the Designer. Go to Help->Install New Software. Add the location of the local update site. Select the needed features and proceed as usual.

8.2 From the Command Line

The following example shows the command line used to install features from the local update site into Designer. Again, the command lines for Windows and Linux are slightly different. It is assumed that the command is executed in the installation folder of Designer.
eclipsec -nosplash -application org.eclipse.equinox.p2.director

-repository <update site location> -installIU <item(s) to install>

8.2.1 Notes The items to install are listed in the form <id>[/<version>], separated by commas. If you want to install a new version of an already installed feature, you have to uninstall the previous version first (using -unistallIU instead of -installIU). When installing items using the Designer UI, due to the way p2 visits update sites (even when not explicitly picked), and due to p2s caching, you may see messages similar to the following: "Authentication failed for https://empower.softwareag.com/eclipse/updatesite82" The same will appear if you hit the Cancel button or enter incorrect user credentials more than four times. In case of an authentication failure error popup, the UI will not ask you for a new credentials till the cache is cleared. To overcome this, please follow the steps bellow: 1. Remove the Software AG update site from the available Software Sites 2. Restart the Eclipse In order to disable the automatic connection to all available update sites, please uncheck the option "Contact all update sites during install to find required software". The above described procedure is applicable for any update site hidden behind any authentication scheme.

9. Miscellaneous
9.1. Virtual machine system properties: Add the following argumens in order to read the credentials from a file rather then providing them on the command line: -vmargs -Dpwdfile=<credentials file> A mirror command on Windows might look like this:
eclipsec -nosplash -application com.softwareag.common.eclipse.p2.mirror -source https://empower.softwareag.com/eclipse/updatesite82 -destination file:c:/mirror/ -vmargs -Dpwdfile=c:/credentials.txt

In case both username/password and vm arguments are included on the console, precedence takes the virtual machine ones. Sample credentials.txt: # mirror/vefiry/list/ping 9

username=fred@example.com pass=FredsPassword

10