IDM Web Services Toolkit for Windows -...

Version 20.1 rev 3

IDM Web Services Toolkit for Windows

Technical Reference

Notices

PUBLISHERThis document is published anddistributed by Vignette Corporation. It wasdesigned and produced using FrameMakerpublishing software.

VERSIONIDM Web Services Toolkit TechnicalReference, version 20.1 rev 3 (PublicationDate: 23 February 2007)

DISCLAIMERVignette does not warrant, guarantee, ormake representations concerning thecontents of this document. All informationis provided "AS-IS," without express orimplied warranties of any kind including,without limitation, the warranties ofmerchantability, fitness for a particularpurpose, quality and title.

Any information provided by Vignettecustomers or partners was obtained afterthe implementation of Vignette softwareand may have changed as of thePublication Date. You may not achieve thesame results or benefits from usingVignette as described in this document.Nothing in this document is considered tobe part of any product documentation orspecification for any purpose. Vignettereserves the right to change the contents

of this document and the features orfunctionalities of its products and servicesat any time without obligation to notifyanyone of such changes.

COPYRIGHT AND TRADEMARKS

Copyright © 2006 Vignette Corporation. Allrights reserved. Vignette, the V Logo,e:fficiency and e:fficiency experts aretrademarks or registered trademarks ofVignette Corporation in the United Statesand other countries. All other company,product, and service names and brandsare the trademarks or registeredtrademarks of their respective owners.

SEND US YOUR COMMENTS

If you have comments or suggestions aboutthis manual, please send them to thisaddress:

[email protected]

A member of the Publications team willacknowledge your mail as soon aspossible.

You can also reach us at the followingaddress:

Vignette CorporationPublications Department1301 South MoPac Expressway, Suite 100Austin, TX 78746USA

© 2007 Vignette Corporation. All rights reserved.2 v20.1 rev 3

Table of Contents

Chapter 1. Introduction 5Overview 5

What are web services? 5Architecture 6

Data tier—IDM Server 6Business tier—Application Server, Web Server 6Presentation tier—Web browser 6Deployment variations 7

Chapter 2. Configuring the repository component9Introduction 9Configuration 10

Connection pooling configuration 10System configuration 10Setup of remoting objects 11Tracing 13

Advanced configuration 15

Chapter 3. Configuring the application server component 17Introduction 17Configuration 18

Tracing 19Advanced configuration 20

Load balancing configuration 20Renderer configuration 20Cache configuration 22Error configuration 22

Chapter 4. Configuring the web server component23Introduction 23Configuration 24Advanced configuration 25

v20.1 rev 3 3IDM Web Services Toolkit Technical Reference

Table of Contents

Web service timeout configuration 26

Configuring for large files 26

Invoking (testing) the Demo Client 26

Invoking (testing) web services 26

Chapter 5. Configuring the viewer applet 29

Introduction 29

Architecture 30

Configuring JAI support 31

Configuration of the viewer applet 31

Developing applications using the viewer applet 35

Sharing and storage of ticket in the Session object of the web server 35

Loading the viewer applet 35

Loading an image into an existing instance of the viewer applet 36

Tying things together 36

Common issues 39

JRE 39

Large TIFF images 39

Using the viewer applet 40

Viewer applet toolbar 40

Annotations 41

Viewer applet context menu 43

Multi-page documents 44

Subpages 44

Chapter 6. Configuring Single Sign-on 47

Demo client settings 47

Viewer applet settings 48

Application server settings 48

IDM Server settings 48

Security parameters related to SSO 49

Appendix A. Uploading large files 51

Explanatory detail 51


Chapter

1
Introduction
OverviewThe IDM Web Services Toolkit is a product that allows users to develop applications that interface with IDM Server using web based standards and protocols.

This technical reference provides an overview of the product and post-installation configuration instructions.

What are web services?A web service can be described simply as programmable application logic accessible using standard Internet protocols. A web service can be thought of as a reusable web component and can be implemented on any platform using any programming language. Applications can be constructed using multiple web services from various sources that work together regardless of where they reside or how they are implemented.

Below is a list of technologies used and their purpose, when used for building or utilizing web services.

• Extensible Markup Language (XML) is a standard used to represent data used by a web service, with XML Schemas used to describe the data types.

• Simple Object Access Protocol (SOAP) (SOAP) is the communications protocol for web services. SOAP is a specification that defines an XML format for messages. SOAP messages are exchanged using the Hypertext Transfer Protocol (HTTP). IWSTW uses document-literal style SOAP, and complies with the Web Services Interoperability standards (WS-I).

• A Web Services Description Language (WSDL) file is an XML document that describes a set of SOAP messages and how the messages are exchanged. A WSDL file is a contract between a web service consumer and the web service. As WSDL is XML, it is readable and editable but in most cases, it is generated and utilized by the software.


1Chapter

ArchitectureApplications written with the IDM Web Services Toolkit will follow the n-tier architecture consisting of presentation, business and data tiers. The following diagram depicts this architecture.

Data tier—IDM ServerThe data tier consists of IDM Server, which manages the storage and indexing of documents. Access to IDM Server from the business tier is achieved through IDM Web Services repository objects. The remote process call mechanism between the data tier and business tier is .NET Remoting for Windows platforms, which is the subject of this manual.

Business tier—Application Server, Web ServerThe business tier consists of an application server and a web server.

The application server hosts the actual web services—exposing the IDM Web Services Toolkit API. Details of the API can be found in the IDM Web Services Toolkit API Reference. The web services toolkit can utilize a Vignette Rendering Server for document rendering.

Custom web applications or web pages are hosted on the web server and are capable of using the IDM Web Services Toolkit API exposed on the application server. Communication between these two machines is through SOAP over HTTP.

Presentation tier—Web browserThe presentation tier consists of a web browser, running on a machine connected to the internet.

A browser would access a web application simply by connecting to the web server and requesting for web pages using the HTTP protocol. Typically, plug-ins, Java applets or

Browser

Web Server

Application Server

IDM Server

Custom Web Pages (ASP)

IDM Web Services

IDM Web Services Toolkit repository objects

HTTP

SOAP/HTTP

TCP

Windows Rendering

Server

SOAP

Presentation tier

Business tier

Data tier


Introduction

ActiveX controls are not required at the browser end to operate the web application except when the Viewer Applet is used, which obviously requires applets to be deployed..

Deployment variationsTypically not all deployments will or can follow the configuration shown in the architecture diagram, that is, using individual machines for the different tiers. The architecture is flexible enough to allow variations in the deployment of the product. Typically it is the business tier where deployments can vary. The following are three examples of deployment configurations:

Example 1• One machine configured as IDM Server and application server

• One machine configured as the web server

• One machine configured as a Vignette Rendering Server

Example 2• One machine configured as IDM Server

• One machine configured as application server and web server

• One machine configured as a Vignette Rendering Server

Example 3• One machine configured as IDM Server

• One machine configured as application server

• One machine configured as web server

• One machine configured as Vignette Rendering Server


1Chapter


Chapter

2
Configuring the repository component
IntroductionThis chapter describes the post-installation configuration of the software components of the IDM Web Services Toolkit repository objects that run on the IDM Server machine.

Before proceeding further, it is important to understand the following terms:

Remoting object An IDM Web Services Toolkit remoting object is typically a dynamic linked library (DLL) that uses .NET remoting technology and contains the business logic. The .NET remoting technology is a form of remote process communication mechanism that allows objects or processes to communicate across process or machine boundaries using the .NET framework. The functionality in a remoting object can only be used if the remoting object has been hosted.

Remoting host In IDM Web Services Toolkit for Windows, the remoting host is implemented as an executable. Each remoting host should host a single remoting object.


2Chapter

Configuration

Connection pooling configurationIf IDM Server is configured to use an Oracle or SQL Server database, ensure that connection pooling is enabled.

To ensure that connection pooling is enabled

