eb ProjectWise Connection Services

Transcription

1 eb ProjectWise Connection Services INSTALLATION & ADMIN GUIDE D rev 2.0

2 TRADEMARK NOTICE Bentley and the "B" Bentley logo are registered or non-registered trademarks of Bentley Systems, Inc. or Bentley Software, Inc. All other marks are the property of their respective owners. COPYRIGHT NOTICE , Bentley Systems, Incorporated. All Rights Reserved. Including software, file formats, and audiovisual displays; may only be used pursuant to applicable software license agreement; contains confidential and proprietary information of Bentley Systems, Incorporated and/or third parties which is protected by copyright and trade secret law and may not be provided or otherwise made available without proper authorization. RESTRICTED RIGHTS LEGENDS If this software is acquired for or on behalf of the United States of America, its agencies and/or instrumentalities ("U.S. Government"), it is provided with restricted rights. This software and accompanying documentation are "commercial computer software" and "commercial computer software documentation," respectively, pursuant to 48 C.F.R and , and "restricted computer software" pursuant to 48 C.F.R (a), as applicable. Use, modification, reproduction, release, performance, display or disclosure of this software and accompanying documentation by the U.S. Government are subject to restrictions as set forth in this Agreement and pursuant to 48 C.F.R , , , and , as applicable. Contractor/Manufacturer is Bentley Systems, Incorporated, 685 Stockton Drive, Exton, PA Unpublished - rights reserved under the Copyright Laws of the United States and International treaties. Bentley Systems, Incorporated Mesa Ridge Court San Diego, CA FAX eb Insight version 5 eb ProjectWise Connection ServicesInstallation & Admin Guide Published by Bentley Systems, Inc. Information in this document is subject to change without notice and does not represent a commitment on the part of Bentley Systems, Inc. The software and/or databases described herein are provided under a license agreement or nondisclosure agreement. The software and/or databases may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or non-disclosure agreement. The purchaser may make one copy of the software for backup purposes. No part of this manual and/or databases may be reproduced or transmitted in any form or by any means, electrical or mechanical, including photocopying, recording, or information recording and retrieval systems, for any purpose other than the purchaser's personal use, without the express permission of Bentley Systems, Inc. Unless otherwise noted, all names of companies, products, street addresses, and persons contained herein are part of a fictitious scenario or scenarios and are designed solely to document the use of the product. page ii

3 Table of Contents Introduction...1 Planning...1 Pre-requisites...1 Installing ProjectWise Components...2 Configuring ProjectWise Components...7 Installation of eb ProjectWise Connection Services...9 Configuration of eb ProjectWise Connection Services - Server Side...11 Configuration of the - Client Side...15 Objects in eb Insight...15 Synchronization...16 Document Registration...17 How to register ProjectWise Attributes with eb...20 Security...22 Deleted Objects Reports...23 page iii

4 List of Figures Figure 1: Example ProjectWise and eb environments...1 Figure 2: ProjectWise Explorer Welcome screen...2 Figure 3: License agreement...3 Figure 4: Setup Type selector...3 Figure 5: Select the default options...4 Figure 6: Ready to install...4 Figure 7: The ProjectWise Gateway Services Welcome Screen...5 Figure 8: License agreement...5 Figure 9: Confirming the components and location to install...6 Figure 10: Deselect the 'Launch License management Tool'...6 Figure 11: Logging in the ProjectWise Explorer...7 Figure 12: Network Configuration Settings - DNS Services...8 Figure 13: Network Configuration Settings - Datasource Listing...9 Figure 14: The eb ProjectWise Connection Svcs Welcome screen...10 Figure 15: License agreement...10 Figure 16: Select components to install...11 Figure 17: Run the ProjectWise package...12 Figure 18: Enable ProjectWise Integration Jobs...12 Figure 19: Accessing the ProjectWise configuration in the SMC...13 Figure 20: Adding a ProjectWise data source...13 Figure 21: Selecting the ProjectWise Projects and Folders that you want to pull into eb...13 Figure 22: Device settings...14 Figure 23: Repository settings...15 Figure 24: Schematic of the interface...16 Figure 25: Files visible after synchronization...17 Figure 26: Relationship of documents after registration...18 Figure 27: Setting a template...18 Figure 28: Automatic registration option...19 Figure 29: Renaming documents to prevent duplicates...20 Figure 30: Attribute mapping...20 Figure 31: ProjectWise Datasource Fields topic...21 Figure 32: ProjectWise attribute list...21 Figure 33: Attribute mapping...22 Figure 34: Security across the interface...23 Figure 35: Historic references report...24 Figure 36: Move failures report...24 Figure 37: Duplicates report...25 Figure 38: Multiple versions report...25 page iv

