IBPM Overview

Designed from the ground up with a unified tool set, IBPM offers unprecedented opportunities for integration, customization and extensibility. The IBPM SDK provides a powerful set of development tools, with the ability to customize and extend product features.

The out-of-the-box IBPM client application is an application framework that acts as a container for one or more IBPM-based tools. These tools interact with the framework and with one another based on the IBPM messaging architecture. The IBPM client dynamically loads a pre-defined collection of tools, called a Gallery, into the application framework based on the rights of the user that logs into the system.

A Gallery is a collection of IBPM tools and their associated rights and configuration information. Galleries are created by an IBPM system administrator and are assigned to individual users or groups.

Third-party software developers and systems integrators can extend the IBPM Application Framework by developing their own tools that adhere to the IBPM Architecture.

One of the most powerful features of IBPM is the ability to issue a single query that spans multiple information sources. These information sources could include archive, report or workflow data as well as legacy data, SQL data, or any data that can be accessed through an ODBC data source. The Information Broker automatically handles joins across structured and unstructured information sources, providing a seamless list of results back to the user.

The Linked Server can be extended to include data sources beyond the standard ODBC-type interfaces. The Information Provider Interface acts as a service provider API, allowing third-party companies and systems integrators to integrate custom data sources with IBPM.

The IBPM Application Framework is based on the concept of a software "bus", similar to a bus you would find in a PC. The purpose of a bus architecture is to enable independent development of components that can snap into the bus and work together seamlessly. This architecture provides the ultimate degree of flexibility and extensibility.

Marshalling the Bus

The Application bus consists of a Marshalling Agent, which acts as an internal message broker between components on the bus. Each component on the bus can submit actions to the Marshalling agent and process actions received from the Marshalling agent. The Marshalling Agent receives requests from components for actions to be processed, for example a display_object action. The Marshalling Agent then looks up the display_object action in its internal list of components and sends a process action request to the component supporting that action.

Figure 1 below illustrates a typical framework transaction:

Marshalling Agent

Figure 1

Marshalling the Network

A standard IBPM tool called the Sock Tool is responsible for communicating on the network. This tool is built on Winsock for standard Internet communications. Consistent with the plug-and-play architecture of IBPM, this tool could be replaced later with a different tool that supports IPX or some other network communications protocol.

The Framework Marshalls requests for actions both on the local computer and across the network. There is a special action that the framework uses for this purpose, called a process_com action. The Sock Tool is registered with the framework to handle any process_com actions and sends those requests out over the network to an IBPM server capable of handling that action.

This capability means that the IBPM tools don’t have to be aware of the network, or know where tools reside. For example, a tool can submit a Print action, and if the Print tool is located on the local computer, it receives the action. If the Print tool is located on another machine (server), the Marshalling agent sends the request to the Sock Tool, which forwards it to the server capable of processing the action.

Snap-in Tools

The application framework allows third-party developers and systems integrators to develop snap-in components for IBPM. An IBPM Snap-in Tool is a Windows Dynamic Link Library (DLL) or ActiveX Executable (EXE) that exposes certain pre-defined interfaces based on the IBPM Tools specification.

An IBPM Tool usually has one or more actions or methods that it exposes to the framework to perform specific functions, such as Display or Print. When a tool is registered in the IBPM system using the Security Administration functions, the framework calls pre-defined functions exposed in the tool for the purpose of finding out the actions that the tool can perform.

IBPM Tools are currently designed as C-callable DLLs. ActiveX controls are currently supported in the IBPM Framework as long as they are embedded within a standard IBPM Snap-in Tool wrapper.

While the IBPM Snap-in Tools are implemented as DLLs, Stellent provides a Tool Template for the purpose of quickly creating a Snap-in Tool. The Tool Template is a DLL shell. The developer has to add functions specific to the tool and compile.

IBPM Standard Tools

IBPM includes a set of standard tools, ready to use out-of-the-box. Some of the standard tools included with IBPM are listed below:

There are several other standard tools provided for performing functions such as creating and managing Galleries, creating and managing user accounts and privileges and other ancillary functions.

IBPM Client Tools

The application framework is designed to provide an extensible out-of-the-box application for production-level users. However, there are many companies that need to integrate IBPM capabilities into existing legacy applications, line-of-business applications and desktop applications. The client tools work together to provide the developer with a robust set of capabilities for integrating and customizing IBPM.

The Client Tools consist of a library of ActiveX components combined with a robust data interface based on Microsoft’s ODBC specification. The IBPM ActiveX components and the Viewer ActiveX, provide drop-in functionality for developers and systems integrators.

IBPM ActiveX Controls

The IBPM ActiveX controls provide drop-in IBPM capabilities to any application that supports 32-bit ActiveX controls. These controls expose their properties, methods and events through the Microsoft COM architecture to allow an application developer to integrate, customize and extend existing IBPM functionality.

Viewer ActiveX Control

The IBPM Viewer ActiveX control provides the capability to display a variety of document formats including standard Stellent TIFF images, Stellent COLD pages, Spreadsheets, Microsoft Word Processing documents and over 200 other native document type. Full document viewing control is also provided, including rotation, zooming and paging.

The Viewer ActiveX control also provides full control over annotations including ability to add, modify and delete annotations, as well as control over placement on the document.

Sample Viewer ActiveX Properties

· Caption - Retrieves or sets the caption displayed in the control

· FitSides - Scales document to fit sides of Viewer ActiveX control

· FitWindow - Scales document to fit entirely within Viewer ActiveX control

· ShowAnnotations - Determines whether or not annotations are displayed

Sample Viewer ActiveX Methods

· DisplayPage - Displays specific page of loaded document in viewer control

· GoToPage - Positions document to specific page

· NextPage - Displays next page in document

· PrevPage - Displays previous page in document

· PrintPage - Prints one or more pages of current document

· RotatePage - Rotates currently displayed page

Sample Viewer ActiveX Events

· AnnotationDown - Called by Viewer ActiveX control when annotation toolbar is closed by user

· DoDblClick - Called by Viewer ActiveX control when mouse button is double-clicked within control

· DoNextPage - Called by Viewer ActiveX control when next page in document is about to be displayed

· DoPrevPage - Called by Viewer ActiveX control when previous page in document is about to be displayed

· DoZoom - Called by Viewer ActiveX control when document is about to be scaled

Summary

In conclusion, IBPM offers a range of sophisticated tools that have been designed to work on various Microsoft platforms. Since IBPM was developed from the ground up with a robust, extensible architecture, the IBPM tools are closely aligned with the major features of IBPM. The IBPM SDK enables a software developer to create custom tool objects to be hosted by, and within, the IBPM Client. These custom tool objects can then communicate transparently across a network with other distributed objects as if they were local. This is accomplished by using COM and the IBPM Marshalling technology.

· Search Builder | Used for defining saved searches and their associated information sources.
· Search Form | Used to display available saved searches and their prompts to user at runtime.
· Search Results | Used to display a consolidated result of saved searches to a user in tabular format.
· Viewer | Used to render objects and their annotations to user at runtime.
· Work List | Used to display a list of packages from a profile.
· Package Viewer | Used to display attributes and contents of a package to the user.


IBPM Toolkit Overview

IBPM Software Development Kit Overview

The IBPM SDK enables a software developer to create custom tool objects to interact with an IBPM Package in four different modes of communication:

  • Stand Alone. An application is created to interact with IBPM Services.
  • Hosted by / within IBPM. Additional tools can be created to work within a Gallery to communicate and grant permissions through the Security service.
  • Stand Alone + IBPM Client relationship. Combines the stand alone application to work through the Windows Client.
  • IBPM Client + Stand Alone relationship. Allows the Windows client to use features in the custom tool according to the permissions granted through the Security service

These custom tool objects can then communicate transparently across a network with other distributed objects as if they were local. This is accomplished using COM and the IBPM Marshalling technology.

Fundamental concepts of the IBPM SDK:

COM is the base object model on which ActiveX and OLE are built. Because it is object-based it allows for reuse of components. Component objects can be developed using different languages, communicating by a binary standard. COM allows an object to expose its functionality to other components, to host applications and to define its life cycle. COM provides network transparency and communication automation so that communications can take place between objects without one object needing to be aware of another object's location. The objects can be in different processes on the same machine, or in separate processes on different machines.

Aggregation - a way in which one object can make use of another.

Interfaces - the mechanism through which an object exposes its functionality.

IUnknown - the basic interface on which all others are based. It implements the reference counting and interface querying mechanisms running through COM.

Marshalling - the mechanism that enables objects to be used across thread, process and network boundaries, allowing for location independence.

QueryInterface - the method used to query an object for a given interface.

Reference Counting - the technique by which an object (or, strictly, an interface) decides when it is no longer being used and is therefore free to remove itself.

Custom tool objects maintain client/server relationships by running either on the same computer (locally), or separate computers connected by a network (remote). They also run either in-process or out-of-process with respect to their clients. An in-process custom tool is implemented as a dynamic-link library (.DLL file), and therefore runs in the same process as the consumer of its objects. An out-of-process custom tool is an executable (.EXE file) that runs in its own address space.

Out-of-process custom tool objects communicate through a proxy/stub mechanism automatically provided by COM. The proxy and stub handle marshalling and unmarshalling of parameters that are passed to methods of the component. Multiple clients can share the out-of-process component. Furthermore, the proxy/stub mechanism is automatically extended across the network by the IBPM Marshalling technology, to provide enterprise-wide services.

IBPM ActiveX Controls:

The IBPM ActiveX controls provide “drop-in” IBPM capabilities to any application that supports 32-bit ActiveX controls. These controls expose their properties, methods and events through the Microsoft COM architecture to allow an application developer to integrate, customize and extend existing IBPM functionality.

Viewer ActiveX Control

The IBPM Viewer ActiveX control provides the capability to display a variety of document formats including standard Stellent TIFF images, Stellent COLD pages, Spreadsheets, Microsoft Word Processing documents, and over 200 other native document types. Full document viewing control is also provided, including rotation, zooming and paging.

The Viewer ActiveX control also provides full control over annotations including ability to add, modify and delete annotations, as well as control over placement on the document.

IBPM Data Interface:

A key component in the IBPM Tools Strategy is the IBPM Data Interface. No longer is a 32-bit ODBC driver used on the client. Now a COM object (OTQuery) passes information to the Information Broker and an ADO record set is returned. This COM object requires a SQL command.

One of the significant features of the IBPM Production Client is to provide the capability to perform a single query (search) across multiple information sources, even when used with third-party applications. The IBPM toolkit can access these multiple information sources using the OTQuery COM object and the proper SQL syntax for each required Link Server.

Intelligent ADO Capabilities:

The IBPM Data Interface works with controls that support Microsoft ADO technology, such as data-aware grid controls and database result set navigation controls. ADO technology allows the returned record sets to be automatically “connected” to these controls without any programming, by setting the data source property of the data-aware control to the ADO record set.

For example, the Microsoft Data Aware Grid control that ships with Visual Basic 6.0 can be used to easily create a “hit-list” control for IBPM in a Visual Basic application. By setting the Data Source and SQL properties of the control, the results of a query (search) can be easily displayed in a tabular format. When a particular row in the grid is selected, other controls and fields on the Visual Basic form can be automatically linked with IBPM data.

IBPM Data Model:

The IBPM Data Model relies on OLE DB, Microsoft SQL Server (please see ReleaseDocs.chm for currently supported database versions) (which must be installed on the Information Broker), and toolkit COM objects. Standard ODBC SQL Select statements are supported to retrieve information from an IBPM application. For instance, here is a sample of the correct SQL syntax required to return an ADO record set:

SELECT IMG.myDBName.dbo.Img1allfields.NAME1 FROM IMG.myDBName.dbo.Img1allfields

SQL Statement Defined:

IMG: Name of the link server
myDBName: Name of the database
dbo: Database Owner
Img1allfields: Database table (application name and index name combined)
NAME1: Database field name IBPM Data Object Retrieval

As depicted in the above query (search) example, there are several columns in the IBPM data model, which are used to retrieve images and objects from the IBPM object repository. By including the appropriate column in the select list, the actual object will be retrieved by IBPM and returned to the client through the COM object as a Blob (binary large object). Images and other objects are not stored in IBPM as Blobs, but rather use the client-side ODBC support for Blobs as a mechanism for delivering objects to the client workstation.

Once an object is retrieved using the Data Interface, it can be passed to the IBPM Viewer ActiveX control for display and manipulation. The IBPM Data Interface also provides support for annotations, galleries, queries and collections.

Data Interface and Queries:

The IBPM Data Interface provides the ability to perform both prompted and unprompted queries. All queries available to the logged-on user can be selected using IBPM Toolkit COM Objects, qualified by security defined with the security tool. Each returned query (search) is identified as a prompted or unprompted query (search). Unprompted queries may be passed directly to a data bound control. Prompted queries require a “form” to be displayed to the user to allow the prompted query elements (search conditions) to be entered.

A run-time form must be generated by the developer for each prompted query (search) to be executed. A prompted query (search) includes embedded codes denoting fields requiring prompted inputs. This query (search) string must be parsed by the application to determine which fields to prompt for additional information. The embedded codes in the original query (search) string can then be replaced with the data input by the user and passed to a data bound control.

Data Interface Communication:

The IBPM Data Interface is very different than standard ODBC drivers in that the Data Interface does not communicate directly to the database server. Instead, the Data Interface uses the IBPM communications layer to communicate to the IBPM Information Broker using a 3-tier architecture model. This method of communications is transparent to the developer, who doesn’t need to worry about how communications between the client and middle-tier are achieved.

IBPM Information Provider Interface:

The IBPM Information Provider Interface (access to outside data sources, such as an external SQL Database) is an important component in the IBPM Information Source integration strategy. The ODBC specification has become a common way of accessing databases in an enterprise. Today there are many third-party tools and applications that are capable of accessing data through an ODBC data source. The IBPM strategy for integrating information in the enterprise is based on this common ODBC specification. Stellent now takes advantage of the Microsoft Query Processor, Linked Services.

Information Providers:

New with IBPM is the use of link servers. Each data source available to IBPM needs to be defined as a link server. These sources are then available to query. A single IBPM query (search) can be configured to search across multiple link server data sources. Setting up a link server is as easy as creating a DSN on the Information Broker and then defining this DSN as a link server using GenCfg. The Information Broker actually performs a join of the different result sets returned from each data source, providing the user with a single unified result set.


Whats New

What's New in 7.6

Full Microsoft .Net Support

The IBPM 7.6 SDK fully supports and is compatible with the Microsoft .Net development languages, including VB.Net and C#. This compatibility includes use in single threaded desktop environments as well as any .Net multi-threaded environment, including Net web development environments such as ASPX and ASMX.

The IBPM 7.6 SDK also now includes support for native .Net forms when developing IBPM Windows client tools and BPM Forms.

The IBPM 7.6 maintains full support for and compatibility with the Visual Basic 6.0 programming environment. This includes support for existing ITools for the IBPM client and for In-Process and Out-Of-Process Forms written in Visual Basic 6.0.

The IBPM 7.6 SDK .Net Object Model

The object model as it is exposed to .Net will be familiar to users of the SDK in Visual Basic 6. However, there are a few basic changes.

  • The IBPM SDK has been organized into .Net friendly namespaces. The namespaces include:
    Stellent.IBPM.Interop.Common
    Stellent.IBPM.Interop.Imaging
    Stellent.IBPM.Interop.Imaging.Controls
    Stellent.IBPM.Interop.Print
    Stellent.IBPM.Interop.Process
    Stellent.IBPM.Interop.Process.Controls
    Stellent.IBPM.Interop.Process.Dialogs
    Refer the Programmer's Guide and Programmer's Reference sections of this IBPM SDK Help file for further details on the objects contained in each of these namespaces
  • All enumeration constants in the object model have been updated to make them more .Net namespace friendly. In VB6, enumeration constant values were always prefixed with the enumeration type name. For example, the enumeration type otTableProperty contained the value otTableProperty_Imaging. However, .Net requires that an enumeration value always be prefixed with is type. So, left unchanged, the otTableProperty example would always have to be written as otTableProperty.otTableProperty_Imaging. The constant repetition of the enum type is tedious to uses and leads to excessively lengthy code. To solve this problem, enumeration constants were changed to removed the type names from the value and prefixed with a shorter 2 or 3 letter character abbreviation of the type name. So, the table property example becomes just TableProperty.tpImaging.
  • Collections in the BPM object model that contain objects with an appropriate name value (e.g., Process.Name in the Processes Collection) now support a text based indexer in the item property in addition to the original ordinal indexer. So, for example, you can now find a specific Process named "MyProcess" in a Processes Collection with the following code : oProcess = oProcesses.Item("My Process") (or with oProcess=oProcesses["MyProcess"] in C#). This mechanism replaces the FindByKey methods available in VB6. Collections that also contain objects with a valid ID based index will additionally have a new FindById method.
  • The QueryConnection.GetResults method in the .Net object model is equivalent to the GetResults2 method in the VB6 environment. Previous VB6 based documentation stated that GetResults2 was preferred, so the original GetResults syntax has been deprecated for .Net.
  • Object and property names containing the term ComparisonOperators in the imaging object model have been updated to just Operators. This affects the ComparisonOperator collection, the otComparisonOperator enumeration, the NamedQueryCondition.AvailableComparisonOps and the NamedQueryCondition.ComparisonOp properties.
  • The object SelectItemExpression has been renamed SelectItem.
  • The object FromItemTable and been renamed FromItem.

Note: The description of changes described above only applies to the SDK as it will be used in .Net. The usage of the SDK in Visual Basic 6.0 remains unchanged unless specifically noted. Any omponent or enumeration changes that do affect VB6 code will be corrected with the SDKUpdateWizard.

New and changed Objects, Properties, and Methods

The following additions to the object model affect both .Net and VB6 development.

LogWriter Object (Stellent.IBPM.Interop.Common) - The IBPM 7.6 includes a new object so that custom applications and scripts can write log entries in the IBPM service log format. The method supports multiple log entry severity levels including Detail, Info, Warning, and Error. If the application or script calling the object are collocated on a machine with an IBPM service, then the object will write its log entries into the combined service log, and these entries can then be view in the IBPM MMC Service Manager.

UserToken.Groups Property (Stellent.IBPM.Interop.Common) - This new property retrieves the complete list of group SIDs in which the user is a member. This is the list on which the user's aggregated permissions is determined. The data is returned as an array of strings.

The User.ActivateUser method now contains an additional ValidationDelay parameter. This parameters specified the length of time, in seconds, that the user object will reuse cached credentials before sending a verifying with UCON service that the request license is still valid. A value of 0 for this parameter forces an immediate validation. The default value is 60. (Note: This parameter is included for use by VB6 in a new User.ActiveUserEx method.)

The OptPage.LoadOptikaPage method has been updated to accept a DocInfo object. A New DocInfo.PageNumber Property has been added to specify which page should be displayed. (Note: Use of the old OTOBJIDLib::ObecttId is not supported in .Net, but is still included with the SDK for use in VB6. OptPage will continue to accept an ObjectId as well as a DocInfo in VB6.)

Deprecated IBPM SDK objects/classes

As of the Acorde 4.0 release of the IBPM SDK product, the following objects and classes are no longer included or supported:

OTApp.dll – Object that returned the application, index, and field level information.

This object experienced slowness issues. Imaging schema object model (OTContext.dll) is already available and provides the functionality that was previously supplied by OTApp.dll.

SystemManager class (OTSysMgr.dll) – Class which provided the add, modify, write, and delete functionality within OTSysMgr.dll.

The DocumentManager class (formerly SystemManager2) replaces the SystemManager class with the same functionality. The new DocumentManager class uses the Imaging schema object model instead of OTApp. DocumentManager also uses the DocInfo object out of the IBPM Base Object Library (OTAcorde.dll). This reduces the need for using OTObjectID in this instance.

PrintDialogTool.dll - Object that provided printing functionality.

The OTPrintTool provides the functionality previously supplied by the PrintDialogTool. OTPrintTool will be available in the 3.0 release of the SDK.

OTFileProvider.dll – Object that provided an interface to the common storage for universal attachments.

This object was never supported. OTFileStore is supported and can be used in its place.

OTDocumentProvider.dll – Object that provided the functionality to add an attachment to a package.

This object was never supported.


IBPM SDK Update Wizard

Stellent IBPM SDK Update Wizard

Because changes are required when existing code is opened and recompiled, Stellent is providing a Visual Basic Add-In called the Stellent IBPM SDK Update Wizard. This wizard automatically makes all changes required to make any pre Acorde 3.1 SDK project compile and function properly against the IBPM SDK.

The SDK Update Wizard will only upgrade existing Visual Basic 6.0 Code to the latest IBPM SDK version. The wizard cannot be used in any .Net environment and will not update code to be be compatible with any .Net language. Conversion of existing VB6 to use the IBPM SDK object model as exposed to .Net must be done manually.

As with any upgrade procedure, make sure all projects files are backed-up before executing the wizard.!!!

To access the wizard, open an existing project into Visual Basic. If there are multiple projects to be converted, they can all be opened up in a single project group. The wizard will convert the entire project group at once.

Once the project is open, select the Stellent IBPM SDK Update Wizard from the Add-Ins menu. If the menu item is not available, select the Add-In Manager, then select the Stellent IBPM SDK Update Wizard from the list of available add-ins. Make sure the Load/Unloaded option in the Load-Behavior section is checked and click OK to close the Add-in Manager dialog. The Stellent IBPM SDK Update Wizard menu item should now be available on the Add-Ins menu.

Once the Stellent IBPM SDK Update Wizard is selected from the Add-Ins menu, the wizard dialog will display.

Click the Update button to begin the update. The dialog will change to progress bars showing the update in process. Once complete, the dialog will appear as follows:

Click close and the conversion is done. Compile the project(s) to validate that they have been converted successfully.

Although it has made changes to the code, the conversion has not yet saved any of the files. Visual Basic will prompt you to save the files that have changed when you close the project. If any error occurs during the update, the wizard is indicate that the project should not be saved.

The wizard will always make all changes that are absolutely required to make pre-Acorde 3.1 SDK project compile. The wizard also provides an advanced option that will attempt some replacements above and beyond those required to make the project compile with the new object models. Advanced replacements primarily includes updating object names for interfaces that have been hidden.

The Stellent IBPM SDK Update Wizard is really just an automated search and replace tool. The following tables lists, in order, the exact search and replacements that the wizard will make on each line of code.

Required Replacements:

Search Text | Replace Text
OTUSRSECLib | OTACORDELib
OTDOMAINLib | OTACORDELib
OTMAGENT2Lib | OTACORDELib
OTMSGLib | OTACORDELib
OTTAGMSGLib | OTACORDELib
OTMSGDSCLib | OTACORDELib
OTDOCIDLib | OTACORDELib
OTCONTAINERSLib | OTACORDELib
OTMSGDEFLib | OTACORDELib
OTHOSTLib | OTTOOLLib
OTCLIENTHOSTLib | OTTOOLLib
OTMSGHNDLib | OTTOOLLib
OTSECCXTLib | OTTOOLLib
OTLICLib | OTACORDELib
OTGALLib | OTCLIENTLib
OTDSMSLib | OTCLIENTLib
OTTOOLMRLib | OTCLIENTLib
OTTOOLDNLib | OTCLIENTLib
OTLGTOOLLib | OTCLIENTLib
OTSCHEMALib | OTCONTEXTLib
OTSYSMGRLib | OTCONTEXTLib
OTEXPTMRLib | OTCONTEXTLib
OTCACHELib | OTCONTEXTLib
OTQUERYLib | OTCONTEXTLib
OTPICKLISTLib | OTCONTEXTLib
OTWFLOWLib | OTPROCESSLib
OTCONTEXTLib.DocInfo | OTACORDELib.DocInfo
OTCONTEXTLib.IDocInfo | OTACORDELib.DocInfo
New OTCONTEXTLib.SystemManager2 | New OTCONTEXTLib.DocumentManager
As OTCONTEXTLib.SystemManager2 | As OTCONTEXTLib.SystemManager2
New SystemManager2 | New DocumentManager
As SystemManager2 | As DocumentManager
OTCONTEXTLib.SystemManager | OTSYSMGRLib.SystemManager
New OTCONTEXTLib.BinaryPredicate | New OTCONTEXTLib.BinaryCondition
As OTCONTEXTLib.BinaryPredicate | As OTCONTEXTLib.BinaryCondition
New BinaryPredicate | New BinaryCondition
As BinaryPredicate | As BinaryCondition
New OTCONTEXTLib.SelectField | New OTCONTEXTLib.BinaryConditionField
As OTCONTEXTLib.SelectField | As OTCONTEXTLib.BinaryConditionField
New SelectField | New BinaryConditionField
As SelectField | As BinaryConditionField
otPredicateOperator | otComparisonOperator
otConditionType_BinaryPredicate | otConditionType_BinaryCondition
tagotToolStyle | otToolStyle
tagotActivateReason | otActivateReason
tagotActivateResult | otActivateResult
tagotDeActivateReason | otDeActivateReason
tagotDeActivateResult | otDeActivateResult
tagotProcessMessageReturn | otProcessMessageReturn
tagotShowCommand | otShowCommand
tagotActionType | otActionType
tagotDictionaryAccessMode | otDictionaryAccessMode
tagotDataFormatStyle | otDataFormatStyle
tagotMessageStyle | otMessageStyle
tagotRoutingDescriptor | otRoutingDescriptor
tagotMessageDefnStyle | otMessageDefnStyle
tagotStyle | otStyle
tagotDSMSConfiguration | otDSMSConfiguration
As OTCONTEXTLib.NamedQueryProperties | As OTCONTEXTLib.INamedQueryProperties
As NamedQueryProperties | As INamedQueryProperties

Advanced Replacements

Search Text | Replace Text
As OTACORDELib.IUserToken2 | As OTACORDELib.UserToken
As IUserToken2 | As UserToken
As OTACORDELib.IUserToken | As OTACORDELib.UserToken
As IUserToken | As UserToken
As OTCONTEXTLib.IPresentationConditions | As OTCONTEXTLib.NamedQueryConditions
As IPresentationConditions | As NamedQueryConditions
As OTCONTEXTLib.IPresentationCondition | As OTCONTEXTLib.NamedQueryCondition
As IPresentationCondition | As NamedQueryCondition
As OTCONTEXTLib.IPredicateOperators | As OTCONTEXTLib.ComparisonOperators
As IPredicateOperators | As ComparisonOperators
As OTCONTEXTLib.ISelectClause | As OTCONTEXTLib.SelectClause
As ISelectClause | As SelectClause
As OTCONTEXTLib.ISelectItems | As OTCONTEXTLib.SelectItems
As ISelectItems | As SelectItems
As OTCONTEXTLib.IFromClause | As OTCONTEXTLib.FromClause
As IFromClause | As FromClause
As OTCONTEXTLib.IFromItems | As OTCONTEXTLib.FromItems
As IFromItems | As FromItems
As OTCONTEXTLib.IWhereClause | As OTCONTEXTLib.WhereClause
As IWhereClause | As WhereClause
As OTCONTEXTLib.IConditions | As OTCONTEXTLib.Conditions
As IConditions | As Conditions
As OTCONTEXTLib.IExportedPages | As OTCONTEXTLib.ExportedPages
As IExportedPages | As ExportedPages
As OTCONTEXTLib.IExportedPage | As OTCONTEXTLib.ExportedPage
As IExportedPage | As ExportedPage
As OTCONTEXTLib.IExportedSections | As OTCONTEXTLib.ExportedSections
As IExportedSections | As ExportedSections
As OTCONTEXTLib.IQueryConnection2 | As OTCONTEXTLib.QueryConnection
As IQueryConnection2 | As QueryConnection
As OTCONTEXTLib.IQueryConnection | As OTCONTEXTLib.QueryConnection
As IQueryConnection | As QueryConnection
As OTCONTEXTLib.IQueryResults | As OTCONTEXTLib.QueryResults
As IQueryResults | As QueryResults
As OTCONTEXTLib.IQueryStatus | As OTCONTEXTLib.QueryStatus
As IQueryStatus | As QueryStatus
As OTCONTEXTLib.IConnection | As OTCONTEXTLib.Connection
As IConnection | As OTCONTEXTLib.Connection
As OTCONTEXTLib.ITables | As OTCONTEXTLib.Tables
As ITables | As Tables
As OTCONTEXTLib.ITable2 | As OTCONTEXTLib.Table
As ITable2 | As Table
As OTCONTEXTLib.ITable | As OTCONTEXTLib.Table
As ITable | As Table
As OTACORDELib.IUser2 | As OTACORDELib.User
As IUser2 | As IUser
As OTACORDELib.IUser | As OTACORDELib.User
As IUser | As IUser

Process Builder

Process Builder supports the use of the Stellent IBPM SDK Update Wizard. This is needed to manually add options to customize forms.

To install the Stellent IBPM SDK Update Wizard perform the following steps:

  1. Open Visual Basic.
  2. Click the Add-Ins menu.
  3. Select 'Stellent IBPM SDK Update Wizard' from the list of Available Add-Ins.
  4. Check the 'Loaded/Unloaded' checkbox.
  5. If this utility is to be available every time, check the 'Load on Startup' checkbox.
  6. Click OK.

The Stellent IBPM SDK Update Wizard is now available in your Add-Ins menu


The IBPM SDK in .Net

Primary Interop Assemblies

The IBPM SDK includes a set of Primary Interop Assemblies (PIAs) that provide a reliable mechanism by which custom applications written in a Microsoft .Net languages can interact with the COM based IBPM SDK components. These PIAs are maintained, signed, and distributed by Stellent and provide unique type identity for all publicly accessible components in the SDK.

Namespaces

These PIAs organize the various SDK objects into an easy-to-use , hierarchical, namespace based structure. The following table details the namespaces contained in the IBPM SDK and the COM Library that each namespace represents.

NameSpace | COM Library
Stellent.IBPM.Interop.Common | OTAcorde
Stellent.IBPM.Interop.Common.ActionModifers | OTActMod
Stellent.IBPM.Interop.Imaging | OTContext
Stellent.IBPM.Interop.Imaging.Viewer | OptPage
Stellent.IBPM.Interop.Print | OTPrintTool
Stellent.IBPM.Interop.Process | OTProcess
Stellent.IBPM.Interop.Process.Controls | OTBPMCtls
Stellent.IBPM.Interop.Process.Dialogs | OTWFDlgs

Adding References

To include these namespaces in a project from within Microsoft Visual Studio .NET, right click on the References item in the Solution Explorer Tree, select “Add Reference”, then select the appropriate Stellent namespaces from the .Net tab. Note: Stellent recommends using .NET references rather than COM references.

For the Stellent components to appear in on the .Net tab, the registry key :

 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\AssemblyFolders\StellentIBPM

must have its (Default) value set to the "Assemblies\v1.0" folder underneath the IBPM product directory (e.g. “c:\Program Files\Stellent\IBPM\Assemblies\v1.0".) And the PIAs must exist in this folder. This registry setting is only required on a developer machine, but the PIAs must exist in the Assemblies folder and be registered in GAC on a client machine at runtime. (The SDK installation should set this registry setting correctly. If it is not configured properly, a reinstall of the SDK should correct the problem.)

To ensure that the PIAs have been properly found, verify that the reference properties for each module indicates "Copy Local = False" and "Strong Name = True" If these properties are not correct, ensure that the IBPM SDK has been installed correctly.

Note. It is possible to add references to the IBPM SDK COM components from the COM tab of the Visual Studio Add Reference dialog. If the primary interop assemblies are properly installed and registered on the development machine, adding the the reference in this way will behave correctly; although, the references in the Solution explorer will display the referenced library using the older OTXXXXXLib nomenclature instead of with the references namespace. As long as the properties for the reference are correct as described below, this will work. Adding the references from the .Net tab is the preferred method.

Once references are added into a project, the namespaces and the objects they contain can be viewed the the Visual Studio .NET Object Browser. The objects within the namespaces can also now be referred to using the full Namespace.Objectname for the object (e.g., Stellent.IBPM.Interop.Common.User). However, usage of full namespaces tends to lead to very lengthy and tedious to write code. One solution is to do an “Imports” of the namespace (or a “using” in C#). Then you can use just the type names directly.

VB.Net

Imports Stellent.IBPM.Interop.Common

...

Dim myUser As User
myUser = New User

C#

using Stellent.IBPM.Interop.Common;

...

User myUser;
myUser= new UserClass();

The problem with this is that you the intellisense feature of typing in a name followed by a “.” to bring up the combo list of available types is lost. This is one of the handiest features of having all of the objects name spaced. It is not sufficient to just do an Imports/Using one level higher in the namespace hierarchy because importing or using a namespace does not give you access to sub namespaces (only to the objects directly in that namespace.) Another solution is to do an Imports/Using Alias as follows:

VB.Net

Imports IBPM = Stellent.IBPM.Interop

...

Dim myUser As IBPM.Common.User
myUser = New IBPM.Common.User

C#

using IBPM = Stellent.IBPM.Interop;

...

IBPM.Common.User myUser;
myUser = new IBPM.Common.UserClass();

Object Names

Each COM object that is exposed to .Net will have three “names” associated with it.

1) Object: Each object will also have an interface defined that is just the Object name.

2) _Object: Each object will have an interface defined with the Object name preceded by an “_”.

3) ObjectClass: Each object will have a class defined as the object name followed by “Class”.

In general the Object and _Object names can be used interchangeably, although the Object form is preferred as it will produce more readable code. In some cases, intellisense may indicate that a property returns and _Object type, however this return type can be safely set into an Object variable. The ObjectClass name is required in C# new statements (e.g., myUser = new IBPM.Common.UserClass()), although VB.Net allows either the Object or ObjectClass form in a New statement (so, in VB.Net, "myUser = New IBPM.Common.UserClass" is equivalent to "myUser = New IBPM.Common.User").

Note: Some methods and/or properties of objects in the IBPM SDK are reserved words in VB.Net. In these cases, the object browser in Visual Studio may should the method or property enclosed in brackets. (e.g., Stellent.IBPM.Interop.Process.[Event]. This is only true in VB (i.e., not in C#) and it is only a visual representation of the label in the object browser. The method or property can be used with or without the brackets in code.

myEvent = myPackage.Event

'Is equivalent to

myEvent = myPackage.[Event]

Thread Safety and Performance

The objects in the IBPM Safety are thread safe and can be used in any .Net multi threaded environment. Additionally, all objects are free threaded, so they may be used on multiple threads in any combination of COM apartment models within a given process. The thread safety of the objects is guaranteed internally within each object by the enforcement of a schema where each individual object instance will only permit 1 thread to be executing inside the object at a time. In general, this means that any number of DIFFERENT instances of objects of a given type may execute simultaneously on multiple threads. However, care should taken when sharing a SINGLE instance of one object across multiple threads as calls to this one object on multiple threads will serialize.

ADO vs ADO.Net

The PIAs supplied with the IBPM 7.6 SDK make usage of the SDK objects as simple as possible in the .Net programming environment. However, underneath the covers, the SDK is still using .Net interop technology to interface with the legacy COM based SDK. Because of this, any property of method that returned data in the form of COM ActiveX Data Objects (ADO) Recordset still does so in the .Net environment. In general, however, .Net applications prefer to manipulate data in the ADO.Net DataSets and DataTables. In fact, the .Net Datagrid will not accept data directly in its COM ADO form. To convert the ADO Recordsets returned by the IBPM SDK, use the OleDBDataAdapter provided in the Microsoft .Net Framework. See the topic Filling a dataset with an ADO Recordset or Record in the .Net Framework Developer's Guide for more information on how to use this object.

As mentioned above, all objects in the IBPM SDK are free threaded. However, objects in the COM ADO object model used internally by the IBPM SDK are marked as apartment threaded by default. This may cause performance issues in some situations. To overcome this problem, ADO supplies a batch file that will convert to registration of the ADO objects to support free threading. This batch file, generally found in the directory C:\Program Files\Common Files\System\ADO\makfre15.bat, should be executed on machines running IBPM SDK applications that are multithreaded.

Managing COM Object Release

Again, because the IBPM SDK .Net implementation is based COM interop, extra care should be taken in managing the release of objects when they are no longer needed. Ordinary .Net class objects are maintained via the standard Dispose and Garbage collection and are generally written with consideration to these mechanism. Legacy COM objects accessed through interop, however have typically be written with a different expectation. COM object expect to be released when they are no longer actively be referenced. As such, COM objects may hold on to large amounts of memory, expecting to free that memory upon release. If these objects are allowed to linger until garbage collection cleans them up, applications written against the objects can potentially grow to consume large amounts of memory for long periods of time. Because of this, programmers writing against ANY interop SDK need to be careful to deliberately force the .Net Framework to release COM objects when they are no longer references. This can be done by using the System.Runtime.InteropServices.Marshal.ReleaseComObject method. See documentation for this method in the .Net Framework help files for more information.


User Security Object

User Security

Before using components in the IBPM SDK, a custom application must supply user authentication credentials under which the toolkit functionality will operate. By requiring this security authentication, the integrity of the IBPM security model is maintained, even for custom applications. Authentication services are accessed via the User and UserToken objects out of the IBPM Base Object Library.

The User object is a creatable object whose primary purpose is to provide Login and Logout methods. The User.Login method takes a user name and password, both of which are sent to the back-end license and security servers for validation. If a user license is available, and the supplied user name and password are valid, the Login method returns a populated UserToken object.

The Login method also takes a third parameter that specifies whether the login should be interactive or not. If an interactive login is specified, a dialog box is presented prompting the user to enter a user name and password. In this case the username and password parameters supplied to the Login method are only used to pre-populate the user name and password fields in the login dialog.

The UserToken returned from the Login method represents a reserved user license and a validated user. This UserToken object should be maintained for the lifetime of the custom application and supplied as required as the IBPM SDK is used to access the IBPM system.

By default, the User object will attempt to log into the default IBPM domain. If the IBPM system is configured to support multiple domains, a domain can be specified.


Using Dictionaries

Many IBPM SDK object methods and properties return a Dictionary object from the Stellent.IBPM.Interop.Common namespace. The Dictionary object is a general-purpose container object that stores information in the form of tag/value pairs. The tags are string keys that identify the values, which can be any variant data type. The keys in the dictionary can be enumerated and the entire dictionary can be persisted and restored to and from a serialized binary format. Because of it flexibility, the Dictionary object is used for properties and method that either require as input or return complex data structure that cannot be represented by basic types.

When an SDK object method or property requires a dictionary as an input parameter, you would create a new dictionary object, set the tag/value pairs as required by the method/property, and pass in the entire dictionary object.


Access Control Contexts

Access control contexts are the mechanism IBPM uses to specify what rights a given user has to data and functionality within the IBPM system. The rights are specified per user group by using the Security tool within the IBPM Windows Client. If a user belongs to multiple groups, the rights for all groups to which the user belongs are aggregated into a single set of rights, granting a given right if any group to which the user belongs has that right. That set of aggregated rights is collectively referred to as the user’s Access Control Context or ACC. A user can have multiple ACC rights, each of which are applicable to different feature of the IBPM system. The following are ACCs available in the core IBPM product:

  • Policy – General administrative rights.
  • Schema – Rights a user has to see and access index table schemas in the Imaging Database.
  • NamedQuery – Right to run, modify and delete Saved Searches.
  • Workflow - Tool preference specifications for BPM functions.
  • Workflow Databases – List of BPM database(s) to which the user has been granted access.
  • Custom – Toolkit users can create custom ACC’s that are configured from the IBPM Security tool and store in IBPM, and aggregated by user group.

Custom Applications can query the rights that a given user has by using the ACCRequest object out of the Stellent.IBPM.Interop.Common namespace. To use the object, create a new ACCRequest object, set the ACCGuid property to the Guid of the desired ACC, and pass the ACCRequest object into the UserToken.GetACC method. The UserToken sends the request to the Information Broker service, which retrieves the data, aggregates it by user group and returns the information back to the UserToken object. The UserToken then returns the information in a dictionary object.

If multiple ACC lookups are required at one time, multiple requests can be formatted into an array and passed into the UserToken.GetMultipleACCs method, which performs the request as a bulk operation.

ACC information can be used through the execution of a custom program. However, if the UserToken.GetACC or UserToken.GetMultipleACCs method are called each time the ACC information is needed, the program will not perform very efficiently because each call amounts to a separate call to the IBPM back-end. The ACCProvider object can be used to provide an ACC caching mechanism. With GetACC and GetMutipleACCs properties, ACCProvider behaves similarly to the UserToken object (in fact, it implementation merely calls the UserToken methods), but it holds on to the retrieved information and does not make repeated back-end request for a given ACC type after the first request. An additional parameter on the GetACC and GetMultipleACCs functions specifies whether the call should refresh the cached data or not.


Accessing the Database Schema

The Imaging database contains the tables used to index and store documents within IBPM. The IBPM SDK provides a mechanism to access the structure and definition of this database schema. The object model used to access database schemas can be depicted graphically as follows.

Connections

At its highest level, the Imaging system is organized into different connections. Connections are accessed using the Connections collection and Connection object found in the Stellent.IBPM.Interop.Imaging namespace. Each Connection object represents a different data repository in which Imaging data may be stored and equate to the Linked Servers configured on the IBPM Information Broker service.

Before refreshing the Connections collection, the Connections.UserToken property must be set. This sets the user credentials under which the Connections collection will operate so that IBPM security model can be enforced.

To enumerate the available connection, create a Connections Object, set the UserToken property, and call the Refresh method.

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
Dim objConnection As Stellent.IBPM.Interop.Imaging.Connection

objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken

objConnections.Refresh

For Each objConnection In objConnections
    ' Use objConnection Object Here
Next

Sometimes it is desirable to enumerate only tables of a specific type. If the Connections.ConnectionFilter is set, the Connections collection will only populate with Connection objects whose Properties match the filter. Specifically, the ConnectionFilter can be used to filter only connections that are Read-only or Write-only (e.g. cold versus imaging connections). The following code segment adds filtering to the connections enumeration sample to list only writable connections:

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
Dim objConnection As Stellent.IBPM.Interop.Imaging.Connection

objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.ConnectionFilter = Stellent.IBPM.Interop.Imaging.ConnectionProperty.cpWriteOnly

objConnections.Refresh

For Each objConnection In objConnections
    'Use objConnections Object Here
Next

The previous two examples demonstrate enumerating through all of the Connection objects populated in the Connections collection. A more typical application would be the situation where a specific connection is required out of the collection. The Connections.Item method is used for this purpose. The simplest usage of the Item property is to access the Connections collection by the ordinal index of items in the collection. This is not usually the most intuitive usage, however. Usually, a custom application writer knows the Connection name that is desired and simply wants to access that connection directly. The item property can be used in this way as well.

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
Dim objConnection As Stellent.IBPM.Imaging.Connection

objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.Refresh

' retrieve the first ordinal item out of the collection
objConnection = objConnections.Item(1)

'retrieve the item named "Documents.Context"
objConnection = objConnections.Item("Documents.Context")

The Item property on the Connections collection is the default property, so the text “.Item” can be omitted for convenience as follows:

'Use Item as default property.
objConnection = objConnections("Documents.Context")

Connection names in IBPM generally take the form LinkedServer.Instance. In the above examples, “Documents” is the LinkedServer and “Context” is the Instance. These values are defined on the Information Broker server when the Linked Servers are configured. The Connection object itself exposes these values through its Name, LinkServer, and Instance properties.

Tables

Once the Connections collection has been refreshed and a Connection object chosen, the tables contained in that connection can be enumerated by retrieving a Tables collection from the Connections.Tables property. The Tables collection contains the database tables available on that connection.

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
Dim objConnection As Stellent.IBPM.Interop.Imaging.Connection

objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.Refresh
objConnection = objConnections("Documents.Context")

Dim objTables AsStellent.IBPM.Interop.Imaging.Table
Dim objTable As Stellent.IBPM.Interop.Imaging.Tables
objTables = objConnection.Tables
For Each objTable In objTables
    'Use the objTable object here
Next

Filtering can also be applied to limit the types of tables that appear in the Tables collection for a connection. If the Connections.TableFilter property is set, the Tables collection will populate only with Tables whose Properties match the filter. (Note that setting the filter at the Connections collection level means that the filter will affect the Tables collections for all connections in the Connections.) By default, the filter is set to return only Imaging application Index tables (otTableProperty_Table). The following example sets a filter to return application index tables and Imaging system tables (otTableProperty_System).

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
Dim objConnection As Stellent.IBPM.Interop.Imaging.Connection

objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.TableFilter = Stellent.IBPM.Interop.Imaging.TableProperty.tpTable + Stellent.IBPM.Interop.Imaging.TableProperty.tpSystem
objConnections.Refresh
objConnection = objConnections("Documents.Context")

Dim objTables As Stellent.IBPM.Interop.Imaging.Table
Dim objTable As Stellent.IBPM.Interop.Imaging.Tables
objTables = objConnection.Tables
For Each objTable In objTables
    'Use the objTable object here
Next

In addition to filtering by TableType, the Connection collection has a mechanism to filter tables based on the Access Control Context (ACC) permissions that a user has been granted for a table. ACC permissions are the granted per user group in the IBPM Client Security tool, Schema Tab (i.e., Create Index, Modify Index, Delete, etc.) The Connections.ACCFilter property can be set to specify that only Tables with a certain set of ACC permission granted should be populated in the Tables collection. In the following example, the selected Tables collection will only contain tables with both Create Index and Modify Index granted.

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
Dim objTables As Stellent.IBPM.Interop.Imaging.Tables

objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.ACCFilter(Stellent.IBPM.Interop.Imaging.SchemaACCFilter.sfCreateIndex) = True
objConnections.ACCFilter(Stellent.IBPM.Interop.Imaging.SchemaACCFilter.sfModifyIndex) = True
objConnections.Refresh

objTables = objConnections.Item("Documents.Context").Tables
'The objTables collection should now contain only tables with the
'CreateIndex and ModifyIndex permission granted

As with the connections collection, Table object in the Tables collection can also be accessed directly by either the ordinal index into the collection or by the Table Name.

' retrieve the first ordinal item out of the collection
objTable = objTables(1)

'retrieve the item named "dbo.ImageMain"
objTable = objTables("dbo.ImageMain")

'Use Item as default property.
objTable = objTables ("dbo.ImageMain")

Table names in Imaging generally take the form Schema.Table. In the above example, “dbo” is the Schema and “ImageMain” is the Table. (The value of Schema is dependant on the database type. Oracle Databases for example do not use Schema so the value is blank.)

Fields

Once a Table object is selected, an SDK application will usually want to access the field or columns for that table. The Table object has two properties for enumerating the Fields on a Table.

The Table.FieldAttributes property returns a FieldAttributes collection containing a FieldAttribute object for each field in the table. The FieldAttribute object identifies the Name of the field, its Data Type, and the pick list for the field if a pick list has been mapped to it (Using the PickList Field Mapper Tool in the IBPM Client.) This is the method that should be used for generally enumerating information about the fields in a table

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.Refresh

Dim objTable As Stellent.IBPM.Interop.Imaging.Table
objTable = objConnections("Documents.Context").Tables("dbo.DMAppMain")

Dim objFieldAttribute As Stellent.IBPM.Interop.Imaging.FieldAttribute
For Each objFieldAttribute In objTable.FieldAttributes
    ' Use objFieldAttribute Here

    Dim objPickList As Stellent.IBPM.Interop.Imaging.PickList
    objPickList = objFieldAttribute.PickList
    If Not objPickList Is Nothing Then
        'Field Attribute has a pick list
    End If
Next

The Table.Fields collection returns an ADO fields collection. While this property can be used to enumerate the field and their types, it is primarily used as a container for passing values for the fields in and out of other SDK objects. For example when a document is created, the Table object representing the index table in which the document is to be indexed must first be selected. Each index value for the document is then set on the Table.Fields collection. The entire Table object is then passed into the DocumentManager.CreateDocument method. This method iterates the fields that have been set in the Table.Field collection and indexes the document appropriately. (See Creating a Document for an example.)


Searching For Documents

Overview

All Imaging SDK based searches are executed on the Search Manager Server (SMS). The QueryConnectionManager is the root object for interfacing with the SMS. When a search is executed from an SDK application, the SMS server sends the query to the Information Broker service to be executed. As the results are asynchronously returned from the Information Broker, SMS holds onto the results set until the SDK application requests them.

QueryConnections

To execute any search against the SMS, a connection must first be created to perform the search. This is done with the CreateConnection method, which returns a QueryConnection object representing an open connection on SMS. An SMS connection will hold on to un-fetched search results on the SMS server until the results are fetched, the connection is destroyed, or the connection times out.

A connection is destroyed by calling the DestroyConnection method, passing in a QueryConnection object. When a connection is destroyed, any open result set data is released.

The connection on SMS is maintained even if the QueryConnection object is release on the client (but not destroyed.) If the client holds onto the QueryConnection.ConnectionId, and the SMS connection has not timeout, a QueryConnection can be restored with the RestoreConnection method.

Performing the Search

With a valid QueryConnection object obtained, a search is executed with the QueryConnection's ExecuteQuery method. This method takes a query object that can either be a NamedQuery object or a SQLSelect object representing a Ad-hoc query. When ExecuteQuery is called, SMS executes the query and caches the results server side. The results are then fetched by the client with a call to GetResults. Each call to GetResults will return a number of result set rows less than or equal to the Granularity parameter passed into the ExecuteQuery method. The client can continue to call GetResults until there are no more results available or until the Connection is canceled, destroyed, or times out.

The Execute method also takes as a parameter an enumeration indicating the ManageStyle. The manage style determines how the Recordset is populated. This can be Managed or Unmanaged

  • A Unmanaged query is one in which each call to GetResults returns a completely new record set. By default, each new record set contains the next <Granularity> records. If the FirstRec, LastRec range parameters are specified in GetResults method, then the record set will contain the record in that range.
  • A Managed query is one in which the QueryConnection holds on to the Recordset between each call to GetResults. Each time GetResults is called, the next Resultset of <Granularity> rows returned from the SMS is appended to the previous ResultSet. The FirstRec and LastRec parameters are ignored for a Managed Query.

At any time after ExecuteQuery, the QueryConnection.QueryStatus object can be checked to determine status of the query executing on SMS and the total number of records available in the query result set cached on SMS. Because Information Broker is returning the records to SMS asynchronously, the QueryStatus.Status may report a status of qsProcessing. In this case, the QueryStatus.RowCount is still increasing. Once the Status changes to qsComplete, then the RowCount is updated with the final count.

In the following examples, the objNamedQuery (assumed that it is obtained previously in the code) will match a total of 100 rows. The ExecuteQuery method is passed a granularity of 10.

Example 1: A Managed Query

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmManaged, 10

objRS As ADODB.Recordset
objRS  = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset
'objRS now contains rows 1-10 of the total 100 rows

objRS  = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset
'objRS now contains row 1-20 of the total 100 row

Example 2: An Unmanaged Query

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 10

Dim objRS As ADODB.Recordset
objRS  = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset
'objRS now contains rows 1-10 of the total 100 rows

objRS  = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset
'objRS now contains row 11-20 of the total 100 rows

Example 3: An Unmanaged Query with a FirstRec, LastRec Range

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 10

Dim objRS As ADODB.Recordset
objRS  = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll, 21, 30).Recordset
'objRS now contains rows 21-30 of the total 100 rows


Runnning a Saved Search

Running a Saved Search

Saved Searches are queries that are predefined by the Search Builder Tool in the IBPM Client. They have a predefined set of select columns and from tables that cannot be changes at execution time. The where clause contains predefined conditions as well, although they may be specified as prompted, which requires that the operator, right hand condition value, or both to be supplied at runtime. They may also include a pick list from which the supplied values must be chosen or an Operator pick list, from which the condition comparison operator may be chosen. The Named query object model is depicted graphically as follows.

To execute a named query, the appropriate NamedQuery object representing the search must first be obtained. This is done by using the NamedQueries collection. The NamedQueries collection is a creatable object that, when refreshed, contains all of the NamedQuery objects to which the calling user has access. The UserToken property must be set on the collection prior to calling Refresh in order to set the user credentials under which the object will operate.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

For Each objNamedQuery In objNamedQueries
'Use the objNamedQuery object here
Next

The previous example demonstrates enumerating through all of the NamedQuery objects populated in the NamedQueries collection. A more typical application would be the situation where a specific named query in the collection is desired. The NamedQueries.Item method is used for this purpose. The simplest usage of the Item property is to access the NamedQueries collection by the ordinal index of items in the collection. This is not usually the most intuitive usage, however. Usually, a custom application writer knows the NamedQuery name that is desired and simply wants to access that item directly. The item property can be used in this way as well.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

' retrieve the first ordinal item out of the collection
objNamedQuery = objNamedQueries.Item(1)

'retrieve the item named "MyQuery"
objNamedQuery = objNamedQueries.Item("MyQuery")

The Item property on the NamedQueries collection is the default property, so the text “.Item” can be omitted for convenience as follows:

'Use Item as default property.
objNamedQuery = objNamedQueries("MyQuery")

Once a NamedQuery object is select, the where conditions that have been defined for it can be enumerated via the NamedQuery.Conditions property. This property returns a NamedQueryConditions collection where each item in the collection is a NamedQueryCondition object representing a single where clause condition. The where clause conditions are basic binary conditions of the form <LeftValue><ComparisonOperator><RightValue>. The <LeftValue> operand is always a column name. The <ComparisonOperator> is a comparison operator such as =, < , > etc. The RightValue can be either a literal value or another column name (e.g. Col1 < 10 .)

The NamedQueryCondition display style indicates what action is required for displaying the condition to users and how the values must be supplied. The following styles are possible:

  • A Hidden condition is one that is not to be displayed to the user, but will always be a part of the results search. It does not require that any value be set.
  • A Display condition that can be shown to the user, but it does not require that any value be set.
  • A Prompt style means that the RightValue operand may be set be for execution. It may however be left blank, in which case the condition is simply ignored.
  • A Prompt Required style requires that the RightValue operand be set. Execution of the search will error if it is left blank.
  • A Picklist style is like a Prompt style, the values available for the RightValue operand are provided by the PickList collection.

The NamedQueryCondition properties also specify additional information that may be useful for providing a user interface that prompts the user for the value to be supplied. These values include DisplayName and DisplayMask.

The NamedQueryCondtion may also have a pick list of comparison operations defined. This is accessed through the NamedQueryCondition.AvailableOps property. The comparison operation for the condition is set on the NamedQueryCondition.Operator. Only the operators defined in the Operators collection (obtainable from the NamedQueryCondition.Operators property) are valid for setting on the Operator property. (The Operator and whether it has an Operators collection is independent of the DisplayStyle. It is possible to have an Operator pick list for Display condition. This means that the RightValue is hard coded for the condition, but the operator is not. Multiple choice operators should not be defined for Hidden conditions, however.)

The following code demonstrates filling out the prompted conditions for the a named query.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

objNamedQuery = objNamedQueries("MyQuery")

Dim objNamedQueryCondition As Stellent.IBPM.Interop.Imaging.NamedQueryCondition
For Each objNamedQueryCondition In objNamedQuery.Conditions
    If objNamedQueryCondtion.DisplayStyle = Stellent.IBPM.Interop.Imaging.DisplayStyle.dsPrompt _
       Or objNamedQueryCondtion.DisplayStyle = Stellent.IBPM.Interop.Imaging.DisplayStyle.dsPromptReq then
       'Set the RightValue to a literal value
       objNamedQueryConditon.RightValue = 123456
    Else If objNamedQueryCondtion.DisplayStyle = Stellent.IBPM.Interop.Imaging.DisplayStyle.dsPickList
       Dim objPickList as Stellent.IBPM.Interop.Imaging.PickList
       objPickList = objNamedQueryCondition.PickList
       'For demonstration purposes, just pick the first picklist item
       objNamedQueryConditon.RightValue = objPickList.Item(1)
   End If

   'Use the AvailableOps Pick list if there is one
If objNamedQueryCondtion.Operators.Count() > 0 Then
        'For demonstration purposes, just pick the first available operand item
        objNamedQueryCondition.Operator = objNamedQueryCondtion.Operators.Item(1)
    End If

Next

Once a NamedQuery is selected, it can be executed using the Execute method of a QueryConnection object. See Searching For Documents for complete details on using a QueryConnection.


Runnning an Ad-Hoc Search

Running an Ad-Hoc Search

Ad-hoc searches are queries that are completely defined in code at the time the search is to be executed (i.e., they are not defined and stored in any way by the back-end Imaging system like Named Queries.) Ad-hoc queries are SQL Select statements. They take the basic form:

SELECT <expression> [AS <alias>],...  FROM <Table>, ... WHERE <conj><condition>... <conj>(<sub conditions>...)
       SelectClause                       FromClause                       WhereClause

The object model architecture used to represent this format is depicted graphically as follows.

In the model, each of the sub components are represented by the individual object under the SQLSelect object. These objects are the SelectClause object, the FromClause object and the WhereClause object. (Note: The IBPM SDK Ad-hoc query object model guarantees that SQL select statements are formed in a manner such that the Information Broker Query Processor can interpret them correctly. Because of this, no free form SQL statement setting mechanism is provided.)

Select Clause

The Select Clause portion of the of the SQL statements for IBPM Ad-hoc queries are of the form:

SELECT <expression> [AS <alias>],<expression> [AS <alias>],...

Where:

  • <expression> - is the column data to be returned in the result set. Column names in IBPM use the Imaging name format of LinkServer.Instance.Schema.Table.Field. (See Accessing the Database Schema for information on Imaging naming formats.)
  • <alias> - is the label to be assigned to the column data in the result set.

The <alias> item is optional. Any number of expression/alias pairs can be included in the select expression.

In the IBPM SDK model, each expression/alias pair is represented by a SelectItemExpression object. Multiple SelectItemExpression objects are added to the SelectItems collection of the SelectClause object. The order in which the SelectItemExpression objects are added to the SelectItems collection is the order, from left to right, that they will appear in the SQL statement.

The following represents an example SQL select clause that might be represented by the SelectClause object. (Note: As stated above, the expression column names would use the Imaging table name format of LinkServer.Instance.Schema.Table.Field. The expressions are simplified in the example for clarity.)

SELECT  Column1 as Name, Column2 as Address, Column3 as Zip

The following code sample populates a SelectClause object to match this statement

Dim objSQLSelect As Stellent.IBPM.Interop.Imaging.SQLSelect
Dim objSelectClause As Stellent.IBPM.Interop.Imaging.SelectClause
Dim objSelItemExp As Stellent.IBPM.Interop.Imaging.SelectItemExpression

objSQLSelect = New Stellent.IBPM.Interop.Imaging.SQLSelect
objSelectClause = objSQLSelect.SelectClause

objSelItemExp = New Stellent.IBPM.Interop.Imaging.SelectItemExpression
objSelItemExp.Expression = "Column1"
objSelItemExp.Alias = "Name"
objSelectClause.SelectItems.Add objSelItemExp

objSelItemExp = New Stellent.IBPM.Interop.Imaging.SelectItemExpression
objSelItemExp.Expression = "Column2"
objSelItemExp.Alias = "Address"
objSelectClause.SelectItems.Add objSelItemExp

objSelItemExp = New Stellent.IBPM.Interop.Imaging.SelectItemExpression
objSelItemExp.Expression = "Column3"
objSelItemExp.Alias = "Zip"
objSelectClause.SelectItems.Add objSelItemExp

MsgBox objSQLSelect.SelectClause.SQLSubString

From Clause

The From Clause portion of the of the SQL statements for IBPM Ad-hoc queries are of the form:

FROM <Table>, <Table>

Where:

  • <Table> - is the table names from which data is to be selected. Table names in IBPM use the Imaging name format of LinkServer.Instance.Schema.Table. (See Accessing the Database Schema for information on Imaging naming formats.)

Any number of Tables can be listed in the From clause.

In the IBPM SDK model, each Table item is represented by a FromItemTable object. Multiple FromItemTable objects are added to the FromItems collection of the FromClause object. The order in which the FromItemTable objects are added to the FromItems collection is the order, from left to right, that they will appear in the SQL statement.

The following represents an example SQL from clause that might be represented by the FromClause object. (Note: As stated above, the table names would use the Imaging name format of LinkServer.Instance.Schema.Table. The table names are simplified in the example for clarity.)

...FROM Table1, Table2...

is built using the following code:

Dim objSQLSelect As Stellent.IBPM.Interop.Imaging.SQLSelect
Dim objFromClause As Stellent.IBPM.Interop.Imaging.FromClause
Dim objFromItemTable As Stellent.IBPM.Interop.Imaging.FromItemTable

objSQLSelect = New Stellent.IBPM.Interop.Imaging.SQLSelect
objFromClause = objSQLSelect.FromClause

objFromItemTable = New Stellent.IBPM.Interop.Imaging.FromItemTable
objFromItemTable.TableName = "Table1"
objFromClause.FromItems.Add objFromItemTable

objFromItemTable = New Stellent.IBPM.Interop.Imaging.FromItemTable
objFromItemTable.TableName = "Table2"
objFromClause.FromItems.Add objFromItemTable

MsgBox objFromClause.SQLSubString

Where Clause

The Where Clause components of the model are the most complex, but they are actually quite straight forward. The generic where clause portion of the of the SQL statements for IBPM ad-hoc queries has of the form:

WHERE <conj><condition>... <conj>(<sub conditions>...)
        BinaryCondition          SearchCondition

The two forms of items is a where clause: "<conj><condition>" and "<conj>(<sub conditions>...)", represent the two basic structures: a BinaryCondition and a SearchCondition, that are combined together to form a where clause. Any number of these two object can be added together to form arbitrarily complex where clauses.

1) A BinaryCondition is a where clause expression comparing two values. It may optionally have a conjunction (AND, OR, NOT AND, or NOT OR) in front of it. It has the form:

[conj] <LeftValue> <ComparisionOp> <RightValue>

Where:

[conj] - A conjunction value that combines the BinaryCondition items together in a SQL where clause. It may be AND, OR, NOT AND, or NOT OR. It may also be NOP indicating the condition has not has not conjunction preceding it (e.g. when it is the first item in a nested expression.)

<LeftValue> - The left had operand in the comparison. In an Imaging search, it is always a column name.

<ComparsionOp> - The comparison operation to be performed. (i.e., =, <, > , etc).

<RightValue> - The right hand operand in the comparison. It may be a literal value, or it may be a column name. If it is a column name, the condition might be a join condition joining two tables together.

2) A SearchCondition represents an expression inside parenthesis (a nested expression.) in a where clause. It may optionally have a conjunction (AND, OR, NOT AND, or NOT OR) in front of it . Thus, a search condition always has the form:

[conj] ( <expression> )

conj - A conjunction value that combines the SearchCondition items together in a SQL where clause. It may be AND, OR, NOT AND, or NOT OR. It may also be NOP indicating the condition has no conjunction preceding it (e.g. when it is the first item in another nested expression.)

<expression> - May be one or more BinaryCondition objects conjoined together, or it may contain another SearchCondition representing a nested expression within a nested expression.

For example, in the SQL where clause:

WHERE col1 = "A" AND (col2 = "B" OR col3="C")

The underlined text is a single SearchCondition. The "B" and "C" items inside the parenthesis are the BinaryCondition objects that would be contained in the SearchCondition.Conditions collection.

The next SQL Statement shows nesting within nesting.

WHERE col1 = "A" AND (col2 = "B" OR (col3="C" and col4="D"))

In this case, the outer "AND" SearchCondition contains an inner "OR" SearchCondition .

Note that the WhereClause object in the SDK model has a SearchCondition property that represents the entire clause as if it were simply another nested expression. Each of these two items are added into the SarchConditon.Conditions collection. The order in which they are add is the order they will appear in the SQL statement.

Because the Conditions collection can contain objects of two different types, special logic must be used when iterating through a Conditions collection. When enumerating the object in a Conditions collection, the item should be returned into a variable of type ICondition, which is a base type that can be either a SearchCondition or a BinaryCondition. Once the ICondition is retrieved, its Type property can be checked to determine which condition type it is. Then it can be set into the appropriate typed variable. The following example demonstrates this procedure.

Dim objCondition As Stellent.IBPM.Interop.Imaging._Condition
Dim objSearchCondition As Stellent.IBPM.Interop.Imaging.SearchCondition
Dim objBinaryCondition As Stellent.IBPM.Interop.Imaging.BinaryCondition

'objConditions is a populated Conditions collection
For Each objCondition In objConditions
    Select Case objCondition.Type
        Case Stellent.IBPM.Interop.Imaging.ConditionType.ctSearchCondition
            objSearchCondition = objCondition
            'Do work with objSearchCondition
        Case Stellent.IBPM.Interop.Imaging.ConditionType.ctBinaryCondition
            objBinaryCondition = objCondition
            'Do work with objBinaryCondition
    End Select
Next

By containing expressions nested within other expressions, the WhereClause object can represent arbitrarily complex conditional statements in a hierarchical fashion. For example, the following where clause:

WHERE col1="A" and (col2 ="B" or (col3="C" and col4="D") or Col5="E")

is represented graphically with the following object hierarchy. Notice that each instance of nesting in the object model correlates directly to the nesting in the SQL where clause.

The following code generates the above statement and hierarchy

Dim objSQLSelect As Stellent.IBPM.Interop.Imaging.SQLSelect
Dim objWhereClause As Stellent.IBPM.Interop.Imaging.WhereClause
Dim objBC As Stellent.IBPM.Interop.Imaging.BinaryCondition
Dim objSC_AND As Stellent.IBPM.Interop.Imaging.SearchCondition
Dim objSC_OR As Stellent.IBPM.Interop.Imaging.SearchCondition

' col1 = "A"
objBC = New Stellent.IBPM.Interop.Imaging.BinaryCondition
objBC.LeftValue = "Col1"
objBC.Operator = Stellent.IBPM.Interop.Imaging.Operator.opEqual
objBC.RightValue = "A"
objWhereClause.SearchCondition.Conditions.Add objBC

'And (
objSC_AND = New Stellent.IBPM.Interop.Imaging.SearchCondition
objSC_AND.Conjunction = Stellent.IBPM.Interop.Imaging.Conjunction.cjAND

' col2 = "B"
Set objBC = New Stellent.IBPM.Interop.Imaging.BinaryCondition
objBC.LeftValue = "Col2"
objBC.Operator = Stellent.IBPM.Interop.Imaging.Operator.opEqual
objBC.RightValue = "B"
objSC_AND.Conditions.Add objBC

'Or (
objSC_OR = New Stellent.IBPM.Interop.Imaging.SearchCondition
objSC_OR.Conjunction = Stellent.IBPM.Interop.Imaging.Conjunction.cjOR

' col3 = "C"
objBC = New Stellent.IBPM.Interop.Imaging.BinaryCondition
objBC.LeftValue = "Col3"
objBC.Operator = Stellent.IBPM.Interop.Imaging.Operator.opEqual
objBC.RightValue = "B"
objSC_OR.Conditions.Add objBC

'or col4 = "D"
objBC = New Stellent.IBPM.Interop.Imaging.BinaryCondition
objBC.Conjunction = Stellent.IBPM.Interop.Imaging.Conjunction.cjOR
objBC.LeftValue = "Col4"
objBC.Operator = Stellent.IBPM.Interop.Imaging.Operator.opEqual
objBC.RightValue = "D"
objSC_OR.Conditions.Add objBC

' )
objSC_AND.Conditions.Add objSC_OR

'or col5 = "E"
objBC = New Stellent.IBPM.Interop.Imaging.BinaryCondition
objBC.Conjunction = Stellent.IBPM.Interop.Imaging.Conjunction.cjOR
objBC.LeftValue = "Col5"
objBC.Operator = Stellent.IBPM.Interop.Imaging.Operator.opEqual
objBC.RightValue = "E"
objSC_AND.Conditions.Add objBC

')
objWhereClause.SearchCondition.Conditions.Add objSC_AND

SQLString, SQLSubstring and Validate

While each of these objects represent their respective portions of the select statement in their own way, they all have a common set of core functionality to return and validate the SQL code they represent.

Once the appropriate items have been added to the Clause object collections, the SQLSubstring property returns a string containing the text of of the currently populated clause. The Validate method returns a Boolean value indicating whether the currently populated object correctly generates a valid SQL clause.

The root level SQLSelect object has similar functionality that applies to the entire SQL statement. The SQLString property returns a text string containing the SQL statement of the currently populated model. The Validate method returns a Boolean indicating whether the currently populated model generates a valid SQL statement.


Retrieving Documents

Retrieving a document is performed with the DocumentManager’s WritePageObjectToFile method. As with all DocumentManager methods, the UserToken property must be set on the DocumentManager before calling WritePageObjectToFile.

The WritePageObjectToFile takes a DocumentID the references the document to be retrieved. The DocumentID may have come from the DocInfo object returned from the CreateDocument method; or, if the DocumentID values are known, a new DocumentID object can be created and the values filled in. A third method for obtaining a DocumentID is to execute a search to find it. The ADO Fields collection of a row in the Recordset returned by the search can be set on a DocInfo.ADOFields property. After this property is set, the DocInfo should contain a valid DocumentID.

Once the DocumentID of the document to be retrieved is obtained, it is passed into the WritePageObjectToFile method along with a directory to place the retrieved file and the page number in the document to be retrieved. The page number can be otFirstPage, indicating that the document’s first page should be retrieved, otLastPage indicating that the document’s last page should be retrieved, or it can be a positive integer specifying the exact page to be retrieved from the document.

The following code segment shows a complete sample of searching for a document, setting the DocInfo, and retrieving the first page.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQuery = objNamedQueries("FindDoc")
' This NamedQuery has a single prompted value requiring
' the PONumber being searched for
objNamedQuery.Conditions(1).RightValue = 123456

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 1

Dim objDocInfo As New Stellent.IBPM.Interop.Common.DocInfo
objDocInfo.ADOFields = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset(1).Fields

'Retrieve the Page
Dim objDocumentManager As New Stellent.IBPM.Interop.Imaging.DocumentManager
objDocumentManager.UserToken = m_objUserToken
objDocumentManager.WritePageObjectToFile (objDocInfo.DocumentID, Stellent.IBPM.Interop.Imaging.PageNumber.pnFirstPage)


Creating a Document

Creating a document (also referred to as Indexing a Document) is performed using DocumentManager’s CreateDocument method.

Before calling any functions on the DocumentManager object, the DocumentManager.UserToken property must be set. This sets the user credentials under which the DocumentManager object will operate so that IBPM security model and audit functionality can be enforced. (i.e., so that the object can make sure the calling user has the right to create a document in a particular index table and so that the system can audit who created a particular document.)

Next, the database table (i.e. application index) into which the document is to be index must be selected. This is done using the Connections->Connection->Tables objects (See Accessing the Database Schema.) Once a table is selected, the new index values for document must be filled into the Tables.Fields collection. This collection is an ADO Fields collection containing an ADO Field object for each field (column) in the Table. (Any field value that is set to NULL in this collection will not be indexed.)

Once the Table.Fields are filled in, the Table object is passed in the DocumentManager CreateDocument method, along with the Path to the file of the document being indexed.

Dim objConnections As Stellent.IBPM.Interop.Imaging.Connections
objConnections = New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.Refresh

Dim objTable As Stellent.IBPM.Interop.Imaging.Table
objTable = objConnections("Documents.Context").Tables("dbo.DMAppMain")

objTable.Fields("PONUMBER") = 123456
objTable.Fields("COMPANY") = "Acme"
objTable.Fields("ADDRESS") = "123 Main St"
objTable.Fields("DATE") = "05/16/2003"

Dim objDocumentManager As Stellent.IBPM.Interop.Imaging.DocumentManager
objDocumentManager = New Stellent.IBPM.Interop.Imaging.DocumentManager
objDocumentManager.UserToken = m_objUserToken

Dim objDocInfo As Stellent.IBPM.Interop.Common.DocInfo
objDocInfo = objDocumentManager.CreateDocument(objTable, "M:\Input\PO123456.tif")
MsgBox "Created " & objDocInfo.DocumentID.UniqueID

Optionally, a MIMEType can be included in the CreateDocument method that will be applied to the document when it is indexed. If a MIMEType is not supplied (or is left blank), the CreateDocument method sets the MIMEType to one of the two core IBPM types, image or universal. By specifying a more specific MIMEType, the system can be configured to perform customized actions on the document. (See Using Action Modifiers for more information on this functionality.)

If the indexes supplied for the new document exactly match the indexes for a document already existing in the application index table, the new document is appended (implicit append) to that document as its last page.

The value returned by the CreateDocument function is a DocInfo object. The DocInfo object is a container object containing the DocumentID, a reference to the stored document, and the IndexID, a reference to the index row.


Inserting Pages into Documents

Inserting a page into a document is performed with the DocumentManager’s InsertPageIntoDocument method. As with all DocumentManager methods, the UserToken property must be set on the DocumentManager before calling InsertPageIntoDocument.

The InsertPageIntoDocument takes a DocInfo object referencing the document in which the page is to be inserted. This could be the same DocInfo return by the CreateDocument method; or, if the DocumentID and IndexID values are known for the document, a new DocInfo object could be created and its properties set. A third method for obtaining a DocInfo is to execute a search to find the document. The ADO Fields collection of a row in the Recordset returned by the search can be set on the DocInfo.ADOFields property. After this property is set, the DocInfo should contain valid DocumentID and IndexID values.

Once a valid DocInfo object is obtained, it can be passed into the InsertPageIntoDocument method along with the path to the file of the document being inserted and the page number at which the insert the document. The page number can be pnFirstPage, indicating that the document should be insert as the first page in the document, pnLastPage indicating that it should be inserted as the last page, or it can be a positive integer specifying the exact page at which the page should be inserted.

The following code segment shows a complete sample of searching for a document, setting the DocInfo, and inserting a new page as the last page.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQuery = objNamedQueries("FindDoc")
' This NamedQuery has a single prompted value requiring
' the PONumber being searched for
objNamedQuery.Conditions(1).RightValue = 123456

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 1

Dim objDocInfo As New Stellent.IBPM.Interop.Common.DocInfo
objDocInfo.ADOFields = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset(1).Fields

'We have a DocInfo, now insert a page into it
Dim objDocumentManager As New Stellent.IBPM.Interop.Imaging.DocumentManager
objDocumentManager.UserToken = m_objUserToken

Dim objNewDocInfo As Stellent.IBPM.Interop.Common.DocInfo
objNewDocInfo = objDocumentManager.InsertPageIntoDocument(objDocInfo,_
                    "M:\Data\NewPage.tif", Stellent.IBPM.Interop.Imaging.PageNumber.pnLastPage)


Deleting Pages from Documents

Deleting a page from a document is performed with the DocumentManager’s DeletePageFromDocument method. As with all DocumentManager methods, the UserToken property must be set on the DocumentManager before calling DeletePageFromDocument.

The DeletePageFromDocument takes a DocInfo object referencing the document from which the page is to be deleted. This could be the same DocInfo return by the CreateDocument method; or, if the DocumentID and IndexID values are known for the document, a new DocInfo object could be created and its properties set. A third method for obtaining a DocInfo is to execute a search to find the document. The ADO Fields collection of a row in the Recordset returned by the search can be set on the DocInfo.ADOFields property. After this property is set, the DocInfo should contain valid DocumentID and IndexID values.

Once a valid DocInfo object is obtained, it can be passed into the DeletePageFromDocument method the page number to be deleted from document. The page number can be pnFirstPage, indicating that the document’s first page should be deleted, pnLastPage indicating that the document’s last page should be deleted, or it can be a positive integer specifying the exact page to be deleted from the document.

The following code segment shows a complete sample of searching for a document, setting the DocInfo, and deleting the first page.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQuery = objNamedQueries("FindDoc")
' This NamedQuery has a single prompted value requiring
' the PONumber being searched for
objNamedQuery.Conditions(1).RightValue = 123456

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 1

Dim objDocInfo As New Stellent.IBPM.Interop.Common.DocInfo
objDocInfo.ADOFields = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset(1).Fields

'We have a DocInfo, now insert a page into it
Dim objDocumentManager As New Stellent.IBPM.Interop.Imaging.DocumentManager
objDocumentManager.UserToken = m_objUserToken

objDocumentManager.DeletePageFromDocument (objDocInfo, Stellent.IBPM.Interop.Imaging.PageNumber.pnLastPage)


Modifying Document Indexes

Modifying a document index is performed with the DocumentManager’s ModifyDocumentIndexes method. As with all DocumentManager methods, the UserToken property must be set on the DocumentManager before calling ModifyDocumentIndexes.

The ModifyDocumentIndexes takes an IndexID the references the index to be modified. The IndexID may have come from the DocInfo object returned from the CreateDocument method; or, if the IndexID values are known, a new IndexID object can be created and the values filled in. A third method for obtaining an IndexID is to execute a search to find it. The ADO Fields collection of a row in the Recordset returned by the search can be set on a DocInfo.ADOFields property. After this property is set, the DocInfo should contain a valid IndexID.

ModifyDocumentIndexes also takes a Table object whose Fields property contains the values of the indexes to be modified. (This is similar to the CreatedDocument method, which uses the Table.Fields collection to supply the initial index values.) The table object passed into the ModifyDocumentIndexes method should be the same table as that referred to in the supplied IndexID. In fact, the IndexID.IndexName property can be used to find the correct Table object to be used.

The following code segment demonstrates executing a search to find the index to be modified, using the search results to fill out a DocInfo to get the IndexID, Using the IndexID to find the Table, and then modify the index.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQuery = objNamedQueries("FindDoc")
' This NamedQuery has a single prompted value requiring
' the PONumber being searched for
objNamedQuery.Conditions(1).RightValue = 123456

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 1

Dim objDocInfo As New Stellent.IBPM.Interop.Common.DocInfo
objDocInfo.ADOFields = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset(1).Fields

‘ Find The Table in which the document is index
Dim objConnections As New Stellent.IBPM.Interop.Imaging.Connections
objConnections.UserToken = m_objUserToken
objConnections.Refresh

Dim objTables As Stellent.IBPM.Interop.Imaging.Tables
Dim objTable As Stellent.IBPM.Interop.Imaging.Table
objTables = objConnections.Item (“Documents.Context”).Tables
objTable = objTables(DocInfo.IndexID.IndexName)

‘Set the index value to be modified
objTable.Fields("ADDRESS") = "456 Oak St"

‘Modify the index
Dim objDocumentManager As New Stellent.IBPM.Interop.Imaging.DocumentManager
objDocumentManager.UserToken = m_objUserToken
objDocumentManager.ModityDocumentIndexes (objDocInfo.IndexID, objTable)


Exporting Documents

Documents can be exported into various formats for display purposes. Exporting renders the document pages in a specified format (which may be different from the native format) and included any annotations that have been drawn on the document. This is different than retrieving a document (See Retrieving Documents), which returns the raw binary file stored in the Imaging system and does not include any annotations.

The object model hierarchy for exporting documents is depicted graphically as follows:

The root object in this model is the ExportedDocument object. As its name implies, it represents a single document in the Imaging system that is to be exported. ExportedDocument is a creatable object. Once created, the UserToken property must be set prior to calling an other properties of methods on the object. Setting the UserToken provides the user credentials under which the object will operate.

Next, the ExportEnvironment property must be set. The ExportEnvironment is another creatable object that specifies the configuration information that will be used to export the document. It specifies items such as export type (i.e. JPEG, GIF, BMP, etc), scale, DPI, etc. The ExportEnvironment object also specifies the export output root directory or ExportBasePath. Within this root directory, exporting supports the concept of NameSpaces. NamedSpaces are just subdirectories within the BasePath directory. However, the ExportEnvironment provides a PurgeNameSpace method which deletes all files within a NamesSpace subdirectory. This allows custom application to group together common sets of exported files and then delete then when they are no longer necessary without affecting other exported file groups that may still be in use. How the NameSpaces are divided and when it is appropriate to purge a name space is completely up to the custom application programmer.

Finally, the DocumentID and IndexID properties must be set with valid Documented and IndexId objects referencing the document that is to be exported. The DocumentID and IndexID may be obtained from a DocumentManager.CreateDocument call; or, if the DocumentID and IndexID values are known for the document, a new DocumentID and IndexID objects could be created and their properties set manually. A third method for obtaining a DocumentID and IndexID is to execute a search to find the document. The ADO Fields collection of a row in the Recordset returned by the search can be set on a DocInfo.ADOFields property. After this property is set, the DocInfo should contain valid DocumentID and IndexID values.

Once the UserToken, ExportEnvironment, DocumentID, and IndexID properties are set on the ExportedDocument object, performing the export function is as simple as walking the object model hierarchy depicted above.

Pages and Sections

Documents in the Imaging system can be made up of multiple stored files. For image based documents (i.e., tiff images) it is typical for a single document to be comprised of a multiple tiff image files. In this case, is is logical that each tiff image file be referred to as a page in the document. Because of this, a PAGE in the Imaging system is equivalent to a single FILE in storage.

For non-image based documents, this remains true but may appear less logical. For example, a single Microsoft Word document file is stored in the Imaging system as a single PAGE, even though it may actually have multiple "pages" within it. In this case, the Imaging system divides the single Microsoft Word document "page" in to multiple SECTIONS. (Note a word document is used as an example. However, the same would be true for any binary file format that internally contains multiple pages.) For an image document described above, there should be one section per page.

So, in the export SDK model, all exporting happens at the document SECTION level. This allows each of the literal pages (i.e. the Microsoft Word document pages...sections) to be exported individually.

The pages of the ExportedDocument are accessed thought ExportedPages collection, which contains individual ExportedPage documents. For a tiff document with multiple stored files, this collection will contain multiple ExportedPage objects. For a Microsoft Word document, it will contain a single ExportedPage object (unless the document is composed of multiple word documents.) The sections of an ExportedPage are then access through the ExportedSections collection. For a tiff image, this will contain a single ExportedSection. For a Microsoft Word document, it may contain multiple ExportedSection objects.) As soon as the ExportedSections collection is accessed, the export operation actually occurs and the exported files are stored in the ExportBasePath\NameSpace directory. TheExportedSection objects' FullPath and RelativePath properties point to the outputted files for the document.

The following example demonstrates searching for a document to obtain the DocumentID and IndexID, setting the ExportedEnvironment, then exported the document pages/sections a jpeg files.

Dim objNamedQueries As New Stellent.IBPM.Interop.Imaging.NamedQueries
objNamedQueries.UserToken = m_objUserToken
objNamedQueries.Refresh

Dim objNamedQuery As Stellent.IBPM.Interop.Imaging.NamedQuery
objNamedQuery = objNamedQueries("FindDoc")
' This NamedQuery has a single prompted value requiring
' the PONumber being searched for
objNamedQuery.Conditions(1).RightValue = 123456

Dim objQCM As New Stellent.IBPM.Interop.Imaging.QueryConnectionManager
objQCM.UserToken = m_objUserToken

Dim objQC As Stellent.IBPM.Interop.Imaging.QueryConnection
objQC = objQCM.CreateConnection
objQC.ExecuteQuery objNamedQuery, Stellent.IBPM.Interop.Imaging.RecordsetManagement.rsmUnmanaged, 1

Dim objDocInfo As New Stellent.IBPM.Interop.Common.DocInfo
objDocInfo.ADOFields = objQC.GetResults(Stellent.IBPM.Interop.Imaging.RecordsetReturn.rsrAll).Recordset(1).Fields

'We have a DocInfo, now insert a page into it
Dim objExportEnvironment As New Stellent.IBPM.Interop.Imaging.ExportEnvironment
Dim objExportedDocument As New Stellent.IBPM.Interop.Imaging.ExportedDocument

objExportEnvironment.ExportBasePath = "M:\ExportOutDir"
objExportEnvironment.ExportNameSpace = "ExpNameSpace"
objExportEnvironment.ExportType = Stellent.IBPM.Interop.Imaging.ExportFileType.etJPG

objExportedDocument.UserToken = m_objUserToken
objExportedDocument.ExportEnvironment
objExportedDocument.DocumentID = objDocInfo.DocumentID
objExportedDocument.IndexID= objDocInfo.IndexID

MsgBox objExportedDocuemnt.Pages(1).Section(1).FullPath


Programmer's Guide Overview

The Process SDK™ Programmer's Guide attempts to provide an overview of the components, concepts and methodologies which Stellent has incorporated into the Process SDK™. It provides a primer for many of the common techniques for using the SDK. While studying the Toolkit can provide substantial insight into the way Process functions, this guide is not intended as a general introduction to Process as a whole. This Process SDK™ Programmer's Guide and the associated reference guides do assume the reader has the prerequisite knowledge of Process terminology and functionality.

The Process SDK is comprised of three basic levels of functionality. At the lowest level, the Process SDK Toolkit Object Model is a full featured set of COM objects, each representing a separate functional entity within a Process database. For instance there are objects representing a Process, a Package Template, and a Package, to name just a few. The model is organized in such a fashion as to be conceptually consistent with the organization of the functional entitles in the database. This object model provides the core client side layer for retrieving Process definition information and manipulating the runtime entities within the database. Internally, the object model Toolkit defers most of its operation via IBPM messaging to the Process Broker. In this regard, the model can be considered as the Toolkit "for the Process Broker".

The second level of functionality included in the SDK is provided by the Process SDK Dialogs Toolkit. The process dialogs are a set of common reusable modal dialogs for performing routine Process Toolkit functions. The dialogs are generally of three basic types:

  • selection dialogs,
  • property dialogs and
  • data entry dialogs.

The selection dialogs present a list of some homogeneous types of items. The user must make a choice before continuing. Examples of the types of selection dialogs that are included are template selection, database selection, start event selection etc.

The properties dialog displays standard information about a specific entity, such as package properties, package history, process properties, and queue properties.

The data entry dialogs request information and perform a particular operation. These include things like a login dialog, a journal entry dialog, a tasks dialog, etc. All of these dialogs are considered to be at a higher level than the Object model Toolkit described above because they actually use the object model themselves. These dialogs are used by the IBPM Window client as well as being made available for custom use.

The final level of functionality is provided by the Process SDK ActiveX Controls. These are a set of controls which provide full feature views of a Process system which can be embedded into a custom application. The controls include such things as a PackageList, a FormViewer, and a PackageViewer. The controls provide the core functionality for the tools within the IBPM Windows Client. The controls are considered to be the highest level in the Toolkit because they internally use the Dialogs Toolkit as well as communicating directly with the Process Toolkit object model.

To begin accessing the power of the Process SDK, see the following sections.

User Authentication and Connecting to a Process Database

The Object Model Collection/Object Architecture

Working with Packages and Profiles

Working with Package Operations

Working with Package Fields

Working with Package Attachments


Object Model Collection/Object Architecture

The Object Model Collection/Object Architecture

The general form of the Process SDK™ Toolkit object model conforms to a standard Collection/Object architecture. The full relationships between all of the objects within this architecture are depicted in the Process SDK™ Toolkit Object Model diagram. In this structure, a particular collection object contains its particular object type. The convention throughout the model is that the collection name is the plural form of the name of the object which is contains. For example, a Packages collection contains Package objects.

There are also many instances in the model where a given object logically contains a sub collection. Such an object-to-collection relationship is used when there is corresponding one to many relationship among the BPM database entities. For example, a Process object give out a Queues collection representing the list of queues that are in that process.

Typically, collections are populated by calling its Refresh method. This is particularly true of the root level collections. Root level collections are those which have no parent object in the model. They are directly creatable and generally require that a UserToken be set before calling the collections Refresh method These include the Processes, Templates, Packages, Profiles, WFUsers, and Databases collections. The rest of the collections are derived as a property of some other parent object. They are non-creatable and inherit the UserToken from their parent. These include Queues, Events, Tasks, FieldDefinitions, etc. Typically, the objects from which these collections are derived will pre "hydrate" the collection by calling its Refresh method internally before returning it. It is therefore not necessary to call Refresh unless more up-to-date information is desired.

Regardless of the how the collection is initialized and filled, all collections support the same basic methods and properties.

  • They all have a Count property which returns the number of items currently in the collection.
  • They have and Item property which will retrieve a contained item by ordinal value. All collection are 1 based indexed, so the range of valid ordinals for the Item property will be from 1 to Count. Many collections may have a named based index, in which case the Item property may also take a string value that is the name of the item to be found in the collection.
  • For collections that also have and Id base indexer, there will also be a FindById property on the collection allowing items to be found by the appropriate Id value.

Most collections / object pairs are read-only and the set of objects they contain is fixed by the Refresh call. In general, these collection represent the definition of the BPM database which is changed only by the BPM Builder program (i.e. process, templates, events, etc).

The few collections and objects that do allow mechanisms for modification represent the instance data within the database, specifically packages, field values and attachments. These topic will be covered in Working with Package Operations, Working with Package Fields, Working with Package Working with Attachments.


User Authentication and Connecting to a Process Database

User Authentication and Connecting to an BPM Database

The user authentication for all levels of the Process SDK™ is based on the UserToken object out of the Stellent.IBPM.Interop.Common namespace. A UserToken must be obtained before performing any operation with the IBPM SDK, including the Process SDK. As the UserToken is passed around within the objects in the Stellent.IBPM.Interop.Process, namespace it serves to uniquely identifying the user under whose security privileges operations are to be performed

Once obtained the UserToken must be connected to a specific BPM database. The is done by calling the UserToken.ConnectToProcess method, passing in the BPM database name. (Note: If unknown, the available BPM databases can be enumerated by refreshing the Databases collection.) Once this is complete, the UserToken is considered to be connected to that particular BPM database. All operations performed through any Process SDK component which has been given that connected UserToken will be directed toward the specified database.

The following code fragment logins in a UserToken and connects it to the database named "ProcessDB"

Dim objUserToken As Stellent.IBPM.Interop.Common.UserToken
 Dim objUser As Stellent.IBPM.Interop.Common.User

 Set objUserToken = objUser.Login("UserId", "Password", False)
objUserToken.ConnectToProcess("ProcessDB")

After the preceding code, objUserToken is "connected" to database ProcessDB. Note that the above code is hard coded and non-interactive. The User.Login method does support an interactive mode by specifying the third parameter as True; however, the database selection remains a separate step. While a single dialog form could have been written to prompt for all three values ( UserId, Password, and Database Name,) there is a dialog provided in the Stellent.IBPM.Interop.Process.Dialogs namespace which performs this single step interactive login procedure. The dialog presents fields for UserId, Password, and Process Database (and IBPM Domain) and returns an authenticated and connected UserToken. the following code demonstrates its use.

Dim objUserToken As Stellent.IBPM.Interop.Common..IUserToken
 Dim objLoginDlg As New Stellent.IBPM.Interop.Process.Dialogs.LoginDialog

If objLoginDlg.DoModal() <> Stellent.IBPM.Interop.Process.Dialogs.drDlgReturn_Ok Then
    End
End If
objUserToken = objLoginDlg.UserToken


Working with Packages and Profiles

The Packages collection is the single source for retrieving Package objects from an BPM database. Unlike other collections, the Packages collection requires filtering criteria specifying which packages should be returned. This filter is called a Profile. Regardless of what kind of package data is desired (inbox items, items from a particular queue, a specific package, or package matching search criteria,) a profile must be created to tell the Packages collection what to get. To accomplish this, there are different types of Profiles. The ProfileType values are enumerated by otProfileType, but the Profiles type is not set directly. Rather, the Profile infers the type from the profile properties which have been set. For example, after setting the Profile.PkgRecId property, the profiles ProfileType will return otProfileType_PkgRecid.

The table below describes each of the otProfileType values and the profile properties which specify them.

Invalid | This is the profile type is non of the profile properties are set. Packages.Refresh will error if a profile of this type is supplied.
PkgRecId | Searches for a single specific package with the given PkgRecId. Since PkgRecId represents a single package instance, this can only return 1 or 0 packages. Setting Profile.PkgRecId specifies this type.
PkgId | Searches for multiple packages with the given PkgId. Since distributed packages are different instance of the same package, this can return many, 1, or 0 packages. Setting Profile.PkgRecId specifies this type.
Named | Searches for packages based on named profile criteria stored in the database. This type of profile is only obtainable from a Profiles collection.
AdHoc | Searches for packages based on criteria contained with a ProfileCriteria object. Setting the Profile.ProfileCriteria property specifies this type.
Inbox | Returns packages for the user represented by the UserToken (as set in the Packages collection running the profile). Setting the Profile.Inbox to True specifies this type. Additionally, and administrator can set the Profile.InboxUserId property to have the collection filled with package from the inbox other than the user represented by the UserToken.
Queue | Returns packages from a specific queue. Setting Profile.Queue specifies this type.


Working with Package Operations

The Package object is likely to be the most used object within the model. Each Package object represents a single package instance in the IBPM Process database. The unique key for the package (which identifies a specific package, in a specific event, in a specific process) is the PkgRecId. This must be disguised from the PkgId which identifies all copies of a particular package including any that have distributed to multiple processes and events.

Most of the Package properties are read only and specify the current state and location of the package. Many of the properties preset equivalent information in multiple formats: Id, Name, and object. Typically, the Id and name are returned from the Process Broker during the packages refresh. Requesting the object requires a message to the back end to fetch the full information for the object.

Properties of the package include:

Identification Information: PkgId, PkgRecId, Title

Type Information: TemplateId, TemplateName, Template

Location information: ProcessId, ProcessName, Process, QueueId, QueueName, Queue, EventId, EventName, Event, LockedByUserId, LockedByName

System Fields: DueDate, DueDateFired, CreateDate, CreatorName, CreatorUserId, InQueueDate, Priority, Threshold1, Threshold2, Threshold3, ThresholdFired.

Contained Objects: FieldValues, Attachments, Forms

Note that the system fields DueDate, DueDateFired,Priority, Threshold1, Threshold2, Threshold3, and ThresholdFired are read-only as package properties but editable as FieldValues.

Package Types

Depending upon a packages location an locked status, a package will be on a particular Package type, as enumerated by PackageType.

Package Operations

The methods of the Package object perform various operations. These include:

  • AddJournalEntry
  • Complete
  • Delete
  • Lock
  • PlaceInFlow
  • RouteAdHoc
  • RouteToEvent
  • RouteToUser
  • Unlock

A number of these methods sent the package to the Process Broker for a routing operation, including Complete, PlaceInFlow, and Route operations. After those calls, the current object will no longer contain the packages correct information (i.e. it is moving). so no further operation on the object is allowed. As such, the package objects PackageType will indicate the otPackageType_Invalid. Note that this only means that the COM object held in memory by the client is invalid and not that the package entity which it formerly represented is invalid.

The methods a given user can perform on a given package depend upon the package's type and location and the users permission level. The user's PermissionLevel for that specific package depends on the rights he has been given to the queue in which the package resides. If a specific operation is not allowed, the call to the operation will fail. A user can determine if the operation is allowed by calling CanDoOperation.


Working with Package Fields

Package Field Values are obtained from a Package object by getting its FieldValues collection. Each FieldValue in the collection represents one of the fields on that specific package. The FieldValue.Value property can be read to obtain the current setting for that field. The Variant type will reflect the type of the actual field as define in BPM Builder.

The FieldValue.Value can also be set to update the fields value. Because the property is a Variant, any data type can be passed in; however, the FieldValue object will attempt to convert the passed in value to the data type of the corresponding field. If it fails to do so, an invalid data type error will be returned.

Any number of FieldValue objects in the collection can be updated, but no actual update occurs in the database until the FieldValues.Commit method is called. If FieldValues.Refresh is called without calling commit, all changes to any FieldValue in the collection is discarded.


Working with Package Attachments

Package Attachments are obtained from a Package object by getting its Attachments collection. Each Attachment in the collection represents one of the attachments contained within that specific package.

The CreateAttachment method creates an new Attachment object with the collection. The newly created attachment is empty so its Title, DocumentId, and IndexId properties must be set for the attachment object to reference real data. Once created, the Attachment exists in a "new" state and has an AttachmentId which is less than 1. It does not get fully attached to the package until the Attachments Commit method is call. See below for information about Adding an Attachment to a Package Programmatically.

The attachment MarkDeleted method flags a Attachment object within an Attachments collection for deletion on the next Commit.

Calling the Attachments Refresh method without calling Commit will reset the internal status of all objects, including those with MarkDeleted set, back to the unmodified state and will discard any Attachment objects newly created by the CreateAttachment method. This functionality can be used to roll-back any undesired changes to the objects within the collection.

References:

  • OTPROCESS.dll
  • OTACORDE.dll

OTACORDE.dll has two main objects that need to be used

  • DocumentId
  • IndexId

If adding a local file object, fill in the information for the DocumentId object. If adding an IBPM object then fill in the information for both the DocumentId object and IndexId object.

DocumentId

    • Mime Type
      • For local file objects use:
        • "application/x-emedia.wfuniversal" for File objects
      • For IBPM objects use one of the following:
        • "image/tiff" for IBPM Imaging
        • "text/x-emedia.cold" for IBPM COLD
        • "application/x-emedia.universal" for IBPM Universal
        • This value is obtained from the IBPM Client in the Mime Type field in the object properties dialog
    • Provider Id
      • For local file objects use:
        • "{081016EE-F688-11D3-9E61-00C04F097031}"
      • For IBPM objects use:
        • "{0BF3C340-4C13-11d3-8166-00C04F99E979}"
        • This value is obtained from the IBPM Client in the Provider GUID field in the object properties dialog.
    • Unique Id
      • For local file objects use:
        • The location of the file
      • For IBPM objects use one of the following:
        • Cold – the full Stellent Object Id
        • Image – the RecId of the object
        • Univ – the RecId of the object
        • This value is obtained from the IBPM Client in the LUCID field in the object properties dialog

IndexId (for IBPM objects only)

    • IndexID
      • Cold – use the Document Id:Physical Cold Number (from the Stellent Object Id, pre padded with zeros to make 10 digits each)
      • Image - the RecId of the object
      • Univ – the RecId of the object
      • This value is obtained from the IBPM Client in the Unique Row Identifier field in the object properties dialog
    • IndexName
      • LinkServerName.Instance.Catalog.Table value
      • This value is obtained from the IBPM Client in the Source field in the object properties dialog
    • IndexProvider
      • Cold - "{0BF3C340-4C13-11d3-8166-00C04F99E979}"
      • Image/Univ - "{608FCB70-10BF-11d4-A931-00C04F94786A}"
      • This value is obtained from the IBPM Client in the Index Provider GUID field in the object properties dialog

Sample: Adding a local file object:
Dim objDocumentId = New Stellent.IBPM.Interop.Common.DocumentID
objDocumentId.UniqueID = "C:\Temp\wftest.jpg"
objDocumentId.MimeType = "application/x-emedia.wfuniversal"
objDocumentId.ProviderID = "{081016EE-F688-11D3-9E61-00C04F097031}"
objAttachments = objPackage.Attachments
objAttachment = objAttachments.CreateAttachment
objAttachment.DocumentId = objDocumentId
objAttachment.Title = "My First Local File Attachment"
objAttachments.Commit()

Sample: Adding an IBPM object:

Dim objDocumentId = New Stellent.IBPM.Interop.Common.DocumentID
objDocumentId.UniqueID = "1.3.12446899.12446899.197988.12.20020214.150738.0.0.0.COLD1.8.1.197988.0.0.0.0.150"
objDocumentId.MimeType = "text/x-emedia.cold"
objDocumentId.ProviderID = "{0BF3C340-4C13-11d3-8166-00C04F99E979}"
Dim objIndexId = New Stellent.IBPM.Interop.Common.IndexID
objIndexId.IndexId = "0012446899:0000000150"
objIndexId.IndexName = "COLD..COLD1.aMain"
objIndexId.IndexProvider = "{608FCB70-10BF-11d4-A931-00C04F94786A}"
objAttachments = objPackage.Attachments
objAttachment = objAttachments.CreateAttachment
objAttachment.IndexId = objIndexId
objAttachment.DocumentId = objDocumentId
objAttachment.Title = "My First IBPM Attachment"
objAttachments.Commit()


Creating and Debugging Process Forms

VB .Net Process forms may be created using the following steps:

· Create a VB .Net form using the Form Wizard within BPM Builder

· When the form wizard is complete it will launch the created solution to MS Visual Studio .Net

· The form project created will contain a Stellent.IBPM.Process.Forms.FormContext member variable that the IBPM Client Framework Form Viewer tool uses to interact with the .Net Windows form through events and properties.

o       Properties

§ UserToken – The user token of the user logged into the IBPM Client

§ Package – The BPM Package object the form is to display

§ Form – For internal use, it is a reference to the Process form.

o       Methods

§ Constructor – The FormContext object is created by passing a reference to the Process form object and a Boolean to enable simulation of the IBPM Client environment

§ SendClientMessage – Allows interaction between the Process form and other IBPM Client tools.

o       Events

§ FormData – Custom data has been passed to the form from another source.

§ PackageDataChanged – The IBPM Client Framework is letting the form know that BPM Package object may have been changed.

VB .Net Process forms may be debugged using simulation by using the following steps:

· The Stellent.IBPM.Process.Forms.FormContext object is capable of simulating parts of the IBPM Client Framework to help in debugging a Process form outside of the IBPM Client.

o       The form when built with the Debug solution configuration will default the simulate environment option to ‘On’ using the following code snippet; which can be found in the ‘New’ method of the form:

SimulateEnvironment = False

#If DEBUG Then

               SimulateEnvironment = True

#End If

o       The form, when ready for production, should be compiled with the active configuration set to ‘Release’. If the simulate environment option is ‘On’ when the form is executed inside the IBPM Client a warning message will appear.

· Build the form with the active solution configuration set to debug.

· Place breakpoints in appropriate locations throughout the code.

· Select the Debug | Start menu option

· A warning message will be displayed to remind the form developer to build the project with the solution configuration set to ‘Release’. This will disable the simulate environment setting.

· After the warning message is displayed a login dialog will be displayed.

· Login using a valid IBPM Process user.

· Once logged in, the Named Package Profiles will be displayed that the previously logged in user has access too. Note: only profiles without prompts will be displayed.

· Choose a Named Profile and select OK.

· Packages will be displayed which match the Profile’s selection criteria.

· Choose a Package and select OK.

· The form will be created and the selected package will be passed to the form.

· Notice the form is now capable of being debugged.

· Notes of interest:

o       The package selected is live; any changes committed will be effected to the package in the database chosen during login. This includes but is not limited to

§ committing field values

§ routing or completing the package

§ adding comments to the package history

o       The PackageDataChanged and FormData events will not be triggered during simulation.


IBPM Web Services Overview

This topic describes the use of the IBPM Web Services portion of the IBPM Web SDK. The IBPM Web Services portion of Web SDK component is provided to facilitate use of the IBPM functionality through a standard Web Service Interface. Web Services are provided through the use of WSDL and ASMX files located on the IBPM Web Server.

IBPM Web Services require the installation of the IBPM Web client and the Web SDK portion of the IBPM SDK install. In addition, an administrator must first enable the SOAP components through the IBPM Web Client using the SOAP Settings Tool to complete the SOAP installation. This action creates WSDL files on the IBPM Web Server that are bound to the machine name.

Web Service calls return complex types defined by objects representing IBPM data as return values. These objects are similar to the objects used in the IBPM COM SDK. The objects provide developers an interface for easily accessing the data returned from a specific Web Service call. The objects only contain data and may also be used as input parameters for some Web Service calls. Each object structure is defined in the IBPM Web Services Objects documentation.

Additional methods have been added that provide the ability to access IBPM functionality with different types of input values. For example, there are three different calls available that provide the ability to Unlock packages.

IBPM Web Services provide a platform independent mechanism for implementing IBPM solutions. The Acorde2.asmx file located in the following directory may be referenced after Web Services have been activated (by enabling SOAP components).

http://MyWebServer/IBPMweb/Services/Acorde2.asmx?wsdl

The ASMX file is a self-documenting. Navigating to this ASMX file in a browser displays available Web Service calls as they are named in the Acorde2 interface. Acorde2 incorporates all the original WSDL based IBPM Web Service calls into a single Web Service.

The newer 4.0 Web Services found in Acorde2 are an additional interface layer constructed around the WSDL based Web Services that were available in previous releases. The Acorde2 Web Service uses complex SOAP objects. The older interface may still be accessed through a single entry point by using the Acorde.asmx file located in the following directory.

http://MyWebServer/IBPMweb/Services/Acorde.asmx

The individual WSDL files may also be accessed directly and are located in the following directory.

http://MyWebServer/IBPMweb/SOAP

Although Web Services may be accessed via Acorde.asmx and the WSDLs, it is strongly recommended that the Acorde2.asmx interface be used for all new integrations.

IBPM Web Service Components

This release of IBPM Web Services focuses on basic BPM and Imaging functionality. The intent is to provide a base functionality for integration of BPM and Imaging functionality in systems that could benefit from that functionality (i.e. ERP systems). The following is a listing of the available IBPM Web Service functionality.

· Request a Profile List for a User

· Request a List of Prompts for a Profile

· Request a Package List based on a Named Profile

· Request a Package List based on a Prompted Profile

· Lock and Unlock Packages

· Request Decisions for a Package

· Complete Packages using Named Decisions or Default Decisions.

· Get and Set Package Field Values

· Get and Return a Saved Search

· Add Comments by Package Rec ID

· Get a List of Saved Searches and their Prompts and Properties

· Start and Stop Saved Searches

· Export Objects from IBPM

In addition to this BPM and Imaging functionality, login functionality is provided. The following is a list of the login functionality provided by IBPM Web Services.

· Login

· Login – Connect with Workflow

· Connect to a specified Language

· Connect to a specified Workflow Database.

The following sections outline the specific functionality described above in more detail.

IBPM User Web Service Methods

The following section describes IBPM User functionality provided by IBPM Web Services. This functionally is defined by the WSDL "AcordeUser.WSDL" found in the SOAP directory on the IBPM Web Server after the IBPM SOAP components have been enabled.

The following specific calls are available.

· LoginUserName

· LoginUserNameProcess

· LoginAlias

· LoginAliasProcess

· RegisterAlias

· ConnectProcess

· ConnectLanguage

· Logout

BPM Web Service Methods

The following section describes BPM functionality provided by IBPM Web Services. This functionally is currently defined by two WSDLs. These are "AcordeProcessProfiles.WSDL" and "AcordeProcessPackages.WSDL". These WSDLs are found in the SOAP directory on the IBPM Web Server after the IBPM SOAP components have been enabled.

The following lists the specific calls available in the AcordeProcessProfiles.WSDL definition.

· GetAvailable

· GetProfilePrompts

The following lists the specific calls available in the AcordeProcessPackages.WSDL definition.

· GetListByProfile

· GetListByPromptedProfile

· GetDecisionsByPkgRecID

· LockPackageByPkgRecID

· LockPackageByPkgRecIDAndQueue

· UnlockPackageByPkgRecID

· CompletePackageByPkgRecID

· GetFieldPicklistsFromTemplate

· GetPackageFields

· SetPackageFields

· AddJournalEntryByPkgRecID

· CreatePackages

· GetPackageTemplates

· GetPackageTemplateIdFields

· GetPackageTemplateNameFields

· GetTemplateIdStartEvents

· GetTemplateNameStartEvents

· PlacePackagesInFlow

Imaging Web Service Methods

The following describes Imaging functionality provided by IBPM Web Services. Imaging functionality is defined by the WSDLs AcordeContextSearch.WSDL and AcordeContextExport.WSDL. These are found in the SOAP directory on the IBPM Web Server after the IBPM SOAP components have been enabled.

· BeginSavedSearch

· ContinueSearch

· StopSearch

· GetAvailableSavedSearches

· GetSavedSearchProperties

· GetSavedSearchPrompts

· Export

· ExportEx

· ExportFromSearchResults

· ExportFromSearchResultsEx

· PurgeCache

IBPM Web Client Utilities Web Service Methods

The following describes IBPM Web Client Utilities functionality provided by IBPM Web Services.The functionality is defined by the WSDL “AcordeWebClientUtilities.WSDL” found in the SOAP directory on the IBPM Web Server once the IBPM SOAP components have been enabled.

The following specific calls are available.

· RegisterURLDescription

· RemoveTicket

· GetAcordeWebServerURL


User Methods

IBPM User Methods

All of the methods exposed by IBPM Web Services will require an AIID as an input parameter. The AIID is the IBPM Infrastructure Initialization Document, which is an xml string containing login information. An AIID behaves similarly to that of a UserToken when developing custom IBPM applications using the IBPM COM SDK. The AIID provides proof that the caller of the method has successfully been able to login to the IBPM system.

The IBPM User Web Service methods ultimately return an AIID once valid login credentials have been provided. Store the AIID in a variable or session state for re-use within your application. Upon the termination of your application, provide the AIID to the Logout web service method in order to logout your connection and free up the consumed license.

The AIID is not used by other web service methods to login to the IBPM system. Instead, AIID information is only used to reactivate the UserToken from the connection established by one of the IBPM User login methods.

Contents of the AIID:

The AIID document does not contain login and password information. Instead, it contains a unique ID used to reactivate the UserToken, a revision number, language id, and a location parameter. An AIID created from an Alias registration will also contain the alias name.

Standard AIID:

<AIID>

<Rev>1</Rev>

<Loc>true</Loc>

<Vals>

<AID>{DA829EC6-4FED-4401-A855-795EAB7A4647}:12570830</AID>

<LANG>en-us</LANG>

</Vals>

</AIID>

AIID with Alias information:

<AIID>

<Rev>1</Rev>

<Loc>true</Loc>

<Vals>

<AID>{2DB0CAB1-416E-4A0C-ACEC-AF8FB907BC87}:12570820</AID>

<AAN>ContextAlias</AAN>

<LANG>en-us</LANG>

</Vals>

</AIID>

Basic Login

The most commonly used login methods are LoginUserName and LoginUserNameProcess. Simply provide a user name and password to login to the IBPM system and obtain a valid AIID. The License Type and Style parameters are reserved for future use.

LoginUserNameProcess has an additional optional parameter; Process Database Name. If no Process Database name is provided, the system will select the default Process Database. If only one Process Database exists, then that database will automatically be selected. If there are multiple databases, the default is the first process database found in the database collection.

string strAIID = objAcorde.LoginUserName(strUserName, strPassword, "", "");

string strAIID_Process = objAcorde.LoginUserNameProcess(strUserName, strPassword, "", strProcessDBName, "");

The variables strAIID and strAIID_Process represent two separate login connections to an IBPM system. The return value “strAIID” points to a Context-only system, while the return value “strAIID_Process” has logged into both Context and Process. These variables will be used with all IBPM Web Service calls that require an AIID. For example, the application could request a list of saved searches using the GetSavedSearches method:

SavedSearchNamesArray objSSNA = objAcorde.GetAvailableSavedSearches(strAIID);

Or strAIID_Process could be used to retrieve a list of profiles:

ProfileArray objPA = objAcorde.GetAvailableProcessProfiles(strAIID_Process);

Using an Alias

The LoginUserName and LoginUsernameProcess methods return an AIID for a connection to the IBPM system that is ultimately terminated from either a call to the Logout method or a Gallery timeout. The next time a login is made, the user name and password must be provided to establish a connection.

An alias allows the user to provide the username and password credentials only once. An alias name is supplied and a public key is returned. The user name and password information is then stored in encrypted format on the IBPM Web Server. Calls to LoginAlias and LoginAliasProcess only require the name of the alias, along with the public key to reestablish a connection and return an AIID.

The benefit of using aliases is to prevent calling applications from having to provide user and password information at login time.

The RegisterAlias method is called only once. This provides a unique name for the alias; along with a username and password. If the web service method can successfully login with the credentials provided, then a public key value is returned. The LoginAlias and LoginAliasProcess methods may be called by passing in the alias name and public key instead of username and password values.

string strAliasName = “Acorde_Alias”;

string strUserName = “user1”;

string strPassword = “webservices”;

string strProcessDBName = “AcordeProcessDB1”;

string KEY = objAcorde.RegisterAlias(strAliasName, strUserName, strPassword);

string strAIID = objAcorde.LoginAlias(strAliasName, KEY, “”, "");

string strAIID_Process = objAcorde.LoginAliasProcess(strAliasName, KEY, “”, strProcessDBName, "");

The string variables strAIID and strAIID_Process will contain an xml document representing the AIID returned from each of the login methods.

Future methods

ConnectLanguage(…)

ConnectProcess(…)

These methods will allow a user to change the current language or process database. They have been exposed via the Acorde2 interface, but are not yet implemented.

Logout

The Logout method should always be called when exiting your application. Otherwise, the login connection will continue to consume an available IBPM license until the specified timeout for connections has been reached or until the web server has been restarted.

The Logout method requires an AIID as an input parameter and returns a string. A successful logout returns a string with the value of “SUCCESS”. A logout failure returns a string containing any error messages.

string strLogout = objAcorde.Logout(strAIID);


Export Methods

IBPM Export Methods

There are six different Export methods available in the IBPM Web Services.

Export

ExportBySystemFields

ExportEx

ExportExBySystemFields

ExportFromSearchResults

ExportFromSearchResultsEx

Also available is a way to remove the temporary cache files.

PurgeCache

All of the Export methods return an <a href=”objects\ExportRestultsArray.htm”>ExportResultsArray</a> object which contains a collection of <a href=”objects\ExportResult.htm”>ExportResult</a> objects. Each ExportResult object relates to a single exported item. This does not mean it corresponds to a single document, as an exported document may be composed of several exported items. The ExportResult object will provide the Page number, Section number, and physical location of each exported item. The location is constructed by creating a URL to the exported document. The web server name used in the URL comes from the SOAP Settings tool’s WebServerName property.

From the SOAP Settings Tool:

WebServerName - The WebServerName registry stores the value of the web location of exported documents on your IBPM Web Server. Users of the SOAP Export functions will use this value when attempting to access the location of exported documents via HTTP.

If the WebServerName parameter has been set to “myWebServer”, then the base path of the Location for the ExportResult object would be:

http://myWebServer/IBPMdata/IBPMsessiondata

The code block below exports a document and displays the ExportResult information:

Using Export:

AcordeWS.ExportResultsArray objERA_Export;

// Export

objERA_Export = objAcorde.Export(AIID, objSSRA.SearchResults[0]);

for(int i=0; i < objERA_Export.Results.Length; i++)

{

AcordeWS.ExportResult objER = objERA_Export.Results[i];

string strLocation = objER.Location;

string strPage = objER.Page.ToString();

string strSection = objER.Section.ToString();

Response.Write("<HR>Page: " + strPage + "<BR>");

Response.Write("Section: " + strSection + "<BR>");

Response.Write("Location: <a href='" + strLocation + "'>" + strLocation + "</a><BR>");

}

This code sample produces the following output:

Page: 1
Section: 1
Location: http://myWebServer/IBPMdata/IBPMsessiondata/_BA2FB412_638B_44D1_980E_366A25CAE4E1__12572882/AcordeContextExport/imgB3/imgB4.jpg

Page: 2
Section: 1
Location: http://myWebServer/IBPMdata/IBPMsessiondata/_BA2FB412_638B_44D1_980E_366A25CAE4E1__12572882/AcordeContextExport/imgB3/imgB5.jpg

The Export methods that end in “Ex” accept additional parameters that allow the programmer to specify the following values:

· DPI - An integer stating the DPI setting of the exported document. Default is 96.

· Type - An integer that represents the format of the exported document. (3 = Image, 5 = Stellent, 9 = Native, 8 = PDF) Default is 3.

· Namespace - The name of the session sub folder in which the documents will be exported. Default is "AcordeContextExport".

· Scale - An integer stating the zoom percent of the exported document. Default is 140.

· Highest Resolution - Default is false.

AcordeWS.SavedSearchResult objSSR_Export = objSSRA.SearchResults[0];

AcordeWS.SystemFields objSF_Export = objSSR_Export.SystemFields;

AcordeWS.ExportResultsArray objERA_Export;

Using ExportEx:

// ExportEx

objERA_Export = objAcorde.ExportEx(AIID, objSSR_Export, 50, 8, "Sample", 50, false);

This code block exports the document with a DPI of 50, as PDFs, in the “Sample” namespace, with a scale of 50, and will not use the Highest Resolution setting.

These methods are particularly useful when documents need to be exported as a type other than .jpg or when the image quality can be reduced for speed and file size concerns (or increased for image quality concerns).

Using ExportFromSearchResults:

Instead of making several Export calls for each item, it is possible to export an entire batch of documents by using either the ExportFromSearchResults or ExportFromSearchResultsEx methods. These methods accept a SavedSearchResultsArray object as an input parameter. The method will export each SavedSearchResult object with an IsSelected property of true. By default, this property is returned as false, so the programmer must mark each of the items to export as in the code block below.

// ExportFromSearchResults

// Set the IsSelected property to true for all results

for(i=0; i < objSSRA.SearchResults.Length; i++)

{

objSSRA.SearchResults[i].IsSelected = true;

}

objERA_Export = objAcorde.ExportFromSearchResults(AIID, objSSRA);

Using PurgeCache:

(Default is “AcordeContextExport”)

Documents are exported into a specific folder on the IBPM Web Services web server.

The following is an example of a typical base location for storing any session-based information for IBPM Web Service calls.

C:\Inetpub\wwwroot\IBPMData\IBPMSessionData\_7767FC52_ABAB_485D_85A6_6CE243244FDE__12572874

The ExportEx methods allow you to specify the name of the folder to export the documents. By default, the location is “AcordeContextExport”. The location below describes the path of where all exported documents will be located after calling any of the Export web service methods.

C:\Inetpub\wwwroot\IBPMData\IBPMSessionData\_7767FC52_ABAB_485D_85A6_6CE243244FDE__12572874\AcordeContextExport\

Before calling the IBPM Web Services Logout method, the PurgeCache method should be called to clear out this export folder. Another approach is to include a call to PurgeCache in any exception code blocks of your application. The purpose of the PurgeCache call is to cleanup the exported files on the IBPM Web Services web server.

// Purge cache

// PurgeCache empties specified folders that contain exported documents within the

// /IBPMData/AcordeSession/Data/<Session ID> folder structure

// on the web server that hosts the IBPM Web Services.

// Empties the default "AcordeContextExport" directory since no value was supplied

AcordeWS.ExportResultsArray objERA_PC = objAcorde.PurgeCache(AIID, "");

// Empties the contents of the supplied directory, "MyCustomNameSpace"

AcordeWS.ExportResultsArray objERA_PC = objAcorde.PurgeCache(AIID, "MyCustomNameSpace");


Search Methods

IBPM Search Methods

The basic level of functionality for Searching is to acquire a list of searches available for the current user. Login in using any of the IBPM User login methods (See the Programmer’s Guide -> Using the Web Services -> IBPM User Methods section) in order to obtain a valid AIID.

Getting a list of Saved Searches:

Here is an example of how to get a list of Saved Searches and list the display name for each of their prompted fields. Begin by passing in the AIID to the GetAvailableSavedSearches method.

// Get a list of available saved searches

AcordeWS.SavedSearchNamesArray objSSNA = objAcorde.GetAvailableSavedSearches(AIID);

From this method, a SavedSearchNamesArray object is returned. Within the SavedSearchNamesArray object is an array of SavedSearchName objects. Each SavedSearchName object contains the name of each Saved Search available for the current user. This web service method will only return the Saved Searches that the current user has security rights for.

This “For Loop” displays the list of SavedSearches using the SavedSearchNamesArray object. Note that you can access the Name property by creating a local SavedSearchName object for each element of the SearchNames array in the SavedSearchNamesArray object OR you could navigate to the Name property directly.

for(int i=0; i<objSSNA.SearchNames.Length; i++)

{

// Get the next SavedSearchName object

AcordeWS.SavedSearchName objSSN = objSSNA.SearchNames[i];

// Each line accesses the Name property

Response.Write("<P><B>" + objSSN.Name + "</b><br>");

Response.Write("<P><B>" + objSSNA.SearchNames[i].Name + "</b><br>");

}

Inspecting the Search Properties:

Here is an example of how to inspect the properties of a Saved Search.

// Get the Properties for a Search

AcordeWS.SavedSearchPropertiesArray objSSPA = objAcorde.GetSavedSearchPropertiesBySearchName(AIID, “Sample Saved Search”);

for(int i=0; i < objSSPA.Properties.Length; i++)

{

AcordeWS.SavedSearchProperty objSSP = objSSPA.Properties[i];

Response.Write("Name: " + objSSP.Name + "<BR>");

Response.Write("MaxRows: " + objSSP.MaxRows + "<BR>");

Response.Write("MaxExecTime: " + objSSP.MaxExecTime + "<BR>");

Response.Write("Offline: " + objSSP.OffLine + "<BR>");

}

This code block will return the following information:

Name: Sample Saved Search
MaxRows: 10000
MaxExecTime: 5
Offline: False

Another approach would be to use the GetSavedSearchPropertiesSingle or GetSavedSearchPropertiesMultiple methods.

GetSavedSearchPropertiesSingle accepts a single SavedSearchName object and GetSavedSearchPropertiesMultiple accepts a SavedSearchNamesArray object.

AcordeWS.SavedSearchPropertiesArray objSSPA = objAcorde.GetSavedSearchPropertiesSingle(AIID, objSSNA.SearchNames[0]);

AcordeWS.SavedSearchPropertiesArray objSSPA = objAcorde.GetSavedSearchPropertiesSingle(AIID, objSSNA

Executing an Unabated Search:

Here is an example of how to execute an unabated search.

Searching requires a valid AIID, Saved Search Name, SavedSearchPromptsArray object, and the number of rows to return.

In order to run an unabated search, simply pass in an empty SavedSearchPromptsArray object along with the other input parameters.

// Create an empty SavedSearchPromptsArray object. Don't set any values.

AcordeWS.SavedSearchPromptsArray objSavedSearchPromptsArray = new ContextSample.AcordeWS.SavedSearchPromptsArray();

// Execute the search

AcordeWS.SavedSearchResultsArray objSSRA = objAcorde.BeginSavedSearch(AIID, “Employee List Search”, objSavedSearchPromptsArray, 100);

In this example, the “Employee List Search” will be executed and only the first 100 rows will be returned. Since none of the prompt values were supplied in the objSavedSearchPromptsArray object, the search will be run unabated. This approach only works as long as none of the prompt fields are required.

Executing a Saved Search based on search criteria:

In order to supply search criteria that will restrict the result set of the Saved Search, simply provide values for each of the prompted fields by setting them in the SavedSearchPromptsArray object.

// Select a specific Search; get the prompts; supply prompt values; execute the search

// walk through the original return object to retrieve the name of a saved search

string strSearchName = objSSNA.SearchNames[4].Name;

// get the prompts for the search

AcordeWS.SavedSearchPromptsArray objSSPA = objAcorde.GetSavedSearchPromptsBySearchName(AIID, strSearchName);

AcordeWS.SavedSearchResult objSSR;

// provide values for a prompt

for(int k=0; k < objSSPA.Prompts.Length; k++)

{

if(objSSPA.Prompts[k].DisplayText == "POZip")

{

objSSPA.Prompts[k].Value = "39426";

}

}

// Execute the search

AcordeWS.SavedSearchResultsArray objSSRA = objAcorde.BeginSavedSearch(AIID, strSearchName, objSSPA, 100);

This code block obtains the prompts for the fifth Saved Search returned from the GetAvailableSavedSearches web service method. It then restricts the search to only return records where the “POZip” field is equal to the value “39426”.

Displaying the User Defined Field values and System Field information for each row in the search results of a Saved Search:

After executing a Saved Search, the result set information is contained within the returned SavedSearchResultsArray object, which contains an array of SavedSearchResult objects and an array of UserDefinedFieldDefinitionArray objects. The UserDefinedFieldDefinitionArray object contains information describing the name and type for each column of the result set.

The SavedSearchResult object contains information that describes an individual row in the result set returned from executing an Imaging Saved Search. The data in this object provides information regarding the status of the Saved Search, the System Fields object (containing data that uniquely identifies an IBPM document), and a UserDefinedFields collection that lists the name and values for each column in the row result.

The following code block runs an unabated search for the “ABC Saved Search”. First, general information about the status of the Saved Search is displayed. Next, the data for each row, along with System Field information, is displayed by using the returned SavedSearchResultsArray object.

// Create an empty SavedSearchPromptsArray object.

AcordeWS.SavedSearchPromptsArray objSavedSearchPromptsArray = new ContextSample.AcordeWS.SavedSearchPromptsArray();

// Execute the search

AcordeWS.SavedSearchResultsArray objSSRA = objAcorde.BeginSavedSearch(AIID, “ABC Saved Search”, objSavedSearchPromptsArray, 100);

// Display the result information

Response.Write("<h2>Search: ABC Saved Search <h2><P>");

// Display Search Information

Response.Write("SearchConnectionID:" + objSSRA.SearchResults[0].SearchConnectionId + "<br>");

Response.Write("Search Status Enumeration:" + objSSRA.SearchResults[0].SearchStatus + "<hr>");

for(int l=0; l < objSSRA.SearchResults.Length; l++)

{

AcordeWS.SavedSearchResult objSSR = objSSRA.SearchResults[l];

// Write the return data

Response.Write("<p><b>Index Info:</b><BR>");

for(int m=0; m < objSSR.UserDefinedFieldValues.Length; m++)

{

AcordeWS.UserDefinedField objUDF = objSSR.UserDefinedFieldValues[m];

Response.Write("<br>" + objUDF.Name + " = [" + objUDF.Value + "]");

}

// Write the System Fields info for this document

AcordeWS.SystemFields objSF = objSSR.SystemFields;

Response.Write("<p><i><b>System Field Info:</b><BR>");

Response.Write("LUCID [" + objSF.LUCID + "]<br>");

Response.Write("MIMETYPE [" + objSF.MIMETYPE + "]<br>");

Response.Write("ROWIDENTIFIER [" + objSF.ROWIDENTIFIER + "]<br>");

Response.Write("SSPROVIDERID [" + objSF.SSPROVIDERID + "]<br>");

Response.Write("TABLENAME [" + objSF.TABLENAME + "]<br>");

Response.Write("LUCINDEXPROVIDERID [" + objSF.INDEXPROVIDER + "]<br>");

Response.Write("</i><hr>");

}

Search: ABC Saved Search

SearchConnectionID:SMS A {1845051}
Search Status Enumeration:1

Index
Info:
POZip = [31909]
POName = [Duluth]
POAmount = [10102]

System Field Info:
LUCID [571143199]
MIMETYPE [application/x-emedia.universal]
ROWIDENTIFIER [571143199]
SSPROVIDERID [{0BF3C340-4C13-11d3-8166-00C04F99E979}]
TABLENAME [Documents.Context.dbo.POTest.Main]
LUCINDEXPROVIDERID [{608FCB70-10BF-11d4-A931-00C04F94786A}]

Index
Info:
PoDate = [2005-01-09T00:00:00]
POZip = [30739]
POName = [Grand Rapids ]
POAmount = [12173]

System Field Info:
LUCID [571143200]
MIMETYPE [application/x-emedia.universal]
ROWIDENTIFIER [571143200]
SSPROVIDERID [{0BF3C340-4C13-11d3-8166-00C04F99E979}]
TABLENAME [Documents.Context.dbo.POTest.Main]
LUCINDEXPROVIDERID [{608FCB70-10BF-11d4-A931-00C04F94786A}]

Index
Info:
PoDate = [2003-05-01T00:00:00]
POZip = [27079]
POName = [Rock Island ]
POAmount = [10185]

System Field Info:
LUCID [571143201]
MIMETYPE [application/x-emedia.universal]
ROWIDENTIFIER [571143201]
SSPROVIDERID [{0BF3C340-4C13-11d3-8166-00C04F99E979}]
TABLENAME [Documents.Context.dbo.POTest.Main]
LUCINDEXPROVIDERID [{608FCB70-10BF-11d4-A931-00C04F94786A}]

Index
Info:
PoDate = [2003-10-22T00:00:00]
POZip = [32747]
POName = [Owensboro ]
POAmount = [6724]

System Field Info:
LUCID [571143202]
MIMETYPE [application/x-emedia.universal]
ROWIDENTIFIER [571143202]
SSPROVIDERID [{0BF3C340-4C13-11d3-8166-00C04F99E979}]
TABLENAME [Documents.Context.dbo.POTest.Main]
LUCINDEXPROVIDERID [{608FCB70-10BF-11d4-A931-00C04F94786A}]


BPM Methods

Process methods within Web Services provides various functionality such as creating a package, routing a package, adding a comment, adding an attachment, modifying field values, and searching for a package (or list of packages).

Logging in to Process:

Login to Process using the LoginUserNameProcess web service method. Refer to the Programmer’s Guide -> Using the Web Services -> IBPM User Methods section for more information about login methods.

The first and second parameters of this method are the user name and password. The fourth parameter is the name of the Process database you wish to login to. If this parameter is left blank, then the default Process database will be used. The third and fifth parameters are reserved for future use.

// Login and get the User Token

string AIID = objAcorde.LoginUserNameProcess("myLogin", "myPassword", "", "myProcessDatabaseName", "");

Getting a list of Named Profiles:

All that is required to obtain a list of Named Profiles is a valid AIID. The web service method GetAvailableProcessProfiles will only return profiles that the user associated with the supplied AIID has security rights for.

The below “For Loop” extracts the name of each Profile returned by accessing information within the ProfileArray object’s Profiles array.

///////////////////////////////////////////////////////////////////////////////

// Get list of Named Profiles

///////////////////////////////////////////////////////////////////////////////

Acorde2WebRef.ProfileArray objProfileArray = objAcorde.GetAvailableProcessProfiles(AIID);

Response.Write("<br><B>List of Named Profiles</b><br>");

for(int ctrProfileArr=0; ctrProfileArr < objProfileArray.Profiles.Length; ctrProfileArr++)

{

Response.Write("<li><i>" + objProfileArray.Profiles[ctrProfileArr].ProfileName + "</i></li>");

}

Response.Write("<HR>");

Sample Output:

List of Named Profiles

All

Batch

FieldCompare

Invoice

PurchaseOrder

Getting a list of Packages by Named Profile:

In order to return a list of Packages by executing a Named Profile, use the GetPackageListByProfileName web service method. This method requires a valid AIID and the name of a valid Named Profile.

This method will return a PackageArray object which contains an array of Package objects. Each Package object contains information about each of the Packages returned from the Named Profile.

Information may be extracted from each Package object to be used as data for your application or for input values for other Process web service methods. Most of the Process web service methods will also accept the Package object and will extract the required information automatically.

///////////////////////////////////////////////////////////////////////////////

// Get list of Packages by Named Profile

///////////////////////////////////////////////////////////////////////////////

Acorde2WebRef.PackageArray objPackageArray = objAcorde.GetPackageListByProfileName(AIID, objProfileArray.Profiles[0].ProfileName);

Response.Write("<br><B>List of Packages By Named Profile</b><br>");

for(int ctrPackageArr=0; ctrPackageArr < objPackageArray.Packages.Length; ctrPackageArr++)

{

Response.Write("<li><b>" + objPackageArray.Packages[ctrPackageArr].PkgRecId + "</b></li>");

}

Response.Write("<HR>");

Sample Output:

List of Packages By Named Profile

17918
17927
17926
17925
17924
17933
17935
17929
17928
17942
17945
17944

Getting a list of Package Templates:

Use the GetPackageTemplates web service method to return a list of Package Templates visible for a particular user. All that is required to obtain the list is a valid AIID.

The below “For Loop” extracts the name of each Package Template returned by accessing information within the PackageTemplatesArray object’s Templates array.

///////////////////////////////////////////////////////////////////////////////

// Get a list of Templates

///////////////////////////////////////////////////////////////////////////////

Acorde2WebRef.PackageTemplatesArray objPTA = objAcorde.GetPackageTemplates(AIID);

Response.Write("<br><B>List of Package Templates</b><br>");

for(int ctrPTA=0; ctrPTA < objPTA.Templates.Length; ctrPTA++)

{

Response.Write(objPTA.Templates[ctrPTA].TemplateName + "<BR>");

}

Response.Write("<HR>");

Sample Output:

List of Package Templates
31UpgradeTempl
31UpgradeTemp2
AP Invoice
Batch Invoice
BatchPkg
Check Run Template
ExternalTempl
FormLocPkg
IndexWFAtmtTempl
InvPkg
Japanese BAT
PerfMonTempl
PurchaseOrder
Test DDE
WebTestPkg

Displaying generic Package information:

The Package object contains information that describes the contents of a Package. These values include PkgRecID, PackageType, Field values, etc.

The below code block shows how to display some of the Package object’s properties.

Refer to the Package object documentation for a full listing of available properties and associated methods.

///////////////////////////////////////////////////////////////////////////////

// Get Single Package Object

///////////////////////////////////////////////////////////////////////////////

Acorde2WebRef.PackageArray objPkgArray = objAcorde.GetPackageListByPkgRecId(AIID, 17918);

Acorde2WebRef.Package objPackage = objPkgArray.Packages[0];

Response.Write("<br><B>Package Object Info</b><br>");

Response.Write("PkgRecId: " + objPackage.PkgRecId.ToString() + "<br>");

Response.Write("Title: " + objPackage.Title.ToString() + "<br>");

Response.Write("Type: " + objPackage.PackageType.ToString() + "<br>");

Response.Write("Creator: " + objPackage.CreatorName.ToString() + "<br>");

Sample Output:

Package Object Info
PkgRecId: 17918
Title: PROCESS BROKER,0,Dec 1 2003,2003/12/01 10:09:37,Dec 8 2003,False,,,,0
Type: 3
Creator: PROCESS BROKER

Locking/Unlocking a Package:

Most Process web service methods that perform actions on individual Packages require locking the Package first. The below code block illustrates how to lock/unlock a package either using the PkgRecId, or locking a single package using a Package object.

///////////////////////////////////////////////////////////////////////////////

// Lock/Unlock by PkgRecId

///////////////////////////////////////////////////////////////////////////////

Acorde2WebRef.PackageResultsArray objPRA = objAcorde.LockPackageByPkgRecId(AIID, 17918);

Response.Write("<br><B>Lock/Unlock Calls</b><br>");

Response.Write("<p>Lock by PkgRecId: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

objPRA = objAcorde.UnlockPackageByPkgRecId(AIID, 17918);

Response.Write("Unlock by PkgRecId: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

///////////////////////////////////////////////////////////////////////////////

// Lock/Unlock by Package object

// And Add Journal Entry Comment

///////////////////////////////////////////////////////////////////////////////

objPRA = objAcorde.LockPackageSingle(AIID, objPackage);

Response.Write("Lock by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

objPRA = objAcorde.UnlockPackageSingle(AIID, objPackage);

Response.Write("Unlock by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

Sample Output:

Lock/Unlock Calls

Lock by PkgRecId: True
Unlock by PkgRecId: True
Lock by Package obj: True
Unlock by Package obj: True

Adding a Comment:

The below code block shows how to lock a Package, add a comment to the package, and then unlock the Package when completed.

This sample uses the LockPackageSingle, AddJournalEntrySingle, and UnlockPackageSingle methods which each accept a single Package object. These same actions can be performed on multiple Packages with a single web service call by using the LockPackageMultiple, AddJournalEntryMultiple, and UnlockPackageMultiple methods that accept a PackageArray object as an input parameter. The associated method will be performed on each Package object in the PackageArray object’s Packages array.

///////////////////////////////////////////////////////////////////////////////

// Lock/Unlock by Package object

// And Add Journal Entry Comment

///////////////////////////////////////////////////////////////////////////////

// Lock the Package

objPRA = objAcorde.LockPackageSingle(AIID, objPackage);

Response.Write("Lock by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

// AddJournalEntry

// By Package object

objPRA = objAcorde.AddJournalEntrySingle(AIID, objPackage, "New Comment");

Response.Write("AddJournalEntry by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

// Unlock the Package

objPRA = objAcorde.UnlockPackageSingle(AIID, objPackage);

Response.Write("Unlock by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

Getting and Setting Package Fields

IBPM Web Services can be used to both get and set the field values for a specific Package.

Methods exist to get and set Packages by PkgRecID, by Package object, or by PackageArray object (for batch operations).

In order to Set Package fields, you must first call a GetPackageFields method and obtain a PackageFieldsArray object which contains field information for a specific Package. Then, traverse the Fields array of the PackageFieldsArray object and modify the value for any of the desired fields you wish to update. Finally, pass in the modified PackageFieldsArray object into one of the SetPackageFields methods and the values will be updated.

Notice that the Package being updated had to be locked prior to performing the SetPackageFields operation. Also note that the Package was unlocked immediately following the update.

Refer to the documentation for more information about the Package, PackageArray, PackageFieldsArray, and PackageField objects and the GetPackageFieldsByPkgRecId, GetPackageFieldsSingle, GetPackageFieldsMultiple, SetPackageFieldsByPkgRecId, SetPackageFieldsSingle, and SetPackageFieldsMultiple methods.

///////////////////////////////////////////////////////////////////////////////

// Get Package Fields

///////////////////////////////////////////////////////////////////////////////

// Alternate approach using the PkgRecID for a single package

//Acorde2WebRef.PackageFieldsArray objPFA = objAcorde.GetPackageFieldsByPkgRecId(AIID, 17918);

// GetPackageFieldsMultiple accepts a PackageArray object and retrieves the fields

// for multiple packages in one web service call

//Acorde2WebRef.PackageFieldsArray objPFA = objAcorde.GetPackageFieldsMultiple(AIID, objPackageArray);

// This approach accepts a single Package object

Acorde2WebRef.PackageFieldsArray objPFA = objAcorde.GetPackageFieldsSingle(AIID, objPackage);

Response.Write("<br><B>GetPackageFields</b><br>");

for (int ctrPF=0; ctrPF < objPFA.Fields.Length; ctrPF++)

{

Acorde2WebRef.PackageField objPF = objPFA.Fields[ctrPF];

Response.Write("<br>" + objPF.FieldName + " = " + objPF.Value);

if(ctrPF == 0)

{

string theValue = objPFA.Fields[0].Value

objPFA.Fields[0].Value = theValue + " Updated Value";

}

}

///////////////////////////////////////////////////////////////////////////////

// Set Package Fields

///////////////////////////////////////////////////////////////////////////////

// Lock

objPRA = objAcorde.LockPackageSingle(AIID, objPackage);

Response.Write("<br>Lock by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

// SetPackageFields

Acorde2WebRef.PackageFieldsArray objPFA2 = objAcorde.SetPackageFields(AIID, objPackage, objPFA);

// Unlock

objPRA = objAcorde.UnlockPackageSingle(AIID, objPackage);

Response.Write("<br>Unlock by Package obj: " + objPRA.Results[0].Succeeded.ToString() + "<br>");

// Display latest changes

Response.Write("<br><B>Changes after SetPackageFields</b><br>");

objPFA = objAcorde.GetPackageFieldsSingle(AIID, objPackage);

for (int ctrPF=0; ctrPF < objPFA.Fields.Length; ctrPF++)

{

Acorde2WebRef.PackageField objPF = objPFA.Fields[ctrPF];

Response.Write("<br>" + objPF.FieldName + " = " + objPF.Value);

}

Sample Output:

GetPackageFields:
BatchId = Indira
Batch Type = AVE
Creator = PROCESS BROKER
Priority = 0
Date Created = 12/1/2003 10:09:36 AM
Date In Queue = 12/1/2003 10:09:37 AM
Due Date = 12/8/2003 10:09:36 AM
Due Date Fired = False
Threshold1 = 12:00:00 AM
Threshold2 = 12:00:00 AM
Threshold3 = 12:00:00 AM
Threshold Fired = 0
Lock by Package obj: True

Unlock by Package obj: True

Changes after SetPackageFields:
BatchId = Indira Updated Value
Batch Type = AVE
Creator = PROCESS BROKER
Priority = 0
Date Created = 12/1/2003 10:09:36 AM
Date In Queue = 12/1/2003 10:09:37 AM
Due Date = 12/8/2003 10:09:36 AM
Due Date Fired = False
Threshold1 = 12:00:00 AM
Threshold2 = 12:00:00 AM
Threshold3 = 12:00:00 AM
Threshold Fired = 0

Creating Direct Login URLs for AWPKVWR:

In many cases, IBPM Web Services will be used to retrieve IBPM information for a particular custom application. In some cases, however, it would be beneficial to allow end users to view IBPM objects without having to construct an entire interface from the ground up.

IBPM Web Services can be used to create Direct Login URLs (see Programmer’s Guide -> Using the Web Services -> Direct Login Methods for a more complete description).

Use data obtained by using IBPM Web Services to provide values within AWVWR, AWSER, and APKVWR Direct Login URLs. These URLs allow external users to view IBPM data within the Image Viewer, Saved Search, and Package Viewer tools.

This approach allows your application to acquire desired data via the web service calls, but gives end users the opportunity to view the associated IBPM objects through an existing IBPM tool. This is beneficial in that it allows you to restrict the IBPM objects that users may see, yet also provides a pre-existing interface to view them.

The following code block uses the GetAcordeWebServerURL web service method and a Package object (object) that was obtained from a previous web service method to create Direct Login URLs for the AWPKVWR tool (the Package Viewer tool).

After the output, the source of the generate HTML is displayed that shows the final construction of each URL.

This concept of combining data acquired from IBPM Web Services and Direct Login URLs may also be used for the AWVWR and AWSER tools (Image Viewer and Search tools).

// Direct login to PkgViewer via AWPKVWR

Response.Write("<br><B>Create Direct Login URLs for AWPKVWR</b><br>");

// For Creating Links

String strWebServerURL = "";

strWebServerURL = objAcorde.GetAcordeWebServerURL(AIID);

Response.Write("<br><B>IBPM Web Server URL</b><br>");

Response.Write(strWebServerURL + "<p>");

string strAWPKVWR;

strAWPKVWR = "<a href='" + strWebServerURL + "ToolName=AWPKVWR";

strAWPKVWR += "&PkgRecID=" + objPackage.PkgRecId.ToString();

strAWPKVWR += "&EOF=1' target='AWPKVWR_win'>";

strAWPKVWR += "Pkg</a>";

Response.Write("<br>" + strAWPKVWR);

strAWPKVWR = "<a href='" + strWebServerURL + "ToolName=AWPKVWR";

strAWPKVWR += "&PkgRecID=" + objPackage.PkgRecId.ToString();

strAWPKVWR += "&NoPkgInfo=1";

strAWPKVWR += "&EOF=1' target='AWPKVWR_win'>";

strAWPKVWR += "No PkgInfo </a>";

Response.Write("<br>" + strAWPKVWR);

strAWPKVWR = "<a href='" + strWebServerURL + "ToolName=AWPKVWR";

strAWPKVWR += "&PkgRecID=" + objPackage.PkgRecId.ToString();

strAWPKVWR += "&NoPkgToolbar=1";

strAWPKVWR += "&EOF=1' target='AWPKVWR_win'>";

strAWPKVWR += "No Toolbar </a>";

Response.Write("<br>" + strAWPKVWR);

strAWPKVWR = "<a href='" + strWebServerURL + "ToolName=AWPKVWR";

strAWPKVWR += "&PkgRecID=" + objPackage.PkgRecId.ToString();

strAWPKVWR += "&HideBanner=0";

strAWPKVWR += "&EOF=1' target='AWPKVWR_win'>";

strAWPKVWR += "Don't Hide Banner </a>";

Response.Write("<br>" + strAWPKVWR);

strAWPKVWR = "<a href='" + strWebServerURL + "ToolName=AWPKVWR";

strAWPKVWR += "&PkgRecID=" + objPackage.PkgRecId.ToString();

strAWPKVWR += "&CSSSet=AcordeBrown";

strAWPKVWR += "&EOF=1' target='AWPKVWR_win'>";

strAWPKVWR += "CSS Brown </a>";

Response.Write("<br>" + strAWPKVWR);

Create Direct Login URLs for AWPKVWR

IBPM Web Server URL
http://myWebServer/IBPMweb/default.asp?

Pkg
No PkgInfo
No Toolbar
Don't Hide Banner
CSS Brown

View Source:

<br><B>Create Direct Login URLs for AWPKVWR</b>br><br>

<B>IBPM Web Server URL</b><br>

http://myWebServer/IBPMweb/default.asp?

<p><br>

<a href='http://myWebServer/IBPMweb/default.asp?ToolName=AWPKVWR&PkgRecID=17918&EOF=1' target='AWPKVWR_win'>Pkg</a><br>

<a href='http://myWebServer/IBPMweb/default.asp?ToolName=AWPKVWR&PkgRecID=17918&NoPkgInfo=1&EOF=1' target='AWPKVWR_win'>No PkgInfo </a><br>

<a href='http://myWebServer/IBPMweb/default.asp?ToolName=AWPKVWR&PkgRecID=17918&NoPkgToolbar=1&EOF=1' target='AWPKVWR_win'>No Toolbar </a><br>

<a href='http://myWebServer/IBPMweb/default.asp?ToolName=AWPKVWR&PkgRecID=17918&HideBanner=0&EOF=1' target='AWPKVWR_win'>Don't Hide Banner </a><br>

<a href='http://myWebServer/IBPMweb/default.asp?ToolName=AWPKVWR&PkgRecID=17918&CSSSet=AcordeBrown&EOF=1' target='AWPKVWR_win'>CSS Brown </a><HR>


Customizing IBPM Web Clients

Customizing the IBPM Web Client

This document focuses on new technologies and features available in the IBPM Web Client and IBPM Web Services that can facilitate two goals:

  • Integration of external web applications or Web Services into the IBPM Web Client
  • Exposure of IBPM functionality through Portals or other Web Service consumers.

Many infrastructure features have been added to the IBPM Web Client to facilitate rapid development and integration of new IBPM Web Client tools. These features allow a developer to define Web Client Tools and their integration points through the extensive use of XML Metadata. The IBPM Web Client also provides several code-based mechanisms that can be used to integrate and expose new features. Use of these features could allow the IBPM Web Client to be used as a Portal for other Web Applications or Web Services.

Several integration features have also been developed to allow an integrator to expose IBPM functionality through Portals or other Web Services consumers. IBPM Web Services have been developed to allow integrations using SOAP and WSDL. The IBPM Web Client can also function as a URL based SDK that can be embedded in Portal applications.

Many of these features have been documented and some have not. This White Paper summarizes the features and technology base used in their implementation.

XML Metadata Based Integration Features

The need for fast integration and customization of the IBPM Web Client has pushed heavy use of XML Metadata to define not only the look and feel of the IBPM Web Client but the actual functionality and User Interface Flow (UIF) of the IBPM Web Client. XML definition files control the following areas of the IBPM Web Client:

  • User Interface Phrase/Translations
  • Menu structure and inter-tool navigation
  • Tool Definitions (Location and Entry Points)
  • Page Definitions (Layout of tools)
  • Portal Entry Point Definitions
  • Search Results Icon Customization
  • CSS Set properties
  • Online Help Content

Phrases

All phrases used in the IBPM Web Client are defined in centrally located XML files. This allows quick turnaround time for the Translation of the IBPM Web Client to new languages. The separation of Phrases and functional code allows a translator to be much less technical.It separates them from interactions with the ASP code and allows them to work with XML files. XML files are much easier to check and the translator can only introduce formatting errors rather than coding bugs. The current IBPM Web client ships with 9 separate translation sets completely translated. These XML files also define the format and parsing of Dates and Floats allowing different languages to access the same IBPM Web Client Server and work in their proper date/float format.

The following XML (Figure 1) shows a complete Phrase Definition. This XML is an English (en-us) version of the phrases used in the IBPM Web Client. This particular example is from the Context Copy Tool.Notice the namespace of the Phrases element is ATCopyTool:

<?xml version="1.0" ?>

<AcordeXMLTranslation version="1.0" copyright="Copyright 1998-2004 Stellent Inc. All rights reserved.">

<Name>IBPM Standard Translation Pages 2.2</Name>

<Company>Stellent Inc.</Company>

<ID>en-us</ID>

<Phrases namespace="ATCopyTool">

<Phrase id="ErrorCopyFailed"><![CDATA[The Copy command failed.]]></Phrase>

<Phrase id="ErrorNoPagesSelected"><![CDATA[Copy failed. No pages were selected.]]></Phrase>

<Phrase id="ErrorTypeNotSupported"><![CDATA[Copy failed. The Copy command does not support the selected document type.]]></Phrase>

<Phrase id=" TB_Copy"><![CDATA[Copy]]></Phrase>

</Phrases>

</AcordeXMLTranslation>

Figure 1: A sample translation XML file used in the IBPM Web Client.

The XML Translation files can be found in the following directory under the web site:

IBPMWeb\OTInfrastructure\ AcordeXMLTranslations

Each of the supported languages will have a sub-directory located there. Additionally, version IBPM Web 3.1.1 and later will have namespace sub-directories below the language sub-directories. The namespace sub-directories improved initial load times for the translation phrases.

New phrases can be added to facilitate use in customized menus (described in the next section). Simply create a new XML Translation File and place it in the appropriate IBPM XML Translations (“AcordeXMLTranslations”) sub-directory.

Menus

Menus are defined through the use of XML files. The available menu commands define how the User Interface flows from one tool to the next (UIF). The IBPM Web Client menus can be modified based on the needs of a particular integration. These modifications can change the UIF of the IBPM Web Application.

A full IBPM Web Client menu definition is encapsulated into the concept of a Menu Set. A developer can define a new Menu Set by defining one or more replacement menus and placing them into a new menu set directory. Use of a Menu Set is defined on the URL through the use of a Menu Set Parameter or the use of a URL Tool.

Customization of the menus can take two forms. The first of these is to remove menu items that are not going to be used at a customer site. This can facilitate more efficient interaction with the IBPM Web Client by helping a user to avoid selecting wrong menu options or having to filter through several unused options every time an action is taken. The URL Tools use this mechanism to limit the available menu commands to the operations needed for the URL Tool. In a similar vein you may want to reorganize the menu items at your site by placing more commonly used menu items at the front of the tool menu.

The second form of menu customization is the use of Integration Point Events to integrate new or custom tools. Currently only the results listing tools (Search Results, Inbox, Worklist) provide Integration Point Events (IPE) that can be fired by menus. All three of these tools provide Navigation IPEs and only Search Results provide Execution IPEs. A Navigation IPE is used to launch a target tool from the hosting tool. An Execution IPE will call a method on an IBPM Tool Interface (ATI) without navigating away from the tool.

Integration Point Events (IPEs) publish a listing of the selected items in the list and any related metadata. When using an IPE in a menu a developer specifies the target tool or ATI and the host IPE that should be fired. A newly integrated tool can be defined and specified as a target tool for a Navigation IPE or an ATI can be created for an Execution IPE.

When an Execution IPE is fired the Host tool publishes the data and invokes the specified method on the specified ATI. The Host tool is reloaded and no user interface is shown to the user.

When a Navigation IPE is fired the Host tool publishes the data and invokes the target tool using the specified entry point. As the IBPM Web Client loads a tool into the GUI it invokes a Query String Generator based on the tool name and the entry point into the tool. This allows the new tool to move data from the published location into its internal data.

The concept of IPEs provides a generic loose coupling between tools within the IBPM Web Client. Data is published through the use of IBPM Tool Interface (ATI) objects. These are objects that are associated with the tool and provide calls to obtain published data from a tool. Currently published data is available from ATIs for the Search Results, Inbox and Worklist Tools.

All menu phrases reference the XML language files allowing a menu developer to work with abstracted phrase and not be concerned with translation issues.

The following (Figure 2) is a sample of a simple Toolbar XML file. This XML defines the IBPM Copy Tool menu. Notice that the CaptionID element of the “cmdCopy” command specifies a namespace and an ID.This references the translation namespace and phrase in translation XML in the previous section.

<?xml version="1.0" ?>

<AcordeXMLToolbar version="1.0" copyright="Copyright 1998-2001 Stellent Inc. All rights reserved.">

<ID>tbCopy</ID>

<Items>

<Command>

<ID>cmdCopy</ID>

<CaptionID namespace="ATCopyTool">TB_Copy</CaptionID>

</Command>

</Items>

</AcordeXMLToolbar>

Figure 2: A sample toolbar XML file used in the IBPM Web Client. This version is translatable.

The next sample shown (Figure 3) below replaces the translation reference with a literal caption. This is a simpler way to create the toolbar but does not allow for translation in the future.

<?xml version="1.0" ?>

<AcordeXMLToolbar version="1.0" copyright="Copyright 1998-2001 Stellent Inc. All rights reserved.">

<ID>tbCopy</ID>

<Items>

<Command>

<ID>cmdCopy</ID>

<Caption>Copy</Caption>

</Command>

</Items>

</AcordeXMLToolbar>

Figure 3: A sample toolbar XML file used in the IBPM Web Client.This version is NOT translatable.

The next sample (Figure 4) is a cut down version of the Search Results XML toolbar file. This is presented here to demonstrate the use of a Navigation IPE. This version of the Query Results menu only has the View menu item.

<?xml version="1.0" ?>

<AcordeXMLToolbar version="1.0" copyright="Copyright 1998-2004 Stellent Inc. All rights reserved.">

<ID>tbQueryResultsTool</ID>

<Items>

<Command>

<NavigationCommand>

<TargetTool>

::ImageViewerTool::FromQueryResults

</TargetTool>

<IntegrationPointEvent>

::QueryResultsTool::LockInSelections

</IntegrationPointEvent>

<NewWindowATO>AcordeATOQRNewWindow</NewWindowATO>

</NavigationCommand>

<Group>MultiSelect</Group>

<CaptionID namespace="OTQueryResultsTool">TB_View</CaptionID>

</Command>

</Items>

</AcordeXMLToolbar>

Figure 4: A sample toolbar XML file used in the IBPM Web Client.This version is translatable.

Notice that the View command in Figure 4 has no Command ID as seen in the previous two examples. Rather, it has a Navigation Command element. The Navigation Command element specifies the tool to load (in this case the Image Viewer Tool) and which entry point to use for that tool (in this case the entry point used is the From Query Results entry point). Additionally, the Navigation Command specifies an Integration Point Event (IPE). This specifies that before loading the new tool (the Image Viewer Tool) the Query Results Tool “LockInSelections” IPE should be fired. This will allow the Query Result an opportunity to lock in the selections the user has made and “publish” that information.

The Navigation Command architecture allows the existing tools, in this case the Query Results Tool, to load tools it has no knowledge of. Additionally IPEs allow the existing tool to publish information available to the target tool even if the existing tool does not understand or know about the target tool.

Navigation Commands can also be used in tools that do not provide IPEs. By leaving out the “IntegrationPointEvent“ element you can simply load a tool without transferring information to the target tool.

You can create new menu sets by creating a new sub directory in the following directory:

IBPMWeb\OTInfrastructure\AcordeXMLToolbars

The name of the sub-directory is the name of the menu set. You can specify a menu set on the URL(see documentation).

Tools

IBPM Web Client tools are defined using XML files. To define the location and entry points of a new tool you need to add an XML file to the IBPM XML Tool Definitions directory. Tool names and Entry Points to those tools are used in the menu XML files when an IPE menu item is specified. Tool location definitions are in the context of the IBPM Web Client. In order to drive an external web site you will need to use Portal Entry Points or wrap the external site with an IBPM Web Tool.

Tool definitions include the relative URL to the tool implementation file and a listing of entry points to the tool. Data is transferred to the tool through the use of a Query String Generator. Each entry point specifies a Query String Generator (not specifying one will use the default for the tool). When the tool is being launched the Query String Generator is instantiated and called. This gives the tool a chance to retrieve any relevant data from the host tool and place it on the on the URL or transfer it to the target tool through the IBPM Tool Interfaces.

The following example (Figure 5) defines a tool named “PrintLocalTool”. This tool has two entry points (“ShowTool” and “FromQueryResults”).

<?xml version="1.0" ?>

<AcordeXMLToolset version="1.0" copyright="Copyright 1998-2004 Stellent Inc. All rights reserved.">

<Company>Stellent Inc.</Company>

<Items>

<AcordeWebTool>

<Name>PrintLocalTool</Name>

<NewWindowClass>AcordePrintQueueWindow</NewWindowClass>

<URL>..\ATPrintLocalTool\ImplPrintLocalTool.asp</URL>

<DefaultEntryPoint>ShowTool</DefaultEntryPoint>

<EntryPoints>

<EntryPoint>

<Name>

ShowTool

</Name>

<QueryStringGenerator>

NewTool

</QueryStringGenerator>

</EntryPoint>

<EntryPoint>

<Name>

FromQueryResults

</Name>

<QueryStringGenerator>

QueryResultToPrintLocal

</QueryStringGenerator>

</EntryPoint>

</EntryPoints>

</AcordeWebTool>

</Items>

</AcordeXMLToolset>

Figure 5: A sample toolset definition XML file used in the IBPM Web Client.

If I wanted to specify this tool as a target tool in a Navigation Command as discussed in the previous section I would use the string “::PrintLocalTool::ShowTool” or “::PrintLocalTool:: FromQueryResults” depending on which entry point I wanted to invoke. Notice the “QueryStringGenerator“ element in each of the entry point elements. This tells the infrastructure which “ASP” query string object to use when invoking the tool entry point. This is the link between the IPE in the host tool and this tools entry point.The “QueryStringGenerator“ can place the published data right on the URL or it can move it to a location accessible by the “PrintLocalTool”.

Tool Definitions for the IBPM Web Client can be found in the directory:

IBPMWeb\OTInfrastructure\AcordeXMLToolDefinitions

If you create a custom tool you can create a new Tool Definition File and place it in this directory to define the tool location and entry points to the IBPM Web Client Infrastructure.

Notice the location of the tool defined in the “URL” element is a relative URL within the IBPM Web Application directory structure. Tools must be defined and run within the IBPM Web Client directory structure. To link to an external application you would need to use a “Portal Entry Point” as described in that section of this document.

A tool needs to be placed on an IBPM Page in order to be accessible.

Pages

IBPM Web Client pages are defined using XML files. Until a tool is placed on an IBPM Page it is not accessible through the IBPM Web Client. As with the tools, to define a new page you need to add an XML file, this time to the IBPM XML Page Definitions directory. Multiple tools can be placed on a single page. One example of this is the Process Inbox Tool and the Process Worklist Tool. Each is a separate tool but both appear together when viewed in the IBPM Web Client.

Most of the IBPM Web Client tools assume that they are being displayed on their own and do not try to interact with any other tools directly. Exceptions include the Process Inbox and Worklist that use IBPM Client Events to notify each other of changes in package status. You can see this if you lock a package in the Worklist. The Inbox will update with a new list of packages. Another notable example is the Work Center tool. Actions taken on the nodes will often generate IBPM Client Events that will cause loaded tools to take some action. A good example of the Work Center interacting with other tools is selecting a Process Profile in the Work Center. If the Worklist tool is loaded it will run the Profile rather than reloading the Inbox/Worklist page. The Work Center interactions with other tools are defined by the IBPM Work Center Nodes.

The following XML example (Figure 6) demonstrates how to create the Page Definition for the tool defined in Figure 5.Notice that there is only one tool in the Layout Description for this page so the PrintLocalTool will load by itself.

<?xml version="1.0" ?>

<AcordeXMLPageset version="1.0" copyright="Copyright 1998-2003 Stellent Inc. All rights reserved.">

<Name>PrintLocalTool</Name>

<Company>Stellent Inc.</Company>

<Items>

<AcordeWebClientPage>

<Name>PrintLocalToolToolPage</Name>

<LayoutDescription>

<Panel>

<AcordeWebToolName>

PrintLocalTool

</AcordeWebToolName>

<width></width>

<height></height>

<attributes>noresize</attributes>

</Panel>

</LayoutDescription>

</AcordeWebClientPage>

</Items>

</AcordeXMLPageset>

Figure 6: A sample pageset definition XML file used in the IBPM Web Client.

The XML example shown in Figure 7 demonstrates how two tools can be placed on the same page. In this case the two tools are the Inbox Tool and the Worklist Tool.

<?xml version="1.0" ?>

<AcordeXMLPageset version="1.0" copyright="Copyright 1998-2003 Stellent Inc. All rights reserved.">

<Name>PrintLocalTool</Name>

<Company>Stellent Inc.</Company>

<Items>

<AcordeWebClientPage>

<Name>ViewPackagesToolPage</Name>

<LayoutDescription>

<Panel>

<AcordeWebToolName>

InboxTool

</AcordeWebToolName>

<width></width>

<height>50%</height>

<attributes></attributes>

</Panel>

<Panel>

<AcordeWebToolName>

WorklistTool

</AcordeWebToolName>

<width></width>

<height>*</height>

<attributes></attributes>

</Panel>

</LayoutDescription>

</AcordeWebClientPage>

</Items>

</AcordeXMLPageset>

Figure 7: A sample pageset definition XML file used in the IBPM Web Client.

Any tool can be placed on a page with any other tools. Demo systems have been created putting the package viewer and the image viewer tools on the same page. However, unless the tools have been designed or customized to interact with each other directory awkward loading and reloading of the tools may occur.

Portal Entry Points

The IBPM Web Client can facilitate the launch of an external Web Site through the use of IPEs in the Search Results, Inbox and Worklist. There are two ways to do this. The first is to create a custom tool that wraps the external web site and define that tool in the IBPM XML Tool Definitions. That has been discussed above. The second way to do this is through the use of Portal Entry Points which are a “Beta” feature of the IBPM Web Client. Portal Entry Points are defined using XML files in the IBPM Portal Definitions directory. These files provide a name, a full external URL and a Query String Generator. The Portal Entry Point poses as a tool in the IBPM Web Client infrastructure that can be used in the Menu Definitions of IPEs. Prior to launching the external URL the Query String generator is asked to construct a URL. At that point relevant information can be obtained from the IBPM Tool Interface objects and placed on the URL.

Figure 8 demonstrates a Portal Entry Point that has been defined to search Yahoo. One thing to Note is that this worked at the time of this article’s writing; Yahoo may have changed their URL API. This is included only as an illustration of the concepts of Portal Entry Point definition.

<?xml version="1.0" ?>

<AcordeXMLPortalset version="1.0" copyright="Copyright 1998-2002 Stellent Inc. All rights reserved.">

<Company>Stellent Inc.</Company>

<Name>IBPM Process Client Tools 2.2</Name>

<Items>

<PortalEntryPoint>

<Name>ShowYahoo</Name>

<URL>http://search.yahoo.com/bin/search</URL>

<QueryStringGenerator>PEP_ShowYahoo</QueryStringGenerator>

</PortalEntryPoint>

</Items>

</AcordeXMLPortalset>

Figure 8: A sample portal entry point definition XML.

Notice that the target URL is an absolute URL to the site we want to integrate. There is a “QueryStringGenerator” specified for the Portal Entry Point. This is an ASP Javascript object that understands how to construct the Query String for the site. Figure 9 illustrates how this Query String Generator might be written if the Portal Entry Point is coming from the IBPM Web Client Search Results.

function _PEP_ShowYahoo()

{

// GenerateQueryString: Called by the IBPM Infrastructure

// to have this object generate the Query String for the

// Portal Entry Point.

function _GenerateQueryString(strEntryPoint)

{

// Get the published Data from the Query Results tool

var objATIQRT = AcordeToolInterfaceQueryResultsTool();

var strDataKey = 'LockInSelections.RecordSet';

var objRS = objATIQRT.GetPublishedIntegrationEntryPointData(strDataKey);

// Begin building the Query String

var strQueryString = 'p=';

// Add only the first non-system field to the search

// for this sample. A real version would extract particular

// values of interest.

strQueryString+=escape(AcordeInfrastructure().Trim(objRS.Fields.Item(7).Value));

return strQueryString;

}

this.GenerateQueryString = _GenerateQueryString;

// IsSessionStatic: Called by the IBPM Infrastructure

// to determine if it needs to call this object each time

// the Portal Entry Point is invoked.

function _IsSessionStatic(strEntryPoint)

{

// We need to return false because we want the Infrastructure to run us every

// time the tool is shown because we need to transfer the new data to the

// Add Remove Pages Tool location

return false;

}

this.IsSessionStatic = _IsSessionStatic;

}

Figure 9: A sample Query String Generator for a Portal Entry Point.

Finally, we can look at the mechanism to invoke the Portal Entry Point. It simply poses as a tool in the IBPM Web Client Infrastructure so the Navigation Command is used in the Menu XML to invoke the Portal Entry Point. Figure 10 illustrates the Menu XML that could be used to invoke the Portal Entry Point from the IBPM Web Client Search Results:

<?xml version="1.0" ?>

<AcordeXMLToolbar version="1.0" copyright="Copyright 1998-2004 Stellent Inc. All rights reserved.">

<ID>tbQueryResultsTool</ID>

<Items>

<Command>

<NavigationCommand>

<TargetTool>

::AcordePortalShowYahoo::ShowYahoo

</TargetTool>

<IntegrationPointEvent>

::QueryResultsTool::LockInSelections

</IntegrationPointEvent>

<NewWindowATO>AcordeATOQRNewWindow</NewWindowATO>

</NavigationCommand>

<Group>SingleSelect</Group>

<Caption>Search Yahoo</Caption>

</Command>

</Items>

</AcordeXMLToolbar>

Figure 10: A sample Menu Item that defines a Navigation Command to a Portal Entry Point.

Notice that the name of the tool is prefixed with “AcordePortal” and the pseudo-tool only has one entry point that is the name of the Portal Entry Point so the navigation command target tool string is”::AcordePortalShowYahoo::ShowYahoo”.

The Portal Entry Point definition files are found in:

IBPMWeb\OTInfrastructure\AcordeXMLPortalDefinitions

The Query String Generators are located in:

IBPMWeb\OTInfrastructure\AcordeQueryStringGenerators

You can add your own custom XML and ASP files to these directories to support you Portal Entry Point integrations.

Icons

The IBPM Search Results Tool and Work Center Search Results Node uses an XML file found in the IBPM Custom Icons directory to figure out which Icon to present to the user. This Object to Icon mapping is defined using the object MIME Type. If your site is filing Custom Objects that have a different MIME Type than the stock IBPM Web Client provides you may want to add a more Icons using this mechanism.

To add your own custom Icons modify the file:

IBPMWeb\OTInfrastructure\AcordeCustomIcons\AcordeCustomIcons.xml

Add your custom icons and place the images in that directory. Figure 11 is a cut down version of the XML file that is distributed with the IBPM Web Client.

<?xml version="1.0" ?>

<AcordeXMLCustomIcons version="1.0" copyright="Copyright 1998-2002 Stellent Inc. All rights reserved.">

<Company>Stellent Inc.</Company>

<Name>IBPM Custom Icons</Name>

<Comment>This is the standard set of Custom Icons</Comment>

<Comment>Do not modify this Tool Set.</Comment>

<Comment>OTInfrastructure\AcordeCustomIcons Directory.</Comment>

<Items>

<CustomIcon>

<Name>image/tiff</Name>

<LargeIcon>DocType_Image.gif</LargeIcon>

<SmallIcon>Bullet_DocType_Image_2.gif</SmallIcon>

</CustomIcon>

<CustomIcon>

<Name>text/x-emedia.cold</Name>

<LargeIcon>DocType_Cold.gif</LargeIcon>

<SmallIcon>Bullet_DocType_Cold_2.gif</SmallIcon>

</CustomIcon>

<CustomIcon>

<Name>application/x-emedia.universal</Name>

<LargeIcon>DocType_Universal.gif</LargeIcon>

<SmallIcon>Bullet_DocType_UNIV_2.gif</SmallIcon>

</CustomIcon>

</Items>

</AcordeXMLCustomIcons>

Figure 11: A Custom Icons XML.

CSS Set Properties

The IBPM Web Client allows the definition of new CSS Set. These CSS Sets can change the colors and appearance of the IBPM Web Client. These CSS Sets can also include some additional XML files that can be used to define the toolbar logos used in URL Toolkit mode. Other information that can be defined include the use of side titles in tools, the use of the Work Center in a CSS Set or even which of the image sets to use for IBPM logos.

This is a useful feature if you are exposing the IBPM URL SDK through a Portal and wish to match the look and feel of the existing Portal. By matching the look and feel of the IBPM URL SDK to the Portal look and feel you can provide the user with a tighter feeling of integration.

Online Help Content

The online help has been moved into XML phrase files. This can facilitate the future translation of the online help. That is not planned for any release at this time. In addition to making the online help translatable new topics can be easily inserted into the IBPM Web Online help. These topics are formatted at run-time allowing customized help topics to retain the look and feel of the main web client. This provides a nice, seamless integration of any help customization you may want to add to the IBPM Web Client.

Code Based Integration Features

This section describes several IBPM Web Client infrastructure features that facilitate the rapid development of integration points and insertion of new features. These features have been added in the past year to improve turnaround time for new tools and new URL SDK calls. The following items are code based integration infrastructure features of interest.

  • IBPM Tool Interface Objects
  • Availability Test Objects
  • IBPM Query String Generator Objects
  • IBPM Work Center Node Objects

Tool Interfaces

IBPM Tool Interfaces (ATI) are Java Script objects that define interfaces for the tools as well as URL interfaces into the IBPM Web Client. Not all of the tools have an IBPM Tool Interface defined. Some of the tool interfaces do not correspond directly to a tool. These objects are used in the following areas:

  • To define URL SDK Objects
  • To Obtain published tool IPE data
  • Application Link URL SDK Redirection
  • Exposure of Execution IPEs

The tool interface object files are found in the General IBPM Objects directory. The prefix on these files is “AcordeToolInterface*.asp”.

IBPM URL SDK Tools are implemented using IBPM Tool Interfaces. Each URL SDK Tool (AWVWR, AWPKVWR, AWSER) has an IBPM Tool Interface. Prior to passing through the login logic this object is created and provided an opportunity to parse the incoming URL. The tool name is obtained from the URL parameter (ToolName) and pre-pended with “AcordeToolInterface” to determine which object to instantiate. To create a new URL SDK Tool you can implement a new IBPM Tool Interface and specify it on the URL. The IBPM Tool Interface object is provided a “Post Login” opportunity to direct the Web Client to a tool defined in the IBPM XML Tool Definitions.

IBPM Tool Interfaces are also used to publish data from one tool to another. Examples of this can be found in the Query String Generators used when launching tools from the IBPM Web Client Search Results tool.

A final use of the IBPM Tool Interface is to redirect the results of an Application Link URL call. The output dictionary from the Application Link URL Tool execute call is examined for a named value “AcordeWebToolInterface”. If that is found in the output dictionary that Tool Interface will be created and passed the output dictionary so it can take a post login action and determine the tool to load.

The IBPM Web Client Search Results Tool provides an Execution IPE. This is not currently being used by any of the integrated tools or as part of the IBPM Web Client. If an integrator wanted to provide a mechanism to call a Web Service or some COM object on the server without navigating away from the Search Results tool an ATI could be created and specified in the Menu as an Execution IPE. When the IPE is fired the Search Results Tool publishes its IPE Data and creates the specified ATI calling into the named method (entry point) and reloads the Search Results UI.

Test Objects

Availability Test Objects or IBPM Test Objects (ATOs) are used throughout the IBPM Web Application to determine availability of features to a user. An ATO is a Java Script object. The ATOs for the IBPM Web Client can be found in the Availability Test Objects directory. One area of interest to an integrator is the use of ATOs in the construction of Menus. If you want the menu item to conditionally appear in the menu as it is being generated you can create an new ATO that tests your conditions and specify that ATO in the Menu XML file. At the time the menu HTML is rendered the ATO object will be created and tested to determine the availability of the menu item.

Query String Generators

IBPM Query String Generators are used as each tool is loaded. Query String Generators are Java Script objects that provide a loose coupling between IBPM Web Client tools or the IBPM Web Client and a Portal Entry Point. When you create a new tool and use an IPE to integrate that tool into the IBPM Web Client you will probably need to create a new Query String Generator. The infrastructure invokes a Query String Generator to have it build the URL Query String for the tool. This gives your tool an opportunity to move data from the host tool’s published data (from its ATI) to your tool’s input data location. You may need to put that data on the URL or place it in session state somewhere. At this point you could even perform a Web Services call to place the data in some location accessible by your tool.

Work Center Nodes

The recently released IBPM Work Center was developed to provide a user with a more efficient mechanism for performing common tasks. Java Script objects located in the IBPM Work Center Nodes directory define Work Center Nodes. To create a new Work Center Node you can implement a Java Script object and drop the file in this directory. On the web server restart the new node will be picked up and interrogated and displayed to the user.

The implementation of the IBPM Work Center Node can generate its content through the use of COM object or external Web Services. The Work Center Node can also issue commands to the infrastructure to cause tool navigations to occur allowing the load of custom tools.

Web Services

The IBPM Web Services provide several BPM and Context functions as Web Services. These Web Services are implemented through SOAP and exposed through the use of WSDL. The IBPM Web Services allow you to:

  • Perform an IBPM Login
  • Search Imaging using Saved Searches
  • Export Imaging objects
  • Run BPM Profiles
  • Lock and Unlock IBPM Packages
  • Add IBPM Package comments
  • Obtain and change IBPM Package Fields
  • Register URL Description for use with the IBPM URL SDK

All of these features have been documented in detail in each release they have been available. Common consumers of Web Services include Portals or any web aware applications. Web Services can be accessed from most common platforms and have become an industry wide mechanism for integration strategies. The core Web Services technologies (SOAP, WSDL and UDDI) are well on their way to becoming industry standards.

The following is a summary of all the available Web Services calls available as of Acorde 3.1 GA:

  • User:
    • LoginUserName– Logs in user
    • LoginUserNameProcess – Logs in a user and connects them to a Process
    • LoginAlias – Logs a user in using a registered Alias
    • LoginAliasProcess – Logs a user in using a registered Alias and connects them to a Process
    • RegisterAlias – Registers an Alias
    • Logout – Logs a user out
  • ProcessPofiles:
    • GetAvailable – Gets the available Profiles for the logged in user
    • GetProfilePrompts - Gets the prompts for a Prompted Profile
  • ProcessPackages:
    • GetListByProfile- Runs a Profile and returns the resulting list of Packages

    • GetDecisionsByPkgRecID- Gets the completion decisions for a Package
    • LockPackageByPkgRecID- Lock a Package to the logged in user
    • UnlockPackageByPkgRecID – Unlocks a Package
    • CompletePackageByPkgRecID – Completes a Package
    • GetPackageFields – Gets the Package Field values
    • SetPackageFields – Sets the Package Field values
    • AddJournalEntryByPkgRecID – Adds a comment to a Package
    • GetListByPromptedProfile - Runs a Prompted Profile and returns the resulting list of packages
  • ContextSearch:
    • BeginSavedSearch - Starts a Saved Search Running
    • ContinueSearch - Gets the next page of results from a running Search
    • StopSearch - Stops a running Search
    • GetAvailableSavedSearches - Gets Saved Searches available to a user
    • GetSavedSearchProperties - Gets the properties of a Saved Search
    • GetSavedSearchPrompts - Gets the Prompts for a Saved Search
  • ContextExport:
    • ExportEx - Exports an IBPM object allowing control over Scale, DPI, Type and other export props.
    • Export - A simple export that simply takes the big six plus FTSFilters
    • PurgeCache - Cleans up the export directory
    • ExportFromSearchResults - Exports selected items in a search results set obtained through SOAP ContextSearch
    • ExportFromSearchResultsEx - Same as ExportFromSearchResults but allows control over Scale, DPI, Type and other export props.
  • WebClientUtilities (URLTools):
    • RegisterURLDescription- Registers a URL description and returns a ticket to be placed on the URL.
    • RemoveTicket – Removes a URL ticket and invalidates it.
URL Tools

The IBPM Web Client provides several URL based tools. These tools can be used to expose portions IBPM functionality to users of Portals or any other “Web Capable” application. The following URL Tools are available as of 3.1 GA.

  • AWSER – Search IBPM using Saved Searches or Application Link in combination with Saved Searches.
  • AWVWR – View an Imaging Object directly
  • AWPKVWR – View an IBPM Package directly.

These URL Tools are well documented in the Product documentation. The following sections provide a high level summary of their use.

AWSER – IBPM Web Search

The IBPM Web Search (AWSER) URL Tool provides access to searching and viewing Imaging objects on the web. Based on the URL parameters provided the Search will run using Application Link or a Saved Search directly. Single hit searches will launch the Viewer Tool rather than displaying the Search Results Tool.

The main use of this URL tool would be to Search or Image enable a web application or portal.

AWVWR – IBPM Web Viewer

The IBPM Web Viewer (AWVWR) URL Tool provides direct access to the Viewer Tool. Rather than trying to run a single hit search to get an image to be displayed you can use the AWVWR URL tool to launch the viewer directly. This URL tool requires that you provide the big-six IBPM System Fields on the URL. This means that you needed to have run a search prior to constructing the URL. Searches can be run through the COM SDK or the SOAP SDK to obtain those values.

As with the AWSER URL Tool, the main use of this URL tool would be to Image enable a web application or portal.

AWPKVWR – IBPM Web Package Viewer

The IBPM Web Package Viewer (AWPKVWR) URL Tool provides direct access to the Package Viewer Tool. You must provide the Package Record ID (PkgRecID) on the URL. That requires that you to have run a Package Search prior to constructing the URL

There are several features in the AWPKVWR that allow you to restrict what the user sees on the screen when the Package Viewer loads. You can hide the Package Information tabs, the title (pre Acorde 3.1 had side titles) and the Menu. This can provide the user with a pure custom interface into the package generated by a Custom ASP form.

The AWPKVWR URL Tool also provides two sub-tools: the Attachment Viewer and the Journal Viewer. The Attachment Viewer sub-tool allows the user to view Imaging attachments directly rather than going through the Package Viewer first. The Journal Viewer allows the user to view the history and make comments without having to load the full Package Viewer.


Search And Retrieval Web SDK Overview

Search And Retrieval Web SDK

The IBPM Search and Retrieval Web SDK component is provided to facilitate image enabling Web Applications.

Search and Retrieval on the web focuses on providing access to the IBPM system to find and view objects in the IBPM System through the use of a browser user interface. This access is provided through a URL interface into the IBPM Web SDK Search and Retrieval component. This URL interface allows a user of the IBPM Web SDK to run searches and view documents.

The IBPM Web SDK Search and Retrieval component is implemented via the standard IBPM Web Client. To begin using the IBPM Web SDK Search and Retrieval component first ensure that the IBPM Services are installed and running. Next, install the IBPM Web Client. Because the IBPM Web SDK Search and Retrieval component is provided through the IBPM Web Client make sure a version of the client is installed that provides this functionality. The first version of the IBPM Web Client that provided Web SDK components is IBPM 2.3.1.

This SDK tool is referred to as AWSER (IBPM Web SDK – Search). The AWSER tool provides access to Saved Searches by mapping Search String parameters on the URL to the fields in a Saved Search. This is the simplest method of accessing the IBPM Web SDK for Search and Retrieval. This method provides a hard-wired access to a single Saved Search in the system.

The IBPM Web SDK Search and Retrieval components are accessed through the use of URL parameters into the default.asp page on the IBPM Web Client web site. The SDK Search and Retrieval tool name must be specified on the URL as a parameter (i.e. &ToolName=AWSER) in addition to data for the tool.
For example, the following URL runs a Saved Search named MySearch with a parameter value for the Account field of "12345”.

http://MySite/IBPMweb/default.asp?ToolName=AWSER&SearchName=MySearch&Account=12345&EOF=1

This runs the Saved Search using the IBPM Web Server installed on MySite. Notice that the default.asp page at that site is specified. This ASP page must be specified to properly accept the URL parameters. The tool AWSER provides access to running a Saved Search directly. The tool is specified using the ToolName URL parameter (i.e. ToolName=AWSER). Notice also that the name of the Saved Search to be run must be specified (i.e. SearchName=MySearch). The parameter for the search is specified using the field name and its value as a URL parameter. If more than one field is desired, simply list the name/value pairs on the URL. Finally, an &EOF=1 parameter is required at the end of any URL specifying access to a toolkit item. This allows the IBPM Web SDK to check for truncated URLs (Max ASP URL length is 2083 characters) and notify the user of the problem.

The above URL will run the Saved Search and either present the user with the Search Results Tool or the Viewer Tool. If the search resulted in a single match, the result will be displayed to the user in the Viewer Tool. If the search resulted in multiple matches or hits, the results will be displayed to the user in the Search Results Tool. From the Search Results Tool the user will be able to view the matches. These are the same tools used by an IBPM Web Client. However, their menus have been altered through the use of the IBPM Web Client Menu Set feature.

The Menu Set feature is a new IBPM Web Client feature allowing Standard IBPM Web Client menus to be overridden by specifying a Menu Set parameter on the URL (i.e. &MnuSet=MyMenus). By creating new menu sets access to IBPM Web Client features and tools can be restricted. The IBPM Web SDK Search and Retrieve entry point into the IBPM Web Client limits access to the IBPM Web Client through the use of its own Menu Set as well as hiding the banner. The menu set can be overridden through the use of a MnuSet parameter on the URL if needed (i.e. &MnuSet =MyMenuSet).

Defining a New Menu Set

One of the new features added to the IBPM Web Client in support of the Web SDK is the ability to define custom IBPM Web Client Menu Sets. The Menu Set feature allows Standard IBPM Web Client menus to be overridden by specifying a Menu Set parameter on the URL (i.e. &MnuSet=MyMenus).

Access to IBPM Web Client features and tools can be restricted by creating new menu sets. The use of a particular menu set can be specified through the use of a MnuSet parameter on the URL if needed (i.e. &MnuSet =MyMenuSet).

The IBPM Web SDK Search and Retrieve entry point into the IBPM Web Client limits access to the IBPM Web Client through the use of its own Menu Sets. The following menu options are available when using the Search and Retrieval Web SDK:

Viewer Menu Items:
· Next Document
· Previous Document
· View Query Results
· Logout

Search Results Menu Items:
· View Selected
· Goto First Page
· Goto Previous Page
· Goto Next Page
· Goto Last Page
· Logout

When using the standard Saved Search the AWDSER menu set is used. Add to the available features by taking one of the following actions:

1. Add to the AWDSER menu set.
2. Specify the standard web client menu on the URL (i.e. &MnuSet =AcordeStandardWebClient).
3. Define a custom menu set and specify it on the URL.

To add to the AWDSER menu set copy commands from the Standard Web Client Menu Sets into the AWDSER menu set XML file. Menu set XML files are found in the following directory:

C:\InetPub\WWWRoot\OTInfrastructure\AcordeXMLToolBars

Each subdirectory under the above directory specifies a menu set. The AWDSER menu set only specifies menus for a portion of the IBPM Web Client Tools. This is because the infrastructure will use the default menu set definitions for menus that are not defined in custom or Web SDK menu sets. The default menu set is defined in the AcordeStandardWebClient subdirectory.

For more information on using menu sets, see the SearchRetrieval.doc file on the application CD, or contact Tech Support at IBPMsupport@Stellent.com.

Login Tool

A new feature for the Login Tools has been added to the IBPM Web Client/IBPM Web SDK to facilitate a user that makes use of the URL IBPM Web SDK components over and over through a single browser instance. By specifying on the URL that a user should not be forced to login (i.e. &ForceLogin=0) a browser/server session will try to use information in the session to Pass Through the login tool directly to the IBPM Web SDK tool. By default IBPM Web SDK entry points into the web client also specify that a user should not be forced to login. This can be overridden through the use of the ForceLogin URL parameter (i.e. &ForceLogin=1). This means that by default the user of the IBPM Web SDK will only have to login once. As long as that session is reused in subsequent IBPM Web SDK call the login steps to the client will be skipped.

Another new feature has been added to the IBPM Web Client/IBPM Web SDK for the Login Tools to facilitate the use of the Banner Menus when using the IBPM Web SDK. By specifying on the URL that the banner should not be hidden (i.e. &HideBanner=0) a browser/server session will display the banner and its menu sets. This will give the user full access to the IBPM Web Client. Table 1 lists the valid AWSER tool parameters that can appear on the URL.

Using URL Encoding With IBPM Web SDK Search and Retrieval Tool

When constructing the URL string to access the IBPM Web SDK Search and Retrieval all parameters need to be URL encoded. This allows any special characters to be passed to the AWSER tool correctly. Failing to encode the parameters will result in an error or the search never being executed. Listed below are some samples of when URL encoding is needed. All parameters that are used in the URL creation should be URL encoded at all times. This will eliminate any issues with special characters being added to a parameter.

AWSER Sample

A user, to save time, creates an IBPM Saved Search with a name of “Account#”. This search is used to find a customer’s name by entering in an account number. The parameters in this example are:

SearchName=Account#
Searching Parameter Name1 is AccountNumber
Searching Parameter Name 2 is CustomerName

Constructing the URL by using all parameters without URL encoding:

http://MySite/IBPMweb/default.asp?ToolName=AWSER&SearchName=Account#&AccountNumber=UserInput&EOF=1

Executing this URL string will cause the error to be displayed.

No '&EOF' parameter was found at the end of the URL requesting a ToolName. The URL may have been greater than 2083 characters.

The pound sign signals the URL parser that the end of string has been reached. Because of this the EOF=1 parameter is never read and the search is never executed. The correct string is:

http://MySite/IBPMweb/default.asp?ToolName=AWSER&SearchName=Account%23&AccountNumber=UserInput&EOF=1


Java Integration for IBPM Web Services

Integrating IBPM Web Services With Java

Overview

The Acorde2.asmx web service interface provides the ability to return complex types to your application. That means that the XML returned via SOAP for each web service call can be converted into an object defined by the calling application’s native language. This allows developers to work directly with objects and bypass the additional coding tasks required to parse return data from the raw XML. This can help avoid errors commonly associated with managing XML data and allows developers to retrieve IBPM data with less lines of code.

The objects that are created are containers of data only. They contain public data members and have no associated methods. The methods are defined by each of the individual web service calls exposed in the ASMX file. The objects may contain other objects. However, all of the objects’ data members ultimately resolve to simple types.

In .NET, the creation and management of the class that represent the objects used by IBPM Web Services are handled automatically when an Acorde2.asmx file is added as a Web Reference to the project. Object functionality may also be achieved in Java applications. However, the programmer will have to take additional steps to create the class stubs and manage the communications interface to the IBPM Web Services. These steps are outlined in the remaining sections of this document.

System Details

The examples described in this document were implemented using the following components:

Red Hat 9.0 Linux operating system

Sun J2SE 1.4.2.03

Apache Axis 1.1

Please note that it is possible to use IBPM Web Services from other configurations or with third party applications that support the ability to create class stubs and manage the connections between the application and a remote web services host.

Integrating Web Services

The following steps are required to integrate IBPM Web Services into your Java application:

  1. Locate Acorde2.asmx on a remote IBPMWeb server
  2. Create Local class ‘stubs’ that represent the IBPM objects defined in the Acorde2.asmx interface
  3. Import these classes into your application
  4. Create an interface object that connects your application to the IBPM Web Services host (IBPMWeb server)
  5. Use the objects to send and retrieve data from IBPM Web Service calls.
Locate Acorde2.asmx

Attempt to view the exposed IBPM Web Services calls by navigating to the Acorde2.asmx file on your local IBPM Web Server from a web browser.

The link will look similar to the following:

http://myWebServer/IBPMweb/services/Acorde2.asmx

The web browser should load with a screen listing the available web service methods.

.Asmx is a Microsoft based extension. From some Java environments, you may be required to append “?wsdl” to the end of the link to view. If you have problems reaching the Acorde2 interface from your browser, try adding the “?wsdl” extension.

http://myWebServer/IBPMweb/services/Acorde2.asmx?wsdl
Creating the class stubs

Many third party tools have built in features that manage the interface between the application and the remote web services host. This may include the ability to manage the class relationships of the objects found in the WSDL or ASMX file being used. In this example, a basic utility called WSDL2Java is used to create the class stubs. Other utilities or applications may be used, as well. However, they are not covered by this document.

WSDL2Java Description

WSDL2Java is a utility found in the AXIS 1.1 SDK. This utility inspects a remote WSDL or ASMX file and then creates individual class files for each object exposed by the web service.

WSDL2Java Usage

Java org.apache.axis.WSDL2Java –O “-1” –v –o “targetDirectory” http://myWebServer/IBPMweb/services/Acorde2.asmx?wsdl

The details of using WSDL2Java are provided in the AXIS 1.1 SDK documentation. Below is a listing of the parameters used for our example:

· -O “-1” – sets the timeout. –1 means to ignore the default timeout. This is recommended, as it can take several minutes for the classes to be generated.

· -v – verbose option. Stream information about the status of the command to the screen.

· -o “targetDirectory” – the directory name where the class files are to be generated.

· http://myWebServer/IBPMweb/services/Acorde2.asmx?wsdl - the location of the Acorde2 Web Services interface on your local IBPM Web server.

Location of the .java files

Classes generated by WSDL2Java will be created in the directory name provided with the –o command line option. WSDL2Java will automatically create a namespace based directory structure starting from the targetDirectory location. The class files will be found in the following location:

targetDirectory/com/Stellent/message/

List the contents of this directory. If several .java class files are not visible, then review your WSDL2Java command for any errors.

Differences between WSDL2Java generated Java classes and .NET

The classes created by WSDL2Java have some differences in relation to the class interfaces used by .NET. The data being passed between your application and IBPM Web Services will be the same. However, developers may have to use slightly different syntax to access the returned data.

The original .NET based class implementation creates the objects with public data members. This allows programmers to access the data directly. WSDL2Java follows the Sun suggested standards and creates the classes with private data members and adds the appropriate get/set methods.

From .Net:

string strLUCID = objSystemFields.LUCID;

From Java (using WSDL2Java):

string strLUCID = objSystemFields.getLUCID();

Both of the commands listed above will return a string value representing the LUCID value returned from a SystemFields object. Using Acorde2 from .NET allows you to access the data member directly. The Java implementation requires the use of a get method.

The syntax of the web service methods will change, too. All methods begin with a capital letter from .NET. The WSDL2Java conversion recreates the methods to begin with a lower case.

These differences are outlined in the code samples below. Both code blocks produce the same end result: a listing of all available saved searches. Notice that Java requires a get method to access the name of the saved search. Also notice the lowercase differences in the web service method calls (GetAvailableSavedSearches(…) vs getAvailableSavedSearches).

.NET

// Get a list of Saved Searches

Acorde2WebReference.SavedSearchNamesArray objSSNA = objAcorde.GetAvailableSavedSearches(strAIID);

// Loop through SavedSearchNamesArray object's SearchNames array

for(int i=0; i < objSSNA.SearchNames.Length; i++)

{

       Response.Write(objSSNA.SearchNames[i].Name + “<BR>”);

}

Java

// Get the saved search names object

SavedSearchNamesArray objSSNA = objAcorde.getAvailableSavedSearches(strAIID);

// Java - using 'get' methods

ArrayOfSavedSearchName objAOSSN = objSSNA.getSearchNames();

SavedSearchName[] arrSSN = objAOSSN.getSavedSearchName();

// loop that displays all saved search names

String strSearchName = "";

for(int i=0; i < arrSSN.length; i++)

{

strSearchName = arrSSN[i].getName();

System.out.println("objSSNA.searchNames[" + i + "].name: " + strSearchName);

}

Import these classes into your application

Once the classes have been created, then they may be imported into any application. Therefore, you should only have to go through the process of creating the class stubs one time. After that, you may reuse the generated code for future projects.

To import those classes, simply import the location of the class files:

import com.Optika.message.*;

Create the Interface Object / Using Objects within the application

WSDL2Java creates the following 4 classes to manage the communications between your application and IBPM Web Services:

· Acorde2.java – Top level class for managing the interface from the application to IBPM Web Services.

· Acorde2Locator.java – Used to create the Acorde2Soap object. Contains the location of the remote IBPM Web Server that hosts the IBPM Web Services.

· Acorde2Soap.java – Contains a listing of all available web service calls for the Acorde2 interface. This object is used to make these method calls and return data to the application.

· Acorde2SoapStub.java – A support class for Acorde2Soap.java not directly used by the programmer.

If you would like to point your application to a different IBPM Web Server, then you must change the following line of code in Acorde2Locator.java:

// Use to get a proxy class for Acorde2Soap

    private final java.lang.String Acorde2Soap_address = "http://newwebserver/IBPMweb/services/Acorde2.asmx";

Creating the interface object from within your code is quite simple. The following code block displays the syntax for creating the locator object.

Notice that the application must catch the exceptions javax.xml.rpc.ServiceException when instantiating the Acorde2Soap interface object from the locator object and java.rmi.RemoteException when making any web service calls using the Acorde2Soap object.

// get the Web Service object connection setup

Acorde2Locator objAcordeLocator = new Acorde2Locator();

try{

Acorde2Soap objAcorde = objAcordeLocator.getAcorde2Soap();

      try{

            // Make all Acorde2 Web Service calls in this try/catch block

            string AIID = objAcorde.loginUserName(“user”, “password”, “”, “”);

      }

      catch (java.rmi.RemoteException e){

            e.printStackTrace();

      }

}

catch(javax.xml.rpc.ServiceException e) {

      e.printStackTrace();

}

Samples

Unzip the file AcordeWebServicesJavaSample.zip to view source code containing the local class stubs, along with two sample Java applications.

The Acorde2 class stubs and Acorde2 interface classes are located in the com/Stellent/message directory.

Navigate to the samples directory to view two Java applications that use IBPM Web Services. Sample1.java simply displays a list of all available saved searches. List.java provides an interface for executing a saved search and displaying the search results.

Sample1.java accepts two parameters, login and password. These parameters allow you to dynamically provide login information when executing the program.

In List.java, the login information must be provided within the application.

Conclusion

Using objects to manage return and input data with IBPM Web Services via the Acorde.asmx interface is easy to do from Java based applications. The examples provided in this document create the class stubs and locator objects using the WSDL2Java utility. However, any utility or third party application that manages the creation of the objects and communications to the remote web service host may also be used.


Work Center Integration Technologies

This document focuses on XML based features available in the Web Client that can facilitate the following:

  • Creating a new IBPM Work Center Node for tool navigation
  • Integration of external Web Services into the IBPM Work Center
  • Integration of external Web Applications using an IBPM Work Center Node

Many infrastructure features have been added to the IBPM Web Client to facilitate rapid development and integration of new IBPM Web Client tools. These features allow a developer to define Web Client Tools and their integration points through the extensive use of XML Metadata.

With the Acorde 4.0 Web Client GA release, we extended the use of XML Metadata to the definition of IBPM Work Center. These new types of Work Center Nodes facilitate an XML definition of their interaction with not only the IBPM Web Client but with External Web Services and Web Applications.

This document is a non-normative description of the XML Work Center nodes. We describe the functionality through examples as opposed to XML Schema.

The Work Center Node

The Work Center was created to provide a more effective mechanism for navigating the IBPM Web Client. Through the introduction of new Work Center nodes, a developer or integrator can provide an efficiently packaged view of data or functionality that a user can access in a single click. The additions of node expand and collapse functions allow the user to customize their workspace in a straightforward manner that is intuitive to most computer users.

The Work Center can be extended through the generation of new Work Center Nodes. Customization can take the form of integration of external web application, external web services or navigation shortcuts within the IBPM Web Client. There are two ways to accomplish the creation of a new Work Center Node. The first is to implement a new ASP node definition and place it in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AcordeWorkCenterNodes

After placing the ASP file in the AcordeWorkCenterNodes directory, restart your IIS server or navigate a browser to the following URL:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\ResetWorkCenterNodeLibrary.asp

After that your node will be added to the Work Center. JavaScript Work Center Node development requires an understanding of JavaScript and JavaScript object development. You will need to implement the JavaScript Work Center Node interface (Appendix A).

** We suggest that you do not use the JavaScript mechanism due to the fact that it is a more difficult implementation than working with the XML Work Center Node mechanism.

The second Work Center extension mechanism is the XML Work Center Node. This is the suggested mechanism for creating new Work Center Nodes. We strongly suggest that you use this mechanism for creating your custom Work Center Nodes rather than the JavaScript Work Center Node implementation. XML Work Center Node development involves the creation of a new XML AcordeWorkCenterNodeDefinition Document and placing it in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AcordeWorkCenterNodes\XMLWorkCenterNodes

After Placing the XML file in the XMLWorkCenterNodes directory you will need to restart your IIS server or navigate a browser to the following URL:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\ResetWorkCenterNodeLibrary.asp

After that your node will be added to the Work Center.

This document focuses on the XML Work Center Node and describes through examples how to create an XML Work Center Node.

The Basic XML Work Center Node

The most basic XML Work Center Node provides a list of tools that can be clicked on to load a tool through a particular entry point. This section will examine this simple case in detail and introduce some basic concepts that will be expanded upon in later sections.

A sample Work Center Node XML file that can be used in the IBPM Web Client

<?xml version="1.0" encoding="utf-8" ?>

<AcordeWorkCenterNodeDefinition name="AdminWCN" xmlns="http://Optika.com/schemas/AcordeWebInfrastructure/AcordeWorkCenterNodeDefinition">

       <AvailabilityTestObject type="javascript">AcordeATOWebAdministrator</AvailabilityTestObject>

       <Rank>1500</Rank>

       <DescriptionID namespace="AdminWCN">AdministratorToolsDescription</DescriptionID>

       <TopLevelWorkCenterNode>

              <WorkCenterNode type="TOPLEVELNODE">

                     <Icon>NAV_Administration.gif</Icon>

                     <Caption>White Paper</Caption>

                     <Name>TopLevelAdministration</Name>

                     <Command>ShowAdminContactTool</Command>

              </WorkCenterNode>

       </TopLevelWorkCenterNode>

       <ChildWorkCenterNodes>

              <NodeGroup

                     name="Tools"

                     type="DATA"

                     sessionstatic="true"

                     AvailabilityTestObject="AcordeATOTrue">

                     <WorkCenterNode type="SUBNODE">

                           <Icon>Bullet_Right_Green_2.gif</Icon>

                           <CaptionID namespace="AdminWCN">

                              AdministratorDefaultsToolPhrase

                           </CaptionID>

                           <Name>AdminDefaults</Name>

                           <Command>ShowAdminDefaultsTool</Command>

                     </WorkCenterNode>

              </NodeGroup>

       </ChildWorkCenterNodes>

       <AcordeCommandMap>

              <CommandMapping command="ShowAdminDefaultsTool" type="NavigationCommand">

                     <NavigationCommand>

                           <TargetTool>

                              ::AdminInfrastructureDefaultsTool::ShowTool

                           </TargetTool>

                           <NewWindowATO>AcordeATOFalse</NewWindowATO>

                     </NavigationCommand>

              </CommandMapping>

       </AcordeCommandMap>

</AcordeWorkCenterNodeDefinition>

XML Block 1

The above sample (XML Block 1) illustrates an XML document that defines a Work Center Node containing one sub-node. The sub-node, when clicked on by the user, will generate a Navigation Command in the IBPM Infrastructure:

“::AdminInfrastructureDefaultsTool::ShowTool”

When it is clicked on, this sub-node will cause the “AdminInfrastructureDefaultsTool” to be loaded through its entry point “ShowTool”.

Examining the document we see several elements of interest. The following summarizes the content of this document and the various element meanings that are present in this sample document. Notice that specific references to Element or Attribute Names are shown in blue:

· Rank – This is a relative ranking that determines where in the Work Center list of displayed node your node will be displayed. This is optional and if it is not there your node will be placed at the top of the Work Center. If there are multiple Work Center nodes that have no rank then the order is not determined.

· DescriptionID – This is an optional element that provides a description of the functionality of the Node.

· AvailabilityTestObject – This is an optional element that provides a name of a JavaScript object that is used to test if the item should be shown. If it is missing then the Node will be displayed.

· TopLevelWorkCenterNode – This element describes the look and content of this Work center Node. There must be one and only one TopLevelWorkCenterNode as a child element of the AcordeWorkCenterNodeDefinition. The sub-element WorkCenterNode must have a type of TOPLEVELNODE. The WorkCenterNode child conforms to a Work Center Node as described below.

· WorkCenterNode – A WorkCenterNode describes a node in the Work Center tree structure and it behavior. A WorkCenterNode has the following child elements and attributes:

o       Icon (required child) – This is the specification of the image to use as the Icon for the work center node. These files are found in the directory: IBPMWeb/NAVAppMapTool/Icons on the web server.

o                               CaptionID or Caption (required child) – This is the specification of the text used as the displayed title of the node. You must have either a Caption child element or a CaptionID child element. If a CaptionID is used then you must specify the namespace the translated phrase is in. Using Caption provides a literal phrase to use for the node.

o                               Name (required child) – This is the Name of the node and is used by the Infrastructure to uniquely identify the node and when the user clicks on that node.

o                               Command (required child) – This is the command that will be executed from the AcordeCommandMap as described below.

o                               Type (required attribute) – This is a required attribute and indicates the type of the Work Center node. Valid values include TOPLEVELNODE, TOOLBARICON and SUBNODE.

· ChildWorkCenterNodes – The content of this element defines the sub-nodes or child nodes of the Work Center Node. These are the nodes that are displayed when the Work Center Node is expanded. The child elements consist of an array of NodeGroup elements. The NodeGroup elements conform to the description below.

· NodeGroup – The content of this element defines the sub-nodes or child nodes of the Work Center Node. The child element content of this node is an array of WorkCenterNode if the type of the Node Group id DATA or TOPTOOLBAR. If the type is WEBSERVICE then the actual Node Group XML is obtained from an IBPM Web Service Sequence. The NodeGroup Element has the following attributes:

o                               Name (optional attribute) – The unique name of the NodeGroup. Useful in debugging XML Work Center Nodes through error messages.

o                               Type (required attribute) – The type of the NodeGroup. Valid values include TOPTOOLBAR, WEBSERVICE or DATA.

o                               Sessionstatic (optional attribute) – Indicates if the content of the NodeGroup can change during an IBPM Web session. This indicates to the IBPM Web application if the content of the node can be cached. Valid values include true or false.

o                               AvailabilityTestObject (optional attribute) – The JavaScript Availability Test Object (ATO) that should be used to determine if this node group should be shown. Can be an empty string or missing completely.

· AcordeCommandMap – Defines the commands that are handled by the work center node. These commands define actions that can take place when a user clicks on the node or sub-nodes. This may include Navigation Commands as well as a few other actions that will be presented in later sections. The content of this node is an array of CommandMapping elements that conform to the description below.

· CommandMapping – Defines action the IBPM Infrastructure needs to take when a user clicks on a Work Center node. These CommandMapping elements are referenced by the WorkCenterNode elements defined earlier. The child element content of a command mapping can vary based on the type of CommandMapping being defined. The specific content variations will be discussed in a later section. Our sample shown above uses a NavigationCommand to instruct the IBPM Infrastructure to navigate the main workspace to a specific tool. The CommandMapping element has the following attributes.

o                               Command (required attribute) – The unique name of the CommandMapping. This is referenced by the WorkCenterNode elements when they need to specify the action to take when a user clicks on the node.

o                               Type (required attribute) – This is a required attribute and indicates the type of the CommandMapping. Valid values include NavigationCommand, ChangeStateCommand, WebServiceCommands, PromptForStateValues. These will be discussed in detail in later sections

Further sections in this document will present each of the element types in more detail.

The WorkCenterNode Element

The WorkCenterNode element is the core user interface element of the IBPM Work Center Node Definition. The WorkCenterNode element defines the look of each of the Work Center Nodes that are displayed to the user. The WorkCenterNode element also defines what command will be executed when the graphical Work Center Node is clicked on.

The WorkCenterNode element is used as a child element of the TopLevelWorkCenterNode and as an Array element in the NodeGroup element in the IBPM Work Center Node Definition. XML Block 2 is an example of a WorkCenterNode element that might be used in an IBPM Work Center Node definition.

An XML WorkCenterNode example

              <WorkCenterNode type="TOPLEVELNODE">

                     <Icon>NAV_Administration.gif</Icon>

                     <Caption>White Paper</Caption>

                     <Name>TopLevelAdministration</Name>

                     <Command>ShowAdminContactTool</Command>

              </WorkCenterNode>

XML Block 2

The type Attribute

In this example the WorkCenterNode type is defined as TOPLEVELNODE. There are three WorkCenterNode types that are supported. These are:

- TOPLEVELNODE – this is the node type used when the node is a child of the element TopLevelWorkCenterNode. That node must have a type of TOPLEVELNODE.

- SUBNODE – this is the node type that is used when specifying children that appear under the top-level node.

- TOOLBARICON – this is the node type that is used when specifying children that appear as children of a Node Group with a type of TOPTOOLBAR.

The Icon Child Element

The Icon element specifies the graphic that should be used when rendering the Work Center Node in the User Interface (UI). This is a file name and refers to an image in the directory:

C:\InetPub\WWWRoot\IBPMWeb\NAVAppMapTool\Icons

All available icons are located in that directory. If you want to use a custom icon you will need to place a copy of the image file in that directory and then specify it in your Icon child element of the WorkCenterNode element.

Figure 1 illustrates what the node will look like and a red circle shows what is affected by the Top Level Node Icon element.

Figure 1: The Icon for a top-level node.

Figure 2 illustrates what portion of the graphical child Work Center Node is affected by the Icon element in a child WorkCenterNode element.

Figure 2: The Icon for a child node.

As was mentioned earlier, it is possible to create a toolbar that appears at the top of the child nodes under the Top Level Node. Figure 3 illustrates the use of the Icon in a Work

Figure 3: The Icon for a Top Toolbar node.

Center Top Toolbar. This is actually a screenshot of the IBPM Web Dashboard Work Center Node which is an XML Work Center Node integrating the IBPM Dashboard Web Application.

The Caption and CaptionID Child Elements

The Caption element specifies the phrase that should appear to the right of the Node Icon Image. XML Block 2 demonstrates a WorkCenterNode element that uses a Caption element to specify its display text. The use of the Caption element allows you to specify a literal phrase for display in the Work Center.

If you need to allow for translation of the phrase you will need to use a CaptionID element in place of a Caption element. The CaptionID element requires the specification of a namespace attribute. XML Block 3 demonstrates the use of a CaptionID element as opposed to a Caption element. Notice that the text value for the CaptionID element is the ID of the phrase as opposed to the literal phrase. The attribute namespace refers to the translation namespace that Id has been specified for. This used the XML based IBPM Web Translation architecture so the actual literal phrase is defined in a translation XML file found in the in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AcordeXMLTranslations\[LANGUAGE]\AdminWCN

where [LANGUAGE] is the language code for the language the user logged in with.

An XML WorkCenterNode example

              <WorkCenterNode type="SUBNODE">

                     <Icon>Bullet_Right_Green_2.gif</Icon>

                     <CaptionID namespace="AdminWCN">AdministratorDefaultsToolPhrase</CaptionID>

                     <Name>AdminDefaults</Name>

                     <Command>ShowAdminDefaultsTool</Command>

              </WorkCenterNode>

XML Block 3

You must specify either a Caption or a CaptionID for every WorkCenterNode element you define.

Figure 4 illustrates the location of the text that has been specified using a Caption element for a WorkCenterNode element defining the Top Level Node of a Node Definition Document.

Figure 4: The Caption for a top level node.

Figure 5 illustrates the location of the text that has been specified using a CaptionID for a child node in the XML Node Definition Document.

Figure 5: The displayed text for a CaptionID element of a sub node.

Figure 6 illustrates the use of a non-empty string as a Caption or CaptionID in a toolbar Work Center Node. Again, notice that this is a screenshot of the Dashboard integration node.

Figure 6: The Caption or CaptionID affect on a toolbar Work Center Node

Later in this document we completely define the concept of StateVariable elements. StateVariable elements are similar to variables in JavaScript or Visual Basic. A quick summary of state variable is that they are values that have been obtained from the user, the IBPM Web Client Infrastructure or an External Web Service that are recorded as part of the IBPM Web Session. Some State Variables can also be recorded as user preferences.

You may want to display state variable information to a user in your Work Center Node. One of the ways to accomplish this is to specify that it should be displayed as part of a Caption or as part of the translated phrase specified by the CaptionID. Figure 7 illustrates the insertion of a state variable used by the Dashboard Node into a Node Caption.

Figure 7: An example of displaying a StateVariable as part of a Caption.

In this case it is the “Start Date” used in querying the Dashboard Web Service for a summary of activity.

You may ask “How do I insert a StateVariable value into my caption?” We accomplish this by placing a recognizable tag into the Caption literal phrase or CaptionID translated phrase. This tag takes the form:

[ACORDESTATEVARIABLE:VariableName]

XML Block 4 illustrates the use of a StateVariable reference inserted into a Caption

An XML WorkCenterNode using the State Variable insertion feature

<WorkCenterNode type="SUBNODE">

<Icon>Bullet_Rect_Blue_2.gif</Icon>

<Caption>Start Date: [ACORDESTATEVARIABLE:STARTDATE]</Caption>

<Name>StartDateNode</Name>

<Command>PromptForSearchValues</Command>

</WorkCenterNode>

XML Block 4

This is an excerpt from the Dashboard Work Center Node definition and is the XML that generates the UI shown in Figure 7. There is a complete set of “Replacement Tags” that have been defined to allow you to insert data from the IBPM Web Client infrastructure into your captions. Appendix B presents a complete summary of the available “Replacement Tags”.

The Command Child Element

The Command element defines the behavior or action that is taken when a user clicks on the Graphical Work Center Node. Commands are defined in the AcordeCommandMap element and referenced from the WorkCenterNode element. The text value of the Command element is simply the value of the command attribute of the CommandMapping element defining that command.

A later section completely defines that IBPM Command Map and the available Command Mapping types.

The InlineCommand Child Element

It is possible to obtain WorkCenterNode definitions from external web services through the use of a WebServiceSequence and a Web Service NodeGroup. This will be described in detail in a later section of this paper. If you are using a web service to generate your WorkCenterNode definitions you may want to specify the Command directly in the WorkCenterNode rather than referencing a CommandMapping element. This may be due to the fact that you are providing a command that is dynamically based on data specific to the current user session. This could be a URL to an external Web Application that contains QueryString data generated by the Web Service.

To facilitate this requirement we have defined an InlineCommand element that would replace the Command element presented in the previous section.

An XML WorkCenterNode using an InlineCommand element rather than an Command element

              <WorkCenterNode type="SUBNODE">

                     <Icon>Bullet_Right_Green_2.gif</Icon>

                     <Caption>Queries: 23</Caption>

                     <Name>DsBdResultQueries</Name>

                     <InlineCommand type=”URL”>

                           <URL>

                           http://myWebServer/IBPMDashboard/DocumentQuerySummary.aspx?

                           AID=%7b1FAAC076-704D-449D-AB77-5B3AE178C397%7d%3a13148786&amp;Category=0

                           &amp;StartDate=10%2f13%2f2003&amp;EndDate=11%2f13%2f2003

                           &amp;user=&amp;server=&amp;application=

                           </URL>

                           <NewWindow>false</NewWindow>

                     </InlineCommand>

              </WorkCenterNode>

XML Block 5

XML Block 5 illustrates the use of the InlineCommand. Using the inline command allows you to define the WorkCenter node at the same time you define its command or behavior rather than relying on a CommandMapping that has been defined in the Work Center Node Definition File.

In the example in XML Block 5 the Dashboard web service has provided a Work Center Node that displays the number of Queries that have been audited. In addition to the visual aspects of the Work Center node the web service has provided a URL link to the Dashboard web application that will display a table of the queries. When the user clicks on the Work Center Node the main workspace in the IBPM Web will be navigated to the URL that has been provided. This provides a good mechanism for embedding external web application as “tools” in the IBPM Web Client.

The type of InlineCommand shown in XML Block 5 is a “URL” Inline Command. This is specified by the type attribute of the InlineCommand element. Supported Inline Command types include

- NavigationCommand - Navigate to a defined IBPM Web tool.

- ChangeStateCommand – Change the value of a State Variable.

- URL – Display a specified URL in the workspace or a new window.

- PublishXML – Publish XML To the IBPM Web Client State Document.

- PromptForStateValues – Prompt a User for values.

- FireClientEvent – Fire an IBPM Client Event into the Web Client.

- WebServiceCommands – Call a Web Service or Expire Web Service results.

- CommandSequence – Combine one or more of the above commands into one sequence of commands

XML Block 6 illustrates the use of an inline command that defines a Navigation.

A second XML WorkCenterNode using an InlineCommand element rather than an Command element

              <WorkCenterNode type="SUBNODE">

                     <Icon>Bullet_Right_Green_2.gif</Icon>

                     <Caption>Web Defaults Tool</Caption>

                     <Name>DsBdResultQueries</Name>

                     <InlineCommand type=”NavigationCommand”>

                           <TargetTool>::AdminInfrastructureDefaultsTool::ShowTool</TargetTool>

                           <NewWindow>AcordeATOTrue</NewWindow>

                     </InlineCommand>

              </WorkCenterNode>

XML Block 6

Command that launches the tool through its entry point “ShowTool”. The NewWindow element specifies that the tool should be launched in a new window.

The inline command also allows you to provide string values as parameters to the target tool. In the tool, IBPM Tool Interface (ATI) provides the “SetEntryPointParam” method you can pass data to that tool using an EntryPointParams element array. The signature of the “SetEntryPointParam” function is shown in JavaScript Block 1.

// This object constructor Adds the ATI method

// SetEntryPointParam so Work Center Nodes can

// Pass data to the tool from an Inline Navigation Command.

function _AcordeToolInterfaceObjectConstructor()

{

function _SetEntryPointParam(strEntryPointName, strParamID, strParam)

{

// Add Code Here

}

this.SetEntryPointParam = _SetEntryPointParam;

}

JavaScript Block 1

An example of using the EntryPointParams element array in a WorkCenterNode element is provided in XML Block 7. Notice that this sample is providing three parameter values to the tool. They are Param1, Param2 and Param3 and their values are Value1, Value2 and Value3 respectively. This is the only case where parameters can be passed to a Navigation Command due to the fact that a Web Service may need to pass data to the Tool and only gets a chance to provide that data when this Work Center Node definition is be generated. If the IBPM Tool Interface does not implement the “SetEntryPointParam” method then the parameters will be ignored. So it is possible for a web service to provide more data than is needed so the tool can take advantage of the data in future implementations.

A third XML WorkCenterNode using an InlineCommand with ATI Entry Point Parameters

       <WorkCenterNode type="SUBNODE">

              <Icon>Bullet_Right_Green_2.gif</Icon>

              <Caption>Web Defaults Tool</Caption>

              <Name>GotoDefaultsTool</Name>

              <InlineCommand type=”NavigationCommand”>

                     <NavigationCommand>

                           <TargetTool>::AdminInfrastructureDefaultsTool::ShowTool</TargetTool>

                           <NewWindow>AcordeATOTrue</NewWindow>

                           <EntryPointParams>

                                  <Param name=”Param1”>Value1</Param>

                                  <Param name=”Param2”>Value2</Param>

                                  <Param name=”Param3”>Value3</Param>

                           </EntryPointParams>

                     </NavigationCommand>

              </InlineCommand>

       </WorkCenterNode>

XML Block 7

We have presented the intended use case of the InlineCommand as an external web service generating the Work Center Node. It is valid to provide an InlineCommand element in the document definition of the Work Center Node. It is processed in the same manner as a Work Center Node definition provided from a Web Service.

A complete definition of all available InlineCommands can be found in the section covering the CommandMapping element. Any supported CommandMapping types can be used as InlineCommands in a Work Center Node definition.

The AvailabilityTestObject Attribute

You can specify a single IBPM Availability Test Object (ATO) object that will determine the availability of the Work Center Node. An IBPM ATO object is a JavaScript object that is written in ASP JavaScript and placed in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AvailabilityTestObjects

Availability Test Objects allow you to provide a richer test than a simple State Variable test. For instance, you may need to interact with a COM object on the Web Server to determine if your Work Center Node should be available to the user. This mechanism allows you to do that

The AvailabilityTest Child Element

There may be times when you want some node hidden while you show other nodes based on State Variables that you have defined. It is possible provide a test that determines whether or not a node is available. This is done by defining an AvailabilityTest child element of the WorkCenterNode element. XML Block 8 illustrates the use of the AvailabilityTest in a WorkCenterNode element.

A WorkCenterNode element that has an AvailabilityTest defined

                     <WorkCenterNode type="SUBNODE">

                           <AvailabilityTest>

                                  <StateVariable>GENERALMODE</StateVariable>

                                  <Value>FullText</Value>

                                  <UseNot>false</UseNot>

                           </AvailabilityTest>

                           <Icon>Bullet_blank.gif</Icon>

                           <Caption>Audit Sub-Categories: Full Text</Caption>

                           <Name>CatTitleFullText</Name>

                           <Command></Command>

                     </WorkCenterNode>

XML Block 8

This example tests the State Variable “GENERALMODE” and checks to see if its value is “FullText”. If it is “FullText” then this node will be displayed if it is some other value then the node will not be displayed. The “UseNot” element allows you to create a “not equal” test. XML Block 9 demonstrates the use of a “NOT EQUAL” AvailabilityTest.

A WorkCenterNode element that has an AvailabilityTest defined with a UseNot as true

                     <WorkCenterNode type="SUBNODE">

                           <AvailabilityTest>

                                  <StateVariable>GENERALMODE</StateVariable>

                                  <Value>FullText</Value>

                                  <UseNot>true</UseNot>

                           </AvailabilityTest>

                           <Icon>Bullet_blank.gif</Icon>

                           <Caption>Audit Sub-Categories: Not Full Text</Caption>

                           <Name>CatTitleNotFullText</Name>

                           <Command></Command>

                     </WorkCenterNode>

XML Block 9

In this example the node will only be displayed if the value of the “GENERALMODE” state variable is NOT “FullText”. You can specify one or more AvailabilityTest elements. Each one will be checked and if any of the tests returns a false then the node will not be available. XML Block 10 illustrates this.

A WorkCenterNode element that has two AvailabilityTest elements defined

                     <WorkCenterNode type="SUBNODE">

                           <AvailabilityTest>

                                  <StateVariable>GENERALMODE</StateVariable>

                                  <Value>FullText</Value>

                                  <UseNot>true</UseNot>

                           </AvailabilityTest>

                           <AvailabilityTest>

                                  <StateVariable>SHOWTOOLBARCATEGORIES</StateVariable>

                                  <Value>1</Value>

                                  <UseNot>false</UseNot>

                           </AvailabilityTest>

                           <Icon>Bullet_blank.gif</Icon>

                           <Caption>Audit Sub-Categories: Not Full Text</Caption>

                           <Name>CatTitleNotFullText</Name>

                           <Command></Command>

                     </WorkCenterNode>

XML Block 10

Replacement Tags (Appendix B) are supported in the StateVariable element and the Value element.

The AvailabilityTest Attribute

You can also specify a single AvailabilityTest as an Attribute. Rather than specifying the test in line this will refer, by name, to an availability test defined in the AvailabilityTest array of the document located in the XPath location:

/AcordeWorkCenterNodeDefinition/AvailabilityTests/AvailabilityTest

You can embed definitions of AvailabilityTest elements inside AvailabilityTest elements. This means that even though you can only specify one AvailabilityTest as an attribute you can create complex tests. XML Block 11 illustrates the definition of a complex availability test.

A definition of a complex AvailabilityTest

<ChildWorkCenterNodes>

       <NodeGroup name="TopToolBar" type="TOPTOOLBAR" sessionstatic="false">

              <WorkCenterNode type="SUBNODE" AvailabilityTest=”IsFullText”>

                     <Icon>Bullet_blank.gif</Icon>

                     <Caption>Audit Sub-Categories: Full Text</Caption>

                     <Name>CatTitleNotFullText</Name>

                     <Command></Command>

              </WorkCenterNode>

       </NodeGroup>

</ChildWorkCenterNodes>

<AvailabilityTests>

       <AvailabilityTest name="IsFullText" aggregation="and">

              <AvailabilityTest>

                     <StateVariable>GENERALMODE</StateVariable>

                     <Value>FullText</Value>

                     <UseNot>false</UseNot>

              </AvailabilityTest>

              <AvailabilityTest>

                     <StateVariable>SHOWTOOLBARCATEGORIES</StateVariable>

                     <Value>1</Value>

                     <UseNot>false</UseNot>

              </AvailabilityTest>

       </AvailabilityTest>

</AvailabilityTests>

XML Block 11

Notice that the Work Center Node references the complex availability test using the attribute “AvailabilityTest” by setting that attribute to the name of the AvailabilityTest element it wants to use.

Notice that the example in XML Block 11 specifies an aggregation of “and”. This means that if any of the sub-tests fail the entire test will fail. The assumed result of the test in this case is true. You can also specify an aggregation of “or”. In the case of “or” if any of the sub-tests succeed then the entire test will succeed. The assumed results of a test using an aggregation of “and” is false.

Optionally an AvailabilityTest can include the use of an IBPM ATO. XML Block 12 illustrates this.

A definition of a complex AvailabilityTest using an ATO as one of the tests.

<ChildWorkCenterNodes>

       <NodeGroup name="TopToolBar" type="TOPTOOLBAR" sessionstatic="false">                    <WorkCenterNode type="SUBNODE" AvailabilityTest=”IsFullText”>

                     <Icon>Bullet_blank.gif</Icon>

                     <Caption>Audit Sub-Categories: Full Text</Caption>

                     <Name>CatTitleNotFullText</Name>

                     <Command></Command>

              </WorkCenterNode>

       </NodeGroup>

</ChildWorkCenterNodes>

<AvailabilityTests>

       <AvailabilityTest name="IsFullText">

              <AvailabilityTest>

                     <StateVariable>GENERALMODE</StateVariable>

                     <Value>FullText</Value>

                     <UseNot>false</UseNot>

              </AvailabilityTest>

              <AvailabilityTest>

                     <AvailabilityTestObject>AcordeATOShowTBCats</AvailabilityTestObject>

              </AvailabilityTest>

       </AvailabilityTest>

</AvailabilityTests>

XML Block 12

The CommandMapping Element

The CommandMapping element is allows you to define behavior or actions that will be taken when a user clicks on a Work Center Node in the UI or a command is executed. It is a “wrapper” element that can contain a variety of child elements based on the type attribute. CommandMapping commands can be executed through two mechanisms:

- A user clicking on a Work Center Node that has a Command element (presented in an earlier section)

- The IBPM Web Client firing an event that the XML Work Center Node handles (presented in a later section).

This section summarizes the available functionality for a CommandMapping element and defines how those various features are manifested for the user when the commands are executed.

The type Attribute

The type attribute for a CommandMapping element defines what content is contained within the sub elements of the CommandMapping node. The following are the types currently supported (IBPM Web 4.0 GA).

- NavigationCommand - Navigate to a defined IBPM Web tool.

- ChangeStateCommand – Change the value of a State Variable.

- URL – Display a specified URL in the workspace or a new window.

- PublishXML – Publish XML To the IBPM Web Client State Document.

- PromptForStateValues – Prompt a User for values.

- FireClientEvent – Fire an IBPM Client Event into the Web Client.

- WebServiceCommands – Call a Web Service or Expire Web Service results.

- CommandSequence – Combine one or more of the above commands into one sequence of commands

Based on the type of the CommandMapping the Work Center takes the appropriate action to process the child elements of the CommandMapping node.

The NavigationCommand Command Type

The command type NavigationCommand specifies that the IBPM Web infrastructure should navigate to a tool defined in the IBPM Web Client through a specified Entry Point. XML Block 13 illustrates the use of a NavigationCommand type.

A sample Command Mapping Node of type NavigationCommand

              <CommandMapping command="ShowAdminDefaultsTool" type="NavigationCommand">

                     <NavigationCommand>

                            <TargetTool>::AdminInfrastructureDefaultsTool::ShowTool</TargetTool>

                           <NewWindowATO>AcordeATOFalse</NewWindowATO>

                     </NavigationCommand>

              </CommandMapping>

XML Block 13

Notice that there are two child elements that are present in the NavigationCommand. Both are required. The text of the TargetTool is the same as IBPM XML toolbar navigation definitions and takes the form:

::TargetToolName::TargetEntryPointName

The second child element specifies the JavaScript Availability Test Object (ATO) that should be used to determine if the tool should be launched in a new window. AcordeATOFalse always returns false and AcordeATOTrue always returns true. If that element is blank then it is assumed to be false and the tool will be loaded into the main IBPM Web Client workspace. If the specified ATO returns true then the tool will be launched in a new window.

Work Center Commands do not yet support the use of Integration Entry Points (IPEs) as do the IBPM Web XML Toolbars. If those child elements are placed in the NavigationCommand they are ignored.

The CommandMapping does not support the use of Entry Point Parameters. This is a feature that is not supported by the IBPM Web XML Toolbars. XML Block 14 illustrates the use of Entry Point Parameters.

A sample Command Mapping Node of type NavigationCommand using Entry Point Parameters

              <CommandMapping command="ShowAdminDefaultsTool" type="NavigationCommand">

                     <NavigationCommand>

                            <TargetTool>::AdminInfrastructureDefaultsTool::ShowTool</TargetTool>

                           <NewWindowATO>AcordeATOFalse</NewWindowATO>

                           <EntryPointParams>

                                  <Param name=”Param1”>Value1</Param>

                                  <Param name=”Param2”>Value2</Param>

                                  <Param name=”Param3”>Value3</Param>

                           </EntryPointParams>

                     </NavigationCommand>

              </CommandMapping>

XML Block 14

Notice that this is the same format that was presented for the InlineCommand in the earlier section. This is a good time to point out that any of these CommandMapping formats can be used in an InlineCommand specification.

A supported variation of the XML provided in XML Block 14 is shown in XML Block 15. In this variation the NewWindowATO element is replaced by a NewWindow element and the value is simply false.

A sample Command Mapping Node of type NavigationCommand using NewWindow

              <CommandMapping command="ShowAdminDefaultsTool" type="NavigationCommand">

                     <NavigationCommand>

                            <TargetTool>::AdminInfrastructureDefaultsTool::ShowTool</TargetTool>

                           <NewWindow>false</NewWindow>

                           <EntryPointParams>

                                  <Param name=”Param1”>Value1</Param>

                                  <Param name=”Param2”>Value2</Param>

                                  <Param name=”Param3”>Value3</Param>

                           </EntryPointParams>

                     </NavigationCommand>

              </CommandMapping>

XML Block 15

A powerful feature in the XML Node definition is the use of Replacement Tags. Replacement Tags can be used to insert State Variable values or IBPM Web Infrastructure Data into a Work Center Node definition value.

Replacement Tags are supported in the TargetTool sub element value, The NewWindowATO value as well as each of the Parameter values and names. XML Block 16 demonstrates the use of

A sample Command Mapping Node of type NavigationCommand using NewWindow

              <CommandMapping command="ShowAdminDefaultsTool" type="NavigationCommand">

                     <NavigationCommand>

                            <TargetTool>::AdminInfrastructureDefaultsTool::ShowTool</TargetTool>

                           <NewWindow>false</NewWindow>

                           <EntryPointParams>

                                  <Param name=”Param1”>[ACORDESTATEVARIABLE:MyVar1]</Param>

                                  <Param name=”Param2”>[ACORDESTATEVARIABLE:MyVar2]</Param>

                                  <Param name=”Param3”>[ACORDESTATEVARIABLE:MyVar3]</Param>

                           </EntryPointParams>

                     </NavigationCommand>

              </CommandMapping>

XML Block 16

Replacement Tags in navigation as Parameter Values to an Entry Point. In this case the values of the State Variables will be passed in as parameters to the Tool as opposed to passing in the literal values shown in XML Block 15. For a complete listing of the supported Replacement Tags see Appendix B.

The ChangeStateCommand Command Type

The command type ChangeState specifies a state variable should be changed to a new value. XML Block 17 illustrates the use of a Change State Command.

A sample Command Mapping Node of type ChangeState

              <CommandMapping command="ChangeStateToSystem" type="ChangeStateCommand">

                     <ChangeStateCommand type=”SETVALUE”>

                           <StateVariableName>GENERALMODE</StateVariableName>

                           <NewValue>System</NewValue>

                     </ChangeStateCommand>

              </CommandMapping>

XML Block 17

This is an excerpt from the Dashboard Work Center node definition file. Notice the type of the ChangeStateCommand in this example is SETVALUE. Currently this is the only change state command type that is supported. Change State command can allow a user to control the mode of a Work Center Node. In the case of the Dashboard node the change state command is used to record the user’s selection of the audit category from the toolbar. Figure 8 illustrates the affect of a user clicking on the toolbar in the Dashboard Work Center Node and the state changing from “Document” to “System”.

Figure 8: One of the affects of the GENERALMODE state variable

changing in the Dashboard Work Center Node

There are also other affects that are also controlled by the state of the GENERALMODE state variable in the Dashboard Work Center Node such as the content of the sub-category list. Further discussion of State Variables and their use will be covered in later sections of this document.

As in other Command Mapping types Replacement Tags are supported by the ChangeStateCommand Command Mapping type. They are supported in the StateVariableName element value and the NewValue element value. For a complete listing of the supported Replacement Tags see Appendix B.

The URL Command Type

The command type URL specifies that a specific URL should be displayed by the IBPM Web Client when the command is executed. This URL can be launched in the main IBPM Web Workspace or in a new window. XML Block 18 illustrates the use of a URL Command Mapping type element.

A sample Command Mapping Node of type URL

       <CommandMapping command="NavToURL" type=”URL”>

              <URL>

              http://myWebServer/IBPMDashboard/DocumentQuerySummary.aspx?

              AID=%7b1FAAC076-704D-449D-AB77-5B3AE178C397%7d%3a13148786&amp;Category=0

              &amp;StartDate=10%2f13%2f2003&amp;EndDate=11%2f13%2f2003

              &amp;user=&amp;server=&amp;application=

              </URL>

              <NewWindow>false</NewWindow>

       </CommandMapping>

XML Block 18

As in the previous Command Mapping types, Replacement Tags are supported by the URL Command Mapping type. They are supported in the URL element value and the NewWindow element value. For a complete listing of the supported Replacement Tags see Appendix B.

The PublishXML Command Type

The command type PublishXML specifies an XML document that should be published to the IBPM Web State Document. This allows your Work Center node to publish data making it available to any of the IBPM Web Tools or IBPM Web Custom Tools. It is also possible for external web applications that have been integrated with IBPM Web to obtain information that has been published by your XML Work Center Node. XML Block 19 illustrates the use of a PublishXML Command Mapping type.

A sample Command Mapping Node of type PublishXML

       <CommandMapping command="PublishMyDocument" type=”PublishXML”>

              <ToolName>MyTool</ToolName>

              <IntegrationPointEvent>MyItegrationPointEventName</IntegrationPointEvent>

              <Description>My custom publication in IBPM Web</Description>

              <Data>

                     <AnyXMLDocument xmlns=”##AnyNamespace”>

                           <MyData>[ACORDESTATEVARIABLE:MyVar1]</MyData>

                           <Children>

                                  <Child>[ACORDESTATEVARIABLE:MyVarC1]</Child>

                                  <Child>[ACORDESTATEVARIABLE:MyVarC2]</Child>

                                  <Child>[ACORDESTATEVARIABLE:MyVarC3]</Child>

                           </Children>

                     </AnyXMLDocument>

              </Data>

       </CommandMapping>

XML Block 19

The ToolName element is an optional element that allows you to specify the ToolName you want to publish the document under. This allows you to “mimic” some other tools functionality with your XML Publication. It also allows you to specify a more meaningful Publication ToolName than the default. If this element is left out then you will publish under your XML Work Center nodes class name, which is generally the name of your XML Work Center node file name prepended by a “AXMLWCN_”.

The IntegrationPointEvent element is another optional element that allows you to specify the Integration Point Event you want the published data to be for. Again, this can allow you to “mimic” some other tools functionality with your XML Publication. It is also used to allow you to specify a more meaningful name for the data than the default name. If this element is left out then you will publish the data using the Command ID of the node that triggered the Processing of the PublishXML command.

As in the previous Command Mapping types, Replacement Tags are supported by the URL PublishXML element. You will notice in XML Block 19 that several Replacement Tags are included in the “AnyXMLDocument” element and its children. Before publication of the XML Document those tags will be replaced with data. For a complete listing of the supported Replacement Tags see Appendix B.

The PromptForStateValues Command Type

The command type PromptForStateValues tells the IBPM Web Infrastructure to prompt the user for some of the State Values that are defined in the StateVariables element of the IBPM Work Center Node Definition XML File. This is useful if you need the user to provide inputs to a Web Service call or to provide settings for your XML Work Center Node.

You can provide a prompt for the user as well as which Prompt Groups you want the IBPM Web Client to display to the user. XML Block 20 demonstrates the format of the PromptForStateValues element.

A sample Command Mapping Node of type PromptForStateValues

       <CommandMapping command="PromptForSearchValues" type=”PromptForStateValues”>

              <Instructions>Enter the filter values for the Audit Sub-Categories:</Instructions>

              <PromptSet>

                     <PromptGroup>a</PromptGroup>

                     <PromptGroup>b</PromptGroup>

              </PromptSet>

       </CommandMapping>

XML Block 20

In this example, the user will be prompted for the values defined as members of Prompt Group “a” and “b”. The prompt to the user will be “Enter the filter values for the Audit Sub-Categories:”. Once the user has entered new values in the Work Center State Variable Prompt Tool, the XML Node will be refreshed and redisplayed to the user.

As discussed in the State Variable section of this document, you can obtain valid lists of State Variable values from a web service to be presented to the user in a Combo Box. Additionally, you can specify that you want a web service to have a chance at validating the Prompt Data before it is recorded in the Work Center Node session state.

XML Block 21 illustrates how to specify that the state variable value set that is generated through prompting the user should be sent to a Web Service Sequence for validation.

A sample Command Mapping Node of type PromptForStateValues that validates the prompt values

<CommandMapping command="PromptForSearchValues" type=”PromptForStateValues”>

       <Instructions>Enter the filter values for the Audit Sub-Categories:</Instructions>

       <PromptSet>

              <PromptGroup validation="ValidateGroupA">a</PromptGroup>

              <PromptGroup validation="ValidateGroupB">b</PromptGroup>

       </PromptSet>

       <Validations>

              <Validation name="ValidateGroupA"

                   type="WEBSERVICE"

                   WebServiceSequence="AWCN_OptikaStockSample3::WSSValidateGroupA(ValidateGroupA)"/>

              <Validation name="ValidateGroupA"

                   type="WEBSERVICE"

                   WebServiceSequence="AWCN_OptikaStockSample3::WSSValidateGroupA(ValidateGroupB)"/>

       </Validations>

</CommandMapping>

XML Block 21

Notice that each of the Prompt Groups are validated separately allowing you to use a single interface to prompt a user for information that will be sent to disparate web services for validation.

The Validation elements specify a WebServiceSequence that should be used to prompt the user. Notice that the Web Service Sequence call passes the name of the Validation in as a parameter to the Web Service Sequence. When the validation request document is constructed an undefined state variable is set that has the same name as the Validation. The value of this variable is the constructed Validation Request document. XML Block 22 is a sample of the XML document that is passed to the Web Service Sequence.

A sample AcordeValidationRequest XML Document

<AcordeValidationRequest version="1.0"

     xmlns="http://Optika.com/schemas/AcordeInfrastructure/AcordeValidationRequest">

       <ValidationValueSet>

              <ValidationValue>

                     <Name>MyStateVar1</Name>

                     <Value>The Value of Variable One</Value>

              </ValidationValue>

              <ValidationValue>

                     <Name>MyStateVar2</Name>

                     <Value>The Value of Variable Two</Value>

              </ValidationValue>

       </ValidationValueSet>

</AcordeValidationRequest>

XML Block 22

You should also note that that document will contain the submitted values not the current state values for the state variable that are being validated. This is because we do not want to set the state variable until after the new values are validated.

You should also note that this is the Document that is passed into the Validation Web Service Sequence. That doe not necessarily mean that this is the document that the web service needs to accept. Web Service Sequences can transform the document into any format required by the web service before it is called

The Web Service Sequence should return an AcordeValidationResponse document. XML Block 23 illustrates the format of the response document.

A sample AcordeValidationResponse XML Document

<AcordeValidationResponse version="1.0"

     xmlns="http://Optika.com/schemas/AcordeInfrastructure/AcordeValidationResponse">

       <ValidationSummary>

              <SetIsValid>False</SetIsValid>

              <DisplayMessage>'Value1' and 'Value2' must be corrected.</DisplayMessage>

       </ValidationSummary>

       <ValidationResults>

              <ValidationResult>

                     <Name>MyStateVar1</Name>

                     <Value>2</StatusCode>

                     <IsValid>False</IsValid>

                     <DisplayMessage>'Value1' must be larger than 'Value2'.</DisplayMessage>

              </ValidationResult>

              <ValidationResult>

                     <Name>MyStateVar2</Name>

                     <Value>50</StatusCode>

                     <IsValid>False</IsValid>

                     <DisplayMessage>'Value2' must be smaller than 'Value1'.</DisplayMessage>

              </ValidationResult>

       </ValidationResults>

</AcordeValidationResponse>

XML Block 23

The prompt tool will notify the user of the problem with the prompted values and the user will be required to fix that problem before the data is stored in a State Variable.

The FireClientEvent Command Type

The command type FireClientEvent tells the IBPM Web Infrastructure to fire an IBPM Client Event on the client side. This allows you to fire a client side event that may be handled by one of the Standard IBPM Web Tools, by the IBPM Web Client Infrastructure or by one of your Custom IBPM Web tools that is built to work with your Custom IBPM Web Work Center Node. You are also provided the option of passing some string data to that event handler. XML Block 20 illustrates the use of a FileClientEvent command type.

A sample Command Mapping Node of type FireClientEvent

       <CommandMapping command="NotifySiblingTool" type=”FireClientEvent”>

              <Scope>MyCustomTool</Scope>

              <Event>onLoadNextPage</Event>

       </CommandMapping>

XML Block 24

In this example, the IBPM Web Infrastructure will look through the frames loaded in the client side browser for a function named “Acorde_MyCustomTool_onLoadNextPage()” and call into it if it is found. In the example shown below in XML Block 25 the event will be called and the value of the State Variable “MyVarData1” will be passed to the client side event handler.

A sample Command Mapping Node of type FireClientEvent with data

       <CommandMapping command="NotifySiblingTool" type=”FireClientEvent”>

              <Scope>MyCustomTool</Scope>

              <Event>onLoadNextPage</Event>

              <Data>[ACORDESTATEVARIABLE:MyVarData1]<Data>

       </CommandMapping>

XML Block 25

Both elements Scope and Event are required elements. If either is not present then the command will be ignored and an error will be displayed in the status bar of the browser.

The WebServiceCommands Command Type

The command type WebServiceCommands allows you to indicate that you want a series of web service sequence commands to be made. Web Service Sequences are defined in files in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AcordeWebServiceSequenceLibraries

You will need to create a Web Service Sequence Library XML file and place it in that directory. A Web Service Sequence Library contains the definition of one or more Web Service Sequences. A Web Service Sequence defines one or more Web Service Sequence Steps. These steps define taking data from the IBPM Web Client Infrastructure and passing it to one or more Web Services to obtain response data. That response data can then be manipulated and returned out of the Web Service Sequence. The data from a Web Service can be cached by the Web Service Sequence to improve performance Sequences that interact with web service that may not provide real time data. The creation of Web Service Sequence Libraries is discussed in another white paper on that topic.

The WebServiceCommands command type allows you to perform the following function on a Web Service Sequence:

- EXPIRE – Allows you to expire the results from a Web Service Sequence

- EXECUTE or CALL – Allows you to call a Web Service Sequence

The WebServiceCommands command type contains a “WebServiceCommands“ element as its first child. The “WebServiceCommands” element contains an array of “WebSeviceCommand” elements.

The sample shown in XML Block 26 illustrates the use of a WebServiceCommands to first reset or “EXPIRE” the cached return value of the “DemoTransforms” Web Service Sequence in the “AWCN_OptikaStockSample3” Web Service Sequence Library.

A sample Command Mapping Node of type WebServiceCommands

<CommandMapping command="ExchangeData" type="WebServiceCommands">

       <WebServiceCommands>

              <WebServiceCommand type="EXPIRE">

                     <SequenceName>AWCN_OptikaStockSample3::DemoTransforms</SequenceName>

              </WebServiceCommand>

              <WebServiceCommand type="CALL">

                     <SequenceName>AWCN_OptikaStockSample3::DemoTransforms(SYMBOLTOUSE)</SequenceName>

              </WebServiceCommand>

       </WebServiceCommands>

</CommandMapping>

XML Block 26

This means that the next time that Web Service Sequence is called it will be sure to execute. The next WebSeviceCommand calls the Web Service Sequence that was just expired.

Notice that you can pass State Variable into the Web Service Sequence. The call being made in XML Block 26 is passing in one of its state variables named “SYMBOLTOUSE”. This may be the sock symbol that the user was prompted for. The Web Service Sequence defines input parameters that will map the values passed from this Work Center node State Variable to the Web Service Sequence State Variable. The Web Service Sequence can then pass that data to an external Web Service for processing. You can pass in multiple State Variables to a Web Service Sequence using a comma-delimited list as shown below:

AWCN_OptikaStockSample3::DemoTransforms(SYMBOLTOUSE, DATAMODE)

That list will be parsed and the all the values will be sent to the Web Service Sequence for processing.

Although Web Service Sequence State Variables are accessible through the use of “Replacement Tags”, you may wan the results from the Web Service Sequence execution to be placed into one of your Work Center Node State Variables. This is accomplished by adding a “StateVariable” element to the “Call” type Web Service Command. This is illustrated in XML Block 27.

A sample Command Mapping Node of type WebServiceCommands placing the WSS results in a state variable

<CommandMapping command="ExchangeData" type="WebServiceCommands">

       <WebServiceCommands>

              <WebServiceCommand type="EXPIRE">

                     <SequenceName>AWCN_OptikaStockSample3::DemoTransforms</SequenceName>

              </WebServiceCommand>

              <WebServiceCommand type="CALL">

                     <SequenceName>AWCN_OptikaStockSample3::DemoTransforms(SYMBOLTOUSE)</SequenceName>

                     <StateVariable>MyStateVariable</StateVariable>

              </WebServiceCommand>

       </WebServiceCommands>

</CommandMapping>

XML Block 27

After the Web Service Sequence is executed the returned value will be stored in the Work Center Node State Variable, “MyStateVariable”.

The CommandSequence Command Type

The command type CommandSequence allows you to specify a series of several CommandStep elements that are nothing more than CommandMapping nodes with a different name. This means that you can combine several CommandMapping nodes of varying types into a single complex CommandMapping node.

XML Block 28 illustrates the use of a CommandSequence Command Mapping Node.

A sample Command Mapping Node of type CommandSequence

<CommandMapping command="ChangeToSelect1" type="CommandSequence">

       <CommandStep type="ChangeStateCommand">

              <ChangeStateCommand type="SETVALUE">

                     <StateVariableName>Icon1</StateVariableName>

                     <NewValue>Bullet_Rect_Blue_2.gif</NewValue>

              </ChangeStateCommand>

       </CommandStep>

       <CommandStep type="ChangeStateCommand">

              <ChangeStateCommand type="SETVALUE">

                     <StateVariableName>Icon2</StateVariableName>

                     <NewValue>Bullet_Rect_Red_2.gif</NewValue>

              </ChangeStateCommand>

       </CommandStep>

       <CommandStep type="ChangeStateCommand">

              <ChangeStateCommand type="SETVALUE">

                     <StateVariableName>Icon1Selected</StateVariableName>

                     <NewValue>(Selected)</NewValue>

              </ChangeStateCommand>

       </CommandStep>

       <CommandStep type="ChangeStateCommand">

              <ChangeStateCommand type="SETVALUE">

                     <StateVariableName>Icon2Selected</StateVariableName>

                     <NewValue></NewValue>

              </ChangeStateCommand>

       </CommandStep>

       <CommandStep type="ChangeStateCommand">

              <ChangeStateCommand type="SETVALUE">

                     <StateVariableName>SelectedIndex</StateVariableName>

                     <NewValue>1</NewValue>

              </ChangeStateCommand>

       </CommandStep>

       <CommandStep type="FireClientEvent">

              <Scope>MyPubTool</Scope>

              <Event>Refresh</Event>

       </CommandStep>

       <CommandStep type="PublishXML">

              <ToolName>MyToolName</ToolName>

              <IntegrationPointEvent>MyIntegrationPointEventName</IntegrationPointEvent>

              <Description>The Data Published By Node Tool 1</Description>

              <Data>

                     <MyWorkCenterNodePublication xmlns="#MyToolNameSpace">

                           <MoreData>The Icon for Node 1 is [ACORDESTATEVARIABLE:Icon1]</MoreData>

                     </MyWorkCenterNodePublication>

              </Data>

       </CommandStep>

 </CommandMapping>

XML Block 28

This is an example of a command that changes the state of a selected item to the SelectedIndex of “1”. There are several actions that take place when this command is executed. The icon state variables are change; presumably these are used as the icon for the nodes being displayed. Two text state variables are changed one to “(Selected)” and the other to “”. The SelectedIndex state variable is changed to “1”. A client side event will be fired that could notify a tool that it needs to update. In this case the tool will need to implement the client side function:

Acorde_MyPubTool_Refresh()

Finally, the Work Center Node publishes an XML document to the IBPM Web Client State Document.

The StateVariable Element

We have presented several use cases that illustrate the basic concept of a StateVariable. This section delves into the details of Work Center Node State Variable and how they can be used. We provide a detailed description of the StateVariable element type and its available features.

The basic purpose of a state variable is its ability to act as a storage location for data that is relevant to the operation and behavior of a Work Center Node.

Through the use of Replacement Tags (Appendix B) Work Center Node state variables can be inserted into many of the Work Center Node Definition element types allowing for dynamically generated session data to be passed to web services or custom tools as well as displayed to users in the Work Center.

State variable prompt groups allow you to group variables that a user can manipulate through the IBPM Web prompt tool. Additionally, the prompt tool makes it possible to call a web service to obtain lists of values for state variables. The prompt tool also makes it possible to validate prompted data through the use of a web service.

Through the use of State Variables you can define preferences for your Work Center Node that are saved with the users IBPM Web Preferences. This form of state variable creates a customizable user environment that can be implemented through simple XML definition in the Work Center Node Definition file.

Let’s first take a look at a simple State Variable definition. XML Block 29 illustrates the definition of a single state variable, SYMBOLTOUSE.

A sample StateVariables element

<StateVariables>

       <StateVariable name="SYMBOLTOUSE" type="string"

            persisttype="session" prompted="true" promptgroup="a">

              <ReadablePrompt>Stock Symbol:</ReadablePrompt>

              <ValueSet type="LIST">

                     <Value default="true">STEL</Value>

              </ValueSet>

       </StateVariable>

</StateVariables>

XML Block 29

This is the State Variable definition for the State Variable used in XML Block 26 to make a Web Service call. First, you should understand that you can reference a State Variable that has not been explicitly defined in a Work Center Node Definition File. It can be referenced in Web Service Calls, Replacement Tags and ChangeStateCommand elements in the CommandMappings. An undefined State Variable will have default behavior that includes a default value of “” (an empty string) and a default persist type of “session”. An undefined State Variable is not prompted and belongs to no Prompt Group. That being said, if you do not want those default behaviors you will need to provide a StateVariable element to define how your state variable should behave.

The definition in XML Block 29 defines a State Variable named “SYMBOLTOUSE”. That variable is prompted and it is a member of prompt group “a”. It has a persistence type of “session” which means that at the beginning of each session it will revert back to its defined default value of “STEL”.

The name Attribute

The name attribute defines the name of the State Variable. This should only have alphanumeric characters and should start with a letter. This will be the string that refers to the state variable when constructing Web Service Sequence Calls and Replacement Tags. This will also be how the variable is referenced by ChangeStateCommand elements.

The type Attribute

The type attribute defines the type of the State Variable. Currently we only support the types “string”, “date” and “xml”.

The persisttype Attribute

The persisttype attribute defines the type of persistent storage that will be used when holding the state variable. The currently supported persisttype values include:

- “session” – The state variable will keep its value for the entire session. When the user logs out and back in the value will revert back to its default.

- “preference” – The state variable will keep its value across sessions. When the user changes the value of the state variable it will be stored in the IBPM Data preference folder on the web so when they log out and log back in the value will remain as what they set it to.

- “none” or “” – The variable is a Page State Variable. This means that the variable can change as the page is being processed but will revert back to its default value on the next round of processing the ASP page.

The use case of “none” is pretty limited and will probably only be used on very complex Work Center Nodes. However, the use of “preference” is extremely powerful. In addition to holding state for the Work Center Node being defined, you can use this as a preference mechanism for a Custom Tool that you may be developing.

The prompted Attribute

This indicates whether or not this state variable is prompted.

The promptgroup Attribute

If this state variable is prompted this attribute indicates which prompt group this state variable belongs to. This allows a CommandMapping to specify that the user should be prompted for this value.

The ReadablePrompt Element

The text in this element is used as the prompt text if the State Variable is displayed to the user as a Prompt.

The ValueSet Element

This element defines the values that are appropriate for the State Variable. The value set can have two types. They are:

- LIST – the values are provided in a list one of which is the default value.

- WEBSERVICELIST – The values are obtained from a Web Service Sequence. There can still be a default value specified.

If the values are obtained from a Web Service Sequence then the format of the return value from the Web Service Sequence must be an AcordeStateVariableValues. XML BLOCK is an example of the format for an AcordeStateVariableValues XML Document.

A sample AcordeStateVariableValues element

<AcordeStateVariableValues version="1.0"

   xmlns=”http://Optika.com/AcordeInfrastructure/AcordeStateVariableValues”>

       <VariableValue>

              <Display>One</Display>

              <Value>Value1</Value>

       </VariableValue>

       <VariableValue>

              <Display>Two</Display>

              <Value>Value2</Value>

       </VariableValue>

       <VariableValue>

              <Display>Three</Display>

              <Value>Value3</Value>

       </VariableValue>

</AcordeStateVariableValues>

XML Block 30

These values will be presented to the user in a combo box that displays “Display” value and when the user selects an item the State Variable will be set to the corresponding “Value” element.

Remember that the Web Service Sequence must return this format of a document. However, the web service can provide a different formatted document and the Web Service Sequence can transform that format into this document format. XML Block 31 illustrates a State Variable that can get its value list from a Web Service Sequence when the user is prompted.

A sample StateVariable element that gets its values from a Web Service Sequence

<StateVariables>

       <StateVariable name="SYMBOLTOUSE" type="string"

            persisttype="preference" prompted="true" promptgroup="a">

              <ReadablePrompt>Stock Symbol:</ReadablePrompt>

              <ValueSet type="WEBSERVICELIST"

                   WebServiceSequence="AWCN_OptikaStockSample3::WSSGetQuoteGroups">

                     <Value default="true">STEL</Value>

              </ValueSet>

       </StateVariable>

</StateVariables>

XML Block 31

The EventHandler Element

You may need to provide Custom Tools or other Work Center nodes the ability to notify your Work Center Node of some event or change in state that it needs to know. This event or change in state may require your Work Center node to update its User Interface or take some other action.

For example, Custom Tools have the ability to change the State Variable value of a Work Center Node. If this happens your node may need to be refreshed.

The EventHandler provides you the ability to specify that your Work Center Node is listening for a particular event. If that event is fired on the client side your Work Center Node can specify which Command it will need to process in response to the client Side Event. XML Block 32 illustrates the specification of two client side event handlers.

A sample EventHandler element

<AcordeClientEventHandlers>

       <EventHandler fireOnLoad="false">

              <Scope>MyEventNode</Scope>

              <Event>ChangeToRed</Event>

              <Command>ChangeIconsToRed</Command>

       </EventHandler>

       <EventHandler fireOnLoad="false">

              <Scope>MyEventNode</Scope>

              <Event>ChangeToGreen</Event>

              <Command>ChangeIconsToGreen</Command>

       </EventHandler>

</AcordeClientEventHandlers>

XML Block 32

The first executes the CommandMapping named ChangeIconsToRed and the second executes the CommandMapping named ChangeIconsToGreen. JavaScript Block 2 illustrates how a Custom Tool could fire the event that causes the Node to execute the ChangeIconsToGreen command.

// In this sample we fire the event in our window on load. You would fire

// it when you needed to.

function window_onload ()

{

// Get the Cutom Tool Infrastructure and Fire the event.

var objACWI = getAcordeCustomWebInfrastructure();

objACWI.FireEvent("MyEventNode","ChangeToGreen");

}

JavaScript Block 2

There is no way to specify the Command to be executed in-line with an Event Handler so you will need to define that command in the AcordeCommandMap using a CommandMapping element.

The NodeGroup Element

Work Center nodes other than the type “TOPLEVELNODE” are defined as arrays contained in NodeGroup elements. This includes “SUBNODE” and “TOPTOOLBAR” Work Center Nodes. The NodeGroup provides a mechanism to control the display of groups of node based on Availability Tests. XML Block 33 is an excerpt from the Dashboard XML Work Center Node.

A sample NodeGroup element

              <NodeGroup name="CatTitle" type="DATA" sessionstatic="true">

                     <WorkCenterNode type="SUBNODE">

                           <Icon>Bullet_blank.gif</Icon>

                           <Caption>Audit Sub-Categories: [ACORDESTATEVARIABLE:GENERALMODE]</Caption>

                            <Name>CatTitleUser</Name>

                           <Command></Command>

                     </WorkCenterNode>

              </NodeGroup>

XML Block 33

This sample demonstrates the use of a Node Group that contains a single node.

In addition to defining Work Center Nodes directly inline as “DATA” in the Work Center Node Definition file, NodeGroup elements can specify that their Node Content should be obtained from a Web Service Sequence. This is a powerful feature that allows you to display web service response data directly in the IBPM Web Work Center. XML Block 34 is an excerpt from the Dashboard node and demonstrates the use of a “WEBSERVICE” type Node Group.

Sample NodeGroup elements that are WEBSERVICE node groups

<NodeGroup name="SearchResultsNodes" type="WEBSERVICE" sessionstatic="false" AvailabilityTest="IsDocuments"

     WebServiceSequence="DashboardWebServices::GetDocumentsNodes(SERVICEMACHINE,

                                  STARTDATE,ENDDATE,USERNAME,SERVER,APPLICATION,RUNSEARCH)"/>

<NodeGroup name="SearchResultsNodes" type="WEBSERVICE" sessionstatic="false" AvailabilityTest="IsSystem"

     WebServiceSequence="DashboardWebServices::GetSystemNodes(SERVICEMACHINE,

                                  STARTDATE,ENDDATE,USERNAME,SERVER,APPLICATION,RUNSEARCH)"/>

<NodeGroup name="SearchResultsNodes" type="WEBSERVICE" sessionstatic="false" AvailabilityTest="IsUser"

     WebServiceSequence="DashboardWebServices::GetUserNodes(SERVICEMACHINE,

                                  STARTDATE,ENDDATE,USERNAME,SERVER,APPLICATION,RUNSEARCH)"/>

<NodeGroup name="SearchResultsNodes" type="WEBSERVICE" sessionstatic="false" AvailabilityTest="IsFullText"

     WebServiceSequence="DashboardWebServices::GetFullTextNodes(SERVICEMACHINE,

                                  STARTDATE,ENDDATE,USERNAME,SERVER,APPLICATION,RUNSEARCH)"/>

XML Block 34

There are several other features demonstrated in XML Block 34. Each of the Node Group elements provides an AvailabilityTest attribute. In the Dashboard Work Center Node Definition file these Availability tests are mutually exclusive so only one of the node groups will be displayed at any one time.

The name Attribute

The required name attribute defines the name of the NodeGroup and allows it to be references using that name from other areas in the Work Center Node XML Definition document.

The type Attribute

The type attribute indicates the type of the NodeGroup. IBPM currently supports the following NodeGroup types:

- DATA – The node group contains child nodes of the main Top Level Node.

- WEBSERVICE – The node group no WorkCenterNode child element. Rather, IBPM needs to execute a Web Service Sequence to obtain the nodes for the Node Group.

- TOPTOOLBAR – The node group contains Top Toolbar Work Center Nodes. These will be displayed just under the Top Level Node across rather than down.

- BOTTOMTOOLBAR – The node group contains Bottom Toolbar Work Center Nodes. These will be displayed after all the child nodes across rather than down.

At this time we do not support obtaining toolbars from a Web Service. Only child nodes can be obtained from a web service.

The sessionstatic Attribute

The optional sessionstatic attribute indicates whether or not the node group content might change during a user session. If there are no sessionstatic=”false” attributes on any of the NodeGroup elements then the IBPM Web Infrastructure will cache the Child Node description from the Work Center Node to improve performance. If any of the node groups in the XML Definition File indicate that they are NOT session static the IBPM Web Infrastructure will take that into account.

The AvailabilityTestObject Attribute

As with Work Center Node elements, you can specify a single IBPM Availability Test Object (ATO) object that will determine the availability of the Node Group. An IBPM ATO object is a JavaScript object that is written in ASP JavaScript and placed in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AvailabilityTestObjects

As was stated earlier, Availability Test Objects allow you to provide a richer test than a simple State Variable test. For instance, you may need to interact with a COM object on the Web Server to determine if your Node Group should be available to the user. This mechanism allows you to do that.

The AvailabilityTest Child Element

There may be times when you want some node group hidden while you show other node groups and this may be based on State Variables that you have defined. It is possible provide a test that determines whether or not a node is available. This is done by defining an AvailabilityTest child element of the WorkCenterNode element. XML Block 35 illustrates the use of the AvailabilityTest in a NodeGroup element.

A WorkCenterNode element that has an AvailabilityTest defined

              <NodeGroup name="CatTitle" type="DATA" sessionstatic="true">

                     <AvailabilityTest>

                            <StateVariable>ShowCatTitle</StateVariable>

                           <Value>1</Value>

                           <UseNot>false</UseNot>

                     </AvailabilityTest>

                     <WorkCenterNode type="SUBNODE">

                           <Icon>Bullet_blank.gif</Icon>

                           <Caption>Audit Sub-Categories: [ACORDESTATEVARIABLE:GENERALMODE]</Caption>

                           <Name>CatTitleUser</Name>

                           <Command></Command>

                     </WorkCenterNode>

              </NodeGroup>

XML Block 35

As with Work Center Node elements you can define multiple AvailabilityTest elements as child elements to the NodeGroup element and define how their results are aggregated.

As with Work Center Node elements, Replacement Tags (Appendix B) are supported in the StateVariable element and the Value element.

The AvailabilityTest Attribute

You can also specify a single AvailabilityTest as an Attribute. Rather than specifying the test in line this will refer, by name, to an availability test defined in the AvailabilityTests array of the document located in the XPath location:

/AcordeWorkCenterNodeDefinition/AvailabilityTests/AvailabilityTest

XML Block 34 (above) illustrated the use of the AvailabilityTest in a NodeGroup element.

Appendix A: The JavaScript Work Center Node Object Interface

This section describes the Work Center Node JavaScript interface that is required for ASP defined Work Center Nodes. This interface is documented here for completeness sake. The intended mechanism for Work Center extension is the XML Work Center node and not the JavaScript Work Center Node; however, there are some features of the Work Center that are not yet exposed through the XML Work Center specification. If you are planning on creating a new Work Center Node you should first try to accomplish this through the use of the XML Work Center Node.

function _AWCN_MyCustomNode()

{

       // Allows the work center to determine if it should

       // display the node return true or false.  You can run

// any tests here to determine if the node should be

// displayed

       function _Display()

       {

              return true;

       }

       this.Display = _Display;

       // Allows the work center to determine the rank of this

       // node for display purposes

       function _GetRank()

       {

              return 950;

       }

       this.GetRank = _GetRank;

       // Allows the work center to get the text to display

       // to the user for the node

       function _GetLabel()

       {

              return "My Node Label";

       }

       this.GetLabel = _GetLabel;

       // Allows the work center to get the name of this node

       // No spaces or special characters are allowed this is

       // used as a JavaScript variable name so it should be

       // structured as one

       function _GetName()

       {

              return "TopLevelForMyNode"

       }

       this.GetName = _GetName;

       // Allows the work center to get the command for the

       // node when the user clicks on it. Again, no spaces

       // or special characters are supported

       function _GetCommandID()

       {

              return "ShowToolSearchResults";

       }

       this.GetCommandID = _GetCommandID;

       // Allows the work center to request that this node

       // process one of its commands.  A string of Client

// Side JavaScript that can be run on the client side

       function _ProcessCommand(strCommandID, strNodeName)

       {

              var strClientCode = "<";

              strClientCode += "script language=javascript>";

              strClientCode += "alert('My command handler...');";

              strClientCode += "getAcordeCustomWebInfrastructure()”

strClientCode += ".ShowTool(\"WizardTool\");";

              strClientCode += "<";

              strClientCode += "/script>";

              return strClientCode;

       }

       this.ProcessCommand = _ProcessCommand;

// Allows the work center to request the array of

// objects that define client side events that this node

// handle

       function _GetEventHandlerCommands()

       {

              var arrReturn = new Array();

              var i = 0;

              arrReturn[i] = new Object();

              arrReturn[i].Name = "NodeNameToEmulate";

              arrReturn[i].FireOnLoad = false;

              arrReturn[i].Scope = "ClientScopeName";

              arrReturn[i].Event = "onMyEventName";

              arrReturn[i++].CommandID = "CommandIdToUse";

              return arrReturn;

       }

       this.GetEventHandlerCommands = _GetEventHandlerCommands;

// Allows the work center to request the array of

// objects that define the top toolbar for the node.

       function _GetTopToolbarCommands()

       {

              var arrReturn = new Array();

              var i = 0;

              arrReturn[i] = new Object();

              arrReturn[i].Label = "";

              arrReturn[i].Name = "MyNodeName";

              arrReturn[i].BulletImage = "Bullet_Double_Up_Green_2.gif";

              arrReturn[i++].CommandID = "TheCommandId";

              return arrReturn;

       }

       this.GetTopToolbarCommands = _GetTopToolbarCommands;

// Allows the work center to request the array of

// objects that define the bottom toolbar for the node.

       function _GetBottomToolbarCommands()

       {

              var arrReturn = new Array();

              var i = 0;

              arrReturn[i] = new Object();

              arrReturn[i].Label = "";

              arrReturn[i].Name = "MyNodeName";

              arrReturn[i].BulletImage = "Bullet_Double_Up_Green_2.gif";

              arrReturn[i++].CommandID = "TBCommand1";

              return arrReturn;

       }

       this.GetBottomToolbarCommands = _GetBottomToolbarCommands;

       // Allows the work center to get the collection of

       // child nodes for this object.

       function _GetChildren()

       {

              var arrReturn = new Array();

              var i = 0;

              arrReturn[i] = new Object();

              arrReturn[i].Label = "My Node 1";

              arrReturn[i].Name = "MyNodeName1";

              arrReturn[i].BulletImage = "Bullet_Double_Up_Green_2.gif";

              arrReturn[i++].CommandID = "NodeOne";

              arrReturn[i] = new Object();

              arrReturn[i].Label = "My Node 2";

              arrReturn[i].Name = "MyNodeName2";

              arrReturn[i].BulletImage = "Bullet_Double_Up_Green_2.gif";

              arrReturn[i++].CommandID = "NodeTwo";

              return arrReturn;

       }

       this.GetChildren = _GetChildren;

       // Allows the work center to determine if this object is

       // session static.  If it is then it will speed up Work

       // Center processing by caching the HTML it generates from

       // the Child Collection.

       function _IsSessionStatic()

       {

              return true;

       }

       this.IsSessionStatic = _IsSessionStatic;

       // Allows the work center to get Icon to use

       // for the object in the UI

       function _GetIconImage()

       {

              return "NAV_SearchResults.gif";

       }

       this.GetIconImage = _GetIconImage;

}

Appendix B: Supported Replacement Tags

This section describes the tags that are supported for replacement in text values in the IBPM XML Work Center Nodes.

In many of the values extracted from a Work Center Node definition file the IBPM Infrastructure will scan the text value of the data for the tags listed in this section. The tag indicates that specific data needs to be extracted from the IBPM Web Infrastructure and put into the data value replacing the tag completely. Tags are available to insert State Variables, Data from the XML Publication Document and IBPM Web Infrastructure values.

The following is a complete summary of all the supported Replacement Tags that are scanned for along with a short description of how those tags are processed.

Tag Format | Replacement Description
[ACORDESTATEVARIABLE:StateVariableName] | The Tag Text is replaced with the value of the state variable that is named in the tag. Simple names such as the one shown reference state variable defined in your Work Center Node Definition file. You can reference Web Service Sequence state variable if your StateVariableName takes the form: WebServiceSequenceLibrary::SequenceName::VariableName
[ACORDESTATEVARIABLEESCAPED:StateVariableName] | The Tag Text is replaced with an escaped version of the value of the state variable that is named in the tag. This is useful if you are placing XML in a string element of an XML document. As in the case of un-escaped variables, simple names such as the one shown reference state variable defined in your Work Center Node Definition file. Again, you can reference Web Service Sequence state variable if your StateVariableName takes the form: WebServiceSequenceLibrary::SequenceName::VariableName
[:ACORDEPUBLICATIONTEXT:MyXPath:] | Notice that the tag is delimited with a “[:” and a “:]”. This is required due to the fact that XPath can contain “[“ and “]”. The Tag Text is replaced with the text of the node in the IBPM State Document found using the specified XPath statement.
[:ACORDEPUBLICATIONXML:MyXPath:] | Again, notice that the tag is delimited with a “[:” and a “:]”. This is required due to the fact that XPath can contain “[“ and “]”. The Tag Text is replaced with the XML of the node in the IBPM State Document found using the specified XPath statement.
[:ACORDEPUBLICATIONXMLESCAPED:MyXPath:] | Again, notice that the tag is delimited with a “[:” and a “:]”. This is required due to the fact that XPath can contain “[“ and “]”. The Tag Text is replaced with an escaped version of the XML of the node in the IBPM State Document found using the specified XPath statement.
[ACORDESTATECONSTANT:TODAYSDATE] | The Tag Text is replaced with a string version of the current date. This date will be formatted in the language the user is logged in with.
[ACORDESTATECONSTANT:LASTMONTH] | The Tag Text is replaced with a string version of the current date minus one month. This date will be formatted in the language the user is logged in with.
[ACORDEINFRASTRUCTURE:LANGUAGE] | The Tag Text is replaced with a string indicating the selected Language ID the user is using.
[ACORDEINFRASTRUCTURE:AIID] | The Tag Text is replaced with a string containing the current IBPM Infrastructure Initialization Document (AIID) for the session.
[ACORDEINFRASTRUCTURE:ENCODEDAIID] | The Tag Text is replaced with an encoded string containing the current IBPM Infrastructure Initialization Document (AIID) for the session.
[ACORDEINFRASTRUCTURE:PUBLICATIONURL] | The Tag Text is replaced with a URL to the IBPM Web Client publication document that publishes the current state of the IBPM Web Client.
[ACORDEINFRASTRUCTURE:ENCODEDPUBLICATIONURL] | The Tag Text is replaced with a URL to the IBPM Web Client publication document that publishes the current state of the IBPM Web Client.
[ACORDEINFRASTRUCTURE:USERNAME] | The Tag Text is replaced with the current User’s UserName.
[ACORDEINFRASTRUCTURE: UPPERCASEUSERNAME] | The Tag Text is replaced with an upper case version of the current User’s UserName.
[ACORDEINFRASTRUCTURE: LOWERCASEUSERNAME] | The Tag Text is replaced with a lower case version of the current User’s UserName.
[ACORDEINFRASTRUCTURE: ENCODEDUSERNAME] | The Tag Text is replaced with an encoded version of the current User’s UserName.


Web Service Integration Technologies using Work Services Sequence

This document focuses on XML based features available in the Web Client that can facilitate the following:

  • Extracting and preparing data from the IBPM Web Client for Web Service consumption
  • Calling Web Services from the IBPM Web Infrastructure
  • Presenting Web Services response data in the IBPM Web Client

Many new infrastructure features have been added to the IBPM Web Client to facilitate rapid development and integration. These features allow a developer to define IBPM Web Client functionality and integration points through the extensive use of XML Metadata.

With the Acorde 4.0 Web Client GA release, we have extended the use of XML Metadata through the use of Web Services. We have introduced the concept of a Web Service Sequence and a Web Service Sequence Library. Web Service Sequences provide a mechanism in the IBPM Infrastructure allowing the execution of Web Service calls. These Web Service Sequences are defined in XML files called Web Service Sequence Libraries located in the OTInfrastructure directory on the IBPM Web Client server.

This document is a non-normative description of the XML Web Service Sequence feature. We describe the functionality through examples as opposed to XML Schema.

The Web Service Sequence

The use of the Web Service (SOAP, WSDL, UDDI) has become a powerful mechanism for the integration of disparate systems. Web Services have become a standard embraced by all of the software industries leading companies. Many large industry leaders such as Oracle, PeopleSoft and Microsoft are providing Web Service provider/consumer infrastructure as native functionality in their systems. The ability to expose and consume functionality over the Internet and intranet through a standard allows integrators greater freedom in deciding what systems they want to use for integration.

IBPM has provided a large amount of Web Service provider functionality. Web Services available from IBPM include Imaging Search, Imaging Export, Process Package Search and Process Package manipulation. Until the Acorde 4.0 release direct support for Web Service consumption was not provided. IBPM Web 4.0 now provides Web Service consumer functionality built directly into the IBPM Web Client infrastructure. This new Web Service consumption functionality can be used in IBPM Web Custom Tools, XML Work Center Nodes and the new Web Service Dashboard Tool. This functionality has been productized in the IBPM Dashboard tools that were made available in the Acorde 4.0 release.

We have encapsulated Web Service consumption in a concept we call a Web Service Sequence. A Web Service Sequence allows you to extract data from the active IBPM Web session, format a Web Service request, execute one or more Web Service calls and finally process the Web Service response content. Web Service Sequences are defined in IBPM Web Service Sequence Libraries. Web Service Sequence Libraries are XML documents that are placed in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\AcordeWebServiceSequenceLibraries

You can create a new Web Service Sequence Library by constructing a definition XML file and placing that file in that directory. There is no need to restart IIS because the XML definition is loaded when the library is accessed.

The remainder of this document presents several examples of Web Services in the IBPM Web infrastructure.

Specification Syntax

This paper uses an informal syntax to describe the XML grammar of a Web Service Sequence Library document. The intent is not to provide a formal definition of the XML format rather to provide an easily readable description of the required formats of the XML to allow a developer to understand how the features should be used. The following describes the specification syntax:

  • The syntax appears as an XML instance, but the values indicate the data types instead of the values.
  • Characters are appended to elements and attributes as follows: “?” (0 or 1), “*” (0 or more), “+” (1 or more), “?+” (required one and only one)
  • Element names ending in “…” (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.
  • Grammar in bold has not been introduced earlier in the document, or is of particular interest in an example.
  • The text <-- extensibility element --> is a placeholder for elements from some “other” namespace (like ##other in XSD)
  • Examples starting with <?xml contain enough information to conform to this specification; other examples are fragments and require additional information to be specified in order to conform.
  • At times in the document we need to indicate a type and a value to allow the demonstration of the remainder of the document. This will be denoted in the following format: “typeName=value”. For example, “optBoolean=true” would show that the type should be optBoolean and the particular example is showing an example of the value being true.

XML Types

This white paper refers to some special types that are defined here. Along with the standard XSD types (such as string) we have defined some types here that restrict the string down to a set of characters or to a set of values. You will also note that some type values have “_1”, “_2”, “_3” and so on appended to their names. This is to provide illustration of variation in use as well as to facilitate discussion around the sample XML.

  • An optURL is a string that is a URL.
  • An optName is a string beginning with a letter and continuing with letters or digits. No spaces or special characters are allowed. Generally used to refer to instances of element types.
  • An optStateVariableName that corresponds to an optName of a State Variable in the context of the document in question
  • An optSequenceCall is a string that corresponds to a Web Service call formatted in the manner “WSSLName::WSSName(SVName1, SVName2,…)”
  • An optDelimeter is a string with a single character including space or special characters.
  • An optPlaceInStateVariableType is a string with one of the following values: “XPATHTEXT”, “PRE-TRANSFORM”, “POST-TRANSFORM”
  • An optBoolean is a string with one of the following values: “true”, “false”
  • An optMessageDataType is a string with one of the following values: “STATICXML”, “STATICXMLWITHVARIABLES”.
  • An optXSLTVarType is a string with one of the following values: “StateVariable”
  • An optWebServiceCallDefinitionType is a string with one of the following values: “SIMPLETYPESOAP”, “COMPLEXTYPESOAP”
  • An optWSSStepType is a string with one of the following values: “WEBSERVICECALL”, “TRANSFORM::AcordeWebPortalPublishedData”, “TRANSFORM”, “SEQUENCEAGGRIGATION”
  • An optTDInputType is a string with one of the following values: “DELIMITEDSTATEVARIABLE”, “XMLSTATEVARIABLE”, “XMLURL”

Abbreviations

This white paper uses several abbreviations for terms throughout. The following summarizes those abbreviations:

  • WSS – Web Service Sequence
  • WSSName – A name of a Web Service Sequence
  • WSSL – Web Service Sequence Library
  • WSSLName – A Name of a Web Service Sequence Library. This is the file name minus the extension.

The Web Service Sequence

This section examines a basic Web Service Sequence defined in a Web Service Sequence Library. This section will examine this simple case in detail and introduce some basic concepts that will be expanded upon in later sections. XML Block 1 is a sample XML Document that defines a Web Service Sequence that calls a web service.

A sample Web Service Sequence Library XML file that can be used in the IBPM Web Client

<?xml version="1.0" encoding="utf-8" ?>

<AcordeWebServiceSequenceLibrary

   version="1.0"

   xmlns="http://Optika.com/AcordeInfrastructure/AcordeWebServiceSequenceLibrary">

   <!--

         ExecutionNameSpace

         This is the namespace used to execute any Web Service sequences in this

         document.  This helps segment the State Variable Storage.

   -->

   <ExecutionNameSpace>AWCN_OptikaStockSample3</ExecutionNameSpace>?+

   <!--

         WEB SERVICE SEQUENCES

         This section describes any Web Service Sequences that are defined Library.

         A Web Service Sequence is a sequence of web service calls that set State Variables

         that can be used in further sequence calls.  This can be useful if you need

         to call several Web Services to deliver values from one Web Service to another.

   -->

   <WebServiceSequences>?+

      <!--

         This Sequence goes and gets the stock price and stores it in this Web Sequence

         as a state variable.

      -->

      <WebServiceSequence

         name="WSSGetStockPrice"

         output="GeneratedNodeSet">*

         <!--

            InputParameterOrder:

            This element defines the order of input parameters for this sequence.

            This defines a mapping between an array of values and state variable names

            used in this AcordeWebServiceSequenceLibrary

         -->

         <InputParameterOrder>?

            <InputParameter stateVariableName="QuoteTickerList"/>

         </InputParameterOrder>

         <!--

            A TRANSFORM type WebServiceSequenceStep takes a state variable or a source doc at a URL

            and transforms it using XSLTs or a standard algorithm.  There are three supported input

            types

         -->

         <WebServiceSequenceStep type="TRANSFORM">*

            <!--

               First we need to transform the Ticker List into a

               Message for the service.

            -->

            <TransformationDefinitions>

               <!--

                  This one Transforms a delimited string into an AcordeValueArray once

                  the string is transformed into an XML it can be further transformed

                  before being placed in state if a transformname attribute is specified.

               -->

               <TransformationDefinition active="true">

                  <Input type="DELIMITEDSTATEVARIABLE"

                         delimiter=" "

                         trimvalues="true"

                         dropemptystrings="true">QuoteTickerList</Input>

                  <Output>QuoteTickerListXML</Output>

               </TransformationDefinition>

              <!--

                 This one Transforms a state variable that is assumed to be XML and

                 places it into a second state variable.

              -->

              <TransformationDefinition active="true">

                 <Input type="XMLSTATEVARIABLE"

                         transformname="ValueArrayToMessage">

                     QuoteTickerListXML

                  </Input>

                 <Output>QuoteTickerListMessage</Output>

              </TransformationDefinition>

            </TransformationDefinitions>

            <!—

               These XSLTransform elements are used by the Transformation Defs above. The

               first thing it does is transform the inpt using the XSLT.  After transforming

               the document, two string replacements are made to the created document.

            -->

            <XSLTransforms>

               <XSLTransform name="ValueArrayToMessage">

                  <XSLT>ValuesToMessage.xslt</XSLT>

                  <POSTTransformReplaceActions>

                     <!-- Get rid of the processing instruction -->

                     <ReplaceAction>

                        <StringToReplace>

                           &lt;?xml version="1.0" encoding="UTF-16"?&gt;

                        </StringToReplace>

                        <NewString></NewString>

                     </ReplaceAction>

                     <!-- Get rid of the extra namespace -->

                     <ReplaceAction>

                        <StringToReplace>

                           xmlns:s=http://Optika.com/schemas/AcordeInfrastructure/AcordeValueArray

                        </StringToReplace>

                        <NewString></NewString>

                     </ReplaceAction>

                  </POSTTransformReplaceActions>

               </XSLTransform>

            </XSLTransforms>

         </WebServiceSequenceStep>

         <WebServiceSequenceStep type="WEBSERVICECALL">

            <!-- WebServiceCallDefinitions: Make the Web Service Call-->

            <WebServiceCallDefinitions>

               <WebServiceCallDefinition type="complextypesoap" active="true">

                  <EndPointURL>

                     http://myWebServer/IBPMweb/services/SampleWorkCenterNode.asmx

                  </EndPointURL>

                  <SoapAction>

                     http://Optika.com/AcordeInfrastructure/AcordeWorkCenterNodeGroupService/GetQuotes

                  </SoapAction>

                  <MessageData type="StaticXMLWithVariables">

                     [ACORDESTATEVARIABLE:QuoteTickerListMessage]

                  </MessageData>

              </WebServiceCallDefinition>

            </WebServiceCallDefinitions>

            <!-- PlaceInStateVariable: Transform the Web Servcie Response into a Node Set-->

            <PostCallCommands>

               <PlaceInStateVariable type="PRE-TRANSFORM">

                  WebServiceResponse

               </PlaceInStateVariable>

               <PlaceInStateVariable type="POST-TRANSFORM" transformname="ResponseToNodeSet">

                  GeneratedNodeSet

               </PlaceInStateVariable>

            </PostCallCommands>

            <!-- XSLTransform: Transform Definitions -->

            <XSLTransforms>

               <XSLTransform name="ResponseToNodeSet">

                  <XSLT>WSResponseToNodeSet.xslt</XSLT>

               </XSLTransform>

            </XSLTransforms>

         </WebServiceSequenceStep>

         <!--

            AvailableOutputs:

            This element defines the values that should be available

            after the Web Service Sequence is executed

         -->

         <AvailableOutputs>?

            <OutputParameter stateVariableName="GeneratedValue"/>

            <OutputParameter stateVariableName="GeneratedNodeSet"/>

         </AvailableOutputs>

      </WebServiceSequence>

   </WebServiceSequences>

</AcordeWebServiceSequenceLibrary>

XML Block 1

The first thing to note is that a Web Service Sequence Library can contain multiple Web Service Sequences. The sample in XML Block 1 shows only one Web Service Sequence to simplify the discussion. Conceptually you can think of the Web Service Sequence Library as the object and the individual Web Service Sequences as method calls on that object.

ExecutionNameSpace - The Web Service Sequences contained in the Library definition run in a particular namespace. This determines the segmentation of the State Variables, as they are stored in the IBPM Infrastructure. You specify the namespace with the element ExecutionNameSpace – a sub-element of the AcordeWebServiceSequenceLibrary document element. In general this should match the name of the XML file containing the Library description.

WebServiceSequence - The main element used to define Web Service Sequences is the “WebServiceSequence” element. Each Web Service Sequence has a name attribute. This should contain only “alpha-numeric” characters and NOT start with a numeric character. The name should NOT contain any spaces or special characters. The Web Service Sequence element has sub-elements of the following types:

· InputParameterOrder

· WebServiceSequenceStep

· AvailableOutputs

There can be zero or one of each the InputParameterOrder and AvailableOutputs. There can be 0 or more WebServiceSequenceStep elements.

The Input Parameter Order defines the mappings between values sent into the Web Service Sequence call and State Variable values within the Web Service Sequence. Later sections in this document will discuss how you send parameters into a Web Service Sequence when calling it.

The AvailableOutputs element provides a listing of State Variables that are intended as outputs from the Web Service Sequence. These are more for documentation than functionality, and may be used in the future. A user of a Web Service Sequence can obtain State Variable values that are set during the process of executing a Web Service Sequence but are not returned as results of the call. This element,” AvailableOutputs”, documents meaningful State Variables that might be useful.

The Web Service Sequence Step (WSS Step) defines an action that should be taken to either manipulate state data or make a call to a Web Service. Notice in the sample shown in XML Block 1, you find WSS Steps that define calls to Web Services as well as WSS Steps that define the transformation of state variable. The combinations of these two types of WSS Steps provides mechanisms to take data provided by the user or the IBPM Infrastructure and transform that data’s format into a format required by the Web Service. After properly transforming the data it can be sent out to the Web Service. Once the Web Service response is obtained you have a chance to transform that data into a format usable by the IBPM Web Infrastructure.

It is possible to have more than one step that accesses a Web Service in a Web Service Sequence. This can allow you to merge or chain several Web Service calls into a single Web Service Sequence. In addition you can define Web Service Sequence dependencies within the steps. There are several mechanisms allowing you to manage dependencies between Web Services. We will present the details in a later section.

The Web Service Sequence provides the ability to specify an output of one of its State Variables. This is specified by the “output” attribute of the Web Service Sequence element. This is the value the Web Service Sequence returns to the caller when it is executed.

Accessing an IBPM Web Service Sequence

Once you have defined a Web Service Sequence Library containing one or more Web Service Sequences, it can be accessed in several ways within the IBPM Web Infrastructure. Access points are available in the following areas of the IBPM Web Client Infrastructure:

  • IBPM XML Work Center Node definitions
  • IBPM Web Custom Tool ASP code
  • IBPM Web Tool Entry Point XML definitions

XML Metadata Calls in the IBPM Infrastructure - A string specification of a Web Service Sequence call is formatted as shown in XML Block 2.

A sample Command Mapping Node of type WebServiceCommands from an XML Work Center Node

<CommandMapping command="ExchangeData" type="WebServiceCommands">

       <WebServiceCommands>

              <WebServiceCommand type="EXPIRE">

                     <SequenceName>AWCN_OptikaStockSample3::DemoTransforms</SequenceName>

              </WebServiceCommand>

              <WebServiceCommand type="CALL">

                     <SequenceName>AWCN_OptikaStockSample3::DemoTransforms(SYMBOLTOUSE)</SequenceName>

              </WebServiceCommand>

       </WebServiceCommands>

</CommandMapping>

XML Block 2

XML Block 2 is a sample from the Work Center Node White Paper. Notice that the library is specified, next a double colon and then the Web Service Sequence name. Finally, a comma-delimited list of State Variable names is provided contained in parentheses. These State Variables reference variables in the context from which the call is being made. The form is:

LibraryName::WebServiceSequenceName(VarParam1, VarParam2)

This is the format that is used in other XML files in the IBPM Infrastructure. Notice that the Library Name is the name of the XML file found in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfrastructure\ AcordeWebServiceSequenceLibraries

And the name of the Web Service Sequence is the value of the “name” attribute on the WebServiceSequence element.

The following is a list of locations in the IBPM XML Metadata that allow the specification of a Web Service Sequence as a Data Element. You will need to refer to the specific documentation that will explain in detail how the returned values are used and how they should be formatted:

  • XML Work Center Node CommandMapping Web Service Command allows you to expire and call Web Service Sequences.
  • XML Work Center Node CommandMapping Prompt For State Values Validation element allows you to validate a value set against a Web Service Sequence.
  • XML Work Center Node State Variable definition allows a Web Service Sequence to provide a list of valid values.
  • XML Work Center Node Node Group element allows you to define a source for the Node Group XML as a Web Service Sequence.
  • The XML Tool Definition allows you to specify a one or more Web Service Sequences that should be called when Entry Points to a tool are executed.

Custom ASP Code Calls - A Web Service Sequence can also be called from custom ASP code. The IBPM Web Custom Tool Infrastructure provides the mechanism shown in Code Block 1 to call defined Web Service Sequences.

A sample of how to use Web Service Sequence Libraries from a Custom Tool

// Get the Custom Web Tool Infrastructure. This is the

// Server side object that encapsulates all the IBPM

// Infrastructure (Server Side) that is available to

// a Custom Web Tool.

var objACWI = AcordeCustomWebInfrastructure();

// Get the Web Service Sequence Library that we want to use

// This is returned as a JavaScript object that has methods named

// the same as

var objMyWSSL = objACWI.GetWebServiceSequenceLibrary("AWCN_OptikaStockSample3");

// Now the sequences can be used as methods on the Sequence Library object

// This line demonstrates a call into the Web Service Sequence shown in

// XML Block 1

var objMyWSSL = objMyWSSL.WSSGetStockPrice(“STEL MSFT IBM”);

Code Block 1

In this sample block of code we see how you can obtain a JavaScript object from the IBPM Custom Web Infrastructure that represents the IBPM Web Service Sequence Library. At that point you can call into any of the Web Service Sequences that Library defines passing in the appropriate values as input parameters to the Web Service Sequence.

The return from the method call is the output State Variable provided by the Web Service Sequence. That output is defined by the “output” attribute on the WebServiceSequence element in the Library XML document.

Web Service Sequence Element

Previous sections have provided general descriptions of the WebServiceSequence element. The following is a comprehensive description of all the available features of the WebServiceSequence element.

The “expires” attribute – The “expires” attribute allows you to specify that the output of the Web Service Sequence “expires” or becomes invalid after some number of seconds. XML Block 3 illustrates the use of the “expires” attribute to specify that the output value of the Web Service Sequence becomes invalid after 10 minutes requiring the entire Web Service Sequence to be run every 10 minutes.

A sample of how the “expires” attribute is used

         <WebServiceSequence expires="600"? …>

            …

         </WebServiceSequence>

XML Block 3

This is a useful feature if you have dependencies between Web Services that require a single call to one Web Service for multiple calls to another. One example would be logging in using one Web Service call before being able to use a secondary Web Service Call.

The “output” attribute – The “output” attribute allows you to specify that the output State Variable of the Web Service Sequence. XML Block 4 illustrates the use of the “output” attribute to specify that the output value of the Web Service Sequence.

A sample of how the “output” attribute is used

         <WebServiceSequence output="ResultReturn"? …>

            …

         </WebServiceSequence>

XML Block 4

In this case, the value of the State Variable “ResultReturn” will be returned to the caller of the Web Service Sequence once the Web Service Sequence has completed.

The “InputParameterOrder” element – The “InputParameterOrder” element allows you to define a mapping of input parameters to local State Variable names. XML Block 5 Demonstrates the use of

A sample of how the “InputParameterOrder” element is used

         <WebServiceSequence…>

            <InputParameterOrder>?

               <InputParameter stateVariableName="optName"/>+

            </InputParameterOrder>

            …

         </WebServiceSequence>

XML Block 5

In this case the value of the State Variable “optName” will be set equal to the first parameter, additional InputParameter elements will map other input parameters to named State Variables. Once these State Variable values are set they can be used in the calls made to the external web services through the use of Replacement Tags. Replacement Tags allow you to interject session data into messages sent to Web Services. More about how to interject session data into Web Services calls will be presented in later sections of this document.

The “WebServiceSequenceStep” element – The Web Service Sequence Step element defines an action that manipulates data, calls a Web Service or aggregates several Web Service Sequences. XML Block 6 demonstrates the location and use of a “WebServiceSequenceStep” element.

A sample of how the “WebServiceSequenceStep” element is used

         <WebServiceSequence…>

            <WebServiceSequenceStep…>*

               …

            </WebSericeSequenceStep >

            …

         </WebServiceSequence>

XML Block 6

A Web Service Sequence Step can only be a direct child of a Web Service Sequence element. A Web Service Sequence can contain multiple Web Service Sequence Step elements. Each Web Service Sequence Step in a Web Service Sequence is process in the order they appear in the sequence. This means that you can create WSS Steps that are dependent on previous WSS Steps in the WSS. The later section on the Web Service Sequence Step will present in detail the allowable content of the various types of steps.

The “AvailableOutputs” element – The “AvailableOutputs” element provides a mechanism to document State Variables that may be useful as outputs from the Web Service Sequence. You can only return one State Variable from a Web Service Sequence call unfortunately you might generate several useful values during the execution of the call. This element allows you to document the useful State Variables that are set during the call. XML Block 7 demonstrates the use of the Available Outputs element

A sample of how the “InputParameterOrder” element is used

         <WebServiceSequence…>

            <AvailableOutputs>?

               <OutputParameter stateVariableName="optName"/>+

            </AvailableOutputs>

            …

         </WebServiceSequence>

XML Block 7

In this case the value of the State Variable “optName” is documented as an available output value that might be useful to a user of the Web Service Sequence defined.

The Web Service Sequence Step

The core element of the Web Service Sequence is the Web Service Sequence Step (WSS Step) element. This element defines the actions that the sequence should take in order to access one or more Web Services. XML Block 8 illustrates a Web Service Sequence Step. Notice that this sample contains example XML for a WEBSERVICECALL type Web Service Sequence Step. The available WebServiceSequenceStep Types are:

  • WEBSERVICECALL
  • TRANSFORM
  • SEQUENCEAGGRIGATION

This section will present each of the WSS Step types in detail.

“WEBSERVICECALL” type - The “WEBSERVICECALL” type allows you to define a call to a web service. You can send data that has been extracted from the IBPM System, obtained from the user or other Web Service Sequences and receive a Web Service response that can be placed into a local state variable. That data can then be used by your Custom ASP Web Tools or displayed as part of a Work Center Node.

If the type attribute is left off of the Web Service Sequence Step element then the assumed type is “WEBSERVICECALL”.

In order to call a Web Service from within the WSS you will need to understand the required Message format that must be sent to the Web Service as well as the Response Message format. Both of these will be XML Documents. You can extract this information by looking at the WSDL or Documentation for the Web Service. If you are accessing a Web Service built on .Net can browse directly to the ASMX to view the information about the Message Structures.

XML Block 8 defines the structure of a Web Service Call type Web Service Sequence Step. In this definition we see the “COMPLEXSOAP” type on the Web Service Call Definition.

A definition of the WEBSERVICECALL Web Service Sequence Step

         <WebServiceSequenceStep type="optWSSStepType=WEBSERVICECALL"?

                                 requiredWebServiceSequence=“optSequenceCall”?>

            <DebugSettings …/>?

            <RequiredWebServiceSequences>?

               <RequiredWebServiceSequence WebServiceSequence=”optSequenceCall”?+/>*

            </RequiredWebServiceSequences>

            <WebServiceCallDefinitions>

               <WebServiceCallDefinition

                             type="optwebservicecalldefinitiontype=COMPLEXTYPESOAP"

                             active="optBoolean">*

                  <EndPointURL>string</EndPointURL>?+

                  <SoapAction>string</SoapAction>?+

                  <MessageData type="optMessageDataType">?+

                     <-- extensibility element -->

                  </MessageData>

              </WebServiceCallDefinition>

            </WebServiceCallDefinitions>

            <PostCallCommands>

               <PlaceInStateVariable

                       type="optPlaceInStateVariableType">*

                  optStateVariableName_2

               </PlaceInStateVariable>

               <PlaceInStateVariable

                       type="optPlaceInStateVariableType=POST-TRANSFORM"

                       transformname="optName_1">*

                  optStateVariableName_3

               </PlaceInStateVariable>

            </PostCallCommands>

            <XSLTransforms>

               <XSLTransform name="optName_1">

                  <XSLT>WSResponseToNodeSet.xslt</XSLT>

                  <XSLTransformParameters>

                     <XSLTVariable type=”optXSLTVarType” name=”optName”>optStateVariableName</XSLTVariable>

                  </XSLTransformParameters>

               </XSLTransform>

            </XSLTransforms>

         </WebServiceSequenceStep>

XML Block 8

The “COMPLEXSOAP” type of Web Service Call Definition requires that you provide three pieces of information to connect and call a Web Service. These are:

  • The EndPointURL – The URL locator for the Web Service.
  • The SoapAction – This identifies the “method” on the web service that you want to call.
  • The MessageData – This is the message that will be sent to the Web Service. The first child of this element is the SOAP Envelope Body content that needs to be sent to the web service. Notice that this can be any XML Document.

Optionally:

  • Any DebugSettings – These are available to help you with debugging your Web Service Sequence. They will be discussed in detail in a later section on Debugging Features.

Take a look at XML Block 9. This is an excerpt from the Dashboard Web Service integration used by the IBPM Web Client.

A sample of a WebServiceSequenceStep from the Dashboard Integration

<WebServiceSequenceStep type="WEBSERVICECALL">

   <DebugSettings logDirectory="c:\IBPMWebServiceSequenceLogs\">

      <WebServiceReturn>false</WebServiceReturn>

   </DebugSettings>

   <WebServiceCallDefinitions>

      <WebServiceCallDefinition type="complextypesoap" active="true">

         <EndPointURL>

            http://[ACORDESTATEVARIABLE:SERVICEMACHINE]/IBPMDashboard/AcordeAuditWorkCenter.asmx

         </EndPointURL>

         <SoapAction>

            http://tempuri.org/GetDashboardWorkCenterNodeGroup

         </SoapAction>

         <MessageData type="StaticXMLWithVariables">

            <GetDashboardWorkCenterNodeGroup xmlns="http://tempuri.org/">

               <strAID>[ACORDEINFRASTRUCTURE:ACTIVATIONID]</strAID>

               <strGENERALMODE>Document</strGENERALMODE>

               <xmlSTARTDATE>[ACORDESTATEVARIABLE:STARTDATE]</xmlSTARTDATE>

               <xmlENDDATE>[ACORDESTATEVARIABLE:ENDDATE]</xmlENDDATE>

               <strUSERNAME>[ACORDESTATEVARIABLE:USERNAME]</strUSERNAME>

               <strSERVER>[ACORDESTATEVARIABLE:SERVER]</strSERVER>

               <strAPPLICATION>[ACORDESTATEVARIABLE:APPLICATION]</strAPPLICATION>

               <strRUNSEARCH>[ACORDESTATEVARIABLE:RUNSEARCH]</strRUNSEARCH>

               <xmlDashboardCache>[ACORDESTATEVARIABLEESCAPED:LASTDOCUMENTNODES]</xmlDashboardCache>

            </GetDashboardWorkCenterNodeGroup>

         </MessageData>

      </WebServiceCallDefinition>

   </WebServiceCallDefinitions>

   <PostCallCommands>

      <PlaceInStateVariable type="XPATHTEXT"

            xpath="/GetDashboardWorkCenterNodeGroupResponse/GetDashboardWorkCenterNodeGroupResult">

            LASTDOCUMENTNODES

      </PlaceInStateVariable>

   </PostCallCommands>

</WebServiceSequenceStep>

XML Block 9

This is a call to get the Dashboard Work Center node group for the “Document” category. The Work Center Node passes in query parameters including Start Date, End Date, Server and Application. These State Variables are then passed to the Dashboard Web Service along with the Activation ID, general mode of “Document” and the previously provided Node Group XML.

The Endpoint URL is the locator of the Web Service. In XML Block 9 the ASMX “AcordeAuditWorkCenter.asmx” implements the Web Service. Notice the text “[ACORDESTATEVARIABLE:SERVICEMACHINE]” in the URL. This is a Replacement Tag (Appendix A). It tells the WSS processor to replace that text with the value of the State Variable “SERVICEMACHINE”. The WSS this step is a member of takes that state variable as a parameter to the WSS.

The SOAP Action identifies which method provided by the Web Service should process the call. In XML Block 9 the SOAP Action has a value of:

http://tempuri.org/GetDashboardWorkCenterNodeGroup

This identifies the function “GetDashboardWorkCenterNodeGroup” as the method to process the Web Service call.

Next, the message data identifies the structure of the XML data that should be sent to the Web Service. XML Block 10 shows the XML that will be sent to the Web Service.

The Message Data from XML Block 9

            <GetDashboardWorkCenterNodeGroup xmlns="http://tempuri.org/">

               <strAID>[ACORDEINFRASTRUCTURE:ACTIVATIONID]</strAID>

               <strGENERALMODE>Document</strGENERALMODE>

               <xmlSTARTDATE>[ACORDESTATEVARIABLE:STARTDATE]</xmlSTARTDATE>

               <xmlENDDATE>[ACORDESTATEVARIABLE:ENDDATE]</xmlENDDATE>

               <strUSERNAME>[ACORDESTATEVARIABLE:USERNAME]</strUSERNAME>

               <strSERVER>[ACORDESTATEVARIABLE:SERVER]</strSERVER>

               <strAPPLICATION>[ACORDESTATEVARIABLE:APPLICATION]</strAPPLICATION>

               <strRUNSEARCH>[ACORDESTATEVARIABLE:RUNSEARCH]</strRUNSEARCH>

               <xmlDashboardCache>[ACORDESTATEVARIABLEESCAPED:LASTDOCUMENTNODES]</xmlDashboardCache>

            </GetDashboardWorkCenterNodeGroup>

XML Block 10

Notice that the XML contains several Replacement Tags and has a type of “StaticXMLWithVariables”. This means that prior to the message being sent the WSS processor will replace the data with the current State Variable and Infrastructure values. If you have a constant XML that does not require any Replacement Tags you can use the type “StaticXML”.

After the Web Service Call is made, an XML Document is returned to the IBPM System. The PostCallCommands allow you to specify what should be done to the returned document and which State Variable any of the data should be placed in. In XML Block 9 the XML has specified an XPath to a node in the return document. The “PlaceInStateVariable” type of “XPATHTEXT” tells the WSS processor to XPath to a node in the returned document and get the text value of that node and place that value in the State Variable “LASTDOCUMENTNODES”. It is allowable to specify any number of “PlaceInStateVariable” commands. The available types include:

  • XPATHTEXT – Extract a Value from the XML using a Microsoft XML DOM and place that value into a state variable.
  • PRE-TRANSFORM – Place the XML Document directly into a State Variable
  • POST-TRANSFORM – Run an XSLT Transformation on the returned XML Document and then place that transformed Document into a State Variable

XML Block 11 illustrates the use of both PRE-TRANSFORM and POST-TRANSFORM types of PlaceInStateVariable.

The use of PRE- and POST-TRANSFORM PlaceInStateVariable types

<WebServiceSequenceStep …>

   …

   <PostCallCommands>

      <PlaceInStateVariable type="PRE-TRANSFORM">WebServiceResponse</PlaceInStateVariable>

      <PlaceInStateVariable type="POST-TRANSFORM"

                            transformname="ResponseToNodeSet">GeneratedNodeSet</PlaceInStateVariable>

   </PostCallCommands>

   <XSLTransforms>

      <XSLTransform name="ResponseToNodeSet">

         <XSLT>WSResponseToNodeSet.xslt</XSLT>

      </XSLTransform>

   </XSLTransforms>

</WebServiceSequenceStep>

XML Block 11

The use of a PRE-TRANSFORM command is simple. In XML Block 11 the returned XML Document is placed in the State Variable “WebServiceResponse” in an un-altered format.

The use of a POST-TRANSFORM command is a bit more complex. You first need to define and name an XSLTransform that can be referenced by the PlaceInStateVariable command. In XML Block 11, we have defined an XSLTransform element named “ResponseToNodeSet” which converts the raw Web Service response to a Node Set for the Work Center. Notice the PlaceInStateVariable command has referenced the XSLTransform using the “transformname” attribute.

The XSLTransform defines an XSLT file that should be used to transform the XML returned from the Web Service. In XML Block 11, the XSLT “WSResponseToNodeSet.xslt” has been specified. The XSLT files are located in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\XSLTTransforms\WebServiceSequences

XSLT files used by your WSSL should be placed in a sub-directory named the same as your WSSL. For example, if your WSSL file is named “MyWSSL.xml” you should place your XSLT file in the directory:

C:\InetPub\WWWRoot\IBPMWeb\OTInfratructure\XSLTTransforms\WebServiceSequences\MyWSSL

The XSLT will be loaded into a Microsoft XML DOM and applied as a Transform to the returned XML Document. After the transformation is successfully accomplished the transformed value will be placed into the specified State Variable. In XML Block 11, the transformed XML Document is placed into the State Variable “GeneratedNodeSet”.

“TRANSFORM” type - The “TRANSFORM” type allows you to define a transformation of data that is being held in state. XML Block 12 provides a definition of the required structure of the “TRANSFORM” type of Web Service Sequence Step.

A definition of the TRANSFORM Web Service Sequence Step

         <WebServiceSequenceStep type="optWSSStepType=TRANSFORM"?+

                                 requiredWebServiceSequence=“optSequenceCall”?>

            <DebugSettings …/>?

            <TransformationDefinitions>?+

               <TransformationDefinition active=”optBoolean”>*

                  <Input type="optTDInputType=DELIMITEDSTATEVARIABLE"?+

                         delimiter="optDelimeter"?+

                         trimvalues="optBoolean"?+

                         dropemptystrings="optBoolean"?+

                         dropnamespace=”optBoolean”?

                         transformname="optName_1"?+>optStateVariableName_1</Input>?+

                  <Output>optStateVariableName_2</Output>?+

               </TransformationDefinition>

              <TransformationDefinition active="optBoolean">*

                 <Input type="optTDInputType=XMLSTATEVARIABLE"?+

                         transformname="optName_2"?+>optStateVariableName_3</Input>?+

                 <Output>optStateVariableName_4</Output>?+

              </TransformationDefinition>

              <TransformationDefinition active="optBoolean">*

                 <Input type="optTDInputType=XMLURL"?+

                         transformname="optName_3"?+>optURL</Input>?+

                 <Output>optStateVariableName_4</Output>?+

              </TransformationDefinition>

            </TransformationDefinitions>

            <XSLTransforms>?

               <XSLTransform name="optName_1"?+>

                   <XSLT>MyFile1.xslt</XSLT>?+

               </XSLTransform>

               <XSLTransform name="optName_2"?+>

                   <XSLT>MyFile2.xslt</XSLT>?+

               </XSLTransform>

               <XSLTransform name="optName_3"?+>

                   <XSLT>MyFile3.xslt</XSLT>?+

               </XSLTransform>

            </XSLTransforms>

            …

         </WebServiceSequenceStep>

XML Block 12

There are three types of input elements usable as children to TransformationDefinition elements. These are:

  • DELIMITEDSTATEVARIABLE – This Input is assumed to be a character delimited list of values (comma-delimited, pipe-delimited or space-delimited). The string is broken into several values and those values are placed in an AcordeValueArray XML Document before processing the transformation.
  • XMLSTATEVARIABLE – The input is assumed to be a State Variable value.
  • XMLURL – The input is assumed to be an XML Document that must be downloaded from the specified URL before being transformed.

The “active” attribute allows you to remove TransformationDefinition elements from being processed without actually removing the XML definition of the Transformation.

Transformations in a WSS Step are processed in the order they appear in the document so it is possible to create several Transformation Definitions in a row that depend on proceeding transformations.

The format of an AcordeValueArray is shown in XML Block 13. This XML could have been generated by one of the following string:

  • Value 1, Value 2, Value 3, Value 4
  • Value 1|Value 2|Value 3|Value 4

The intent is to generate a simple XML format. This simple XML document can then be transformed, through the use of an XSLT, into a more complex XML.

An example of an AcordeValueArray where the Namespace was not dropped

<AcordeValueArray version="1.0" xmlns=”http://Optika.com/schemas/AcordeInfrastructure/AcordeValueArray”>

   <Value>Value 1</Value>

   <Value>Value 2</Value>

   <Value>Value 3</Value>

   <Value>Value 4</Value>

</AcordeValueArray>

XML Block 13

You may find it easier to work with an XML that does not use a default namespaces. By specifying the dropnamespace attribute as “true” you can generate the example in

An example of an AcordeValueArray where the Namespace was dropped

<AcordeValueArray version="1.0">

   <Value>Value 1</Value>

   <Value>Value 2</Value>

   <Value>Value 3</Value>

   <Value>Value 4</Value>

</AcordeValueArray>

XML Block 14

XML Block 15 is an example of the use of a TRANSFORM type of Web Service Sequence Step.

An example of the TRANSFORM Web Service Sequence Step

<WebServiceSequenceStep type="TRANSFORM">

   <TransformationDefinitions>

      <TransformationDefinition active="true">

         <Input type="DELIMITEDSTATEVARIABLE"

                delimiter=" "

                trimvalues="true"

                dropemptystrings="true"

                transformname="">DelimitedString</Input>

         <Output>DelimitedStringInXML</Output>

      </TransformationDefinition>

      <TransformationDefinition active="true">

         <Input type="XMLSTATEVARIABLE"

                transformname="ConvertArrayToReq">DelimitedStringInXML</Input>

         <Output>ReqFormat</Output>

      </TransformationDefinition>

      <TransformationDefinition active="true">

         <Input type="XMLURL"

                transformname="PubToNodes">http://MyServer/AnApp/PublishedData/PubDoc.xml</Input>

         <Output>DelimitedStringInNewXML2</Output>

      </TransformationDefinition>

   </TransformationDefinitions>

   <XSLTransforms>

      <XSLTransform name="ConvertArrayToReq">

         <XSLT>ConvertArrayToReq.xslt</XSLT>

      </XSLTransform>

      <XSLTransform name="PubToNodes">

         <XSLT>ConverPubToNodes.xslt</XSLT>

      </XSLTransform>

   </XSLTransforms>

   </WebServiceSequenceStep>

XML Block 15

In this example there are three transformations defined. They make use of two defined XSLTransforms.

The first TransformationDefinition takes the State Variable named “DelimitedString” as a type of “DELIMITEDSTATEVARIABLE” and parses that string using a space (“ “) character as specified by the delimiter attribute. It trims the values of any trailing or leading spaces (trimvalues=”true”) and drops any empty strings that are generated (dropemptystrings=”true”). XML Block 15 is an excerpt from a stock quote sample so a valid input may look like this:

STEL MSFT IBM

If that is the value of the State Variable DelimitedString, an XML String is generated that would look like XML Block 16.

An example of an AcordeValueArray where the Namespace was dropped

<AcordeValueArray version="1.0" xmlns=”http://Optika.com/schemas/AcordeInfrastructure/AcordeValueArray”>

   <Value>STEL</Value>

   <Value>MSFT</Value>

   <Value>IBM</Value>

</AcordeValueArray>

XML Block 16

That string value is then placed in the State Variable “DelimitedStringInXML”. It can now be used by any of the Transform Definitions or Web Service Sequence Steps that follow.

The second Transformation Definition takes the XML string that was generated and placed into the State Variable “DelimitedStringInXML” and transforms that XML using an XSLT. The input type is specified as “XMLSTATEVARIABLE” which indicates the State Variable is already an XML. The Transformation Definition specifies that the XSLTransform “ConvertArrayToReq” should be used to transform the document from an AcordeValueArray to the required XML format (whatever that is). The XSLTransform specifies that the XSLT file “ConvertArrayToReq.xslt” should be used.

The final Transformation Definition specifies an “XMLURL” which instructs the WSS Processor to download the XML document to be transformed from the provided URL. This means that the first thing the WSS Processor does is download the XML from the URL:

http://MyServer/AnApp/PublishedData/PubDoc.xml

That document is then transformed using the XSLT file “ConvertPubToNodes.xslt” as specified by the referenced XSLTransform “PubToNodes”.

“SEQUENCEAGGRIGATION” type - The “SEQUENCEAGGRIGATION” type allows you to define a Web Service Sequence Step that simply aggregates one or more other Web Service Sequence Calls. It does this through the use of the “RequiredWebServiceSequences” element.

A definition of the SEQUENCEAGGRIGATION Web Service Sequence Step

         <WebServiceSequenceStep type="optWSSStepType=SEQUENCEAGGRIGATION"?+

                                 requiredWebServiceSequence=“optSequenceCall”?>

            <DebugSettings …/>?

            <RequiredWebServiceSequences>?

               <RequiredWebServiceSequence WebServiceSequence=”optSequenceCall”?/>*

            </RequiredWebServiceSequences>

            …

         </WebServiceSequenceStep>

XML Block 17

XML Block 18 is an example of how the Sequence Aggregation type might be used.

An example of the SEQUENCEAGGRIGATION Web Service Sequence Step

         <WebServiceSequenceStep type="SEQUENCEAGGRIGATION"

                                 requiredWebServiceSequence=“optSequenceCall”>

            <RequiredWebServiceSequences>

               <RequiredWebServiceSequence WebServiceSequence=”MyWSSL::MyWSS1(StateVar1,StateVar2)”/>

               <RequiredWebServiceSequence WebServiceSequence=”MyWSSL::MyWSS2(StateVar1,StateVar2)”/>

               <RequiredWebServiceSequence WebServiceSequence=”MyWSSL::MyWSS3(StateVar1,StateVar2)”/>

            </RequiredWebServiceSequences>

         </WebServiceSequenceStep>

XML Block 18

In this example, the three Web Service Sequence calls are made passing the State Variables (StateVar1 and StateVar2) to each of them.

The XSLTransforms Element

One powerful and critical feature of the Web Service Sequence infrastructure is the support of XSLT transforms as a mechanism for transforming raw data obtained from the Web Services into usable data by the IBPM Web Infrastructure.

Appendix A: Supported Replacement Tags

This section describes the tags that are supported for replacement in text values in the IBPM XML Work Center Nodes.

In many of the values extracted from a Work Center Node definition file, the IBPM Infrastructure will scan the text value of the data for the tags listed in this section. The tag indicates that specific data needs to be extracted from the IBPM Web Infrastructure and put into the data value replacing the tag completely. Tags are available to insert State Variables, Data from the XML Publication Document and IBPM Web Infrastructure values.

The following is a complete summary of all the supported Replacement Tags that are scanned for along with a short description of how those tags are processed.

Tag Format | Replacement Description
[ACORDESTATEVARIABLE:StateVariableName] | The Tag Text is replaced with the value of the state variable that is named in the tag. Simple names such as the one shown reference state variable defined in your Work Center Node Definition file. You can reference Web Service Sequence state variable if your StateVariableName takes the form: WebServiceSequenceLibrary::SequenceName::VariableName
[ACORDESTATEVARIABLEESCAPED:StateVariableName] | The Tag Text is replaced with an escaped version of the value of the state variable that is named in the tag. This is useful if you are placing XML in a string element of an XML document. As in the case of un-escaped variables, simple names such as the one shown reference state variable defined in your Work Center Node Definition file. Again, you can reference Web Service Sequence state variable if your StateVariableName takes the form: WebServiceSequenceLibrary::SequenceName::VariableName
[:ACORDEPUBLICATIONTEXT:MyXPath:] | Notice that the tag is delimited with a “[:” and a “:]”. This is required due to the fact that XPath can contain “[“ and “]”. The Tag Text is replaced with the text of the node in the IBPM State Document found using the specified XPath statement.
[:ACORDEPUBLICATIONXML:MyXPath:] | Again, notice that the tag is delimited with a “[:” and a “:]”. This is required due to the fact that XPath can contain “[“ and “]”. The Tag Text is replaced with the XML of the node in the IBPM State Document found using the specified XPath statement.
[:ACORDEPUBLICATIONXMLESCAPED:MyXPath:] | Again, notice that the tag is delimited with a “[:” and a “:]”. This is required due to the fact that XPath can contain “[“ and “]”. The Tag Text is replaced with an escaped version of the XML of the node in the IBPM State Document found using the specified XPath statement.
[ACORDESTATECONSTANT:TODAYSDATE] | The Tag Text is replaced with a string version of the current date. This date will be formatted in the language the user is logged in with.
[ACORDESTATECONSTANT:LASTMONTH] | The Tag Text is replaced with a string version of the current date minus one month. This date will be formatted in the language the user is logged in with.
[ACORDEINFRASTRUCTURE:LANGUAGE] | The Tag Text is replaced with a string indicating the selected Language ID the user is using.
[ACORDEINFRASTRUCTURE:AIID] | The Tag Text is replaced with a string containing the current IBPM Infrastructure Initialization Document (AIID) for the session.
[ACORDEINFRASTRUCTURE:ENCODEDAIID] | The Tag Text is replaced with an encoded string containing the current IBPM Infrastructure Initialization Document (AIID) for the session.
[ACORDEINFRASTRUCTURE:PUBLICATIONURL] | The Tag Text is replaced with a URL to the IBPM Web Client publication document that publishes the current state of the IBPM Web Client.
[ACORDEINFRASTRUCTURE:ENCODEDPUBLICATIONURL] | The Tag Text is replaced with a URL to the IBPM Web Client publication document that publishes the current state of the IBPM Web Client.
[ACORDEINFRASTRUCTURE:USERNAME] | The Tag Text is replaced with the current User’s UserName.
[ACORDEINFRASTRUCTURE: UPPERCASEUSERNAME] | The Tag Text is replaced with an upper case version of the current User’s UserName.
[ACORDEINFRASTRUCTURE: LOWERCASEUSERNAME] | The Tag Text is replaced with a lower case version of the current User’s UserName.
[ACORDEINFRASTRUCTURE: ENCODEDUSERNAME] | The Tag Text is replaced with an encoded version of the current User’s UserName.


Tool Object Overview

The Tool Object Model consists of objects used when creating a custom tool within the IBPM framework.

A custom tool is an application that is displayed within the IBPM client. It can be added to a gallery from the Security tool. It is distributed through the DSMS service. It can act independently or interact with other tools in that gallery.

The Tool Object Module (Stellent.IBPM.Client.ToolNotifier) is the object that the custom tool component must interact with so that the IBPM client can recognize it as a tool and thus communicate with it. This object is used to define message handlers for a message associated with a unique GUID. This GUID will be passed by another tool.

The Stellent.IBPM.Client.MessageDictionary object is a key/value pair dictionary used for processing messages.


IBPM Client Framework Hosting

The Windows Client supports the hosting of Custom Tools through the use of Stellent supplied .Net objects. Custom Tools include any .Net Win Form that interacts, through the use of events, with all of the required Custom Tool objects and events. Additional optional events are defined and may be implemented to enhance the functionality of a Custom Tool. The SDK end-user provides the implementation for each of these events to meet the specific requirements of the Custom Tool. Stellent provides a generic implementation of certain supporting events, but the SDK end-user is not required to use these implementations.

Through the use of the Custom Tool objects and events, the IBPM Client Framework provides support for Custom Tool installation and distribution, Gallery setup and configuration and tool creation and management of interaction between the Custom Tool and the framework.


Custom Tool Installation and Distribution

Custom Tools, and all dependent components required by the Custom Tool implementation, must reside in the MasterFiles directory used by the DSMS server to distribute software components. Each Custom Tool and all of its dependent components must be placed in the MasterFiles directory.

The Custom Tool and all dependent components are distributed to the client machine in the same manner as native IBPM Tools. The IBPM Client Framework automatically handles registration of all COM components.

A dependency file should be created for the Custom Tools. For Custom Tools the dependency file should be similar to the following:

tool "CustomTool.dll" client nettool("NameSpace.CustomToolClassName", "Custom Tool Name")

{

     // Any files that the tool is dependent on go here

     file “CustomToolDependency.dll”

}


Debugging a Custom Tool

Custom tools may be debugged using the following steps:

  1. Open the VB.Net project that is the custom tool.
  2. Select: Project | Properties | Configuration Properties | Debugging. Choose ‘Start External Program’ and browse to IBPM.exe. Add the following No DSMS Update parameter to the command line parameters: /nodsmsupdate
  3. Build the Custom Tool project.
  4. Copy the CustomTool dll file to the DSMS, and reset the DSMS and Security Service.
  5. Run IBPMStartUp from the development machine to bring the binary file across to the \Stellent\IBPM folder. If the Gallery does not already have it, add the Custom tool using the Security tool. Logout of the production client.
  6. Place a breakpoint in the Custom Tool’s ‘New’ method.
  7. Run the project. It will prompt the user to login to IBPM and then will stop on the break when the Custom Tool class is created.


Order of Events called for the custom tool

When the tool is loading in the production client:

CustomTool New method

When the tool is viewed in the production client:

Stellent.IBPM.Client.ToolNotifier ShowingTool event is fired

When the tool is closed in the production client:

Stellent.IBPM.Client.ToolNotifier HidingTool event is fired

When the tool is open and you switch a gallery:

Stellent.IBPM.Client.ToolNotifier HidingTool event is fired

When the production client has been closed:

Stellent.IBPM.Client.ToolNotifier HidingTool event is fired if the tool is currently being viewed


Imaging Messages

Browser Tool:

Navigate to URL – This message will load the specified URL address into the Browser Tool. This message requires one value:
  • URL – is the URL address that you would like to load into the tool.

objSendTagMsg.MessageID="360EDCD6-D113-4647-B752-954AF2781069"
objSendTagMsg.Value(“URL”) = “www.Stellent.com”

Search Results Tool:

This message will send a saved search (named query) into the Search Results Tool. This message requires one value:
  • NamedQuery – the populated query object set to a valid saved search

objSendTagMsg.MessageID="{380D0090-BAC8-11D2-8409-00C000023600}"
objSendTagMsg.Value("Named Query") = objQuery


Process Messages

.NET Form Viewer Tool:

.NET Form Launch – This message loads the specified .NET windows form into the .NET Form Viewer Tool. This message requires two values:
  • PkgRecId - the unique value that identifies the form’s package
  • FormId – the unique value that identifies the form
  • (Optional) AutoLock – specifies whether you want the lock dialog to be displayed. If this tag is not sent, it will default to True. If this is set to False, the form will open in read-only mode if the package is not locked

objSendTagMsg.MessageID="0CF96389-897D-4CAF-8431-372BD528A557"
objSendTagMsg.Value("PKGRECID") = objPackage.PkgRecId
objSendTagMsg.Value("FORMID") = objForm.FormId
objSendTagMsg.Value("AUTOLOCK") = False

(Legacy) Form Viewer Tool:

(Legacy) Form Launch – This message loads the specified legacy form into the Form Viewer Tool. This message requires two values:
  • PkgRecId - the unique value that identifies the form’s package
  • FormId – the unique value that identifies the form
  • (Optional) AutoLock – specifies whether you want the lock dialog to be displayed. If this tag is not sent, it will default to True. If this is set to False, the form will open in read-only mode if the package is not locked

objSendTagMsg.MessageID="07B02C41-8FE9-11d4-9E91-00C04F097031"
objSendTagMsg.Value("PKGRECID") = objPackage.PkgRecId
objSendTagMsg.Value("FORMID") = objForm.FormId
objSendTagMsg.Value("AUTOLOCK") = False

Close All Forms – This message will close all the active forms open in the Form Viewer Tool. If the Close on Empty option is enabled, the tool will close also. This message does not require any values.

objSendTagMsg.MessageID=”BC53AA08-F4DC-43ac-ABD6-8FA97E4B65D2”

Close Form – This message will close the specified form. If this is the only form loaded in the Form Viewer Tool and the Close on Empty option is enabled, then the tool will also close. This message requires one value:
  • PkgRecId – the unique value that identifies the form’s package

objSendTagMsg.MessageID="09088DDF-67B8-4014-B1D8-D9C3029991DC"
objSendTagMsg.Value("PKGRECID") = objPackage.PkgRecId

Send Data – This message will send data to the specified form. This message requires two values:
  • PkgRecId – the unique value that identifies the form’s package
  • FormData – the data that you are sending to the form

objSendTagMsg.MessageID="F3C2C41A-8523-473f-B74D-FFEE0C5B6625"
objSendTagMsg.Value("PKGRECID") = objPackage.PkgRecId
objSendTagMsg.Value("FORMDATA") = objFormData

Package Viewer Tool:

View Package – This message will load a package into the Package Viewer Tool. This message requires one value:
  • PkgRecId – the unique value that represents the package

objSendTagMsg.MessageID="4317C120-E48F-11d3-B970-00C04F94787B"
objSendTagMsg.Value(“PKGRECID”) = objPackage.PkgRecId

Get PkgRecId – This message will ask the Package Viewer Tool for the PkgRecId of the package currently loaded in the tool. This message returns one value:
  • PkgRecId – the unique value that represents the package

objSendTagMsg.MessageID=”58F6E170-3D62-11d4-9E7B-00C04F097031”

Close Tool – This message will tell the Package Viewer to close. This will close all forms that are currently loaded in the tool. This message does not require any values.

objSendTagMsg.MessageID="A98B8580-F95D-4a93-A8EB-C65B682CF8CB"

Refresh Package – This message will refresh the package information on the package currently loaded in the tool. This message returns one value:

  • PkgRecId – the unique value that represents the package

objSendTagMsg.MessageID= "7CC9C609-7874-4e1a-92B6-52EE3E78BB64"
objSendTagMsg.Value(“PKGRECID”) = objPackage.PkgRecId

Map Viewer Tool:

View Map – This message will load a package into the Map Viewer Tool. This message requires two values:
  • ProcessId – the unique value that represents the process
  • MapId – the unique value that represents the map

objSendTagMsg.MessageID="4A478AB0-FDC4-11d3-9E63-00C04F097031"
objSendTagMsg.Value(“PROCESSID”) = objProcess.ProcessId
objSendTagMsg.Value(“MAPID”) = objMap.MapId

Package Search Tool:

Execute Search – This message will execute the associated package search into the Package Search Tool. This message requires one value:
  • Profile – the package search that you would like to execute

objSendTagMsg.MessageID="96370370-0D76-11d4-9E6A-00C04F097031"
objSendTagMsg.Value(“PROFILE”) = objProfile

Refresh Package Search – This message will refresh the package search currently loaded within the Package Search Tool. This message does not require any values.

objSendTagMsg.MessageID="6AC5E082-C47F-11d4-9E9F-00C04F097031"

Inbox Tool:

Refresh Inbox – This message will refresh the Inbox Tool. This message does not require any values.

objSendTagMsg.MessageID="6AC5E080-C47F-11d4-9E9F-00C04F097031"

WorkList Tool:

Refresh WorkList – This message will refresh the profile currently loaded within the WorkList Tool. This message does not require any values.

objSendTagMsg.MessageID= "6AC5E081-C47F-11d4-9E9F-00C04F097031"

Package Bar Tool:

Get Package – This message will return the PkgRecId of the package currently loaded in the tool. This message will return one value:
  • PkgRecId - the unique value that represents the package

objSendTagMsg.MessageID= "4614E1D8-DFDE-47a4-9F19-F024330895E7"

Refresh Package – This message will refresh the package information on the package currently loaded in the tool. This message does not require any values.

objSendTagMsg.MessageID= "7CC9C609-7874-4e1a-92B6-52EE3E78BB64"

Complete Package – This message will complete the package currently loaded in the tool. This operation will only be successful if the PkgRecId sent with the message matches the PkgRecId of the package currently loaded in the tool. This message requires one value:
  • PkgRecId – the unique value that represents the package

objSendTagMsg.MessageID="AAC8C464-8FE1-4f45-B498-F8658C90DA2F"
objSendTagMsg.Value(“PKGRECID”) = objPackage.PkgRecId

Skip Package – This message will skip the package currently loaded in the tool. This operation will only be successful if the PkgRecId sent with the message matches the PkgRecId of the package currently loaded in the tool. This message requires one value:

  • PkgRecId – the the unique value that represents the package.

objSendTagMsg.MessageID="1DDB6689-8E43-4c4f-9938-3AC45BD4FF8F"
objSendTagMsg.Value(“PKGRECID”) = objPackage.PkgRecId

Batch Bar Tool:

Get Package – This message will obtain the PkgRecId from the invoice package that is currently loaded in the Batch Bar Tool. This message will return one value:
  • PkgRecId - is the unique value that represents the package.

objSendTagMsg.MessageID="4614E1D8-DFDE-47a4-9F19-F024330895E7"

Get BatchId – This message will obtain the BatchId from the Batch Bar Tool for batch package currently loaded in the tool. This message returns one value:
  • BatchId – is the BatchId value for batch package and associated invoice packages.

objSendTagMsg.MessageID=”09D41A0C-D584-4d69-A88C-E23817B89975”

Refresh Package – This message will refresh the invoice package information on the package currently loaded in the tool. If the invoice package’s BatchId field has been set, the Batch Bar will validate that package and move to the next invoice package. If the batch package still has an invalid BatchId (<PkgRecId>), then the batch package will be updated with the BatchId of the invoice package. This message does not require any values.

objSendTagMsg.MessageID= "7CC9C609-7874-4e1a-92B6-52EE3E78BB64"

Toggle Status – This message will inform the Batch Bar tool to toggle the status of the invoice package. If the invoice package has a valid BatchId, then the status will be changed to “Valid”, otherwise the invoice package will be marked as an exception package. This message does not require any values.

objSendTagMsg.MessageID="1D41E6A3-A88B-4b74-B8D0-A157F0002AC1"

Move Next – This message will inform the Batch Bar tool to move to the next invoice package of the batch package. If the current invoice package is the last invoice of the batch, this message will be ignored. This message does not require any values.

objSendTagMsg.MessageID="62425E15-61EC-4a98-B778-E17972E5EBB8"

Move Prev – This message will inform the Batch Bar tool to move to the previous invoice package of the batch package. If the current invoice package is the first invoice of the batch, this message will be ignored. This message does not require any values.

objSendTagMsg.MessageID="D1F8B1C0-4085-43db-861F-6BC5358F7F50"


Creating a DSMS Dependency File

This topic is a quick reference for adding or altering the dependency files in the DSMS system. A full reference can be found in the DSMS Dependency Syntax Specification. Users of this document should be familiar with the purpose of DSMS and how it works.

The first thing that should be determined before making changes to any dependency file is which file should be changed. The core dependency file is dsms.dp0. This file should preferably not be changed. Changing it may break dependencies for Stellent’s software and that could cause a nonfunctioning or partly functioning system. If you are using the DSMS system to install custom software you probably want to create a new dependency file. That way if anything goes wrong that file can be removed and the system should function as before. Please use dsms.dp0 as an example when creating or modifying other dependency files.

Creating the new dependency file

A dependency file is a plain text file with any name and the extension .dpX, where X is any number between 0 and 9. The extension .dp0 is reserved for DSMS.dp0. Lower numbers are read first by the DSMS system therefore only dsms.dp0 should have the .dp0 extension. To create a new dependency file named custom.dp5 follow the steps below.

1. Use a text editor (notepad for example) to create a text file.

2. Add some contents to the file. Please see other sections in this document on how to add tools or groups.

3. Save the file as custom.dp5 in the same directory as dsms.dp0 resides in.

The DSMS server should automatically pick up the change, now using custom.dp5 also, 1 minute after the file has been saved to the DSMS directory.

Adding a tool to a dependency file

Let’s say we want add a client tool to DSMS. Let’s also say that the tool consists of three files Customtool.dll, a.dat and b.olv. Customtool.dll is a COM object so we want it to be registered on the client computer. Also Customtool.dll needs the Microsoft Visual C runtime libraries to work. Follow the steps below to add a tool with these requirements.

1. Open the particular dependency file you want to modify in a text editor.

2. Go to the end of the file. Groups and tools have to be defined before they can be included in any other tool or group definition. Therefore you probably want to add the new tool at the bottom of the dependency file. That way you can make your tool dependent on any groups or tools that have already been defined in this file or any other dependency file with a lower number in the filename extension.

3. Type in the tool definition you want. This particular tool definition should look something like this:
tool "Customtool.dll" register client
{
file "a.dat"
file "b.olv"
group MSVC
}

The keyword tool tells DSMS that a tool is being defined. A tool needs a filename, which is considered the tool itself. Since this tool is a COM object we want it to be registered on the client. Typing register after the filename in the tool definition takes care of that. If this tool didn’t need registration we would just omit that keyword. The client keyword tells DSMS that this is a client tool (a tool security server will enumerate). Tools that are not client tools are not necessarily server tools. They just aren’t client tools. Once we are done with the tool definition header we define all files that this tool is dependent upon. In this case it is only a.dat and b.olv. The file directive tells DSMS that these files should also be downloaded whenever Customtool.dll is requested. This is the simplest form of file definitions. More about file definitions later. To accommodate the need for the runtime libraries we just include the MSVC group in the tool definition. The MSVC group is already defined in dsms.dp0 so we can just use it.

Adding a group to a dependency file

Tools and groups are very similar. Let’s reuse the example and steps from adding a tool above. We could accomplish almost the same thing using a group instead of a tool definition. It would look like this instead:

group MyCustomGroup

{

file "Customtool.dll" register
file "a.dat"
file "b.olv"
group MSVC
}

This is very similar but we have lost some functionality. Now these file will have be requested using the name MyCustomGroup instead of Customtool.dll and we have lost the client tool aspect. Security server will no longer recognize this as a client tool. Groups should only be used as logical groupings of files. The MSCV group is a great example of this. The group contains some library files and the actions associated with them and that is all. Of course a group can contain other groups and tools as well.

File definitions

The smallest and most important part of a dependency file is its file definitions. The file definition tells DSMS what to do with the file, when it should be done and where in the client’s file system the file should be placed. The simplest file definition possible looks like this:

file "filename.ext"

It tells DSMS to download the file and put it in the install directory. If the file needs to be registered type register after the quoted filename. Several other actions can be associated with a file such as deletion, unregistration, update depending on product version, execution, etc. Please refer to the syntax specification for these commands.

The same file cannot be defined twice. In the case the more than one tool needs a certain file it should be places in a group and that group should be referenced instead.

IBPM Toolkit Runtime Files

The IBPM Toolkit Runtime files are distributed via the DSMS server. Four groups are included in the DSMS.dp0 file to accomplish this. The groups include ToolkitContext, ToolkitProcess, ToolkitViewer and Toolkit.

The fourth group, Toolkit, includes three smaller groups. These toolkit groups may be referenced by new custom tool groups. For a new custom tool a new dependency will would be created. Within this file a group or tool clause would be used to specify the new custom tool that is based on the IBPM Toolkit. Within this group are references to the pieces of the toolkit that are relevant.

Tool "NewCustomTool.dll"

{

group toolkit

file "Support.dll"

}

These toolkit groups include only the runtime portions and not the documentation or samples. Those items should be installed on development machines via the Install provided for the Toolkit.

Troubleshooting

Problem

Client tool and dependency file added but the tool does not show up in Security tool.

Possible Cause

DSMS is aware of the tool but Security is not.

Solution

1. Stop Security server.

2. Run IBPMStartup.exe for the Command prompt. This loads the new tool.

3. Restart the server after it becomes fully operational. Skip to the last step if Security server and DSMS reside on separate machines.

4. Run the IBPM Service Configuration application (GenCfg.EXE).

5. Select the DSMS tab

6. Click Update install directory on exit.

7. Click Ok.

8. Run IBPMStartup.EXE on the client machine to load the new tool to the client.

Problem

Custom tool was specified in the dp file but returned an error:

InitInstance failed in .NET Custom Tool Tester
Reported error: The form class, xxxx, was not found in the assemby, xxxx..

Possible Cause

Specification of custom tools in the dp file is case sensitive.

Solution

Make sure the dp file specifies all custom tools as case sensitive.


Syntax Specification

DSMS File Syntax Specification

File Name Conventions

Dependency files have a two part naming convention. The first part may be any number of characters and numbers up to the Windows NT file system limit, but must not be "DSMS", which is reserved by Stellent, Inc.

The second part of the dependency file name is known as the extension. The file name extension must be "dpx" (case insensitive), where x is any number from 1 to 9, but must not be "dp0", which is reserved by Stellent, Inc.

The two parts of the file name are delimited by a period (".").

Every file name with the extension of "dpx" is recognized as a dependency file. Non-dependency files must not have the extension of "dpx".

Comments and White Space Conventions

Comments and white space may be entered into the dependency file.

White space is any character, such as a tab or space character, which is displayed as a space. Blank lines are also optional.

Comments are optional in the dependency file. A comment is any instance of 'C' or C++ style comments. 'C' style comments are bracketed by "/*" and "*/" sequence of characters, and may appear on more than one line. For example:

/* This is an example of a 'C' style comment */
or
/*

This is another example of a 'C' style comment

*/

C++ style comments must only appear on one line and are defined by the sequence of two slashes ('//'). For example,

// this is a C++ style comment

Keyword Specifications

This syntax is composed of numerous keywords, which are defined in this section.

In General

  • All keywords are listed alphabetically.
  • All syntax is parsed in a case-insensitive manner.
  • Quoted strings may include quotes by placing two double quotes adjacent. For example given a command line string of:
    “/dir:””c:\program files\my documents”” “
    it would appear to the receiving program as
    /dir:”c:\program files\my documents”
  • There are four predefined substitution values that can be used within command line argument strings or the file location strings. The values for these substitutions are provided based on the current installation location. The first two strings will include quotes around them when they are substituted.
    <InstallPath>
    <SystemPath>
    <ProgramFilesPath>
    <OldInstallPath>
    <ShortcutPath>
    <OldShortcutPath>

    The second two will not include quotes around them when they are substituted
    <InstallPathNoQuotes>
    <SystemPathNoQuotes>
    <ProgramFilesPathNoQuotes>
    <OldInstallPathNoQuotes>
    <ShortcutPathNoQuotes>
    <OldShortcutPathNoQuotes>

    So the following command line
    “/dir:<InstallPath>
    /args:””<InstallPathNoQotes>\subdirectory”” “
    might look like this after substitution
    /dir:”c:\Program Files\Stellent\IBPM”
    /args:”c:\Program Files\Stellent\IBPM\subdirectory”
  • All files have the installation directory (as defined by the user) as their default installation location.
  • All actions have sequence 10 as their default install sequence.
  • Dependency files are positional in nature. Defined groups or tools must appear before they are referenced by a group or tool.
  • System maintenance by DSMS is broken up into three (3) phases: Pre-install, Install, and Post-install. The purpose of the phases are defined as follows:
  • Pre-install phase is to bring the operation system environment up to required specifications to host the IBPM product.
  • Install phase is to update the IBPM system to the correct version. This is the default install phase if no install phase is specified.
  • Post-install phase installs third-party products to be hosted by the IBPM product.

File actions and attributes

A file can have any number of actions or attributes in any order associated with it.

FILE "filename" <action id>, <attribute id>, …, <action id>

There are two types of actions: Install actions and uninstall actions. These two types of actions cannot be mixed. The only uninstall actions are DELETE and UNREGISTER. All other actions are install actions. LOCATION is currently the only attribute.

Possible actions or attributes must be one or more of the following:

DELETE – Removes the file from its specified location.

GAC - Requests that the associated object be installed into the GAC (Global Assembly Cache).

LOCATION "path" | identifier | regpath "registry-path"– Causes a file to end up in the specified location.

OSPROTECTED "w2k" | identifier – Causes a file to be ignored if the operating system specification matches.

PREINSTALL ["command line"] [ONCE | EACHVERSION] [SEQUENCE #] – Causes this action to be performed during the pre-install phase of system update.

POSTINSTALL ["command line"] [ONCE | EACHVERSION] [SEQUENCE #] – Causes this action to be performed during the post-install phase of system update.

REGISTER [SEQUENCE #] [UNVERIFIABLE] [OPTIONAL [[CLIENT] | [SERVER]]] – Causes this file to be registered.

VERSIONUPDATE – Causes the file to be updated only if a newer version of the file is available (regardless of file time stamp) .

UNGAC - Requests that the associated object be removed from the GAC (Global Assembly Cache).

UNREGISTER [SEQUENCE #] – Causes the file to be unregistered.

ACTION

The ACTION keyword defines an action that is to be performed using a program that is specified.

ACTION "Action Name" use "Program Name" (PREINSTALL... | POSTINSTALL ...)

"Action Name" refers to a unique name for this event. It must be unique within the entire scope of the dependency files included within the installation. For example: "Install Form Viewer".

"Program Name" refers to an executable that is to be executed to perform the action. The following POSTINSTALL or PREINSTALL actions define when the action will be performed and the parameters that will be provided to the program when it executes. the program must exist separately within the install as a separately downloaded element.

Example

File "FormInstaller.exe"
ACTION "Install Form Viewer" USE "FormInstaller.exe"
POSTINSTALL "/silent"

Note that in most cases the value of the ACTION clause is that it allows multiple actions to be defined that leverage the same program. The program is usually placed in a group by itself and referenced multiple times in various other groups in conjunciton with ACTION clauses.

ACTIONMODIFIER

The ACTIONMODIFIER keyword is a type of category of a tool or group. The format of the ACTIONMODIFIER keyword is:

TOOL "filename" [REGISTER] CATEGORY ACTIONMODIFIER …

{
FILE …
GROUP …
}

The ACTIONMODIFIER signifies that this tool modifies actions as they flow through the system.

CATEGORY

The CATEGORY keyword allows DSMS to specify tools by type. The format of the CATEGORY keyword is:

TOOL "filename" [REGISTER] [CLIENT] CATEGORY <ACTIONMODIFIER, SECURITYCONTEXT> …

{
FILE …
GROUP …
}

There are two categories at present of TOOLS:

ACTIONMODIFIER – Signifies that this tool modifies actions as they flow through the system.

SECURITYCONTEXT – Allows the tool to show up as a tab inside the security context component category.

The CATEGORY keyword must be followed by at least one of the above category type keywords. If more than one category type keyword is used, then the category type keywords must be separated by a comma (",") and a white-space character.

CLIENT

The CLIENT keyword causes DSMS to regard a TOOL as a client type tool. The format of the CLIENT keyword is:

TOOL "filename" [REGISTER] CLIENT

{
FILE …
GROUP …
}

TOOLS are not considered CLIENTTOOL by default.

DELETE

The DELETE keyword is a type of uninstall action which causes DSMS to remove a file from its specified location. The format of the DELETE keyword is:

FILE "filename" DELETE …

EACHVERSION

This program is executed every time the date-time or size of the program changes, which implies a new version of the program.

EXTEND

The EXTEND keyword allows a third-party developer in their dependency file to extend (or inherit from) a known GROUP or TOOL. The formats of the EXTEND keyword are:

EXTEND <groupname> // extending a group

{
FILE …
FILE …
TOOL…
}

or

EXTEND <"toolname"> // extending a tool
{
FILE …
FILE …
TOOL…
}

As a result of using the EXTEND keyword, the specified files, tools or groups are appended to the named group or tool. Consider this example:

GROUP BaseGroup

{
FILE1 …
FILE 2…
FILE3…
}

…

EXTEND BaseGroup
{
FILE 4 …
GROUP XYZ…
}

The result of the above extension is that when group BaseGroup is installed, File 4 and any files or tools specified in group XYZ will also be installed.

FILE

FILE keywords specify a file and the actions to be performed on it.

The FILE keyword may occur within a GROUP or a TOOL specification.

The format of the FILE keyword is:

FILE "filename" [<action id> ] [ LOCATION "path" | identifier ] [SEQUENCE #]

Where

FILE is the keyword

"filename" is must be quoted in double-quotes, and defines the file name and extension of the file to be installed

ACTION and <action id> are defined above

LOCATION is a keyword for where the file is to be installed, the syntax following specify the target location.

SEQUENCE # may be used to specify the order that the action should be performed. Example: SEQUENCE 5.

GAC

The GAC keyword causes DSMS to register the file or TOOL within the GAC (Global Assembly Cache).

GROUP

GROUP keywords specify a list of files.

The GROUP keyword may occur during the specification of a group, or within a TOOL specification. Thus, there are two formats of the GROUP keyword:

GROUP <group name> // definition
{
FILE …
FILE …
TOOL…
}

or

TOOL <"tool name">
{
GROUP <group name> // reference to a group
}

In the first format above, the GROUP keyword specifies the beginning of a group definition. The second use of GROUP means that a TOOL requires a specific GROUP.

The group name must be one word with no white space, and must not be quoted, and must immediately follow the word GROUP.

Dependency files may have one or more unique groups specified. TOOLS may uniquely specify one or more required groups. A specific group must be unique within a dependency file (i.e., group A may only be defined once per dependency file, but may be included as a tool requirement by multiple tools).

LOCATION

The LOCATION keyword causes DSMS to install a file to the specified location on disk, and is part of the FILE specification. The format of the LOCATION keyword is:

FILE "filename" … LOCATION "path" | identifier |regpath "registry-path"

"path" must be enclosed in double quotes, and is a file path, such as "c:\program files\Stellent\misc".

Identifier must be either SYSTEM or INSTALL if used (not enclosed in quotes). INSTALL is the default location if the LOCATION keyword is not specified.

regpath indicates that the file path to be used is located within the registry. The “registry-path” is a path to the registry value, that contains a file path, which is the location at which the file will be placed. For example:

“… LOCATION regpath
“\\HKEY_LOCAL_MACHINE\Software\Optika\ Setup\InstallDirectory “… “

The above clause directs the installation to follow the registry path to the “InstallDirectory” registry string. This contents of this registry string is then used to define the location of the file.

The default LOCATION of FILES is the user-supplied install directory.

NETTOOL

The NETTOOL keyword is used to identify client tools that utilize the .Net framework instead of COM. It may only be used in conjunction with the TOOL syntax. This command requires two configuration strings to be provided:

NETTOOL(“FormClassReference”,”Tool name”)

The subparameters are defined as follows:: “FormClassReference” is a reference to the fully namespaced reference to the class within the .Net assembly that identifies “tool” to be instantiated.

For example: MyCompany.MyProduct.Forms.PaymentForm. The second subparameter, “Tool name”, is the name that will appear in galleries to refer to this tool.

ONCE

The ONCE keyword limits the execution of a program to a single time. Once executed successfully the program will not be executed again by DSMS unless the associated keys are removed from the registry.

OPTIONAL

The OPTIONAL keyword effects the registration of files. It may be used by itself or it may be modified with the CLIENT or SERVER modifiers.

When used alone OPTIONAL indicates that the failure to register the associated file is acceptable. When used with CLIENT, it indicates that the failure to register the file is only allowable in client situations. Conversely, if used with the SERVER modifier, registration failures are acceptable on the server side.

OSPROTECTED

The OSPROTECTED keyword causes DSMS to install filter files from the download list, and is part of the FILE specification. The format of the OSPROTECTED keyword is:

FILE "filename" … OSPROTECTED "os" | identifier

“os” must be enclosed in double quotes, and is an operating system identifier, such as “w2k”.

Identifier must be W2K if used (not enclosed in quotes). There is no default filter if the OSPROTECTED keyword is not specified.

If the operating system making the DSMS request matches the OSPROTECTED designation, the file is filtered from the download list. At the present time, the only supported OS designation is “w2k”.

PREINSTALL

The PREINSTALL keyword is a type of install action causing DSMS to take action upon the file during the pre-install phase of system maintenance. The format of the PREINSTALL keyword is:

FILE "filename" PREINSTALL …

Files are acted upon during the install phase by default.

POSTINSTALL

The POSTINSTALL keyword is a type of install action causing DSMS to take action upon the file during the post-install phase of system maintenance. The format of the POSTINSTALL keyword is:

FILE "filename" POSTINSTALL …

Files are acted upon during the install phase by default.

REGISTER

The REGISTER keyword causes DSMS to register the file or TOOL as a COM object, and is a type of an action performed on a FILE or a TOOL. Thus the two formats of the REGISTER keyword are:

TOOL "filename" REGISTER …
{
FILE …
GROUP…
}

or

FILE "filename" REGISTER …

FILES or TOOLS are not registered by default.

SECURITYCONTEXT

The SECURITYCONTEXT keyword is a type of category of a tool or group. The format of the SECURITYCONTEXT keyword is:

TOOL "filename" [REGISTER] CATEGORY SECURITYCONTEXT …
{
FILE …
GROUP…
}

If this keyword is specified on a tool then the DSMS client side code will add the CLSID of the COM Server that lives in the module to the Security Context Component Category. This will allow the COM object to appear as a security tab inside of the Security Administration tool.

SEQUENCE

The SEQUENCE keyword defines which order an action should be executed.

The SEQUENCE keyword must only occur during the specification of an action. The format of the SEQUENCE keyword is:

FILE "filename" … SEQUENCE #

The default sequence number of all actions is 10.

TOOL

The TOOL keyword defines a tool and those files and/or groups required by that tool.

The TOOL keyword must only occur during the specification of a tool. The format of the TOOL keyword is:

TOOL "filename" [REGISTER] [CLIENT] [CATEGORY ACTIONMODIFIER | SECURITYCONTEXT] [NETTOOL("FormClassReference","Tool name")]
{
FILE …
GROUP…
}

The filename consists of the file name and the extension.

The REGISTER keyword may be used to cause the tool to be registered as a COM object.

The CLIENT keyword may be used to signify that this tool is a client type tool (as opposed to a server type tool). If CLIENT is not used, then this does not mean that the tool is automatically assumed to be a server type tool, simply that it is not a client tool.

The CATEGORY keyword is used to categorize a tool. Any number of categories can be listed as long as they are comma separated.

The NETTOOL keyword is used to identify tools as .Net tools.

Dependency files may have one or more unique tools specified. TOOLS may uniquely specify one or more required groups. A specific tool must be unique within a dependency file (i.e., tool B may only be defined once per dependency file).

VERSIONUPDATE

The VERSIONUPDATE keyword causes DSMS to update the file only if a newer version of the file is available, regardless of the file time stamp. The format of the VERSIONUPDATE keyword is:

FILE "filename" VERSIONUPDATE …

UNGAC

the UNREGISTER keyword causes DSMS to remove the file or TOOL from the GAC (Global Assembly Cache).

UNREGISTER

The UNREGISTER keyword causes DSMS to unregister the file as a COM object. The format of the REGISTER keyword is:

FILE "filename" UNREGISTER …

UNVERIFIABLE

The UNVERIFIABLE keyword tells the DSMS client that the registration of a particular file cannot be verified. Therefore the file will always be registered if it is updated.

FILE "filename" REGISTER [SEQUENCE #] UNVERIFIABLE

The UNVERIFIABLE keyword applies specifically to file registration. During installations the client portion of DSMS attempts to verify that registrations are correct before reapplying them. Some files do not follow the guidelines for constructing registry entries generally used by applications that may be registered. In these cases, the DSMS client may repeatedly re-register files since it can not determine that the file is correctly registered. Applying this modifier directs DSMS to assure that registrations are correct, but if any changes are detected within the installed base, to re-register these files as a precautionary measure.


Action Modifier Overview

The topic provides a brief overview of the functionality provided by the Action Modifier Toolkit.

Document Actions

When a user right clicks on a hit in the Search Results Tool, a menu is presented indicating the list of operations that are available for that document. The available options might be such things as Open, Print or Annotate. These menu options, or, generically, Document Actions, are the subject of the Action Modifier Toolkit.

The Toolkit addresses document actions from two perspectives, a consumer and an implementer. From a Consumer perspective, the Toolkit provides support for an application performing custom display of some set of documents stored in Imaging similar to Search Results, or for an application or Form which might be providing custom display of attachments added to an BPM Package. The SDK makes the list of actions for the document/attachment available and provides a mechanism for making a call to perform the given action on the document.

From an Implementer's perspective, the Toolkit can be used to implement custom handling for documents stored within the system. By implementing the appropriate interfaces within the SDK, a custom component can either overload the default actions provided for the standard document types (image, COLD, universal) or provide new handlers for new data types.

Consumers

The following description will describe the Toolkit architecture from the consumer perspective. For the purpose of explanation, the discussion will focus on a hypothetical application which presents a list of documents. Each item in the list must have a unique token to represent the Document and its index values. This functionality is jointly provided by the DocumentId and the IndexId objects. The properties of the DocumentId provide sufficient information to both determine a document's type (based on its MIMEType and to retrieve the actual object data (i.e. to view it). The IndexId provides sufficient information to access the index row for the Document.

Once the list of items is presented (and the Document Ids and Index Ids are stored internally), the user may right click, requesting a popup menu of the actions available for a specific document. The list of options that should be returned is determined by figuring out which ActionModifiers are currently registered in the system. An ActionModifer is simply a component which exposes a collection of Verbs for documents of a given MIME Type. Each verb corresponds to a single Document Action (such as Print or Open).

The container does not have to figure out what ActionModifiers are registered directly. This functionality is encapsulated in the ActionModiferLibrarian. To get the ActionModifiers collection for the selected document, the application needs to create an ActionModiferLibrarian, set the Filer property with the MIME Type string of the selection, and then retrieve the ActionModifiers property. The ActionModiferLibrarian will figure out the registration details and fill the ActionModifiers collection with the ActionModifer objects that support the filtered MIME Type. With the ActionModifiers collection, the application can iterate through the ActionModifer objects, getting the Verbs collection for each. Each Verb in the collection can then be presented in Menu form.

Once a specific menu selection is made by the user, the application bundles the DocumentId, IndexId, and a Description text string (Title) for the document, and uses it to call the selected Verb.Invoke method.

Implementation

An implementation of a custom document type handler is basically a COM object that supports the IActionModifier interface and is registered in the ActionModiferLibrarian's component category. Actually, because the type information is currently only MIME Type based, the object must also implement the IMIMETypeActionModifier. IMIMETypeActionModifier is derived from IActionModifier and adds only the SupportedMIMETypes property. To implement this function, the object need only return an array of strings listing the MIME types which it can handle. The ActionModiferLibrarian reads its component category and calls the SupportedMIMETypes on each object to build a map of which ActionModifiers support which MIME Types. It then uses this map when a consumer sets a MIME Type filter and requests an ActionModifiers collection.

Secondly, the implementer must fill the Verbs collection when the consumer requests it. To fill the Verbs collection, the implementation must create the collection and then call Verbs.Add. This will create and return a new verb in the collection. The add verb can specify the type of the verb. The type can specify certain default type of operations which have generic meaning. For instance, the otOpen type is traditionally the verb invoked when the document is double clicked.

The returned Verb must be filled out with a Caption (i.e. the menu item text), Description, ToolTipText, Picture, and VerbId. The VerbId must be a unique identifier for the verb and is typically a GUID string. In many cases it will also be the MessageId that is sent when the verb is invoked.

By default, The Verb.Invoke method will interpret the VerbId as a MessageId. It bundles the SelectItems passed in and sends them as a Tagged Message with MessageId equal to the VerbId. If this functionality is desired, an Action Handler tool must be written and exist on the system to receive the message and perform the desired operation.

Optionally the InvokeHelper property may be set on the Verb. The object set to InvokeHelper is a COM object which supports the IVerbInvokeHelper interface. To provide custom handling for a verb (i.e. handling that is not received via a message,) the implementer of IVerbInvokeHelper implements the IVerbInvokeHelper.Invoke method to perform the custom operation.


SDK Reference Guide Home Page

Oracle® Imaging and Process Management

Software Development Kit (SDK) Reference Guide
Version 7.7

May 2007

Oracle

Oracle Imaging and Process Management Software Development Kit Reference Guide, Release 7.7

Copyright © 1998, 2007, Oracle. All rights reserved.

Primary Author: Amy Willard

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.


Upgrading Exisiting Code

Upgrading Existing Code

The changes that have been made to the SDK (as of Acorde 3.1) are designed to make the toolkit simpler to understand, easier to use, and to facilitate custom application distribution. With all of the changes however, the toolkit remains binary compatible with previous version of IBPM. This means that executable modules and DLL's written and compiled against the toolkit supplied with previous IBPM versions will function without any changes.

If the code is opened up into Visual Basic, a number of changes will be required to make the code compile and function properly. Fortunately, a Visual Basic Add-in called the Stellent IBPM SDK Update Wizard is provided that will automatically perform the search and replace function required to make the code compile.

The following topic provides a detailed explanation of all of the changes that are required to upgrade pre 3.1 code to IBPM 7.5.

Module Name Changes

Since pre-Acorde 3.1, the number of modules required to support the IBPM SDK has been reduced by 60%. In doing so, the total footprint in disk space was reduce by approximately 30%. To accomplish this, all of the COM objects that comprise the IBPM toolkit were repackaged into 5 basic modules. Note: Process Dialogs, Process ActiveX, Printing/Faxing and Viewing objects were not modified.

OTAcorde.dll - IBPM Base Object Library: Contains all of the core components without which no other part of the toolkit will function. User, UserToken, MarshallingAgent, Domains, Domain, Dictionary, DocInfo, DocumentId, IndexId, etc.

OTContext.dll - Imaging Object Library: This module contains all of the object models needed to access the Imaging product. Query, Schema, ExportManager, Cache, Picklist, DocumentManager.

OTProcess.dll - BPM Object Library: This is the same the old OTWFLOW module, just renamed to be consistent IBPM product names.

OTActMod.dll - IBPM Action Modifiers Library: This module remains unchanged, it still contains all components required for supported action modifiers, both in Imaging and BPM.

OTTool.dll - IBPM Tool Hosting Type Library: This module consists only of a type library containing all of the interfaces required for hosting a tool within the IBPM Client. ITool, IMessageHandler, IClientHost, etc.

OTClient.dll - IBPM Client Object Library: Contains lesser, predominately internally used SDK components and/or components that are primarily used by the IBPM Client. Galleries and Gallery.

Because of the re-packaging, any existing code that refers to the old module names (OTUSRSECLib, OTQUERYLib, OTSCHEMALib, etc) need to be replaced with the new module names. The following table lists all of the required replacements. (The Stellent IBPM SDK Update Wizard makes these changes automatically.)

New Library | Old Library
OTACORDELib | OTUSRSECLib
OTDOMAINLib
OTMAGENT2Lib
OTMSGLib
OTTAGMSGLib
OTRAWMSGLib
OTMSGDSCLib
OTDOCIDLib
OTCONTAINERSLib
OTMSGDEFLib
OTLICLib
OTCONTEXTLib | OTSYSMGRLib
OTSCHEMALib
OTEXPTMRLib
OTCACHELib
OTQUERYLib
OTPICKLISTLib
OTPROCESSLib | OTWFLOWLib
OTTOOLLib | OTHOSTLib
OTCLIENTHOSTLib
OTMSGHNDLib
OTSECCXTLib
OTCLIENTLib | OTGALLib
OTDSMSLib
OTTOOLMRLib
OTTOOLDNLib
OTLGTOOLLib

In addition to changing all of the old module names to the new module names in the code, the Visual Basic Project References will needed to be updated to point to the new modules. The Stellent IBPM SDK Update wizard makes these changes automatically.

Object/Enumeration Name Changes

In previous versions of the IBPM SDK, there were a few objects that were named so badly it was confusing to many customers and was difficult to understand exactly what the objects were used for and where the fit in the model. While there are many name changes in the new toolkit where the old names are still supported; there are a select few instances where the old names are completely removed and therefore a change IS required.

  1. SystemManager2 is now DocumentManager. This name was change to to avoid the continuing confusion over the difference between the back-end server System Manager component and the SDK object, they are two unrelated objects with the same name. Additionally, the old name, SystemManager2, did not convey the purpose of the object, which is to create, index, modify, and retrieve documents. In the regard, DocumentManager is a much more intuitive name.
  2. In the query model, all references to the term "Predicate" have been changed to Condition. Specifically, BinaryPredicate is now BinaryCondition. The purpose of this change is the confusion caused by the term "Predicate". While it is actually a perfectly valid SQL term, few users knew what it meant. Because the object is contained in the model by NamedQueryConditions and SearchCondtions, the term BinaryCondition should be more intuitive as to where the object fits with the model.
  3. A number of enumeration values in the SDK were mixed up. Some had both a version beginning with the phrase "tag" and without. For example, there was both a tagotProcessMessageReturn and an otProcessMessageReturn. Both values could be used interchangeably, but the fact that both existed was very confusing to many users. All of the "tag" version enumerations have now been removed. (Most of the enumeration constants involved are used very infrequently.)

The following table details the complete list of REQUIRED object/enumeration name changes. The Stellent IBPM SDK Update wizard makes these changes automatically.

Old Name | New Name
SystemManager2 | DocumentManager
BinaryPredicate | BinaryCondition
SelectField | BinaryConditionField
otPredicateOperator | otComparisonOperator
otConditionType_BinaryPredicate | otConditionType_BinaryCondition
tagotToolStyle | otToolStyle
tagotActivateReason | otActivateReason
tagotActivateResult | otActivateResult
tagotDeActivateReason | otDeActivateReason
tagotDeActivateResult | otDeActivateResult
tagotProcessMessageReturn | otProcessMessageReturn
tagotShowCommand | otShowCommand
tagotActionType | otActionType
tagotDictionaryAccessMode | otDictionaryAccessMode
tagotDataFormatStyle | otDataFormatStyle
tagotMessageStyle | otMessageStyle
tagotRoutingDescriptor | otRoutingDescriptor
tagotMessageDefnStyle | otMessageDefnStyle
tagotStyle | otStyle
tagotDSMSConfiguration | otDSMSConfiguration


Working with Process ActiveX controls

Working with Process SDK™ ActiveX controls

text


Working with Definition Objects

Two of the primary trees in the Process SDK™ Toolkit Object Model exist for the sole purpose of allow the use to obtain information about how what entities are defined in an BPM database, these are the Processes Tree and the Templates tree.

From the Processes tree, one can enumerate the list of processes within the database. If a particular process is chosen, the sub


Tool Creation and IBPM Client Interaction Management

Each Custom Tool within a Gallery is created when it becomes active and terminated when it becomes inactive. This allows the tool to perform tasks during the entire lifetime of the Gallery. The ToolNotifier object defines a set of events and properties that are called by the IBPM Client Framework to notify the Custom Tool of relevant events within the framework. These event invocations follow a protocol allowing the Custom Tool to exercise complete control over its state and operation.

When the custom tool is created by the IBPM Client framework, the tool should perform any necessary initialization here. The tool should create its Stellent.IBPM.Client.ToolNotifier object here. The ToolNotifier object’s lifespan should be for the duration of the custom tool. When creating the ToolNotifier object the only parameter required is a reference to the Win Form class itself.

The following is a list of the ToolNotifier events used to notify the tool of relevant framework events:

ShowingTool

The ShowingTool event is fired from the ToolNotifier object in response to the IBPM Client Framework’s request that the tool become active. The event arguments passed include the reason the show request has been made. By default if the event is not handled the tool will respond with the action to bring the tool to the front of the currently displayed tools. Should the reason for showing be a process message action the MessageId property of the event arguments will be populated with the GUID of the message about to be received. The event arguments Action property should be set to reflect the operation wanted, either Show, Bring To Front, or Remain As Is can be chosen.

The ShowingTool event is typically fired in response to the framework’s request for the tool to be displayed when the user selects the tool from the Client View menu.

HidingTool

The HidingTool event is fired from the ToolNotifier object in response to the IBPM Client Framework’s request that the tool become deactivated. The event arguments passed include the reason the hide request has been made. By default if the event is not handled the tool will respond with the action to hide the tool. The tool developer is free to apply the specific meaning and implications of the tool leaving the active state. The tool has the option of either accepting or rejecting the hide tool request. To accept the request set the HideTool property of the event arguments to true. To reject the request set the HideTool property to false.

The HidingTool event is typically fired in response to the framework’s request when the tool’s user interface child window is closed. It can also be called when the client is closed or the gallery is switched.

MessageReceived

The MessageReceived event is fired from the ToolNotifier object in response to registered message being received from the IBPM Client Framework. The event arguments passed include properties for the MessageId which will be a GUID that was previously registered through a call to ToolNotifier.AddMessageToListener. The MessageId can be used to determine what actions are required by the developer of the tool. The Request object in the event arguments is a Stellent.IBPM.Client.MessageDictionary which has the key/value pairs for the message to be processed. The Reply object in the event arguments is also a MessageDictionary that can be filled out to with key/value pairs to be returned to the message sender. The MessageHandled property of the event arguments is used to let the IBPM Client Framework know if a message handler has been found and has handled this message. The PostProcessMessageAction property can be used by the developer to cause the tool to be shown after processing a message, by default this property is set to RemainAsIs.

The following is a list of the ToolNotifier methods to help a custom tool interact within the client framework:

AddMessageToListener

This method takes a string representation of a GUID as a message identifier that the tool requests to be notified of from the IBPM Client Framework. A MessageReceived event, see above, will be fired when a message matching the GUID is received.

HideTool

The HideTool method can be used by the custom tool to cause the IBPM Client Framework to hide its tool window and place the tool in the deactivated state.

ShowTool

The ShowTool can be used by the custom tool to cause the IBPM Client Framework to show its tool window and place the tool in the activated state.

SendClientMessage

SendClientMessage can be used to interact with other client tools through the use of messages.

The following is a list of the ToolNotifier properties to enhance a custom tool:

UserToken

This is the usertoken of user logged into the IBPM Client Framework and can be used to interact with other IBPM SDK objects. It is available once the ToolNotifier object has been created.

StatusBarText

To set the text in the status bar of the IBPM Client Framework just pass the string wished to be displayed. To clear the text of the status bar pass an empty string.

ToolBusy

The ToolBusy property is used to turn on/off the IBPM Client Framework busy indicator, the spinning Stellent ‘S’ in the top right hand corner of the client.


AMY THIS IS NO LONGER SUPPORTED PLEASE REMOVE THIS PAGE.

Tool Styles