1. Open up the “Data Sources (ODBC)” control panel. This is located in Start > Settings > Control Panel > Administrative Tools > Data Sources (ODBC).

2. Select the “Connection Pooling” tab.

3. Locate the relevant database ODBC driver – for Oracle it is Oracle in OraHome<vv> (where <vv> denotes the version) while for SQL Server it is SQL Server. Double-click to launch the selected driver and a dialog should appear.

• Ensure that “Pool connections to this driver” is selected.

• Leave the unused time period at the default value of 60 seconds.

Apply these changes.

System configurationIn the System folder of IDM System Administration, there are two variables related to sessions. These variables are set to their default values and can be modified according to custom requirements.

IDM Repository: Ticket alive period (in mins)The time a ticket must exist before it can timeout or is considered for cleanup. This setting is measured in minutes with a default minimum value of 1 minute.As the consequence of this variable, if the user logs off and then on again the number of logged-in users will not decrease immediately; refreshing the frame that displays the number of current users after “ticket_alive_interval” will decrease the number.

IDM Repository: Ticket timeout period (in mins)The period of inactivity of tickets before tickets will timeout. This setting is measured in minutes with a default value of 60 minutes.

NOTE: Here “ticket” refers to a successful login session.

In the Install folder of IDM System Administration, there are two configuration variables that control queue connection recovery in the queue remoting host.

Number of connection retriesSpecify the number of retries a queue remoting host will perform to re-establish a connection to a queue manager. The default value is zero.

Time between connection retries (in secs)Specify the time interval in which a queue remoting host will wait



between connection attempts to a queue manager. The default value is 1 second.

NOTE: These two settings also apply to other IDM products which may connect to queuesystem, such as IDM Client and IDM System Administration.

Setup of remoting objects

1. Login to IDM Server as the instance user.

2. Add a Windows system environment variable named imagestore. Set this to the IDM Server hostname or IP address. This variable must be set before starting up the remoting objects on IDM Server.

3. Add the remoting object port numbers to the file $CTL_RUNTIME_DIR/is/config/services:

Use tabs to space the columns. Do not use spaces or other characters.

rlogin 9500/tcp # Login services remoting object

rdb 9510/tcp # Data services remoting object

rdoc 9520/tcp # Retrieval services remoting object

rimport 9530/tcp # Import services remoting object

rmisc 9540/tcp # Miscellaneous services remoting object

rannot 9590/tcp # Annotations remoting object

rqueue 9595/tcp # Queue services remoting object

rdm 9615/tcp # Document management

NOTE: If the Web Services Toolkit on a particular IDM Server is to be used to accessqueues on a different IDM Server, these queue systems and ports must be defined inthe $CTL_RUNTIME_DIR/is/config/services file on both servers.

These internal remoting service port numbers must be unique on the server (regardless of the IDM Server instance or type of process). If they are not unique assign different port numbers.

These service port numbers are classified as “internal” because they are used exclusively on the IDM Server. No external processes will communicate on these ports.

NOTE: If any of the port numbers in the $CTL_RUNTIME_DIR/is/config/services fileneeds to be changed, then the honcho service must be restarted for the changes totake effect.

4. Ensure that the remoting hosts are configured with the external service port numbers.

For every remoting host, there is a corresponding configuration file, installed in $CTL_RUNTIME_DIR/is/system directory.


2Chapter

The remoting hosts, their configuration files and default port numbers are listed below:

These port numbers are exposed and are external to IDM Server. The external service port number is contained in the <channel> XML tag within the remoting host configuration file. For example:

<channel ref="tcp" port="9020"> ... </channel>

NOTE: If the IDM Server services need to be tunnelled through a firewall, then thefirewall needs to be configured to allow communication through these ports.

All the remoting hosts except ttnloginhost and ttnqueuehost use the services provided by the other remoting hosts.

For example, ttndbhost, ttndochost, ttnimporthost, ttnmischost, ttnannothost and ttndmhost use the services provided by ttnloginhost. Therefore, the external port number for the service ttnloginhost must be defined in the configuration file (using the <client> XML tag) for the remoting hosts ttndbhost, ttndochost, ttnimporthost, ttnmischost, ttnannothost and ttndmhost.

In the example below, the remoting host being configured requires the services of the login remoting object, which is listening on the local machine on external port number 9000.

<client><wellknown type="Towertech.Common.RemotingInterface.ITTRLogin, ttnRemotingInterface" url="tcp://localhost:9000/Login" /></client>

Starting remoting hostsThe honcho process can start and stop the remoting hosts automatically when IDM Server is started and shutdown. To do this, use IDM System Administration to add the processes to the STARTUP file:

1. Start IDM System Administration.

2. Select IDM Configuration Management.

3. Click on Custom folder.

4. Click on Startup List.

5. Add new entries for the following, if they do not already exist:

ttnloginhostttndbhostttndochost

Remoting host Configuration file Default port number

ttnloginhost ttnloginhost.exe.config 9000

ttndbhost ttndbhost.exe.config 9010

ttndochost ttndochost.exe.config 9020

ttnimporthost ttnimporthost.exe.config 9030

ttnmischost ttnmischost.exe.config 9040

ttnannothost ttnannothost.exe.config 9090

ttnqueuehost ttnqueuehost.exe.config 9105

ttndmhost ttndmhost.exe.config 9115



ttnimporthostttnmischostttnannothostttnqueuehostttndmhost

6. Restart the IDM Server instance to start the remoting hosts.

NOTE: The IDM Server instance(s) of ttnmischost MUST be restarted after adding a newcustom event or modifying an existing custom event.

TracingAll trace files are located in $CTL_RUNTIME_DIR/is/log. Errors will be written to the trace file and the errorlog ($CTL_RUNTIME_DIR/is/log/errorlog). The trace file names and their locations are not configurable.

A feature of the tracing facility is the ability to set trace levels to control the amount of tracing information output to all the trace files. The trace level feature is governed by a configuration variable in the System folder of IDM System Administration, called IDM Repository: Trace Level (MAX, HIGH, MEDIUM, LOW, MIN). The default setting is MAX. This variable refers to the severity of logged records. Therefore MAX means “maximum severity” (effectively errors) and MIN refers to minimum severity (all available trace messages).

The trace level configuration variable accepts the following values:

MAX Only errors are traced and errors are always logged

HIGH High severity trace messages

MEDIUM Medium severity trace messages

LOW Low severity trace messages

MIN Debug mode showing function entry and exit

This should only be changed if there are problems that need to be diagnosed.

Remoting object trace filesThese are trace files for information generated by the remoting objects. Remoting objects are those components that expose an interface to IDM Server. The name of these trace files begin with a lowercase ‘r’.

Tracing information will be recorded in the following files:

rlogin This log contains tracing related to allocation, deallocation and verification of licenses.

rdoc This log contains tracing related to retrieval of documents.

rimport This log contains tracing related to the importing of documents.

rdb This log contains tracing related to the database operations.

rmisc This log contains tracing related to system configuration and application list.

rannot This log contains tracing related to storage and retrieval of annotations.

rqueue This log contains tracing related to queue session registrations and queue connection retries.

rdm This log contains tracing related to document management functionality.


2Chapter

Low level component trace filesThese are trace files for information generated by lower level components, which are used by the remoting objects. The names of these trace files begin with a lowercase ‘m’.

These trace files should only be enabled if there is no corresponding remoting object trace file or if more detailed information is required.

Tracing information will be recorded in the following files:

mlogon This log contains tracing of low level operations related to license management.

mdb This log contains tracing related to database operations including each SQL statement issued to the database.

mdoc This log contains tracing of low level operations related to retrieval of documents.

mmisc This log contains tracing related to general operations such as retrieval of application lists and retrieval of configuration variables.

mimport This log contains tracing of low level operations related to the importing of documents.

mannot This log contains tracing of low level operations related to storage and retrieval of annotations.

mqueue This log contains tracing of low level queue related operations.