5 Introduction Introduction Both ProjectWise and eb can each offer a number of different services. Each service can be installed to a dedicated server, or one server can run multiple services. Each user s requirements will be different, and so the diagram below gives an indication of the services available, rather than the number of servers required. Figure 1: Example ProjectWise and eb environments The eb-projectwise integration has been developed so that documents can be pulled out of the Project- Wise environment, and placed into the eb environment. Planning The process of transferring ProjectWise documents to eb is the responsibility of the eb Work Queue. ProjectWise jobs are added to the Work Queue, and the server processing those ProjectWise jobs is called upon. It works in conjunction with the eb Storage Server, which therefore has to be configured with a new Repository for ProjectWise documents. The following components must be installed: ProjectWise connector components, installed to either the current Work Queue Server, or to a brand new server that will act as the work queue server for ProjectWise jobs. The Storage Server. Pre-requisites Operational eb and ProjectWise Environments Within ProjectWise, a dedicated user called 'ebconnector' must be created with the following permissions: View Access to all ProjectWise Folders Full Access (except change permissions) to ProjectWise documents - including Delete User Credential Expiration Policy set to "No Expiration" D rev 2.0 nov12 page 1

6 Installing ProjectWise Components Installing ProjectWise Components No eb components need be installed to any of the ProjectWise Servers. ProjectWise Explorer and Gateway Services are required on the eb Server. The installation steps of these ProjectWise pre-requisites are detailed below, for the convenience of those users not familiar with ProjectWise installations. On the eb Server(s) that will run the Work Queue Server and the Storage Server, install the ProjectWise Explorer: 1. Click on setup.exe. The Welcome screen is displayed. Figure 2: ProjectWise Explorer Welcome screen 2. Click on the Next > button. The license agreement is displayed. D rev 2.0 nov12 page 2

7 Installing ProjectWise Components Figure 3: License agreement 3. Accept the license agreement. The Setup Type screen is displayed. Figure 4: Setup Type selector 4. Select the custom setup type and click on the Next > button. The Custom Setup screen is displayed. D rev 2.0 nov12 page 3

8 Installing ProjectWise Components Figure 5: Select the default options 5. Only select the default options for the ProjectWise Explorer component. Figure 6: Ready to install 6. And install. 7. The install runs, and completes. Click on the Finish button. Once the ProjectWise Explorer is installed, now install the ProjectWise Gateway Service onto the eb Work Queue Server. 1. Click on setup.exe. The Welcome screen is displayed. D rev 2.0 nov12 page 4

9 Installing ProjectWise Components Figure 7: The ProjectWise Gateway Services Welcome Screen 2. Click on the Next > button. The license agreement is displayed. 3. Accept the license agreement Figure 8: License agreement D rev 2.0 nov12 page 5

10 Installing ProjectWise Components Figure 9: Confirming the components and location to install 4. There is only one component to select. Confirm the location, and click on the Next > button. 5. Click Install. It runs, installs and completes. Figure 10: Deselect the 'Launch License management Tool' 6. On the finish screen, uncheck the 'Launch Licence management Tool checkbox. A license is not required for ProjectWise services, only servers. D rev 2.0 nov12 page 6

