IBPM Viewer Toolkit Overview

The Viewer Toolkit enables a software developer to have access to an easy and intuitive interface to the power and functionality of the IBPM Viewer technology. This is accomplished through the use of the ActiveX custom control known as the OptPage Viewer Control. The OptPage Viewer Control supports hundreds of file formats with full annotation capabilities. The OptPage Viewer control can be customized and extended to satisfy the most demanding requirements through the use of methods, properties and events.

The Viewer Toolkit samples described in this file explain how to use the OptPage ActiveX control enabling developers to create applications using Microsoft Visual Basic. Although there may be some functions that are not included in the samples, the samples cover most of them.

The OptPage ActiveX Control is intended to be used with Microsoft Developer Studio and Microsoft Visual Basic releases as listed in the Release Notes document.

See the following sections for more information:

IBPM Viewer Toolkit Getting Started Guide

IBPM Viewer Toolkit Redistribution Information


IBPM Viewer Toolkit Getting Started Guide

Contents:

A Quick Start Tutorial

Building and Running the Samples

Where to go from Here

Compatibility

A Quick Start Tutorial

Loading and viewing documents

1. Load Visual Basic and create a Standard EXE project.

2. From the Project menu choose the Components option.

3. From the Components dialog, ensure that the Controls tab at the top is selected, then activate the checkbox labeled IBPM OptPage ActiveX Control Module.

4. Click "OK".

5. From the control toolbox, select the OptPage control and place it on the current form.

6. Select the control and press the F1 key. This displays the OptPage control help.

7. Search for the AutoLoadPage method and scroll down to the Sample section. Copy this function from the sample by highlighting the code and pressing CTRL+C.

8. Return to the VB editor and paste the copied code into your project by pressing CTRL+V.

9. Run the project. The selected page is now displayed in the control.

Enabling annotations

1. After the AutoLoadPage call in the Form_Load function, add the following line of code: Let OptPage1.ActivateAnnotations = True

2. Now run the project. An annotation toolbox is now displayed. This toolbox can be used to add annotations to the page. When the form is closed a save prompt appears. If the annotation is saved, it reappears when the project is opened the next time.

Building and Running the samples

The Visual Basic Samples can be found in a subfolder on the SDK CD.

The Samples fully describe additional capabilities. Stellent recommends that the developer step through these samples as a further tutorial of using the OptPage ActiveX Control. The setup program has installed icons for all of these samples, so they can also be run directly from the Start menu.

ANNOBAR - Demonstrates usage of the annotation toolbar

LOADER - Implements the load process for all file types

MDIAPP - Fully functional MDI application

PRINTER - Demonstrates print capabilities

ROTATOR - Demonstrates TIFF rotation capabilities

SDIAPP - Fully functional SDI application

ZOOMER - Implements zooming and information capabilities.

Where to go from Here

Use the F2 key in Visual Basic to bring up the Object Browser. The Object Browser's Paste button is a simple way to find a method or property and then paste it directly into VB code. The Object Browser can also be used to determine constant names for functions that expect constant values.

Shorten development time by pasting code into your application from the samples provided in this toolkit. The MDI and SDI example applications are a great starting point for most applications.

Use the context sensitive help key (F1) to obtain a full description of any of the methods or properties for which more detailed information is needed.

Additional help can be obtained by contacting your IBPM Business Partner or IBPM Customer Support.


IBPM Viewer Toolkit Redistribution Information

The redistribution of the IBPM Viewer (OptPage) ActiveX control requires the following:

All files listed under ToolkitViewer group in the DSMS.dp0 file must be copied to the location of the OptPage ActiveX control (OptPage.ocx), unless you use the DSMS server to distribute the application. If you are using this form of deployment, make sure to include the ViewerToolkit group in your custom deployment file.


Annotations Overview

A custom storage mechanism is provided for the storage and retrieval of annotations. Unlike other viewers, the OptPage ActiveX Control viewer does not automatically burn annotations into the page being viewed. In fact, the viewed page is never modified from its original format. Instead, annotations are stored in a separate directory according to a specific scheme. Assume the page being viewed is:

c:\docs\viewpage.doc

If annotations exist on any page of the document, the annotation file is stored as:

c:\docs\viewpage.doc\notes.ann

Annotations provide the ability to add comments, highlights, etc. to a section of a document page in the Viewer control. Any user can add annotations at any time. Annotations can also be hidden to provide an unobstructed view of the document.

A user (or application) can add any number of annotations. Annotations are saved or discarded when the document is closed, annotations are "unlocked" via the LockAnnotations method, or the user manually closes the annotation toolbar.

The Viewer control provides three methods for annotating a document. The methods, described below, include:

· Using the built-in Annotation ToolBar

· Using an Application-defined ToolBar

· Though direct use of the Using the Annotation API.


Loading IBPM Documents

The first step when integrating with IBPM is retrieving and loading an IBPM Document from the IBPM System. To do this, a client machine must have previously downloaded the IBPM modules including the modules from the IBPM Toolkit, preferably using the IBPM DSMS (see IBPM Documentation for further details on what modules need to be loaded on a client and how they are downloaded to a client). Once this has been completed an IBPM Viewer application integrated with the IBPM System can be developed. The following list summarizes the basic implementation of some of the more important methods and properties that can be used to integrate with IBPM:

1) Method: LoadOptikaPage

To load an IBPM Document Page into the IBPM Viewer ActiveX control, the method LoadOptikaPage is used. One implementation for using this method could be achieved through a menu item, a button, or any other event driven control. To use this method the IBPM SDK Object will need to be implemented since LoadOptikaPage takes an ObjectID object as a parameter (see the IBPM SDK Documentation on the details and examples for using an ObjectID object).

Note: This method is specific to integrating with the IBPM System and should not be used in an application that does not integrate with IBPM.

2) Method: NextPage and PrevPage

To go to the next or previous page in an IBPM Document call one of these methods. These methods will attempt to retrieve the next or previous page from the IBPM System so that it can be displayed by the IBPM Viewer.

Note: These methods can also be used in an application that is not integrated with IBPM so that a user can navigate between pages in a universal file that is opened from a user's local machine.

3) Method: IsNextPage and IsPrevPage

These methods are used to check if there is a next or previous page in an IBPM Document. These should be used in a condition statement to determine if NextPage or PrevPage should be called.

Note: These methods can also be used in an application that is not integrated with IBPM so that a user can check if there is a next or previous page in a universal file that is opened from a user's local machine.

4) Method: GoToPage

This method can be used to navigate directly to another page in an IBPM Document. For instance, it could be implemented through a pop-up dialog containing a text box so that a user could enter a certain page number to navigate directly to the associated page.

5) Method: DisplayPage

This method can be used to navigate to a specific page in a Universal Document. For instance, it could be implemented through a pop-up dialog containing a text box so that a user could enter a certain page number to navigate directly to the associated page.

Note 1: A Universal document could be Microsoft Word, Excel, a bitmap image, etc. that had been previously filed into the IBPM System. For more information on filing a Universal document read the IBPM Documentation on filing Universals from a client machine into the IBPM System.

Note 2: When integrating with IBPM, this method is different than GoToPage since it is only used with Universal Documents. This method can also be outside of the IBPM system to allow a user to navigate to certain page in a file that is loaded from a user's local machine.

7) Property: PageCount

This property returns the number of pages in a document. It can also be used on documents that are loaded locally from a user's machine.

7) Property: PageNumber

This property returns page number of a currently viewed page in a document. It can also be used on documents that are loaded locally from a user's machine.


Security and Annotations Overview

Security and Annotations

The IBPM System contains many security features that are associated with galleries, applications, users, and IBPM tools (see the IBPM System Documentation for details on the security features of the system and how to manage the security of the system using the Security Tool). When integrating the IBPM Viewer SDK with the IBPM System, there are several items to understand with regard to the IBPM Viewer:

1) Each user in the IBPM System has certain viewing privileges and an assigned security level (which are configured with the Security Admin Tool in the IBPM System or by using a security object defined in the IBPM SDK).

2) A user can only view annotations on an IBPM Document if the user is assigned a security level equal to or higher than the security level assigned to a given annotation. For instance, a user with a security level of 7 could see all annotations of security level 7 or less, however, the user would not see annotations of a higher security level.

Note 1: An annotation's security level is dependent upon the user that created the annotation. For instance, a user with a security level of 5 could create annotations that could be viewed by other user's with a security level of 5 or greater. However, user's with a security level below 5 would not be able to view the annotation.

Note 2: Black and White Redaction’s always show up no matter what the security level is since they may hide sensitive data. However, a user can only alter them if the user has an equal or higher security level.

3) A user can only add, modify, and/or delete annotations to an IBPM Document if the user has been assigned the appropriate privileges and security level to do so. For instance, a user must be given Add/Modify rights in the IBPM System to be able to add, modify, and/or delete annotations. Furthermore, the user's security level also determines if the user can alter an annotations. See the section above for information on a user's security level.

4) Before a user can add, modify, and/or delete annotations, the user must lock the IBPM Document Page. This is only possible if the page is not locked another user. When developing for this scenario, the developer has to take into account that if the page is locked then a MessageBox is returned informing the user that the page is currently locked and the user who has the page locked (Optional). Another scenario is if the attempt to lock the page fails then it would be appropriate to return a MessageBox informing the user that the lock failed and the error code of the failure (Optional).

5) When unlocking an IBPM Page, there should be a check to see if the page changed and, if so, then either the changes to the page (page changes could be adding, modifying, and/or deleting annotations and/or page rotation) could be saved automatically or the user could be prompted to save changes. This requires the developer to take into account several scenarios. The first scenario is that annotations could be saved automatically and only a MessageBox would pop up if the unlocking and saving failed. The second scenario could be to use the predefined Viewer SDK PromptSave method which would pop up a dialog to allow the user the option to save annotations. The third scenario is to create a customized save dialog that would have the logic to do the saving and unlocking (possibly of multiple documents) which would require utilizing the Viewer SDK LockAnnotations method under various conditions. The third scenario is more advanced, however, it would offer the developer the greatest flexibility when creating a customized application.

6) Using the Viewer SDK there are two methods to allow the creation of annotations. The first method is to use the predefined IBPM Annotation Toolbar. This could be implemented by using a menu item or any other event-driven control to set the KeepAnnotToolbarVisible property to TRUE and to then set the ActivateAnnotations property to TRUE (see these two properties for examples). The second method would be to create a customized annotation toolbar and then use the ExecuteAnnotToolboxCmd method to execute the creation of the appropriate annotation on an IBPM Page. This second method is more advanced, however, it gives the developer more control for a customized application.

Note: Using either of these mechanisms requires the developer to implement logic that determines if the page has been successfully locked before enabling the annotation toolbar.


ViewerFlag - OptPage (Viewer)

These constants are used to specify the ViewerFlags parameter to the Load methods

(AutoLoadPage, AutoPrintPage, LoadOptikaPage).

Value | Notes
1 | Reserved
2 | Reserved
4 | Reserved
8 | Reserved
16 | Establish a user as annotation administrator for a particular application. User must have Modify rights to be an annotation administrator.
32 | Reserved
64 | Allows the user to add or modify annotations.
128 | Reserved
256 | Deletes the currently viewed file when it is closed.
512 | Disables the ability to Print.
1024 | Disables the ability to Fax.
2048 | Disables Export Capability
4096 | Reserved
8192 | Disable the Overlay
16384 | Reserved
32768 | Reserved
65536 | Enables Stamp Administration
131072 | Enables Black Redaction
262144 | Enables White Redaction
524288 | Enables Span Documents
1048576 | Disables Annotation Capability
2097152 | Shows Hits on Page
4194304 | Reserved
8388608 | Disable Launch Capability