mdm This log contains tracing of low level document management operations.



Advanced configurationYou may run multiple instances of the services, except the login service.

Note that trace logs will then include <instance name>:<process id> to identify which instance logged the record.

To configure IDM Web Services Toolkit .NET repository to run more than one instance of a particular service

As an example, consider the situation where an extra document retrieval remoting service is desired to improve the response time of document retrieval. The steps to perform this configuration are similar to those shown in the previous sections.

1. Select the particular service to be duplicated. Do not select the login service, as there can only be one instance of the login service running at a time. All the other remoting objects may have multiple instances running.

2. Make a copy of the remoting host and its configuration file. In a Korn shell, enter:

cd $CTL_RUNTIME_DIR/is/system

cp ttndochost.exe ttndochost2.exe

cp ttndochost.exe.config ttndochost2.exe.config

3. Change the external remoting object port number in the remoting host configuration file from:

<channel ref="tcp" port="9020">

to:

<channel ref="tcp" port="9021">

All other settings in the remoting host configuration file should remain unchanged. The remoting host trace filename can be changed, if desired.

4. Add an internal remoting service port in $CTL_RUNTIME_DIR/is/config/services. For example:

rdoc2 9521/tcp Second Retrieval Services Remoting Object

5. Add a command entry in $CTL_RUNTIME_DIR/is/config/HANDLERS. (Note that this is the customisable HANDLERS file located under the config subdirectory rather than admin.)

ttndochost2 8 ttndochost2 –s rdoc2

This can also be done via the IDM System Administration / IDM Configuration Management snap-in.

6. Add a “run” command in $CTL_RUNTIME_DIR/is/config/STARTUP to automatically start up this second service.

run ttndochost2

This can also be done via the IDM System Administration / IDM Configuration Management snap-in.

7. Stop and restart the IDM Server instance to start up the remoting services.


2Chapter


Chapter

3
Configuring the application server component
IntroductionThis chapter describes the configuration of the software components required on the application server.

For a typical system, the procedures described in the following subsections should be performed. Some components may not be used, or there may be no need to change the factory defaults. In these cases, the corresponding subsection can be skipped after checking its applicability.


3Chapter

Configuration1. Note down the IP address of the Application Server machine in use.

2. Using Internet Information Services (IIS) Manager, create a virtual directory with a chosen name, for example WSAppServer, as a subdirectory of the default web site.

This will be the name used in all other references to the application server virtual directory.

3. Set the path to the installation directory you have chosen. This should result in a Properties window similar to the one shown here:

The IIS properties

Make sure that Execute permissions are set to Scripts only.

4. If your organization uses a proxy server for Internet access, perform the following:

In Internet Options on the Control Panel, select the Connections tab, then click the LAN Settings... button. Make sure that the Bypass proxy server for local addresses field is selected and the appropriate IP addresses are entered.

5. Open for editing the web services configuration file (web.config, located in the installation directory of the application server) with the following information regarding external port numbers on which remoting objects are listening, as well as the IP address of the IDM Server.

• The URL of the Renderer Manager

• The absolute file path of the ExceptionMessages.xml file

• The absolute file path of the ParamsValidation.xml file

• The absolute file path of the object-format.xsd file

• The absolute file path of the Local.log file

• The URL of IDM Server, for all remoting objects.



The places in the file where attention is required are well marked. As an example, one of the lines that requires the URL of IDM Server is:

<wellknown type="Towertech.Common.RemotingInterface.ITTRLogin, ttnRemotingInterface" url="tcp://<IP address of IDM Server>:9000/Login" />

More information can be found in the section Advanced configuration on page 20.

6. Test the web services. To do this, start a new web browser and enter this URL:

http://<IP address of Application Server>:<port>/<Virtual Directory name>/sysservices.asmx

You only need to specify the port number if it is not 80.

Verify that a list of functions is listed in the browser. This test verifies that the installation of web services has been successful.

7. If you wish to configure Single Sign-on (SSO) refer to Chapter 6, Configuring Single Sign-on. There are settings to be made here and in other parts of the system.

TracingTracing can be enabled to aid in debugging and support of the web service components. The locations and names of the trace files are defined in web.config.


3Chapter

Advanced configurationThe configuration file for web services is <install directory of application server>/web.config.

Load balancing configurationIDM Web Services Toolkit can run in a cluster environment, such as Network Load Balancing as used on Windows Server 2003. No special configuration is required for clustering.

Specify your load balancing configuration in a construct of this form:

<wellknown type="Towertech.Common.RemotingInterface.ITTRDoc, ttnRemotingInterface" url="tcp://<IP address>:9020/Doc, tcp://<IP address>:9021/Doc" />

The type specifies

• the interface running on IDM Server, Towertech.Common.RemotingInterface.ITTRDoc in this case.

• the name of the dynamic link library in which the remoting object type can be found, in this case ttnRemotingInterface.

The url specifies

• the remoting objects that implement the interface. In this case there are two remoting objects that implement the interface Towertech.Common.RemotingInterface.ITTRDoc running on IDM Server. The URL of the first object is tcp://<IP address>:9020/Doc. The URL of the second object is tcp://<IP address>:9021/Doc and this web service uses both of them.

(Here, <IP address> is the IP address of IDM Server.)

Renderer configurationOnly rendition to .png format is supported with IDM Web Services Toolkit for Windows.

Renderer manager configurationThe Renderer Manager is a component of the Windows Rendering Web Services product. Refer to the Vignette Rendition Server Technical Reference for further information. The Renderer Manager is used by the IDM Web Services Toolkit for on-the-fly renditioning of documents.

The configuration of the renderer manager is controlled by the VignetteRepEpoWS.RendererManager.RenderManagerService variable. The value of this variable is a URL to the Renderer Manager. The default value needs to be changed but in most cases only the IP address needs to be modified. Enter the IP address of the Render Manager in the following section in the application server configuration file located at <Application Server Installation Directory>/web.config.

<appSettings><add key="VignetteRepEpoWS.RendererManager.RenderManagerService"value="http://<IP add>:<port>/RenderManager/RenderManager.dll?Handler=Default"/>

where <IP add> is the IP address of the render manager and <port> is the render manager web server port.

You need not configure this variable if you do not require on-the-fly rendering of documents.

Renderer cache configurationThe renderer cache uses these variables:


Renderer.retry The number of retries to try to obtain a Renderer Agent Reference.

Renderer.retryIntervalSleeping interval (in seconds) in between retries.

Renderer type configurationThese variables define the classes that perform the rendering conversion for each specified file extension:

Renderer.AFP Specifies the name of the renderer type that converts AFP byte streams to PNG byte streams.

Renderer.PCL Specifies the name of the renderer type that converts PCL byte streams to PNG byte streams.

Renderer.EPS Specifies the name of the renderer type that converts PS byte streams to PNG byte streams.

Renderer.TIF Specifies the name of the renderer type that converts TIFF byte streams to PNG byte streams.

Renderer.DOC Specifies the name of the renderer type that converts DOC byte streams to PNG byte streams.

Renderer.XLS Specifies the name of the renderer type that converts XLS byte streams to PNG byte streams.

The renderer type must be one of the following:

• AFPRenderer—used to render AFP files.

• PCLRenderer—used to render PCL files.

• PSRenderer—used to render PostScript files.

• TIFRenderer—used to render TIF files.

• OutInRenderer—used to render various Windows documents.

Rendering parameter translation table configurationThese variables define the corresponding names of rendering parameters between Tower IDM and the Windows Rendering Server:

HEIGHT Specifies the corresponding name of the Tower IDM HEIGHT rendering parameter as recognized by the Windows Rendering Server.

WIDTH Specifies the corresponding name of the Tower IDM WIDTH rendering parameter as recognized by the Windows Rendering Server.

ZOOMFACTOR Specifies the corresponding name of the Tower IDM ZOOMFACTOR rendering parameter as recognized by the Windows Rendering Server.