11 Configuring ProjectWise Components Configuring ProjectWise Components The first step is to configure ProjectWise Gateway Service so that the eb Server can act as a Gateway server. Proceed as follows: 1. Open the file C:\Program Files\Bentley\ProjectWise\bin\dmskrnl.cfg in Notepad. You need to make two changes. Firstly, you must add a setting to that the eb Server will act as a Gateway server to just the one ProjectWise Server that you wish to connect to. 2. Add a section to the bottom of the file in the following format: [db0] Description=********** Server=************ Description is the ProjectWise Datasource name (NOT the ODBC Name.) Server is the ProjectWise Integration Server Name (NOT the Gateway Server.) If you are not sure of these settings, please look at how you log into the ProjectWise Explorer currently. For example, if your ProjectWise Explorer screen looks like this: Figure 11: Logging in the ProjectWise Explorer then the entry that you need to add into the dmskrnl.cfg file will be this: [db0] Description=CROSSRAIL_ORACLE Server=EQ-APP3 The second change is simply to define the database value for db0 in the databases section. 3. Locate the following section: ;Comma separated list of databases, which are defined below. ;Databases=db0,db1 4. Remove the semi-colon in front of the "Databases=" line and remove the db1 entry. The lines now read: ;Comma separated list of databases, which are defined below. D rev 2.0 nov12 page 7

12 Configuring ProjectWise Components Databases=db0 5. Restart the Gateway Services. 6. Log in to ProjectWise Explorer. 7. Click Tools, Network Configuration Settings. 8. Confirm that the settings are similar to the following. By making changes to the "DNS Services" and the "Datasource Listing" tabs, we can force the ProjectWise Client to read from the local server only. Figure 12: Network Configuration Settings - DNS Services Prevent UDP - ON Name can be FQDN (provides better resolution) Host/IP can also be FQDN Port always 5800 D rev 2.0 nov12 page 8

13 Installation of eb ProjectWise Connection Services Figure 13: Network Configuration Settings - Datasource Listing Prevent UDP - ON Name can be FQDN (provides better resolution) Host/IP can also be FQDN Port always 5800 Now when you log in to ProjectWise Explorer you should only see the one database you want eb to connect to. Congratulations! Half way there. This means that you can now log into ProjectWise using the eb Server as a ProjectWise Gateway server! Installation of eb ProjectWise Connection Services To start the installation process: 1. Insert the CD into the CDROM drive. Using the windows Explorer, browse to \Server Installation\eB ProjectWise Connector 2. Run the appropriate.msi for the version of Windows you are running : 32-bit version of Windows - use the installer (x86).msi 64-bit version of Windows - use the installer (x64).msi The Welcome screen of the wizard is displayed. Click on the Next button. D rev 2.0 nov12 page 9

14 Installation of eb ProjectWise Connection Services Figure 14: The eb ProjectWise Connection Svcs Welcome screen 3. Click on the Next button. The license agreement is displayed. Figure 15: License agreement 4. Be sure you can accept the license agreement before clicking on the Next button. The custom Setup screen is displayed. The default selection depends on whether you are installing the software onto an existing eb Work Queue Server, or a brand new server. On an existing server, the Work Queue Service and the eb System Management Console are not required. D rev 2.0 nov12 page 10

15 Configuration of eb ProjectWise Connection Services - Server Side Figure 16: Select components to install If you are installing onto a brand new server, you are prompted for Logon Information. This Logon information is the credentials assigned to the eb Service Manager Service (a Windows Service,) and therefore the credentials that run the eb Work Queue Service. The logon information you supply should be the same user as the identity running the eb Service Manager Service on the main eb Application Service. It should be a domain user with local admin permissions to the eb Work Queue Server. 5. Once added, click on the Next button. Installing on an existing eb Application Server omits this step, and the next step will be to click on the Install button. 6. The installation commences, and completes. Click on the Finish button. Configuration of eb ProjectWise Connection Services - Server Side This is a three-part process. Updating your Data Source: For instructions on adding a new Data Source, please see System Management Console User s Manual, Document #D On the eb Application Server, open up the eb System Management Console (SMC), expand your Server - Data Sources - <Data Source name>, and click on the 'Upgrade or Update the Database' hyperlink. You see a list of any packages that have been installed on the server. 2. Select the ProjectWise package and click on the 'Click to start the Database Update' hyperlink. D rev 2.0 nov12 page 11

