Professional Documents
Culture Documents
6
Enterprise Component Library for .NET User Guide
May 2008
Copyright Notice
Metastorm, Metastorm BPM, e-Work, Process Pod, Enterprise Process Advantage, ProVision, The Best Process Wins, Proforma, Metastorm Knowledge Exchange, Metastorm DNA, Metastorm Discovery, STAR, Insight, Envision, and Metastorm Enterprise are either registered trademarks or trademarks of Metastorm in the United States and/or other countries. Microsoft, Outlook, SQL Server, Windows, Vista, Active Directory, Visual Basic, JScript, SharePoint and BizTalk are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Adobe is a registered trademark of Adobe Systems, Inc. Netscape is a registered trademark of Netscape Communications Corporation. Other trademarks are the property of their respective owners.
Disclaimer
Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However, Metastorm accepts no responsibility, and offers no warranty whether expressed or implied, for the accuracy of this publication. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the express written permission of Metastorm Inc. The information in this document is subject to change without notice.
ii
May 2008
Contents
2 3
4 5
Appendix A - ECL Files ............................................................................................................................ 32 ECL Server and Client (Common) Files .............................................................................................................32 ECL Client Component Files...............................................................................................................................33
May 2008
iii
ECL Sample Client Files...................................................................................................................................... 33 Appendix B - Deployment Details........................................................................................................... 35 Configuration Files............................................................................................................................................... 35 Client Configuration Service List Files ................................................................................................... 35 Server Configuration ................................................................................................................................... 37 Detailed Configuration......................................................................................................................................... 39 Local Direct Access..................................................................................................................................... 39 Remote High Performance.......................................................................................................................... 41 Remote Open ............................................................................................................................................... 43
iv
May 2008
Metastorm BPM Release 7.6 Enterprise Component Library for .NET User Guide
INTRODUCTION
This guide is intended to describe: What the Enterprise Component Library for .NET (.NET ECL) is. How to deploy the .NET ECL. How to test ECL Remoting. How to use the .NET ECL interfaces to develop Metastorm Client applications. How to use the sample Metastorm Client application supplied with the .NET ECL.
1.1
Acronyms
May 2008
Acronym SDK SOAP SQL SSO TCP TP UI URI URL VPN XML Software Development Kit Simple Object Access Protocol Structured Query Language Single Sign-on Transmission Control Protocol Transaction Protocol User Interface Uniform Resource Identifier Uniform Resource Locator Virtual Private Network Extensible Markup Language
Meaning
Table 1: Acronyms
1.2
This manual does not cover remoting technology in detail. The .NET ECL is part of the Process Orchestrator for .NET, which also includes the .NET Activator. This manual does not cover the .NET Activator or the Process Orchestrator for .NET in detail. The following table lists where to find detailed information on these topics:
For Information on Remoting technology .NET Activator Process Orchestrator for .NET See http://msdn.microsoft.com/library/default.asp?url=/library/enus/dndotnet/html/introremoting.asp .NET Activator Help Process Orchestrator for .NET Designer's Guide
May 2008
The Metastorm Transaction Protocol API has provided access to elements of Metastorm functionality. This requires Metastorm Clients to encode requests into an XML document, and returns responses in the same form. The Enterprise Component Library for .NET (.NET ECL) is a class library which exposes a component-based interface for Metastorm functionality. It is easier to use than the Metastorm Transaction Protocol because: Construction and parsing of XML documents is no longer required, as methods are provided for individual elements of Metastorm functionality. Each session is now maintained transparently by the Session object itself, and Metastorm Clients no longer need to handle Session IDs.
May 2008
2.1
ECL Architecture
The following diagram illustrates how the components of the .NET ECL interact:
Figure 1: .NET ECL Architecture For details of the Server components, refer to Appendix A.
May 2008
This Section provides an overview of the deployment of the .NET ECL components, and covers: Configuration options overview Location of configuration file.
For more detail of the deployment configurations, refer to Appendix B.
There are three configuration options: Direct Access Remote High Performance Remote Open.
3.1
Direct Access
Direct Access is only applicable where the ECL Client and Server are installed on the same host.
3.2
The ECL server side component is hosted directly in the Engine process. In order to provide maximum performance, the remoting connection may be configured to use only the TCP protocol with the binary message formatter. This option is not compatible with Metastorm SSO. Firewall restrictions may render this option unusable.
3.3
Remote Open
The ECL server side component is hosted by IIS and consequently the only supported protocol is HTTP. By default messages are binary formatted, but SOAP may be used in order to overcome firewall restrictions. This option is required when using Metastorm SSO. The Remote Open
May 2008
configuration may be a better option when large numbers of concurrent users are expected because IIS is optimised for scalability.
3.4
The Service List Configuration file (EngineServiceConfig.xml) determines the protocol that a client uses to connect to a particular Metastorm service.
For further information on EngineServiceConfig.xml is documented, refer to the Adminstration Guide.pdf, and the section Configuring the List of Available Metastorm Services.
3.5
The Version 7 SR1 ECL Client is compatible with the Release 7.5 Engine. It is not necessary to take any steps in order to run this configuration. However, customers running this configuration cannot take advantage of new client-side features introduced in 7.5. Upgrading the engine from versions earlier than 7 SR1 does require the following additional steps: For Metastorm .NET ECL to operate correctly the (Version 7 or earlier) client-side components version number must be the same as the server-side components version number. This means is that any existing applications built using earlier versions of .NET ECL client-side components must be migrated to the latest version if the server-side components, hosted in the Engine process, are updated. Usually, migrating applications that depend on earlier version of a component requires recompiling the applications. The .NET Framework provides a mechanism call Assembly Binding Redirection that enables existing applications to use the latest .NET ECL client-side components by making a few changes to the application configuration files. For .NET Windows application, the application configuration file is often referred to as the app.config file, where the actual file name is based on the name of the application itself. For example, if the application name is myprogram.exe, then the configuration file name will be myprogram.exe.config. This file must be in the same directory as myprogram.exe. For .NET web applications, the application configuration file is the web.config file. Redirection is needed on the following .NET ECL client-side components: Metastorm.ECL.dll Metastorm.ECL.Support.dll
10
May 2008
The following example shows how to redirect .NET ECL version 6.6.2.40 client-side components to version 7.0.0.8 <configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="Metastorm.ECL" publicKeyToken="0fa3cc64eebf4c8b" culture="neutral" /> <bindingRedirect oldVersion="6.6.2.40" newVersion="7.0.0.8"/> </dependentAssembly> <dependentAssembly> <assemblyIdentity name="Metastorm.ECL.Support" publicKeyToken="0fa3cc64eebf4c8b" culture="neutral" /> <bindingRedirect oldVersion="6.6.2.40" newVersion="7.0.0.8"/> </dependentAssembly> </assemblyBinding> </runtime> </configuration>
For information on assembly binding redirection, refer to Microsoft .NET General Reference documentation.
May 2008
11
An application, TestECLRemoting, is provided to test whether a Client can connect remotely to the Engine. This can be found in the following location, after installation of the .NET ECL: <.NET ECL location>\Client Library\Test ECL Remoting\Metastorm.ECL.TestECLRemoting.exe To test ECL remoting: 1. Double-click on TestECLRemoting.exe. The ECL Client dialog is displayed:
For further information on the status, click on the Details button. 2. Select the Services menu, then the Select Service menu option. The Service List dialog is displayed:
12
May 2008
3. 4.
Choose the configuration file for the type of connection you want to test. Click on the Refresh button to see the list of services. The Services are listed:
May 2008
13
5.
6.
7. 8.
Enter a valid Metastorm User Name and Password. Click on the Login button. If the login is successful, the message 'Login succeeded' is displayed:
14
May 2008
9.
Click on the Logout button to log out. If the logout is successful, the message 'Logged out' is displayed:
May 2008
15
This section provides an overview of how the Enterprise Component Library for .NET can be used to build a custom Metastorm Client. It covers: An overview of how to use the .NET ECL. The documented interfaces of the .NET ECL class library. Creation of a Session object. Logging in. Logging out. Retrieving alerts and forms lists. Navigating processes. Changing Metastorm data. Managing a session using XML.
For a detailed listing of the Enterprise Component Library for .NET, refer to the Metastorm Enterprise Component Library Help. For details of the sample application provided with the .NET ECL, refer to Section 6.
5.1
The general approach to using the .NET ECL to implement a Client is: 1. 2. In Visual Studio .NET, the developer imports a reference to the Metastorm.ECL.dll, Metastorm.ECL.Support.dll and Interop.ADODB.dll assemblies. The Client creates a SessionConfigurer object.
16
May 2008
3. 4.
The SessionConfigurer object obtains information from a configuration file about service locations, etc. The Client calls the SessionConfigurer's CreateSession method to create the Session object.
For further details, refer to the Metastorm .NET Class Library Help.
The Session object is used to hold persistent client-related information, for example, Metastorm Session ID, client locale, preference for form layout to be returned in responses. 5. 6. 7. The Client calls the Session objects Login method to pass credentials to an Engine. The Client makes other calls on ISession to accomplish the users task. For each required element of Client functionality: i. ii. iii. iv. 8. The Client calls the relevant methods of the Session object. The Session object communicates with the .NET ECL. The .NET ECL communicates with the Engine. The Engine performs the required operations.
The Client calls the Session objects Logout method and the session ID is removed from the Session object.
5.2
Interfaces
These classes provide the prime interface to a service: ISession, provides the Metastorm service interface. ISession2, extends ISession to provide an enhanced service interface. ISessionConfigurer, which is used to configure and control sessions on the client side but contains nothing that corresponds to a TP request. ISessionConfigurer2, extends the ISessionConfigurer interface to configure and control enhanced service sessions on the client side
These classes provide high-level access to the following functionality: Session maintenance (login, logout). Blank and Admin Forms. To Do and Watch List Alerts.
May 2008
17
They also permit user interaction with Metastorm BPM by providing methods to: Start, commit, and cancel actions. Open folders. Manage attachments. Refill forms.
Responses from the service are returned to the ECL client as simple or complex data types (for example: Session ID, Form, Folder, Action List, Alerts list in DataSet ). All operations provided by the Metastorm TP are exposed as ECL methods. Developers writing .NET clients can implement their application using the ISession class as the interface to the underlying Metastorm technology.
5.3
Creating a Session
A Metastorm Client creates an ESessionConfigurer object, which obtains information from a configuration file about service locations, then calls the ESessionConfigurer's CreateSession method to create an ESession object. The following sample code demonstrates the use of ESessionConfigurer to create an ESession object:
ISessionConfigurer sessionConfigurer = new ESessionConfigurer(); sessionConfigurer.ConfigLocation = "http://<host>/<directory>/servicelist.config"; if ( sessionConfigurer.Ready ) { ISession session = sessionConfigurer.CreateSession(); }
5.4
Logging In
Custom .NET clients can authenticate to a Metastorm service via: Simple login, using the built in Metastorm user table. Open Authentication-compatible login method.
5.4.1
Authentication is achieved through the Login and Logout methods of the ISession class.
18
May 2008
To use the simple Login method, the eUser.js Metastorm open authentication SAP must be installed and assigned.
For information on Metastorm open authentication SAPs, refer to the Administration Guide and the Open Authentication document provided with the Metastorm Software Developers Kit.
The following sample code demonstrates the use of ISession to authenticate to a service:
ISession session = sessionConfigurer.CreateSession(); session.ServiceName = "Metastorm Server"; session.Login("username", "password"); if ( session.LoggedIn ) { // Can carry out authenticated operations here... }
5.4.2
The Client must have knowledge of the authentication SAPs requirements, and must construct the field input list to match the expected login data.
For information on Metastorm open authentication SAPs, refer to the Administration Guide and the Open Authentication document provided with the Metastorm Software Developers Kit.
The following sample code demonstrates the use of ISession to authenticate to a service using the Open Authentication-compatible Login method:
FieldList loginData = new FieldList(); loginData.Add( username, new Field( "username", "user name" )); loginData.Add( password, new Field( "password", "password" )); session.Login( "WEB", "0", loginData ); if ( session.LoggedIn ) { // Can carry out authenticated operations here... }
5.4.3
The following sample code demonstrates authentication to a service using Single Sign-on:
FieldList loginData = new FieldList(); session.Login( "WEB;SSO", "0", loginData ); if (session.LoggedIn) { // Can carry out authenticated operations here... }
May 2008
19
5.5
Logging Out
The following sample code demonstrates how to log the current user out:
ISession session = sessionConfigurer.CreateSession(); session.ServiceName = "Metastorm Server"; session.Login("username", "password"); if ( session.LoggedIn ) { // Can carry out authenticated operations here... // Finished with session... session.Logout(); bool authenticated = session.LoggedIn; // authenticated = false; }
5.6
Alerts and forms are available through typed Datasets which permit data binding to UI. The form and alerts collections are populated from the relevant TP list responses behind the faade of the ISession class. The ISession class maintains four types of list (To Do, Watch, Blank Forms, and Admin Forms), and handles the population and subsequent refreshes for each list. To Do and Watch lists are represented by instances of the AlertsDataSet class, which is derived from System.Data.Dataset. Blank and Admin Forms lists are represented by instances of the FormsDataset class. The contents of these four collections can be retrieved using the following ISession methods: BlankFormsList. AdminFormsList. ToDoList. WatchList.
These methods have the following parameters: FilterType filter If the filter parameter is null, all of the alerts or forms are returned. Where SQL where clause Combined with the Filter parameter to filter the list contents. string orderBy
20
May 2008
If orderBy is null, the alerts or forms are returned in the default sort order. This parameter takes the form of an SQL Where clause.
For a complete list of fields available for the Where clause expression, refer to the Transaction Protocol Developers Guide, which is provided with the Metastorm Software Developers Kit.
int page The page value refers to the page of the alerts or forms collection to return. The alerts or forms returned will also depend on the value specified for the pageSize parameter.
int pageSize The pageSize value is the number of alerts or forms to return on each page of the alerts collection. If the page or pageSize parameters are 1 then all alerts or forms will be returned. Lists should be refreshed whenever the user changes their filter, order, page or pageSize options. Simple Blank Forms Example The following sample code demonstrates how to obtain the first page of 10 blank forms, ordered by map name.
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... eFormsListResponse blankFormsList = session.BlankFormsList( null, "eMapName", "", 1, 10 );
Admin Forms Example The following sample code demonstrates how to obtain all admin forms published as part of the Customer Admin procedure.
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... eFormsListResponse adminFormsList = session.AdminFormsList( null, "", "eProcedureName = 'Customer Admin'", -1, -1 );
ToDo List Example The following sample code demonstrates requesting a ToDo list, then starting an action on the first alert in the list.
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... eAlertsListResponse todoList = session.ToDoList( null, "", "", -1, -1 );
May 2008
21
eActionResponse actionResponse = null; eSubmitResponse submitResponse = null; AlertsDataSet.AlertRow alert = todoList.Alerts.row[0]; session.StartAction( alert.eFolderID, alert.eMapName, "action name", false, 1, null, out actionResponse, out submitResponse ); // User can refill, cancel, or submit action here...
5.6.1
Filtering Lists
Filters are organized hierarchically: To Do and Watch lists: Service Process Stage
Blank and Admin Forms lists: Service Group Filters are queried on a per-service basis. Each eSession instance corresponds to a single service. The available filters for each of the four list types are populated by, and available through the interface of, the eSession instance. Alert lists can be filtered by service, map, or stage name. Form lists can be filtered by service and group name. A filter can be obtained by calling the Filter method in one of the following ways: FilterType[ ] FilterType[ ] FilterType[ ] todoFilters = session.Filters(ListContentsType.ToDo); todoFilters = session.Filters(ListContentsType.Watch); todoFilters = session.Filters(ListContentsType.Blank);
FilterType[ ] todoFilters = session.Filters(ListContentsType.Admin); The four list types (To Do, Watch, Blank Forms, and Admin Forms) can be refreshed at any point by calling the Filter method again or the corresponding member of eSession: BlankFormsList. AdminFormsList. ToDoList. WatchList.
To Do List Filter Example The following sample code demonstrates how to pick a specific filter from the hierarchy and use it to restrict an alerts list request. Typically, the filter hierarchy is displayed in a tree and alerts/forms list updates are made when the user clicks on tree nodes.
22
May 2008
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... FilterType[] todoFilters = this.session.Filters( ListContentsType.Todo ); FilterType selectedFilter = todoFilters[0].Filter[0].Filter[1]; eAlertsListResponse todoList = session.ToDoList( selectedFilter, "", "", -1, -1 );
5.7
Navigating Processes
This section describes how to open a folder, start an action, perform a refill, and submit and cancel action requests and responses.
5.7.1
Opening a Folder
To open an existing folder from a users To Do or Watch list, make a call to the eSessions OpenFolder method you will need to know the folderID for the folder. The folderID must be specified, but the second String page parameter is optional. If the page parameter is not specified, the first form for the folder will be returned. The call to OpenFolder returns a Folder object, which has the following properties: FieldList. FolderActionType. FolderPageType. FolderLayoutType. FolderID. FolderName. MapName. Name. StageName.
OpenFolder Example The following sample code demonstrates how to use the OpenFolder method to open a folder:
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... Folder folder = session.OpenFolder( "folder id", "form name" ); // Step through the field data of the form... foreach ( OutputField fieldData in folder.Fields )
May 2008
23
5.7.2
Performing Refills
If a page contains fields that are dependent on other fields, a refill request should be made whenever the fields that have dependants are updated. A button may also have fields that are dependent on it. The request must include any updated field and grid values. Refill and Field Value Example The following sample code demonstrates how to start an action, update one of the field values in the action form, then refill to update the folder field in the service database. The form has a server-action button (intended to trigger a refill when pressed), named RefillButton, and an editable text field name, EditableText, which is to have a new value written to it.
ActionResponse response = session.StartAction( "folder id", "map name", "action name", false, null ); if ( response.Type == ActionResponseType.Action ) { Action action = response.Action; action.Fields[ "EditableText" ].Value = "hello, world"; action.RefillUpdates = new string[]{ "RefillButton" }; Refill refillResponse = session.Refill( action.FolderID, action.Name, action.FormName, action.RefillUpdates, action.ServerData, action.Fields ); // Action is still locked, user can carry out further refills, cancel, or submit. }
5.7.3
Once a folder has been opened, it is possible to find out the form and action information for that folder. The form can then be updated and actions can be submitted or canceled. There are three types of actions: Confirmation actions A confirmation action is a two-step process. Once an action has been started, the client must cancel or commit this action. Non-confirmation actions Non-confirmation actions will be committed immediately when the call to StartAction is made. Form actions To close a folder or form without making any changes, make a call to CancelAction.
24
May 2008
Submit Example The following sample code demonstrates how to update a field and use the SubmitAction method to submit a form:
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... ActionResponse response = session.StartAction( "folder id", "map name", "action name" ); // Folder is locked, field values may be updated. Action action = response.Action; action.Fields["TextField"].Value = "updated text"; session.SubmitAction( action.FolderID, action.Name, action.FormName, action.Server, action.Fields ); // Folder is unlocked, is now at stage pointed to be submitted action, // and field values have been written to the database.
5.8
5.8.1
This section includes examples of posting, retrieving and deleting attachments. If an attachment with the same name exists in the Metastorm database, the Engine amends the name. Developers can query the name of the attachment that has been posted, as shown in the following examples: PostAttachment Example
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... // Post a file attachment... System.IO.FileStream fileData = System.IO.File.OpenRead( "filename" ); string attachmentName = session.PostAttachment( "folder id", "filename", fileData );
GetAttachment Example
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... // Post a file attachment... System.IO.FileStream fileData = System.IO.File.OpenRead( "filename" ); string attachmentName
May 2008
25
= session.PostAttachment( "folder id", "filename", fileData ); // Retrieve the file attachment... System.IO.Stream attachmentData = session.GetAttachment( attachmentName, "Folder", "folder id" );
DropAttachment Example
ISession session = sessionConfigurer.CreateSession(); // Select service and login here... // Post a file attachment... System.IO.FileStream fileData = System.IO.File.OpenRead( "filename" ); string attachmentName = session.PostAttachment( "folder id", "filename", fileData ); // Delete the file attachment... session.DropAttachment( "folder id", attachmentName );
5.8.2
Error Handling
An ESessionException is raised when an ISession operation fails. Exception Example The following sample code shows how to handle a Session exception.
try { eCancelResponse cancelResponse = session.CancelAction( "folder id", "action name" ); // Action was cancelled successfully. } catch ( ESessionException ex ) { // Action cancellation failed, find out why: System.Windows.Forms.MessageBox.Show( ex.Message ); }
5.9
The eWorkTransaction method of the eSession class continues, as in previous versions, to permit raw TP requests to be made to the Metastorm Engine. The XML request is passed in, and an XML response is returned. The method is:
public string eWorkTransaction (string request) For help in forming TP requests, refer to the Transaction Protocol Developer Guide, provided with the Metastorm SDK.
26
May 2008
Clients using this method must carry out their own session management. This is different to all other public methods of eSession, which require each instance to be authenticated before other operations can be successfully carried out.
All Metastorm BPM operations can be performed by the .NET ECL. Use of the TP is not necessary. We recommend using the high-level .NET ECL operations and not the TP.
May 2008
27
FilterType filter Specify a custom list filter; this must have been obtained from a previous custom list response for the same type of custom list. All available items can be obtained by passing null in this parameter.
string orderBy Not implemented. Reserved for future use. string where Not implemented. Reserved for future use. int page A one-based index to indicate the page size. Specify -1 to return all the items in the list. If a value other than -1 is specified then the pageSize parameter must also be specified.
int pageSize Specify the number of items to return in a page. Specify -1 to return all the items in the list.
bool filters A boolean value indicates if filter information should be included in the response.
Custom List Example The following sample code demonstrates how to obtain the first page of 10 custom list items for the custom list with the identifier Custom.Alerts.
ISession2 session = sessionConfigurer.CreateSession2(); // Select service and login here... eListResponse customList = session.CustomList(Custom.Alerts, null, null, null, 1, 10);
28
May 2008
A sample application is provided to demonstrate how the .NET ECL can be used to create a Metastorm Client application. This can be found in the following location, after installation of the .NET ECL: <.NET ECL location>\Client Library\ECL Sample Client The following subsections describe how to: Build the sample. Use the sample.
It is possible to use the sample without building it.
6.1
To build the sample: 1. 2. Open the Visual Studio solution file in Visual Studio .NET. Import a reference to Metastorm.ECL.dll and Metastorm.ECL.Support.dll and Interop.ADODB.dll assemblies. Public classes are contained in the Metastorm.ECL namespace. The assemblies can be found in the following location, after installation of the .NET ECL: <.NET ECL location>\Client Library\Redistributables 3. Build the solution in the normal way.
Before debugging the sample client in Visual Studio, open the samples property pages and set the Start Options Specific Page setting to ecllogin.aspx.
May 2008
29
In addition, ensure that the paths in the References section for the following assemblies are appropriate: Metastorm.ECL Metstorm.ECL.Support Metastorm.ECL.Sample.WebControls
6.2
The Sample Client reads Metastorm service information from a service configuration file. The location of the service configuration file must be specified in the Sample Client web.config file:
6.3
To use the sample: 1. 2. Start a web browser. In the Address field, enter the following URL: <server name>/<virtual directory name>/ECLLogin.aspx The Login page of the .NET ECL Sample Client is displayed:
30
May 2008
3. 4. 5.
Enter a valid Metastorm User name and Password. Select the name of the ECL Service to which you want to connect. Click on the Login button. In all lists (Blank Forms, Admin, ToDo and Watch) in the ECL Sample Client, the first 2 columns are, in order: Links which call the Metastorm Web Client. Links which call the .NET ECL code.
6. 7.
Use the sample Client. Log out of the Client, when required, by clicking on the Logout link at the top righthand side of the Client.
May 2008
31
This Appendix describes: ECL Server and Client (common) files. ECL Client component files. ECL sample Client files.
Metastorm.ECL.Support.dll Metastorm.ECL.Support.resources.dll Metastorm.ECL.Support.resources.dll Metastorm.ECL.Support.resources.dll Metastorm.ECL.dll Metastorm.ECL.resources.dll Metastorm.ECL.resources.dll Metastorm.ECL.resources.dll Interop.ADODB.dll MDAC 2.8
GAC GAC GAC GAC GAC GAC GAC GAC GAC Proprietary
Table 3: ECL Server and Client (Common) Files If a 3rd party client is intended to run on a system on which Metastorm BPM has not been installed, the Metastorm.ECL.Support.dll must be installed in the GAC. The Metastorm.ECL.dll may be installed in the GAC, but may also be installed anywhere on the path where the client application can find it.
32
May 2008
iis client.xml performance.xml DirectAccess.xml Sample Client source code Files IIS Virtual Folder "MetastormECLSample" (no physical file)
Metastorm.ECL.Sample.MetastormControls.dll
DirectAccess.xml
performance.xml
iis client.xml
[INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\configuration [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\configuration [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\configuration [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\ECL Sample Client mapped to [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\ECL Sample Client [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\MetastormWebControls [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\ECL Sample Client\bin [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\ECL Sample Client\bin\configuration [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\ECL Sample Client\bin\configuration [INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\ECL Sample Client\bin\configuration
[INSTALLDIR]\Process Orchestrator for .NET\ECL\Client Library\Test ECL Remoting [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables\de [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables\es [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables\fr [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables
May 2008
33
Component
Destination
[INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables\de [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables\es [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables\fr [INSTALLDIR]Process Orchestrator for .NET\ECL\Client Library\Redistributables Table 5: ECL Sample Client Files
34
May 2008
This Appendix provides details on the supported deployment scenarios described in Section 39.
Configuration Files
Client Configuration Service List Files
ECL Service List configuration files are structured in a similar way to the existing Metastorm BPM Request Broker configuration file.
<?xml version="1.0" encoding="UTF-8" ?> <ServiceDirectorConfig Name="Metastorm BPM Service List"> <HTTPUseSOAP>false</HTTPUseSOAP> <PreAuthenticatedRaiseFlag>true</PreAuthenticatedRaiseFlag> <ServiceList Type="Engine"> <Service Name="TCP" Description="Engine via TCP"> <Engine Name="Engine1"> <Transport Type="Remoting"> <Server>tcp://server:4001/ECL</Server> </Transport> </Engine> </Service> <Service Name="HTTP" Description="Engine via HTTP/IIS"> <Engine Name="Engine1"> <Transport Type="Remoting"> <Server>http://webserver1/ECL/ECL.rem</Server> </Transport> </Engine> <Engine Name="Engine2"> <Transport Type="Remoting"> <Server>http://webserver1/ECL/ECL.rem</Server> </Transport> </Engine>
May 2008
35
There are two global settings: HTTPUseSOAP The client supports two message formatters when connected to an IIS server using HTTP. By default the more efficient binary formatter is used, but optionally the SOAP formatter can be used when firewall restrictions prevent the transfer of binary data. This value is boolean, valid values are false and true, values must be in all lower case with no leading or trailing spaces or punctuation characters. The HTTPUseSOAP element may be omitted. In this case the default binary formatter will be used. PreAuthenticatedRaiseFlag For previous versions of the Metastorm Engine this value must be false. This value should to be true for version 7.0 of the Metastorm Engine. The Metastorm services are defined after the global settings. Services are listed as children of a single ServiceList element. The Type attribute of ServiceList must be present, and its value must be set to Engine. Service elements contain Name and Description attributes which are available from ISessionConfigurer for display in UI. The Name attribute is also used to specify the service when constructing ISession instances. Each Service contains one or more Engine elements. ECL supports load-balancing between the Engines in a service and routes requests to alternative Engines if one fails to respond. Each Engine element contains a Transport element, which for the ECL must have its Type attribute set to Remoting. The Server element contains a URL which is used to contact the remote server. There are three possibilities: IPC ipc://<ipc port name>/<objectUri> Remote High Performance tcp://<host>:<port>/<objectUri> Remote Open http://<host>:<port>/<virtual folder>/<objectUri>
The purpose of the objectUri value is to associate a client with a specific server instance. This value is defined in the objectUri attribute of the wellknown element in the server remoting configuration file.
36
May 2008
Server Configuration
Server configuration is specified in one of two files, depending on the deployment scenario. remoting.config (Remote High Performance)
<?xml version="1.0" encoding="utf-8" ?> <configuration> <system.runtime.remoting> <application name="EngineSupport"> <service> <wellknown mode="SingleCall" type="Metastorm.ECL.Support.EngineSupportRemote,Metastorm.ECL. Support,Version=6.6.2.37,Culture=Neutral,PublicKeyToken=0fa3cc64 eebf4c8b" objectUri="ECL" /> </service> <channels> <channel ref="tcp" port="4001"> <serverProviders> <formatter ref="binary" typeFilterLevel="Full" /> </serverProviders> </channel> </channels> <service> <wellknown mode="SingleCall" type="Metastorm.ECL.Support.EngineSupportRemote,Metastorm.ECL. Support,Version=6.6.2.37,Culture=Neutral,PublicKeyToken=0fa3cc64 eebf4c8b" objectUri="ECL.rem" /> </service> <channels> <channel ref="ipc" portName="ECLService" authorizedGroup="QA\Domain Users"> <serverProviders> <formatter ref="binary" typeFilterLevel="Full" /> </serverProviders> </channel> </channels> </application> </system.runtime.remoting> </configuration> When using the IPC protocol, all ECL clients must run under an identity that is a member of the user group specified by the authorizedGroup attribute of the IPC channel element. The file remoting.config is installed in C:\Documents and Settings\All Users\Application Data\Metastorm.
May 2008
37
<wellknown mode="SingleCall" type="Metastorm.ECL.Support.EngineSupportRemote, Metastorm.ECL.Support,Version=a.b.c.d, Culture=Neutral,PublicKeyToken=0fa3cc64eebf4c8b" objectUri="ECL.rem" /> </service> <channels> <channel ref="http"> <serverProviders> <formatter ref="binary" typeFilterLevel="Full"/> </serverProviders> </channel> </channels> </application> <customErrors mode="Off"/> </system.runtime.remoting> <system.web> <httpRuntime maxRequestLength="100000" useFullyQualifiedRedirectUrl="true" executionTimeout="40000"/> </system.web> </configuration> The file web.config is installed in the Web folder within the Metastorm BPM installation folder.
The system.runtime.remoting element contents are common to both files. In general, values should not be changed from the defaults provided on installation. Values which may need to be changed by the system administrator are: wellknown element, objectUri attribute. Client-side URL format is shown in the Client Configuration Service List Files section. The objectUri attribute dictates the <url-path> component of the URL. it can be set to any value which is permitted in a URL. channel element, ref attribute. Defines the network protocol which client/server operations run over. ECL supports two options: For Remote High Performance, ref must be set to tcp. For Remote Open, ref must be set to http. formatter element, ref attribute. Message formatter which encodes client/server operation data. For Remote High Performance, the only supported value is binary. For Remote Open, by default the value is binary. Alternatively soap may be configured. In this case, on the client side, the <HTTPUseSOAP> element must be specified and have a value of true. customErrors element.
38
May 2008
Normally not specified, but can be added for troubleshooting. If remoting configuration is correct, but a problem occurs on the server, sometimes an error message will be returned to the client instructing them to turn custom errors on. In fact, what is required in order to see a detailed error message is to turn custom errors off, this is done by adding the customErrors element as a child of system.runtime.remoting, with the mode attribute set to a value of Off. The only other user-configurable value is in web.config. The maxRequestLength attribute of the httpRuntime element does not affect the ECL directly, but if attachments are being up- or down-loaded using ECL operations the value must be greater than the maximum permitted attachment size in bytes.
Detailed Configuration
The three deployment scenarios are described in more detail in this section.
May 2008
39
Server Components The server components of the Local Direct Access deployment are installed by the main Metastorm BPM installation. The server components of the Local Direct Access deployment require the following section of the remoting.config configuration file:
- <service> <wellknown mode="SingleCall" type="Metastorm.ECL.Support.EngineSupportRemote,Metastor m.ECL.Support,Version=6.6.2.37,Culture=Neutral,PublicKeyTo ken=0fa3cc64eebf4c8b" objectUri="ECL" /> </service> - <channels> - <channel ref="tcp" port="4001"> - <serverProviders> <formatter ref="binary" typeFilterLevel="Full" /> </serverProviders> </channel> </channels>
Client Components The client components of the Local Direct Access deployment require the DirectAccess.xml configuration file:
<?xml version="1.0" encoding="UTF-8" ?> - <ServiceDirectorConfig Name="Metastorm BPM Service List"> <PreAuthenticatedRaiseFlag>true</PreAuthenticatedRaiseFlag> - <ServiceList Type="Engine"> - <Service Name="Local Service" Description="Local Engine via direct access"> - <Engine Name="Engine1"> - <Transport Type="Remoting"> <Server>ipc://ECLService/ECL.rem</Server> </Transport> </Engine> </Service> </ServiceList> </ServiceDirectorConfig>
40
May 2008
The Remote High Performance deployment may not be possible over firewalls because of restrictions on binary data and the use of a non-standard TCP port. This is almost the same as the Local Direct Access configuration, except that Client and Server are deployed on separate machines. In this scenario, the network connection between client and server should support TCP connections containing binary data (a firewall is likely to be configured to block this type of communication). The network port used for communication is configurable and should be set to an unused port on the server. Server Components The ECL Server components of the Remote High Performance deployment are installed by the main Metastorm BPM installation. The ECL Server components of the Remote High Performance deployment require the remoting.config configuration file.
For more information on the editable values in the remoting.config file, refer to the Configuration Files section. <?xml version="1.0" encoding="utf-8" ?>
May 2008
41
<configuration> <system.runtime.remoting> <application name="EngineSupport"> <service> <wellknown mode="SingleCall" type="Metastorm.ECL.Support.EngineSupportRemote,Metastor m.ECL.Support,Version=a.b.c.d,Culture=Neutral,PublicKeyTok en=0fa3cc64eebf4c8b" objectUri="ECL" /> </service> <channels> <channel ref="tcp" port="4001"> <serverProviders> <formatter ref="binary" typeFilterLevel="Full" /> </serverProviders> </channel> </channels> </application> </system.runtime.remoting> </configuration>
The Version=a.b.c.d attribute matches the version of Metastorm.ECL.Support.dll. The channel port=4001 attribute may be changed by administrators to any available TCP port number on the server.
If you make changes to the remoting.config configuration file, you must restart the Engine service for the changes to take effect. The identity under which the Metastorm ECL Support Service runs must be added to the Engine COM+ application Client roles list.
Client Components The ECL Client components of the Remote High Performance deployment require the performance.xml configuration file:
<?xml version="1.0" encoding="UTF-8" ?> <ServiceDirectorConfig Name=" Metastorm BPM Service List"> <PreAuthenticatedRaiseFlag>true</PreAuthenticatedRaiseFlag> <ServiceList Type="Engine"> <Service Name=" Metastorm BPM Service via TCP " Description="Remote Engine via TCP/binary"> <Engine Name="Engine1"> <Transport Type="Remoting"> <Server>tcp://remotehost:4001/ECL</Server> </Transport> </Engine> </Service> </ServiceList> </ServiceDirectorConfig>
42
May 2008
The Server element value must be changed by a system administrator so the host name, port number, and objectUri value match those configured on the ECL Engine server.
Remote Open
The following diagram illustrates the Remote Open deployment configuration:
ECL makes use of the system proxy server configuration, which is set from Internet Explorer. Proxy authentication is not supported.
The ECL IIS account (by default the local machines ASPNET account) must be added to the Engine COM+ application Client roles list. In addition, the ECL IIS account must have read and execute permissions to the ECL virtual folder and all of its contents.
Server Components The ECL Server components of the Remote Open deployment are installed by the main Metastorm BPM installation. The ECL Server components of the Remote Open deployment require the web.config configuration file.
For more information on the editable values in the web.config file, refer to the Configuration Files section. <?xml version="1.0" encoding="utf-8" ?>
May 2008
43
<configuration> <system.runtime.remoting> <application> <service> <wellknown mode="SingleCall" type="Metastorm.ECL.Support.EngineSupportRemote,Metastor m.ECL.Support,Version=a.b.c.d,Culture=Neutral,PublicKeyTok en=0fa3cc64eebf4c8b" objectUri="ECL.rem" /> </service> <channels> <channel ref="http"> <serverProviders> <formatter ref="binary" typeFilterLevel="Full" /> </serverProviders> </channel> </channels> </application> </system.runtime.remoting> <system.web> <httpRuntime maxRequestLength="100000" useFullyQualifiedRedirectUrl="true" executionTimeout="40000" /> </system.web> </configuration>
Client Components The ECL Server components of the Remote Open deployment require the iis client.xml configuration file:
<?xml version="1.0" encoding="UTF-8" ?> <!-It is only possible to support one HTTP channel type at a time. In order to change type, the client must be stopped and restarted. If HTTPUseSOAP is true, the channel type will be SOAP, otherwise binary. --> <ServiceDirectorConfig Name="Metastorm Metastorm BPM Service List "> <HTTPUseSOAP>false</HTTPUseSOAP> <PreAuthenticatedRaiseFlag>true</PreAuthenticatedRaiseFlag> <ServiceList Type="Engine"> <Service Name=" Metastorm BPM Service via HTTP " Description="Remote Engine via HTTP/IIS"> <Engine Name="Engine1"> <Transport Type="Remoting"> <Server>http://remotehost/ECL/ECL.rem</Server> </Transport> </Engine> </Service> </ServiceList> </ServiceDirectorConfig>
It is possible for the client to use only one message formatter type at a time and once configured
44
May 2008
the formatter cannot be changed. To switch from binary to SOAP or vice-versa, the client configuration file must be changed, then the ECL client stopped and restarted. Server Configuration for Single Sign-On Single sign-on is supported only when hosting ECL in IIS Web Application. It is compatible with the existing Metastorm SSO implementation, but ECL appends an additional field to the login method field input collection, which contains a configurable field name, with the value set to the identity of the current IIS application. The web.config file specifies the name of the field added to the field input collection. If this setting is not present, then SSO is not enabled.
<configuration> <appSettings> <add key ="SSOFieldName" value ="nt4user" / > <appSettings> </configuration>
May 2008
45