FORCE8BITS Specifies the corresponding name of the Tower IDM FORCE8BITS rendering parameter as recognized by the Windows Rendering Server.

CONVTYPE Specifies the corresponding name of the Tower IDM CONVTYPE rendering parameter as recognized by the Windows Rendering Server.

COLORON Specifies the corresponding name of the Tower IDM COLORON rendering parameter as recognized by the Windows Rendering Server.


3Chapter

Cache configurationRenderer.CacheDirectory

This variable specifies the location to cache the images retrieved from IDM Server on the fly. Make sure that the user which runs WSAppServer has write permission to this location. Typically this is IUR_<computer name>, which is an Internet Anonymous User account.

Example:

<add key="Renderer.CacheDirectory" value="c:/etc/tower/cache"/>

The statement above means that the images retrieved will be cached in c:/etc/tower/cache location.

IDMCache.CleanupIntervalThis variable specifies the time interval to cleanup the images in the cache that is not being used or had been time-out.

Example:

<add key="IDMCache.CleanupInterval" value="90"/>

The statement above means that time interval to cleanup the images in the cache is 90 seconds.

Error configurationcustomErrors This variable controls the amount of exception/error information

that is returned to clients that call the web service methods. This variable is a standard .NET configuration variable. The possible values are:

On—Always display user-friendly messages. This does not show stack trace information.

Off—Always display complete exception information. This setting is useful during development but should not be used during production.

RemoteOnly—Display user-friendly messages if the client is not running on the local web server, otherwise return complete exception information.


Chapter

4
Configuring the web server component
IntroductionThe web server component is an ASP.NET-based demonstration client application utilizing web services. Its purpose is to demonstrate the usage of the IDM Web Services Toolkit on the .NET platform for professional service developers.


4Chapter

Configuration• Ensure that you have completed Configuration on page 18 of Chapter 3.

• Note down the IP address of the Demo Client Web Server machine in use.

1. Create the virtual directory. This is done using the Virtual Directory Creation Wizard.

2. Moving through the wizard and input the necessary information.

• Input the name (Alias), for example IDMWSWebServer, as a subdirectory of the default web site.

• Set the path to the installation directory of the web server.

• Allow the permisions Read, Runscripts (such as ASP), and Execute (such as ISAPI applications or CGI).

3. Right click on the virtual directory and select Properties.

4. Click Configuration and select the Mappings tab.

5. Click on Add and enter the following information:

Executable: %windir%\Microsoft.NET\Framework\<version of ASP.NET>\aspnet_isapi.dllExtension: .avpVerbs: GET,HEAD,POST,DEBUGUncheck "Verify that file exists"

6. Click Create to create the Application.

7. Apply all changes and dismiss all dialogs by clicking OK.

8. If your organization uses a proxy server for Internet access, perform the following:

In Internet Options on the Control Panel, select the Connections tab, then click the LAN Settings... button. Make sure that the Bypass proxy server for local addresses field is selected and the appropriate IP addresses are entered, after which the Demo Client can be used.



Advanced configurationIf the Demo Client web server is being hosted on a different machine from the one hosting the web services, it will need to be configured to locate the web services from the different machine as follows.

If you are configuring the Demo Client web server for IDM Web Services Toolkit for Windows, change the following section in the web server configuration file located at <Demo Client Installation Directory>/web.config.

<appSettings><add key="Vignette.IDM.WebServices.AppServices" value="http://<IP address of

Application Server>/<Virtual directory created on Application Server>/AppServices.asmx"/>

<add key="Vignette.IDM.WebServices.DocServices" value="http://<IP address of Application Server>/<Virtual directory created on Application Server>/DocServices.asmx"/>

<add key="Vignette.IDM.WebServices.SysServices" value="http://<IP address of Application Server>/<Virtual directory created on Application Server>/SysServices.asmx"/>

<add key="Vignette.IDM.WebServices.QueueServices" value="http://<IP address of Application Server>/<Virtual directory created on Application Server>/QueueServices.asmx"/>

<add key="Vignette.IDM.WebServices.LibServices" value="http://<IP address of Application Server>/<Virtual directory created on Application Server>/LibServices.asmx"/></appSettings>

If you are configuring the Demo Client web server for IDM Web Services Toolkit for Unix, change the section in the web server configuration file to match the configuration as shown below:

<appSettings><add key="Vignette.IDM.WebServices.AppServices" value="http://<Application

Server>:<port number of Application Server>/vidm_wst_server/AppServices"/><add key="Vignette.IDM.WebServices.DocServices" value="http://<Application

Server>:<port number of Application Server>/vidm_wst_server/DocServices"/><add key="Vignette.IDM.WebServices.SysServices" value="http://<Application

Server>:<port number of Application Server>/vidm_wst_server/SysServices"/><add key="Vignette.IDM.WebServices.QueueServices" value="http://<Application

Server>:<port number of Application Server>/vidm_wst_server/QueueServices"/><add key="Vignette.IDM.WebServices.LibServices" value="http://<Application

Server>/<Virtual directory created on Application Server>/vidm_wst_server/LibServices"/></appSettings>

(Specify <Application Server> as a hostname or an IP address.)

If you are using the viewer applet for image viewing, refer to Configuring the viewer applet on page 29.

To test your configuration, open a browser and execute the following URL:

http://<IP address of Web Server>/<Virtual directory created on Web Server>/loginForm.aspx

A login form should be displayed.

NOTE: The IDM Web Services Windows Demo Client can be used in the following webbrowsers:

Microsoft Internet Explorer 6.0 SP1


4Chapter

Web service timeout configurationThe following is used to customise the timeout for web service API calls from the Demo Client web server. These are found in the file <Demo Client Installation Directory>/web.config.

TimeoutGeneral Specifies the timeout period in milliseconds for all web services APIs except the image retrieval and import related APIs. The default setting is 100 000 milliseconds.

TimeoutRetrieve Specifies the timeout period in milliseconds for image retrieval related web service APIs. The default setting is 100 000 milliseconds.

TimeoutImport Specifies the timeout period in milliseconds for image import related web service APIs. The default setting is 100 000 milliseconds.

Configuring for large filesBy default, ASP.NET permits only files that are 4096 kilobytes (KB) (that is, 4 megabytes) or less to be uploaded to the web server but you may allow larger files by changing the maxRequestLength parameter in the <httpRuntime> section of the Web.config file.

For further information, refer to Appendix A, Uploading large files.

Invoking (testing) the Demo ClientAfter completing the installation you can now access the Demo Client using

http://<computer>:<port>/<virtual directory name>/loginForm.aspx

where

<computer> is the name or IP Address of the box with the Demo Client installed.

<port> is the port number. You need not specify this if it is 80.

For example:

http://192.161.0.1/WSDemoClient/loginForm.aspx

In this example, the port number is 80.

Invoking (testing) web servicesYou can verify web services using

http://<computer>:<port>/<virtual directory name>/<web service end point name>

where

<computer> is the name or IP Address of the box on which the application server component is installed.

<port> is the port number. You need not specify this if it is 80.

<web service end point name> is one of these:

• AppServices.asmx

• DocServices.asmx

• SysServices.asmx

• QueueServices.asmx

• LibServices.asmx

These services are further described in the IWST API Reference Manual.



For example:

http://localhost/iwstw201/AppServices.asmx


4Chapter


Chapter

5
Configuring the viewer applet
IntroductionThis optional component of the IDM Web Services Toolkit product allows developers to integrate a viewing application into their custom web application developed using the IDM Web Services Toolkit.

This chapter is intended for developers of custom web applications.

The viewing application is a Java-based component (called the viewer applet) that allows viewing of images retrieved from an IDM Server. The viewer applet provides the following functionality:

• Support of TIFF, JPEG, PNG, and GIF file formats

• Display and saving of annotations

• Client based image zooming and rotation

• Viewing of sub-pages


5Chapter