16 Configuration of eb ProjectWise Connection Services - Server Side Figure 17: Run the ProjectWise package 3. Once complete, click on the 'Click to Run data maintenance scripts' link. 4. On the server running the Work Queue Service, click Work Queue in the left pane of the SMC, check the checkbox against your community and enable the ProjectWise Integration. Figure 18: Enable ProjectWise Integration Jobs Adding a ProjectWise Data Source: 1. Now expand your communities and highlight ProjectWise. D rev 2.0 nov12 page 12

17 Configuration of eb ProjectWise Connection Services - Server Side Figure 19: Accessing the ProjectWise configuration in the SMC 2. In the toolbar at the top of the screen, select the 'Add Data Source' icon. In the eb ProjectWise Server box, you must enter the name of the eb Server running your ProjectWise Gateway service. Figure 20: Adding a ProjectWise data source 3. Available ProjectWise Data Sources appear. Select the correct one. 4. Then expand your data source. You will be prompted for your ProjectWise credentials. You should log on as the dedicated ebconnector user. 5. Expand your Data Source and choose the Projects and Folders you need to pull into eb. Figure 21: Selecting the ProjectWise Projects and Folders that you want to pull into eb D rev 2.0 nov12 page 13

18 Configuration of eb ProjectWise Connection Services - Server Side Setting Up Devices and Repositories: 1. On the eb Storage Server, open up the SMC, highlight Storage in the left pane. Right-click and select 'Add device.' For more detail, please see System Management Console User s Manual, Document #D A new Device will be created for each ProjectWise database that will be connected to. The settings are as follows: Name - something simple. It is just a label. Description - not mandatory but useful. It is just a label. Driver - must be the ProjectWise File Driver. Speed - relative concepts as per SMC documentation. Select Fast. Root Access - this is the sub-path in the ProjectWise hierarchy. But it will be Documents in most cases. Server - the ProjectWise Gateway Server DataSource - the ProjectWise datasource name (from the dmskrnl.cfg file referred to in the configuring ProjectWise components section.) Username and Password - the ProjectWise username you are using to connect. This is the dedicated ebconnector user. Figure 22: Device settings Once a valid eb Storage Device has been created, 'Repositories' must be created and assigned to this storage device. The settings should be as follows: Name - something simple. It is just a label. Community - select your eb Community. Path - add.\ This signifies that any file in the datasource can go into the repository. It will be write-enabled, and be an external repository D rev 2.0 nov12 page 14

19 Configuration of the - Client Side To add a Repository, select the storage device you just created under 'Storage' from the left pane. From the menu options presented, click on the 'Repositories' tag and select Add Repository from the drop-down menu. Figure 23: Repository settings Configuration of the - Client Side To complete the eb - ProjectWise Connector setup, various attribute mapping and synchronization settings need to be established in eb Director. Objects in eb Insight All ProjectWise objects shown in the eb Insight system are representations of the information imported from the ProjectWise system. When eb Insight users look at ProjectWise data they are referring to the last known information that the eb Insight system has synchronized with. For each ProjectWise datasource, project, folder or file that the eb Insight system is aware of, an object is created inside the eb Insight system to represent the ProjectWise object. This object contains all the necessary references back to the ProjectWise object. Because this representation is a fully-fledged eb Insight object, user access to it from within the eb Insight system can be controlled with permissions, audit trails can be recorded against it, etc. D rev 2.0 nov12 page 15

