Document Redirection Module

User Guide

Page 1 of 6

Introduction

The IDS Document Redirection Module provides a way to download document files from an IDS server to an attached IDS client .

This manual is intended for System Administrators and programmers who wish to utilize the IDS Document Redirection Module in their own products.

Redirecting a document requires a call to the IDS Document Redirection Server program (IdsRdSvr.exe).

The call to IdsRdSvr.exe can be initiated in two ways. IdsRdSvr.exe can be published directly on an IDS Server, or it can be called by another program that is running in an IDS client session.

Regardless of how the document redirection is initiated, the result is the same. A of the server side document is downloaded to a temporary folder on the client computer and the user is presented with a File SaveAs dialog. The default save location is the current users My Documents folder and the default is the original document name.

Depending on the arguments passed to IdsRdSvr.exe, an attempt may also be made to open the document with whatever program is associated with its file in the Windows File Associations on the client machine.

See the following section , for details about calling IdsRdSvr.exe.

Calling the IDS Document Redirection Server program (IdsRdSvr.exe) The syntax for calling IdsRdSvr.exe is as follows:

IdsRdSvr.exe DocumentPath [/SaveType]

where: DocumentPath (required) The fully qualified of the server document to be redirected. /SaveType (optional) Can be one of the following Save Type switches. /SaveOptOpen - If the user saves the document, prompt to see if it should also be opened. /SaveOnly - Do not prompt to see if the document should be opened. /SaveOpen - If the user saves the document, always attempt to open it.

If the Save Type switch is omitted, the client program (IdsRdCli.exe) determines the Save Type by checking the following value in the on the client machine.

HKEY_LOCAL_MACHINE\SOFTWARE\IDS LLC\IDS\IdsRdCli\DocumentAction

The default value of DocumentAction is /SaveOptOpen.

Publishing a document directly in the Program Window

Use this method to show a document as an icon in the user’s program window. The user can then double click the icon to download it.

Page 2 of 6

1. the IDS Cluster Manager. 2. Use the Add button on the Applications tab to publish IdsRdSvr.exe. In the Display Name property, enter a descriptive name for the document. In the Executable Name property, specify the fully qualified path to IdsRdSvr.exe. In the Command Line property, specify the fully qualified path of the document to be published, followed by the Save Type argument if required. 3. Optionally, use the Change Icon button to select a suitable icon for the document.

Redirecting a document from within another published application

Use this method if you are publishing your own software and want to provide the user with a way to download and open a file on their local machine from inside one of your applications.

1. Provide a means for the user to choose the file to download/open. This will typically be a link, menu item, or button within your application. 2. Use the Windows CreateProcess() API call, or the Windows Shell function ShellExecute() to start IdsRdSvr.exe. Pass the fully qualified path to the document as the first command line argument. Pass a Save Type switch as the second argument if desired.

Typical example of use

A user starts the IDS Client program, logs on to an IDS Server and double clicks on one of the published applications in the Program Window. The selected application contains a link to a Microsoft Word document. When the link is clicked, the document is redirected back to the client machine and a SaveAs dialog box is presented. The user selects a location on the local machine and clicks Save. A Yes/No dialog box appears offering to open the document. If the user selects Yes, the document is opened according to the Windows File Associations set on the local machine. Typically, this would cause a .doc document to be opened with the Microsoft Word application.

How it works

When the user clicks on the document link, the underlying program uses the Windows ShellExecute() function to call IdsRdSvr.exe and pass it the of a Microsoft Word document that resides on the server. The call to ShellExecute() also includes a special Save switch to let the client know that the user should be prompted to open the document. (/SaveOptOpen)

An example of the call to ShellExecute() might look something like this: (Both the path to IdsRdSvr.exe and the document itself have been quoted, since they contain embedded spaces)

HINSTANCE Inst = ShellExecute(NULL, NULL, "\"c:\\Program Files\\IDS LLC\\IDS Server\\Programs\\IdsRdSvr.exe\"" , "\"c:\\Customer Documents\\Welcome Letter.com\" /SaveOptOpen" , "" , SW_SHOWNORMAL);