ArchitectureThe following diagram describes how the viewer applet fits into an n-tier application developed using the IDM Web Services Toolkit.

Note that the viewer applet is downloaded from the customer web server when the custom web application is accessed.

Browser

Viewer Applet

Web Serv ices Server

IDM Web Services Toolkit

IDM Server

Customer Web Server

Viewer Applet configuration file

Viewer Applet ASPX/JSP pages

HTTP

HTTP/SOAP



Configuring JAI supportJava Advanced Imaging (JAI) Support is software used by the viewer applet to help display TIFF and JPG images. The JAI software package is installed automatically if the viewer applet detects that it is not already available.

To ensure that JAI support for the viewer applet is correctly downloaded

This procedure requires that you have a JDK installed, so that you can use tdpviewer.jar. If there is no JDK installed, there are alternative approaches:

• You can transmit MANIFEST.MF and tdpviewer.jar to some other machine that does have a JDK (via binary mode FTP or some other mechanism), perform the following operations, with suitable adjustments to the paths, and then transmit the files back.

• You may use WinZip to extract MANIFEST.MF, then make required changes as described below and re-zip it.

1. Ensure that you have a JDK installed.

2. Change directory to <Web Server Installation Directory>\AppletPak\JRE.

3. Extract the MANIFEST.MF file. To do this, run

jar -xvf tdpviewer.jar META-INF\MANIFEST.MF

4. Open META-INF/MANIFEST.MF for editing, and look for the line reading

jai-Implementation-URL: http://172.16.1.233/tower/jsp/jre/jai_win.jar

Change the URL to a value with the following convention:

http://<Web Server hostname or IP address>/<Web Server Installation Directory>/AppletPak/JRE/jar-win.jar

For example:

http://TestServer/WSDemoClient/AppletPak/JRE/jar-win.jar

If you do not want to use the default port number of 80, specify the custom port number as part of the custom web server hostname.

5. Change directory to <Web Server Installation Directory> and run this command:

jar -ufm viewer/tdpviewer.jar .\META-INF\MANIFEST.MF

Configuration of the viewer appletTo configure the viewer applet edit the file<Web Server installation directory>\WSDemoClient\AppletPak\web.config. Recall that the demo client’s configuration file is also called web.config, but it resides in the WSDemoClient subdirectory.

As supplied, the demo client’s web.config file contains entries that are relevant only to IDM Web Services, while the viewer applet’s web.config file contains entries relevant only to the viewer applet.

To use the viewer applet with the demo client web server, change the following items in the web server configuration file web.config:

<add key="av.Doc.DocServices" value="http://<IP address of Application Server>/<Virtual directory created on Application Server>/DocServices.asmx"/>

<add key="av.Sys.SysServices" value="http://<IP address of Application Server>/<Virtual directory created on Application Server>/SysServices.asmx"/>


5Chapter

The following are descriptions of the configuration values used by the viewer applet:

Configuration variable Description

av.TraceSwitch This is a trace switch controlling the amount of tracing information output by the viewer applet web pages to the configured trace file.

1 = traces error messages only2 = traces errors and warnings3 = traces detailed error information4 = verbose trace information

Default value is 1

av.Doc.DocServices This is a URL to the DocServices web service. The URL must be valid.

Default value (example) http://ttw2000/WSAppServer/DocServices.asmx

av.MustUnderstandWhenSSO Refer to Configuring Single Sign-on on page 47.

av.SharedSSOKey This is a password key used for Single Sign-on. Refer to Configuring Single Sign-on on page 47.

av.Sys.SysServices This is a URL to the SysServices web service. The URL must be valid.

Default value (example) http://ttw2000/WSAppServer/SysServices.asmx

av.TimeoutSysWS This sets the timeout value for a SysServices web service request in milliseconds.

Default value is 10 000 mS.

av.TimeoutDocWS This sets the timeout value for a DocServices web service request in milliseconds. This value can be increased for situations where image retrieval is taking longer than expected but application response may suffer.

Default value is 10 000 mS.

av.traceFile The name and location of trace file used by the viewer applet web pages.

Default value is C:\tmp\appletviewer.log

av.props.display This variable controls how the image is displayed within the viewer applet window.

0=Original image size1=Fit to width2=Fit to height3=Fit to windowOther values = Original image size

Default value is 0.

av.props.extractrgn This option is not in use in this product and should always be 0.

av.props.blankrgn This option is not in use in this product and should always be 0.

av.props.emailfax This option is not in use in this product and should always be 0.

av.props.docexport This option is not in use in this product and should always be 0.



av.props.maxsubpages For a multi-page document:

- configures the maximum number of pages that can be displayed for a particular IFN.

For a single page with sub-pages document:

- configures the maximum number of sub-pages that can be displayed for a particular page.

av.props.maxzoomheight The maximum zoom height of image (in pixels).

Default value is 1200 pixels.

av.props.maxzoomwidth The maximum zoom width of image (in pixels).


av.props.minzoomheight The minimum zoom height of image (in pixels).


av.props.minzoomwidth The minimum zoom height of image (in pixels).


av.props.imagetype Controls the type of image displayed in the viewer applet—that is color, grayscale or black and white.

color = as a color imagegray = as a grayscale imagemono = blank and white image

Default value is color.

av.props.highlights Defines the number of highlight buttons in the viewer applet annotation toolbar.

Default value is 4.

av.props.highlight.color.n Color property of the nth highlight definition.

av.props.highlight.translucency.n Translucency property of the nth highlight definition.

Possible values are OPAQUE or TRANSLUCENT.

av.props.underlines Defines the number of underline buttons in the viewer applet annotation toolbar.

Default value is 2.

av.props.underline.color.n Color property of the nth underline definition.

av.props.underline.width.n Width property of the nth underline definition in pixels. This controls the thickness of the underline.


av.props.stickynotes Defines the number of sticky notes buttons in the viewer applet annotation toolbar.

Default value is 3.

av.props.stickynote.color.n Color property of the nth sticky note definition.

av.props.stickynote.maxnumchar.n Maximum number of characters property of the nth sticky note definition. This controls the number of characters allowed in a sticky note.

Default value is 1024 characters.

av.props.margincomments Defines the number of margin comment buttons in the viewer applet annotation toolbar.

Default value is 2.

av.margincomment.color.n Color of the nth margin comment definition.

av.props.margincomment.font.n Font property of the nth margin comment definition.

Possible values are TIMESROMAN and SERIF.



5Chapter

NOTES:

Settings for line width and character height are provided for compatibility with other IDM products only; they have no effect in the viewer applet.

The available color names are the standard Java color names: BLACK, BLUE, CYAN, DARKGRAY, GRAY, GREEN, LIGHTGRAY, MAGENTA, ORANGE, PINK, RED, WHITE and YELLOW. Colors can also be specified as RGB values, in the form <red value>.<green value>.<blue value>, where each value lies in the range 0–255. For example, 0.0.0 is black and 255.255.255 is white.

av.props.margincomment.charheight.n Character height property of the nth margin comment definition in points.

Default value is 240 points.

av.props.margincomment.style.n Style property of the nth margin comment definition.

av.props.freehands Defines the number of freehand buttons in the viewer applet annotation toolbar.

Default value is 3.

av.props.freehand.color.n Color property of the nth freehand definition.

av.props.freehand.width.n Width property of the nth freehand definition in pixels. This controls the thickness of the freehand.


av.props.ellipses Defines the number of ellipses buttons in the viewer applet annotation toolbar.

Default value is 2.

av.props.ellipse.color.n Color property of the nth ellipse definition.

av.props.ellipse.width.n Width property of the nth ellipse definition in pixels. This controls the thickness of the ellipse.


av.props.smoothshape Enables or disables anti-aliasing of images when zooming.

0 = disable1 = enable

Default value is 1.

av.props.showsavedialog Enables or disables notification to save annotations if annotations have not been saved.


Default value is 1.