20 Configuration of the - Client Side Figure 24: Schematic of the interface Synchronization Synchronization is an on-going process. Each time changes are made in a project or folder inside Project- Wise that is monitored by eb Insight these changes need to be synchronized so the latest information can be shown in the eb Insight system. Every time synchronization is initiated it finds the following changes: Find name changes in projects, folders or documents. Find new documents/files in the monitored ProjectWise folders. Find documents/files that have been deleted from the ProjectWise folders being monitored. Find changes in attribute data that must be mapped into the eb Insight system. Verify the file contents of files being referenced. Synchronization can be done at any level synchronizing a datasource updates all projects, folders and files inside the datasource. Synchronizing a file only updates the file meta-data. The following is an example after the folder being monitored has been synchronized. All files not previously known to eb Insight are now visible: D rev 2.0 nov12 page 16

21 Configuration of the - Client Side Figure 25: Files visible after synchronization Document Registration Importing documents into the eb system is referred to as Registering an Enterprise Document. This process creates a document in eb that maps to the ProjectWise document and file which allows users in the eb system access to these documents in the same way as any other eb document. Referencing files As described in the section Objects in eb Insight on page 15, before a document is registered, there is an eb Insight representation of the document in the eb Insight system this serves to show that the document exists in the ProjectWise system but cannot be read from within eb Insight. After registration, the eb Insight object representation remains the same (albeit updated with the latest information) but, in conjunction with this, an eb Insight document is created as well. This eb Insight document allows a reference to the physical file contained in the ProjectWise document and is the object a typical eb Insight user will work with. D rev 2.0 nov12 page 17

22 Configuration of the - Client Side Figure 26: Relationship of documents after registration The eb Insight document is created from a template that may be configured for different projects and folders. An Approved eb Document Template must be set on the ProjectWise project or folder. 1. In Director, select the ProjectWise Project or Folder. 2. Select the Default Template. Figure 27: Setting a template Template resolution cascades down a Project/Folder structure, lower level definitions overwriting definitions at a higher level. Note: Director will display Default Template (Inherited) if the value is not set explicitly on the folder/ project but inherited from a higher level. D rev 2.0 nov12 page 18

23 Configuration of the - Client Side Moving Files Instead of a reference, files may be moved into eb. The same steps are followed as with a reference (including mapping of attributes) except the file is copied into the eb system and once the process is complete the document is deleted from within ProjectWise. Once complete, it appears as if there is only an eb document in the system with no apparent link to Project- Wise although the historic reference functionality, as well as the original filename property on the file, hints at the origin of the document. Since the ProjectWise document does not exist anymore, there is no subsequent synchronization. Opening Reference Files Once a document is registered as an Enterprise document in eb Insight, it may be used like any other document in the system. Users may not necessarily be aware that it refers to a document and file contained in an external ProjectWise system. When the file is opened it is read, although the normal eb Insight storage infrastructure is used the file is read directly from the ProjectWise repository. The eb Insight system only contains references to the ProjectWise file; it does not make a copy. Any change to the physical file within ProjectWise will therefore be reflected in the eb Insight system when an eb Insight user attempts to open the file. Note: The file referenced in eb Insight is a direct one to one map of the file in ProjectWise, when opened the exact file is opened but no attempt is made to resolve references within the file. Note: The connector only allows references to the active version of a document inside ProjectWise. Note: An eb Insight user will not be presented with or given the opportunity to register older versions. Automatic Document Registration Settings are provided on Project and Folder level to allow automatic registration of documents when they appear in a folder. The configuration allows a choice of the type of registration that should occur (reference or move) and additionally a specific attribute value has to be set on the ProjectWise document before it becomes eligible for automatic registration. Figure 28: Automatic registration option Automatic registration will only be done on documents that are currently excluded, if it has previously been registered as a reference document, changing the options to automatically move new documents the existing registrations won't be affected. Preventing Duplicates To prevent duplicate documents from being included, options exist to immediately rename the eb document once it is created. Typically the template used to create the document generates the number based on a mask, these options allow the eb document to take the same number, version and title as the ProjectWise document. Attempting to register a ProjectWise document with the same name at a later stage will cause a conflict based on the normal eb business logic, thereby allowing the user to determine if it is the same doc- D rev 2.0 nov12 page 19