Page 3 of 6

IdsRdSvr.exe generates a GUID and uses it to create a unique temporary subdirectory in the same directory as the original document. It then copies the original document into the temporary directory and appends a special IDS document extension to its name. The special IDS document extension consists of two parts. The first part depends on the value of the Save Type argument passed to IdsRdSvr.exe. The second part is always .ids as outlined in the following table:

Save Type argument Special IDS document extension /SaveOptOpen .idsOptOpen.ids /SaveOnly .idsSave.ids /SaveOpen .idsOpen.ids

Using the ShellExecute() statement above as an example, the path of the copied document would be:

C:\Customer Documents\{4D36E96A-E325-11CE-BFC1-08002BE10318}\Welcome Letter.doc.idsOptOpen.ids

IdsRdSvr.exe uses the Client Process Manager SDK to download the copied document to a temporary directory on the client computer. After downloading the document, the SDK attempts to open it using the Windows File Associations on the client machine.

Since, during the IDS client install, a Windows File Association is created that associates the .ids file extension with the program IdsRdCli.exe, this program is run on the client. The user is presented with a File SaveAs dialog and can choose to save the document on their local machine. The default save location is the current users My Documents folder and the default filename is the original document name (in our example: Welcome Letter.doc).

IdsRdCli.exe uses the first part of the special IDS document extension, to determine what action to take next. In our example, this value is .IdsOptOpen, so IdsRdCli.exe knows that the user should be prompted to open the document. A Yes/No dialog box is presented. If the user selects Yes, the document is opened using whatever program is associated with it’s document type on the client machine (For .doc documents this is typically Microsoft Word).

The test server application (IdsRdSvrTest.exe)

In order to aid with the setup and testing of the IDS Client Redirection Module, a test application is included in the server program installation. In the default installation, this program will be located in the server programs folder. (c:\Program Files\IDS LLC\IDS Server\Programs\IdsRdSvrTest.exe)

IdsRdSvrTest.exe can be published on an IDS server and launched from a connected client machine to test the functionality of the Redirection Module.

When the test program is launched, the screen shown in Fig 1 should appear.

Page 4 of 6

Fig 1

Either type the fully qualified path of the document to redirect into the edit box, or click on the ellipse button to browse the IDS server and select a document.

Test program options “Launch the document on the client exactly as it appears” Normally, IdsRdSvr.exe appends a special IDS extension to the name of the file being redirected. This causes IdsRdCli.exe to be executed on the client machine (because the .ids file extension is associated with IdsRdCli.exe during the IDS client install). If you check this checkbox, IdsRdSvr.exe will download the document without appending the IDS file extension and attempt to execute it on the client machine using whatever program is associated with the its file extension.

Important Note: When this option is checked, IdsRdCli.exe will not be executed. The document will be saved and executed in the temporary directory where it is downloaded. (Typically: "c:\Documents and Settings\UserName\Local Settings\Temp\BSFileCache") The temporary file will not be deleted after the program is executed. If the same document is downloaded again without deleting the first temporary file, the new file will automatically get renamed with a unique number. For example, downloading MyDoc.doc twice will result in MyDoc.doc and MyDoc(1).doc being created in the temporary folder.

“Include detailed information in the server log file” Check this box to include detailed information in the server log file (IdsRdSvr.log). This can be useful when troubleshooting issues on the server side.

“Save Type” Select one of the available Save Types from the radio button group. This determines what if any Save Type argument is passed to IdsRdSvr.exe. The choices are as follows: • Use the default Save Type on the client machine. o No Save Type argument is passed to IdsRdSvr.exe. The Save Type is determined by checking a registry setting on the client. The default setting is to prompt the user to open the file (/SaveOptOpen). • Use /SaveOptOpen

Page 5 of 6

o The user is always prompted to open the file. • Use /SaveOnly o The user is never prompted to open the file. • Use /SaveOpen o The file is always opened without prompting the user.

Page 6 of 6