av.props.loadzoomdialog Enables or disables the zoom factor dialog for TIFF images. This setting is not available in the viewer applet package.


Default value is 1.

av.plugin.tcc Sets the web page used for loading and viewing web-capture documents.

Default value is TccPlugIn.aspx.

This variable should not be modified.




Developing applications using the viewer applet

To use the viewer applet within the custom web application

These are the steps in outline:

1. Sharing and storage of ticket in the Session object of the web server

2. Loading the viewer applet

3. Loading an image into an existing instance of the viewer applet

4. Tying things together

These are described in detail immediately below.

Sharing and storage of ticket in the Session object of the web server

The viewer applet web pages utilize the IDM Web Services Toolkit API for retrieval of images and retrieval and saving of annotations. In order to function correctly, these web pages need access to the current ticket. As the viewer applet does not log into IDM Server, it assumes that the custom web application will and that this ticket is stored in the Session object of the web server with an index value of “ticket”.

For example, each web service invocation by the viewer applet web pages, are performed as follows:

string ticket = (string)Session["ticket"]; // retrieve ticket

Validate the ticket using isValid() // validate ticket

Call relevant web service method // invoke web service

Session["ticket"] = ticket; // store new ticket

Your custom web application should follow a similar coding strategy.

Loading the viewer appletLoading the viewer applet is a case of invoking a particular web page with an appropriate query string. That particular web page is called “ViewerApplet.aspx”. The required and optional query parameters for this page are:

Required parametersappname The IDM Application of the requested document

ifn The IFN of the requested document in SSN/DS-ID format

Optional parameterspg The number of the page to display. This value should be between 1

and the number of pages in the document. The default value is 1.

npages The total number of pages in the requested document. If this parameter is not supplied, this value will be automatically determined. This particular parameter enables/disables the next page/previous page/goto page toolbar buttons.


5Chapter

If this parameter is supplied, then this value will be used regardless of the actual number of pages. For example, npages can be set to 97 even if the document contains only 15 pages.

ExamplesAssume that IFN 2/6-1 has 4 pages.

http://testserver/customApp/AppletPak/Server/Viewer/ViewerApplet.aspx?appname=demo&ifn=2/6-1&npages=4&pg=2

This example will load the second page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

http://testserver/customApp/AppletPak/Server/Viewer/ViewerApplet.aspx?appname=demo&ifn=2/6-1

This example will load the first page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

Loading an image into an existing instance of the viewer applet

The downloading of the viewer applet every time an image is retrieved can result in wasted bandwidth but more importantly, unacceptable application response. In most cases, it is desirable to download the viewer applet once and load subsequent images into the existing instance of the viewer applet. Again, to do this, it is a case of invoking the appropriate web page with an appropriate query string. This particular web page is named ImageLoader.aspx and the query parameters are the same as those for ViewerAppplet.aspx described in point 2.

Exampleshttp://testserver/customApp/AppletPak/Server/Misc/ImageLoader.aspx?appname=demo&ifn=2/6-1&npages=4&pg=2

This example will load the second page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

http://testserver/customApp/AppletPak/Server/Misc/ImageLoader.aspx?appname=demo&ifn=2/6-1

This example will load the first page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

Tying things togetherWhile points 2 and 3 describe how to load the initial and subsequent images into the viewer applet, some javascript is required to tie these two steps together in a custom web application for seamless operation.

The first thing to understand is that the result of the invocation of ViewerApplet.aspx is a HTML page with the viewer applet tags embedded inside. Additionally there are two frames in this HTML page—one frame to contain and display the viewer applet and another invisible frame that is used to invoke the viewer applet to load subsequent images.

The loading of the subsequent images into the viewer applet is achieved by changing the location property of the second invisible frame with an invocation to the ImageLoader.aspx page. This step is best illustrated with a commented example from the IDM Web Services Demo Client.

In ResultsForm.aspx, there is a small javascript function called OpenAppletWindow() shown below:



// checks whether the specified window has the applet

// viewer loaded. Returns true or false.function isAppletWindow(win){if (win && win.open && !win.closed && win.frames.length >= 2 &&

win.frames[0] != null){ // If the location property of the first frame // contains 'ViewerApplet', then the applet is loadedframeLocation = win.frames[0].location.toString();if (frameLocation.indexOf("ViewerApplet") != -1){

return true;}}return false;}// open a new child window for the applet viewer// the code behind associates the onClick event with this function// for each of the titles displayed. Essentially when a user clicks on a// title, this function is called. Therefore the loading of the applet// viewer is initiated from the browser and not from the web server.function openAppletWindow(queryStr){// queryStr is constructed by the code behind of ResultsForm.aspx// because it has details about the document such as appname and ifnvar loadAppletUrl = 'AppletPak/Server/Viewer/ViewerApplet.aspx?' + queryStr;var nextImageUrl = 'AppletPak/Server/Misc/ImageLoader.aspx?' + queryStr;var win;var appletViewerOpen = false;

// loop through the child windows of this page and // locate the applet viewer window.for (i = 0; i < _arrayWin.length; i++){

win = _arrayWin[i];

// check whether the window has the applet viewer

// loaded

appletViewerOpen = isAppletWindow(win);

if (appletViewerOpen)

{

break;

}

}

if (!appletViewerOpen){

// no applet viewer window has been opened_arrayWin[_arrayWin.length] = window.open(loadAppletUrl);

}else{

// an applet viewer window has been opened so// load the image into the existing applet// the loading of the image is achieved by changing// the location of the second frame in the applet page

win.frames[1].location = nextImageUrl;}


5Chapter

return false;}

NOTE: The above code only works with Microsoft Internet Explorer.



Common issues

JREThe viewer applet requires the presence of the Sun Java Runtime Environment on the user’s PC in order to function. Ideally this should already be installed but if it is not installed, the user will be prompted to download and install the Sun JRE plug-in. The plug-in will be downloaded from AppletPak/JRE/jre-win.exe on the customer web server. If an earlier version of the Sun Java Runtime Environment is installed on the user’s PC Vignette recommends that you uninstall it and install the current version in its place.

For the correct versions, please consult the Supported Platforms Matrix.

NOTE:

In some cases, the download of the Sun JRE may not have the required AuthentiCode. Ifthis occurs, the browser settings must be changed to allow the download of unsignedActiveX controls, or an error message will be displayed. The browser setting only needs tobe enabled for the download, and once the JRE has been downloaded successfully, thesetting should be changed back to disabled.

The system administrator can supply the AuthentiCode for the JRE themselves, in whichcase the browser setting is irrelevant. In this configuration, the user will be prompted todownload the Sun JRE plug-in every time a document is selected until the Sun JRE isinstalled.

A message “Unsupported document type” will be displayed in the applet’s status bar if a document’s format is not supported by JRE/JAI (only GIF, TIFF, PNG, and JPEG are supported).

The viewer applet supports the English and German languages. The required language must be installed on the machine and the Windows locale must be set to the appropriate country.

Large TIFF imagesWhen the viewer applet is used to view a TIFF image, best efforts are made to display the image as close as possible to its original size. If the image viewed is too large, a JVM “out of memory” exception may be thrown.

The larger the image, the longer it will take to appear on screen. If this exception is being thrown, it can be resolved by increasing the amount of memory available to the JVM. This can be done by setting minimum and maximum heap limit for the JVM.

To set the minimum and maximum heap limit for the JVM

1. Open the Java plug-in control panel—Start > Settings > Control Panel > Java plug-in

2. Select the Advanced tab.

3. In the Java Runtime Parameters text box, enter the following:

-Xms256m -Xmx512m

These values are illustrative only—the values configured are dependent on the physical memory installed on the PC. More information about these parameters can be obtained from the Sun web site.


5Chapter

Using the viewer appletThe viewer applet runs within a browser window or within a frame. This is dependent on how the custom web application has been designed to display the viewer applet. In any case, a toolbar is displayed above the displayed image. The current page and subpage number are shown in the status bar at the lower right-hand corner of the window. The viewer applet can be resized by clicking and dragging the sides or corners of the display window or frame.