24 Configuration of the - Client Side ument and to take the appropriate action of either preventing the import or renaming documents to avoid conflicts when they are in fact unique. Figure 29: Renaming documents to prevent duplicates Mapping Attributes Attribute mapping allows properties or attributes from the registered enterprise document in the Project- Wise system to be mapped over to the eb Insight document. Any time synchronization is issued on the file or the folder containing the file, the mapping is updated with the latest values from the ProjectWise system. Figure 30: Attribute mapping How to register ProjectWise Attributes with eb All user-defined ProjectWise attributes need to be registered with eb prior to setting up your Attribute Mapping. Proceed as follows: 1. In eb Director, go to the ProjectWise datasource in Explorer and expand the ProjectWise Data- Source Fields topic: D rev 2.0 nov12 page 20

25 Configuration of the - Client Side Figure 31: ProjectWise Datasource Fields topic 2. Click on the button and select an appropriate attribute in the dialog that you would like to map to an eb Attribute: Figure 32: ProjectWise attribute list 3. Navigate to the ProjectWise project / folder level and expand the Attribute Mapping topic. The attributes will now be available to be mapped to eb Attributes.: D rev 2.0 nov12 page 21

26 Configuration of the - Client Side Figure 33: Attribute mapping Security When eb Insight users access any ProjectWise object or attempt to open a referenced file, the security as configured on the objects inside the eb Insight system determines the level of control the eb Insight user has over the object. No attempt is made to 'map' the eb Insight user to a user that exists in the ProjectWise system to determine if that user should have access to the object inside ProjectWise. The eb Insight users that work with the eb Insight documents created when registering ProjectWise documents may not even be users in the ProjectWise system. The eb Insight service requires credentials to the ProjectWise system that allows it access to all the projects and folders that must be monitored. D rev 2.0 nov12 page 22

27 Configuration of the - Client Side Figure 34: Security across the interface Additional eb Insight permissions exist to determine which eb Insight users have access to any of the ProjectWise functionality (to allow synchronization, registration of documents, etc); it can be hidden completely if not appropriate for some user groups. Deleted Objects When objects are deleted from a monitored ProjectWise folder, in most cases the references can simply be removed from the eb Insight system. Usually the referenced object will however be marked as historic and will be accessible from the eb Insight system until a decision is made to remove the record from the eb Insight system if it serves no purpose. In the case of a document that was registered, deleting the document and file from the ProjectWise system forces the eb Insight system to break the reference link to the file. The document inside eb Insight remains minus the file. Reports Several reports are included to help with ProjectWise specific queries. Historic References This report provides a list of items that originated from ProjectWise but do not exist in ProjectWise any more. Typically, this would be documents that were moved into eb. D rev 2.0 nov12 page 23

28 Configuration of the - Client Side Figure 35: Historic references report Move Failures This report provides a list of queue jobs that failed to move documents into eb. Typically the error message will indicate the reason and usually it is caused by the inability to delete the document from ProjectWise. The problem should be resolved either by freeing the ProjectWise document to allow it to be deleted or deleting it manually, and then resubmitting the job so it can complete. Figure 36: Move failures report Duplicates This report provides a list of queue jobs that failed to register document due to the fact that there is already a document in eb with the same unique identifier. Users needs to determine if the document in either ProjectWise or eb needs to be renamed or if the registration should be cancelled when it is the same document and multiple copies of it should not be moved into the eb system. D rev 2.0 nov12 page 24

29 Configuration of the - Client Side Figure 37: Duplicates report Multiple Versions of Moved Document This report provides a list of documents that were moved from the ProjectWise system but had multiple versions. Since only the latest version will be copied into eb all the older versions will have been deleted as well from ProjectWise. Figure 38: Multiple versions report D rev 2.0 nov12 page 25