The scale (resolution) of the initial display is the original size of the image but you can use the zoom in, zoom out and zoom to rectangle functions to change the scale of the displayed image.

When positioned over the displayed image (with zoom to rectangle disabled), the mouse pointer takes the shape of a four-pointed arrow. You can click-and-drag the image to reposition it in the frame, as an alternative to using the scroll bars.

Viewer applet toolbarThe complete viewer applet toolbar is shown below. Note that, depending on your viewer applet configuration, you might not have access to all toolbar functions.

Viewer applet toolbar

First page: Display the first page of the document. This option will be visually disabled if the first page is currently displayed.

Previous page: Display the previous page of the document. This option will be visually disabled if the first page is currently displayed.

Go to page: Display a dialog where you can enter the required page of the document. This option will be visually disabled if the current document has only one page.

Next page: Display the next page of the document. This option will be visually disabled if the last page is currently displayed.

Last page: Display the last page of the document. This option will be visually disabled if the last page is currently displayed.

Zoom to rectangle: Enlarge a selected rectangular area to the limit of the frame. To define the rectangular area, position the pointer (a hand) over one corner of the rectangle; when you hold down the left mouse button, the pointer changes to a cross-hair. Move the cross-hair to the opposite corner of the rectangle, then release the button.

Zoom in: Enlarge the currently displayed image by a factor of 1.5 both vertically and horizontally.

Zoom out: Reduce the currently displayed image by a factor of 1.5 both vertically and horizontally.

Fit to width: Scale the displayed image to occupy the width of the frame.

Fit to height: Scale the displayed image to occupy the height of the frame.

Restore original size: Rescale the displayed image to its default size.

Rotate to left: Rotate the displayed image 90 degrees anti-clockwise.

Rotate 180 degrees: Rotate the displayed image 180 degrees.



AnnotationsIf your user ID is set up to do so, you can use the viewer applet to add annotations to a document. Annotations can take several forms:

• Overlay highlight—an opaque rectangle that you can draw anywhere on the image.

• Underlay highlight—a transparent rectangle that you can draw over any part of the image.

• Freeform line—a line of any shape and length that you can draw over any part of the image.

• Straight line—generally used to underline text.

• “Sticky note”—a “piece of sticky paper” on which you can type any text.

• Margin note—a textual note that you can write anywhere on the image.

• Oval—a closed oval line of any size that you can draw around any part of the image.

The annotations toolbar

The default annotations toolbar is shown below. Note that your system administrator might have given you a different selection of colors for some or all types of annotation.

Annotations toolbar

These functions are explained in Table 1, Functions on the annotations toolbar, on page 42.

Viewing annotations

Whenever an annotated document is displayed, all annotations are visible. However, although “sticky notes” are visible, the text in them is not visible. You can view (and, if you wish, modify) the text by double clicking the note; the text then appears in a pop-up window. Other annotations may be moved or resized by dragging them or by clicking and dragging their edges.

Saving annotations

Usually, any additions or changes you make to the annotations on a page will be saved when you click on the Save Annotations button, or when you move to another page of the document. (If you move to a different document without saving your new annotations, they will be lost.) However, it can happen that another user has made and saved changes to the same annotation at the same time. In such a case, your changes will not be saved, because they would over-write the other user’s changes that have already been saved. Instead, you will receive a message telling you that there is a conflict, and that one or more annotation changes have not been saved.

Rotate to right: Rotate the displayed image 90 degrees clockwise.

Annotations: Toggle to show or hide the annotations toolbar. (See Annotations on page 41.)

Print: Print the current document, including any annotations.


5Chapter

Table 1: Functions on the annotations toolbar

Overlay highlight (black):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. The rectangle will be filled with the chosen color and will be opaque. Use these like a conventional marker pen.

Overlay highlight (white):

Underlay highlight (yellow):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. The rectangle will be filled with the chosen color and will be transparent. Use these like a conventional highlighter pen.

Underlay highlight (green):

Freeform line (green):

Holding down the left mouse button, use the cross-hair cursor to draw a line of any shape and length (including curves, loops, and polygons) in the chosen color.

Freeform line (blue):

Freeform line (white):

Underline (blue):

Holding down the left mouse button, use the cross-hair cursor to draw a straight line of any length in the chosen color.

Underline (red):

Oval (red):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. An oval ring (ellipse) of the chosen color will be drawn to the edges of the rectangle.

Oval (gray):

Sticky note (pink):

Click where you want to place the sticky note. A pop-up window will then allow you to type any text onto the note. The note will appear as a rectangle of the chosen color.

Sticky note (green):

Sticky note (blue):

Margin comment (red):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. A pop-up window will then allow you to type any text as a note. The text will appear in the chosen color.

Margin comment (yellow):

Save annotations: Save all annotations attached to the current document. Annotations will be saved automatically if you move to another page of the document (but refer to Saving annotations on page 41). This button is only available if you have relevant permission; check with your system administrator.)

Delete annotations: Remove all annotations from the document. (To delete a single annotation, right-click on it, then choose Annotation > Delete.)



Viewer applet context menuIn the viewer applet, the following facilities are available through the context menu, displayed by right-clicking on the image:

Menu option

Submenu option

Purpose

Properties Displays the properties of the current document page/subpage (the page/subpage under the pointer when you right-clicked).

Undo Reverses the last annotation change (disabled if the last action cannot be undone). Multiple undo is supported; actions will be undone in reverse sequence.

Close Subpage Closes the current document subpage (the subpage under the pointer when you right-clicked).

Page Closes the current document page (the page under the pointer when you right-clicked).

Document Closes the current dcoument.

Reload Subpage Reloads the subpage.

Page Reloads the page.

Document Reloads the document.

Order Vertical If multiple pages or subpages are open, they will be arranged in page/subpage number sequence from left to right.

Horizontal If multiple pages or subpages are open, they will be arranged in page/subpage number sequence from top to bottom.

Select Select Subpage The current subpage or page is selected (e.g., for printing); a broken line is drawn around it in the display frame. Disabled if the current subpage or page is already selected.

Unselect Subpage

If the current subpage or page is selected, as shown by a broken line around it in the display frame, it will be unselected, and the broken line around it will be removed. Disabled if the current subpage or page is not selected.

Select All All displayed subpages or pages are selected (e.g., for printing); a broken line is drawn around them in the display frame. Disabled if all displayed subpages or pages are already selected.

Unselect All All currently selected subpages (or pages) are unselected; the broken line around them is removed. Disabled if no displayed subpages or pages are selected.


5Chapter

Multi-page documents

If the displayed document contains multiple pages, the viewer applet can display more than one at the same time. If you already have a page open, opening another page (with Next Page, Previous Page, or Goto Page) will open the new page without closing any current page.

It is possible to zoom out on all open pages to reduce them to “thumbnail” size. You can click-and-drag individual pages. The zoom, scale, and rotate buttons on the toolbar act on the last page you clicked on.

You can navigate through multi-page (or multi-subpage) documents using the keyboard:

Subpages

If the displayed document page includes subpages, a small subpage navigation bar appears below the vertical scroll bar in the display frame.

Options Zoom On Server If checked, all requests for zoom in or out will be processed on the server, and the resultant image sent to the browser.If unchecked, all requests for zoom in or out are processed locally.

Smooth Shape If checked, “anti-aliasing” will be applied in order to smooth transitions between colors. Anti-aliasing improves the appearance of continuous-tone (photographic) images, but is generally unsuitable for bitmap images.

If unchecked, anti-aliasing is not performed.

Note that anti-aliasing of large images can impose a heavy processing load.

Show Save Dialog

If checked, you will be prompted to confirm saving any changed annotations when you move to another page of the document.

If unchecked, changed annotations will be saved without prompting when you move to another page of the document.

Show On Load Zoom Dialog

If checked, then whenever a “big tiff” document (document whose size prevents a display in max. zoom, defined by the system administrator in ttuws.props) is requested, a message will be displayed.

Image type Monochrome Sets color depth to monochrome.

Gray Sets color depth to gray scale.

Full Color Sets color depth to full color.

Function Key

Previous Page PageUp

Next Page PageDown

Previous Subpage Ctrl+PageUp

Next Subpage Ctrl+PageDown

Menu option

Submenu option

Purpose



Viewer applet showing document with subpages

The subpage navigation bar looks like this:

Subpage navigation bar

Go to the previous subpage.

Display a dialog allowing you to enter the number of the subpage you want to navigate to. If the number you enter is greater than the number of subpages, the last subpage will be displayed.

Go to the next subpage.

Subpage navigation bar

Document display


5Chapter


Chapter

6
Configuring Single Sign-on
Single Sign-on (SSO) operates between

• Customer web site (demo client) and application server

• Web server and IDM Server

Separate passwords (encrypted using SHA-1) are used for each of these. They may be the same or they may be different.

The following describes the parameters to be configured if you wish to use SSO.

Demo client settings

These parameters are in the Demo Client configuration file web.config.

By default, these appear in web.config as follows:

<add key="SSO" value="False"/>

<add key="MustUnderstandWhenSSO" value="False"/>

<add key="SharedSSOKey" value="changeme"/>

Change them as appropriate.


SSO Set this to True to use SSO and False for standard username/password login. The default value is False.

MustUnderstandWhenSSO This parameter defaults to True when SSO is in use. If SSO is not turned on it has no effect (but it defaults to False). If SSO is in use, and if your .NET demo client is attempting to communicate with IWST for Unix, difficulties will probably arise and you should set MustUnderstandWhenSSO to False.

SharedSSOKey This is the password key used between the demo client and the application server and therefore it must match SharedKey.WSClient in the application server’s web.config file.

6Chapter

Viewer applet settingsIf the viewer applet is used you must configure these settings in the viewer applet’s web.config.


<add key="av.MustUnderstandWhenSSO" value="False"/>

<add key="av.SharedSSOKey" value="changeme"/>).

Application server settingsYou must configure these settings in the application server’s web.config.


<add key="SharedKey.WSClient" value="changeme" /><add key="SharedSSOKey" value="changeme"/>

IDM Server settingsYou must configure this setting in IDM Server’s install file.


av.MustUnderstandWhenSSO This parameter defaults to True when SSO is in use. If SSO is not turned on it has no effect (but it defaults to False). If SSO is in use, and if your .NET demo client is attempting to communicate with IWST for Unix, difficulties will probably arise and you should set MustUnderstandWhenSSO to False.

av.SharedSSOKey This is the password key used between the viewer applet and the application server and therefore it must match SharedKey.WSClient in the application server’s web.config file.


SharedKey.WSClient This is the password key used between the application server and the demo client and therefore it must match SharedSSOKey in the demo client’s web.config file, and the viewer applet’s web.config file if appropriate.

SharedSSOKey This is the password key used between the application server and IDM Server and therefore it must match SharedKey.WSClient in IDM Server’s install file.


SharedKey.Repository This is the password key used between the IDM Server and the application server and therefore it must match SharedSSOKey in the application server’s web.config file.

Configuring Single Sign-on

By default, this appears in install as follows:

<add key="SharedKey.Repository" value="changeme" />

Security parameters related to SSOThe page ViewerApplet.aspx in AppletViewerPak .NET implementation can be used as a public page to display a document stored in IDM Server.

In this case you must add security-related query parameters to the URL.

For example, the following might be appended to a URL, among the parameters, after the ? symbol:

...&&vign-security-username=tower&&vign-security-nonce=NDY5NmJlNzAxMDNmNDNkMTg4ODg4ZjczMTQyMTA0Y2M%3d&&vign-security-timestance=2005-04-08T13%3a17%3a50&&vign-security-hash=vo5b%2f30uQC%2fINyyYXsTyw0060KQ%3d


vign-security-username The user name used to log into IDM Server.

vign-security-nonce The nonce used to create the message digest.

vign-security-timestance The created time stamp.

vign-security-hash The message digest derived by applying the SHA-1 function to a concatenation of vign-security-nonce, vign-security-timestance and a security key shared between the client and IDM web services.


6Chapter


Appendix

A
Uploading large files
There are two critical stages to uploading a large file from a client PC to IDM Server using IWSTW. The first stage is to upload the file from a client PC to a web server and the second stage is to transfer the file from that web server to IDM Server.

Currently the system relies on ASP .NET to upload a file from the browser to the web server but ASP .NET has limitations on the size of a file to be uploaded.

By default, ASP.NET permits only files that are 4096 kilobytes (KB) (that is, 4 megabytes) or less to be uploaded to the web server but you may allow larger files by changing the maxRequestLength parameter.

To upload larger files

1. Determine whether you wish to change Web.config (for a local change) or Machine.config (for a machine-wide change).

If you choose to change Machine.config, you will find the maxRequestLength parameter already present. If you choose to change Web.config, you will have to add the maxRequestLength parameter and in this case you may find it convenient to copy the syntax from Machine.config.

The Machine.config file is located in the <System Root>\Microsoft.NET\Framework\Version Number\Config folder.

2. Open the file for editing.

3. As appropriate to your situation, either locate and change the maxRequestLength parameter, or add a httpRuntime section with the required maxRequestLength parameter.

4. Save and close the editor.

Note that if this maxRequestLength parameter is set and a request is posted for an upload that exceeds the value of maxRequestLength, a custom error page cannot be displayed. Instead, Microsoft Internet Explorer will display a “Cannot find server or DNS” error message.

Explanatory detailThis information is taken from http://www.microsoft.com, specifically from Article 323245, How to upload a file to a Web server in ASP.NET by using Visual Basic .NET.

Theoretically, the maximum file upload size is fairly large. However, because of ASP.NET health monitoring, you cannot upload very large files in ASP.NET. The ASP.NET worker process has a virtual address space of 2 gigabytes (GB). However, the ASP.NET worker process only uses a little more than 1 GB because of health monitoring and memory fragmentation.

During the upload process, ASP.NET loads the whole file in memory before the user can save the file to the disk. Therefore, the process may recycle because of the memoryLimit


AAppendix

attribute of the processModel tag in the Machine.config file. The memoryLimit attribute specifies the percentage of physical memory that the ASP.NET worker process can exhaust before the process is automatically recycled. Recycling prevents memory leaks from causing ASP.NET to crash or to stop responding.

Additionally, other factors play a role in the maximum file size that can be uploaded. These factors include available memory, available hard disk space, processor speed, and current network traffic. With regular traffic of files being uploaded, Microsoft recommends that you use a maximum file size in the range of 10 to 20 megabytes (MB). If you rarely upload files, the maximum file size may be 100 MB.

NOTE: You can upload files that are larger than 100 MB in ASP.NET. However, Microsoftrecommends that you follow the maximum file upload sizes that are mentioned in thisarticle. To determine more precise file sizes, perform stress testing on computers that aresimilar to the ones that will be used in production.

You may notice the following error messages if you encounter file size limits during the file upload process:

• The page cannot be displayed.

• Server Application is Unavailable

In the event log, the error message will be similar to the following:

aspnet_wp.exe (PID:PIDNumber) was recycled because memory consumption exceeded the SizeLimit MB (Percentage percent of available RAM).

• Exception of type System.OutOfMemoryException was thrown.

You may also find that uploads occur very slowly. If you watch the Aspnet_wp.exe process in Windows Task Manager, you will notice that the memory delta changes by 64 KB every 1 to 2 seconds. Depending on the size of the file, this delay may cause the ASP.NET worker process to recycle because of a responseDeadlock error.


IDM Web Services Toolkit for Windows -...

Documents

Transcript of IDM Web Services Toolkit for Windows -...