EMC Documentum Capital Projects Connector for EMC Supplier Exchange

Transcription

1 EMC Documentum Capital Projects Connector for EMC Supplier Exchange Version 1.9, 1.10, 2.0 Installation and Configuration Guide EMC Corporation Corporate Headquarters Hopkinton, MA

2 Legal Notice Copyright EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used herein are the property of their respective owners. Documentation Feedback Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback about how we can make our documentation better or easier to use, please send us your feedback directly at ECD.Documentation.Feedback@emc.com

3 Table of Contents Preface... 7 Chapter 1 Overview... 9 Chapter 2 Pre-installation Tasks Installing the Java Cryptography Extension Chapter 3 Installing the Connector Preparing for Installation Installing Content Server Components Installing Application Server Components for Capital Projects Express 2.X Installing Application Server Components for Capital Projects 1.X Setting log4j for Connector Logs Configuring Repository File Formats Upgrading the Connector Upgrading Content Server Components Upgrading Application Server Components Upgrading Application Server Components for Capital Projects Express Post Upgrade Task (Mandatory) Chapter 4 Configuring Capital Projects Connector for Supplier Exchange Enabling Capital Projects Connector for Supplier Exchange Configuring Supplier Exchange Connection Details Encryption of the External System Information Registering Capital Projects with Supplier Exchange Project Registering External Deliverable Document to Supplier Exchange Validating the Deliverables / Deliverable Set in Supplier Exchange Ingestion of Submitted Deliverables / Deliverable Set from Supplier Exchange to Capital Projects Synchronization of Fields set on Deliverables in Supplier Exchange Sending General Transmittals to Supplier Exchange Acknowledging Transmittals sent to Supplier Exchange Close Deliverable Message Handler Jobs in Supplier Exchange Configuring Supplier Exchange Configuring Projects Creation in Supplier Exchange Configuring Contract Creation in Supplier Exchange Configuring Deliverable Creation in Supplier Exchange

4 Table of Contents Configuring Transmittal Creation in Supplier Exchange Configuring Roles and Picklist Profile Configure Connector to Regulate Clearing of Supplier Exchange Deliverables Chapter 5 Troubleshooting Unable to check-in the xchange_config file Problem Resolution XChangeImportValidation job stops when the document does not have Latest revision Problem Cause Resolution No Supplier Exchange Delivery Method option while sending General Transmittals Problem Cause Resolution Failure while sending General Transmittals to multiple recipients in Capital Projects Problem Cause Resolution Registration of Documents Fails in Capital Projects Problem Cause Resolution An Exception Occurs While Updating the RCF Problem Cause Resolution Unable to Connect to Supplier Exchange Problem Cause Resolution Exception Occurs when you Install the DARS Problem Cause Resolution Multiple xchange_config Files Created Problem Cause Resolution Transmittal Fails Problem Cause Resolution Multiple Entries of Type xchange Problem Cause Resolution Deliverable Registration Failure Notification Problem

5 Table of Contents Cause Resolution Issues with Connector Functionality Problem Cause Resolution Retrieve Contracts from Supplier Exchange Fails Problem Cause Resolution Registration of Documents Fails in Capital Projects Problem Cause Resolution Unable to Register Deliverable in Supplier Exchange Problem Cause Resolution Supplier Exchange Project is Not Getting Deleted Problem Cause Resolution No Values for Revision Code List of Registered Deliverable in Supplier Exchange Problem Cause Resolution Deliverable Stuck in Pending Validation State Problem Cause Resolution Deliverable Stuck in Accepted State in Supplier Exchange Problem Cause Resolution Transmittal in Capital Projects Not Being Acknowledged Problem Cause Resolution Useful DQL Queries Appendix A Supported File Formats

6 Table of Contents List of Tables Table 1. Message Key Details

7 Preface Intended Audience This guide is intended for administrators who install and configure Documentum Capital Projects and who are familiar with Documentum products such as Documentum Content Server. Revision History Revision Date December 2016 Description This release contains the following updated sections: Chapter 2, Pre-installation Tasks Installing Content Server Components, page 13 Installing Application Server Components for Capital Projects Express 2.X, page 15 Installing Application Server Components for Capital Projects 1.X, page 16 Setting log4j for Connector Logs, page 16 Upgrading the Connector, page 17 Validating the Deliverables / Deliverable Set in Supplier Exchange, page 25 Ingestion of Submitted Deliverables / Deliverable Set from Supplier Exchange to Capital Projects, page 26 Jobs in Supplier Exchange, page 29 Configuring Deliverable Creation in Supplier Exchange, page 32 Configuring Transmittal Creation in Supplier Exchange, page 33 Configuring Roles and Picklist Profile, page 35 Chapter 5, Troubleshooting 7

8 Preface Revision Date January 2016 Description This release contains the following new sections: Installing Application Server Components for Capital Projects Express 2.X, page 15 Ingestion of Submitted Deliverables / Deliverable Set from Supplier Exchange to Capital Projects, page 26 Configuring Contract Creation in Supplier Exchange, page 31 Chapter 5, Troubleshooting July 2015 Useful DQL Queries, page 51 Initial publication 8

9 Overview Chapter 1 The Documentum Capital Projects Connector for Documentum Supplier Exchange connects an on-premise version of Capital Projects to a software as a service (SaaS) Supplier Exchange environment. After you install the connector, plant owners and operators can exchange deliverables and transmittals with Engineering, Procurement, and Construction (EPC) companies through Supplier Exchange. The following diagram illustrate the flow of deliverable content between Capital Projects and Supplier Exchange: The following diagram illustrate the flow of transmittal content between Capital Projects and Supplier Exchange: 9

10 Overview 10

11 Pre-installation Tasks Chapter 2 Perform the following step as a pre-installation task: Installing the Java Cryptography Extension The Java Cryptography Extension (JCE) is a cryptography library that supports encryption mechanisms that are not supported by Java out of the box. Install the JCE for connectivity between the connector and Supplier Exchange. Download the latest copies of the JCE extension from Oracle for the version of JRE that you are using. Follow the instructions in the Readme file to replace the files in the Java Method Server JRE. 11

12 Pre-installation Tasks 12

13 Chapter 3 Installing the Connector This chapter contains the following topics: Preparing for Installation, page 13 Installing Content Server Components, page 13 Installing Application Server Components for Capital Projects 1.X, page 16 Setting log4j for Connector Logs, page 16 Configuring Repository File Formats, page 17 Upgrading the Connector, page 17 You must use Connector installation related steps only if you have not installed any of the builds of Capital Projects Connector previously. Whereas, you must use upgrade related steps if you have already installed Capital Projects Connector for a specific version of Capital Projects. For example: If User A has installed Capital Projects Connector 1.10 Build 18 in an environment. Now, User A wants to install Capital Projects Connector 1.10 Build 25. In this example, User A must upgrade the Connector. Also, User A cannot install Capital Projects 1.8 or 1.9 Connector related builds. Preparing for Installation To prepare for installation: 1. Download the connector package from the Documentum Download Center through the EMC Online Support ( 2. If Documentum Content Server and the application server that hosts Documentum Capital Projects are on separate computers, copy the connector package to each computer. 3. Unzip the connector package to a temporary installation location. For example: C:\temp\<connector folder>\ Installing Content Server Components Note: You must ensure that Java Method Server (JMS) is not running from command prompt. Instead, use Windows service to run the JMS service. JMS must be in running condition before you install the Content Server. 13

14 Installing the Connector 1. Navigate to the respective batch file corresponding to the Capital Projects version: Capital Projects Express 2.0: InstallCPConnectorOnCS.bat for Windows or InstallCPConnectorOnCS.sh for Linux. Note: You must set the CP2X variable to true for Capital Projects 2.X installation. Capital Projects 1.9 and 1.10 InstallCPConnectorOn*.* for Windows or InstallCPConnectorOn*.* for Linux Note: You must set the CP2X variable to false for Capital Projects 1.X installation. 2. Open the batch file in a text editor and specify parameter values for your environment. For example: LOCAL_REPOSITORY=testrepo LOCAL_REPO_USERNAME=dmadmin LOCAL_REPO_PASSWORD=password GLOBAL_REPOSITORY=testrepo GLOBAL_REPO_USERNAME=dmadmin GLOBAL_REPO_PASSWORD=password COMPOSER_PATH=C:\Composer DFC_SHARED_DIR=%Documentum%\Shared DCTM_CONFIG_DIR=%Documentum%\config JBOSS_VERSION=jboss7.1.1 JBOSSDEPLOYFOLDER=deployments XCHANGE_CONNECTION_NAME=Supplier Exchange Site XCHANGE_CONNECTION_DESCRIPTION=Details of the Supplier Exchange Site XCHANGE_URL=URL of the Suplier Exchange Site For example: XCHANGE_URL_ENCRYPTION=none XCHANGE_KEY_ID=Key ID of the Supplier Exchange Service Account. For example:param_xchange_key_id XCHANGE_KEY_ID_ENCRYPTION=lockbox XCHANGE_PRIVATE_KEY=Private Key of th Suppler Exchange Service Account XCHANGE_PROXY_HOST=URl of the proxy host(if any)for example: XCHANGE_PROXY_HOST_ENCRYPTION=none XCHANGE_PROXY_PORT=Port number of the proxy port(if any)for example:8888 XCHANGE_PROXY_PORT_ENCRYPTION=none JAVA_KEYSTORE_PASSWORD=Key store password.for example:changeit For the repository user name and password values, use the Documentum installation owner account values. If your environment does not have a global registry repository, use local repository values for GLOBAL_REPOSITORY, GLOBAL_REPO_USERNAME, GLOBAL_REPO_PASSWORD. Use Composer 6.7 or higher version. Set the JBoss version and the JMS deployment folder, that is deploy (jboss5.1.0) /deployments (jboss7.1.1). 3. The parameters related to Documentum folders have default values based on DOCUMENTUM environment variable. If the DOCUMENTUM_SHARED environment variable is set and if the JBOSS directory is located in it, you must set the following JBOSS_SERVER_DIR parameter: JBOSS_SERVER_DIR=%DOCUMENTUM_SHARED%\%JBOSS_VERSION% 4. Run the InstallCPConnectorOn*.*/InstallCPConnectorOn*.* file for Windows or corresponding shell script file for Linux. 5. Type Y, when you get the prompt for certificate installation. Note: You may not notice the prompt if the certificate is already installed in your keystore. 14

15 Installing the Connector 6. In Windows, the Java Method Server restarts automatically after the cache is cleared by the installer. 7. Start the Java Method Server. This step is applicable only when you install on Linux. After you complete the installation, the Capital Projects Connector verifies the connectivity check between Capital Projects and Supplier Exchange. Note: The authentication information for Capital Projects 1.9 is specified in the RCF file and in the System Connection Config file for Capital Projects The inability to connect to the Supplier Exchange does not imply that the Connector installation is failed. The connection failure can be due to: Network issues Incorrect certificate or no certificate installed in the Java keystore Incorrect authentication details in the external system configurations View the exact message in the console where you run the batch/sh file. Installing Application Server Components for Capital Projects Express 2.X 1. Stop the application server. 2. Navigate to the InstallCPConnectorOnAS.bat for Windows or InstallCPConnectorOnAS.sh for Linux in the temporary installation location. For example: C:\temp\<connector folder>\installcpconnectoronas.bat Note: You must set CP2X=true for Capital Projects 2.X installation. 3. Open the file in a text editor and specify the web application folder parameter value. For example: WEB_APP_FOLDER=C:\apache-tomcat \webapps\cp-rest-web\ 4. Run the InstallCPConnectorOnAS.bat or corresponding shell script file for Linux. 5. Clear the application server cache. For example, delete the contents of the following folders from an Apache Tomcat instance: C:\apache-tomcat \temp\ C:\apache-tomcat \work\ C:\apache-tomcat \bin\documentum\cache\ C:\apache-tomcat \logs\ 6. Start the application server. 15

16 Installing the Connector Installing Application Server Components for Capital Projects 1.X 1. Stop the application server. 2. Navigate to the InstallCPConnectorOnAS.bat for Windows or InstallCPConnectorOnAS.sh for Linux in the temporary installation location. For example: C:\temp\<connector folder>\installcpconnectoronas.* Note: You must set CP2X=false. 3. Open the file in a text editor and specify the web application folder parameter value. For example: WEB_APP_FOLDER=C:\apache-tomcat \webapps\epfm\ 4. Run the InstallCPConnectorOnAS.* file applicable for the corresponding operating system. 5. Clear the application server cache. For example, delete the contents of the following folders from an Apache Tomcat instance: C:\apache-tomcat \temp\ C:\apache-tomcat \work\ C:\apache-tomcat \bin\documentum\cache\ C:\apache-tomcat \logs\ 6. Start the application server. Setting log4j for Connector Logs To set the log4j connector logs: 1. Navigate to log4j file from <DOCUMENTUM_HOME>\<JBOSS_VERSION>\server\DctmServer _MethodServer\<DEPLOYMENT_LOCATION>\serverApps.ear\APP-INF\classes \log4j.properties path. 2. Add the following details: # supex connection log4j.appender.supexcon=org.apache.log4j.rollingfileappender log4j.appender.supexcon.file=c:/logs/supex_connection.log log4j.appender.supexcon.maxfilesize=10mb log4j.appender.supexcon.layout=org.apache.log4j.patternlayout log4j.appender.supexcon.layout.conversionpattern= %d{hh\:mm\:ss,sss} %10r %5p [%10t] %-20c - %5x %m%n # supex requests log4j.appender.supexreq=org.apache.log4j.rollingfileappender log4j.appender.supexreq.file=c:/documentum/jboss7.1.1/server/dctmserver_methodserver/logs /supex_requests.log log4j.appender.supexreq.maxfilesize=10mb log4j.additivity.supexreq=false log4j.appender.supexreq.layout=org.apache.log4j.patternlayout log4j.appender.supexreq.layout.conversionpattern=%d{hh\:mm\:ss,sss} %10r %5p [%10t] %-20c - %5x %m%n # log configurations for modules

17 Installing the Connector Note: log4j.logger.com.ecs=debug, epfm log4j.additivity.com.ecs=false log4j.logger.com.eif=debug, epfm log4j.additivity.com.eif=false log4j.logger.com.emc.documentum.http=debug, supexreq log4j.logger.com.emc.documentum.http.connection.java=debug log4j.additivity.com.emc.documentum.http=false The value set on log4j.appender.supexcon.file and log4j.appender.supexreq.file must be a valid path on the computer that hosts the method server. <JBOSS_VERSION>: Use jboss7.1.1 for Documentum 7.1 and jboss5.1.0 for others. <DEPLOYMENT_LOCATION>: Use deployments for Documentum 7.1 and deploy for others. Configuring Repository File Formats If Supplier Exchange uses a file format that the Capital Projects repository does not support, run a Documentum Query Language (DQL) command to update the repository to support the file format. 1. In Documentum Administrator, select Tools > Dql Editor. 2. Run the DQL command for each file format that you want to support. The following example shows the command for configuring the repository to support Microsoft Word documents with a docx extension: CREATE dm_format OBJECT SET name = 'msw14', SET description = 'Microsoft Word document', SET dos_extension = 'docx', SET mime_type = 'application/vnd.openxmlformats- officedocument.wordprocessingml.document' Appendix A, Supported File Formats lists file formats that you can configure the repository to support. 3. Click Execute. Upgrading the Connector This chapter contains the following topics: Upgrading Content Server Components, page 18 Upgrading Application Server Components, page 18 Upgrading Application Server Components for Capital Projects Express, page 18 Post Upgrade Task (Mandatory), page 18 17

18 Installing the Connector Upgrading Content Server Components Note: Perform the following: For Capital Projects 1.9 and Capital Projects 1.10: Set Upgrade = true and CP2X = false. For Capital Projects 2.X: Set Upgrade = true and CP2X = true. You must set Upgrade = true, whenever you want to upgrade any of Capital Projects or Capital Projects Express version. Then, you must again run the steps documented in Installing Content Server Components, page 13 section. Here, Supplier Exchange details are not required for upgrade steps. Upgrading Application Server Components Note: You must set Upgrade = true, whenever you want to upgrade any of Capital Projects versions. In addition, you must set CP2X = false. Then, you must again run the steps documented in Installing Application Server Components for Capital Projects 1.X, page 16 section. Upgrading Application Server Components for Capital Projects Express Note: You must set Upgrade = true, whenever you want to upgrade any of Capital Projects versions. In addition, you must set CP2X = true. Then, you must again run the steps documented in Installing Application Server Components for Capital Projects Express 2.X, page 15 section. Post Upgrade Task (Mandatory) Note: The following upgrade steps are applicable only for any builds prior to Build 25. The upgrade deliverable link tool changes the linking information that maps the registered Capital Projects deliverable to Supplier Exchange. You must update these information because of security related changes made to Supplier Exchange. You can use upgrade deliverable link tool, if you have an environment where the projects and deliverables are already registered in Supplier Exchange. The deliverable link tool is packaged in UpgradeSelfLinks.jar. By default, the UpgradeSelfLinks.jar file is placed in the lib folder for Capital Projects Connector 1.9, and Capital Projects Connector To run the upgrade deliverable link tool, use the following command: java-cp <installer location>\upgradeselflinks.jar;<jms jars location>\*;<documentum Shared folder location>\*;<documentum Config folder location> com.emc.xchange.tasks.upgradeselflinks java cp [jars required in classpath] com.emc.xchange.tasks.upgradeselflinks [-options] 18

19 Installing the Connector Here, docbase (mandatory) - Specify the name of the docbase on which self links have to be updated. username (mandatory) - Specify the name of the user whose credentials are to be used to establish a session with the docbase. password (mandatory) - Specify the Password of the user trying to establish a session with the docbase. projectref (optional) - Specify the Project reference of the Capital Projects project whose self links you wish to upgrade. help (optional) - Specify the usage instructions ignoring all other options passed. For example, java -cp C:\UpgradeSelfLinks.jar;C:\Documentum\jboss7.1.1\server \DctmServer_MethodServer\deployments\ServerApps.ear\DmMethods.war \WEB-INF\lib\*;C:\Documentum\Shared\*;C:\Documentum\config com.emc.xchange.tasks.upgradeselflinks -docbase=mydb -username=administrator -password=password@123 -projectref=g89471 Here, <installer location> = C:\ <JMS jars location> = C:\Documentum\jboss7.1.1\server\DctmServer _MethodServer\deployments\ServerApps.ear\DmMethods.war\WEB-INF\lib <Documentum Shared folder location> = C:\Documentum\Shared <Documentum Config folder location> = C:\Documentum\config After updating the Capital Projects object, the tool validates the link to Supplier Exchange by retrieving the associated Supplier Exchange deliverable. The following result is shown on the user interface: The object - object_name, with r_object_id object_id, is VALID or INVALID in the event of a failed validation. 19

20 Installing the Connector 20

21 Chapter 4 Configuring Capital Projects Connector for Supplier Exchange The Capital Projects Connector for Supplier Exchange connects Capital Projects to a software as a service Supplier Exchange environment. After you install the connector, plant owners, external vendors, and operators can exchange deliverables and transmittals with Engineering, Procurement, and Construction companies through Supplier Exchange. The Capital Projects Connector for Supplier Exchange includes two levels of configuration, that is RCF and xchange_config.xml. This chapter contains the following topics: Enabling Capital Projects Connector for Supplier Exchange, page 21 Configuring Supplier Exchange Connection Details, page 22 Registering Capital Projects with Supplier Exchange Project, page 24 Registering External Deliverable Document to Supplier Exchange, page 24 Validating the Deliverables / Deliverable Set in Supplier Exchange, page 25 Ingestion of Submitted Deliverables / Deliverable Set from Supplier Exchange to Capital Projects, page 26 Synchronization of Fields set on Deliverables in Supplier Exchange, page 26 Sending General Transmittals to Supplier Exchange, page 27 Acknowledging Transmittals sent to Supplier Exchange, page 27 Close Deliverable, page 28 Message Handler, page 28 Enabling Capital Projects Connector for Supplier Exchange In the RCF file, you can enable or disable the Supplier Exchange connector by updating the following parameters: <param name="isxchangeenabled" value="true"/> 21

22 Configuring Capital Projects Connector for Supplier Exchange Set the isxchangeenabled parameter to true for enabling the Capital Projects Connector for Supplier Exchange. By default, it is set to false for Capital Projects installation and after the Connector is installed this flag is set to true. Configuring Supplier Exchange Connection Details You must configure system connections because Capital Projects requires the authentication details of external systems it is attempting to connect. For Supplier Exchange, the details required includes the URL of the Supplier Exchange tenant being used and the service account information. A service account authenticates any Capital Projects system that is attempting to connect with Supplier Exchange. After you create a service account in Supplier Exchange, you may receive a Key ID and Private Key. The Zendesk -Account-Creation provides details on the creation of service account. To connect to the Supplier Exchange site by using Capital Projects 1.10 and 2.X, /System/EPFM/CP/System_connection.xml must be updated with the following <system_connection> element: <system_connection description="<description of Supplier Exchange site>" name="name of Supplier Exchange site" provider="beacon" type="xchange> <param name="url">url of the SE Site</param> <param name="key_id" encryption="encryption used">public Key Value as displayed in Supplier Exchange</param> <param name="private_key" encryption="encryption used">public Key Value as displayed in Supplier Exchange </param> <param name="proxy_host">host Name of the proxy server (if any)</</param> <param name="proxy_port">host Port of the proxy server (if any)</</param> </system_connection> To connect to the Supplier Exchange by using Capital Projects 1.9: <RCF>/<system_connections> must be updated with the following <system_connection> element: <system_connection name="supplier Exchange Site" description="<description of Supplier Exchange site>" type ="xchange" provider="beacon"> <url>url of the Supplier Exchange Site</url> <key_id encryption="encryption used" >Public Key Value as displayed in Supplier Exchange</key_id> <private_key encryption="encryption used">public Key Value as displayed in Supplier Exchange</private_key> <proxy_host>host Name of the proxy server (if any)</proxy_host> <proxy_port>host Port of the proxy server (if any)</proxy_port> </system_connection> Where: url: Specify the url to connect to the Supplier Exchange. key_id: This element has an attribute name encryption whose possible value is dfc. For example, 22

23 Configuring Capital Projects Connector for Supplier Exchange Capital Projects 1.10:<param name="key_id" encryption ="lockbox">6885e2341bcf47dd c0c4ee</param> Capital Projects 1.9: If you have <key_id encryption= dfc >xxxxxxx</key_id> the value xxxxxxx is decrypted by using DFC s RegistryPasswordUtils class. private_key: Specifies the encryption/decryption key. proxy_host : Specify the proxy host details if any. proxy_port : Specify the proxy port if any. Note: Where, key_id and private_key values are generated from the Supplier Exchange Service Account page. The EMC Documentum Capital Projects Quick Reference Guide provides additional details on creating a service account to get private key and key id. If your environment does not use a proxy server, remove the <proxy_host> and <proxy_port> elements. The <key_id>,<private_key> value can be specified in encrypted form. When using the encrypted form specify the attribute: encryption = lockbox to the <key_id>, <private_key>. For example: <key_id encryption="lockbox">asdfgewffd==</key_id> To encrypt the password, open a command prompt and run the following command: java -cp "%DOCUMENTUM_SHARED%\dfc.jar" com.documentum.fc.tools.registrypasswordutils <password> where %DOCUMENTUM_SHARED%\dfc.jar is the path to the dfc.jar file in your environment. Encryption of the External System Information You can encrypt key_id and private_key. To encrypt a password you can execute the following command: java-cp <path_to_dfc_jar>\dfc.jar com.documentum.fc.tools.registrypasswordutils <text_to_encrypt> The Capital Projects 1.10 Connector supports lockbox encryption. The Creating and Configuring the Lockbox section in the Capital Projects Installation Guide provides more details on the lockbox configuration. 23

24 Configuring Capital Projects Connector for Supplier Exchange Registering Capital Projects with Supplier Exchange Project When you register the project in Capital Projects, the Supplier Exchange connector verifies if there is a project in Supplier Exchange with the same project code. Else, a new project is created in Supplier Exchange with the Capital Projects project reference and project name. You can assign the project coordinator role for the newly added project. These configurations are controlled by the settings set in the xchange_config.xml file. To register the project: 1. Log in to Capital Projects. 2. Navigate to the project work area. 3. Select the project to be registered. 4. Click Tools>Actions. 5. Click Register Project with Supplier Exchange. In the RCF file, you can configure the <operation name="register_project_xchange"> operation and corresponding <action name= register_project_xchange_action > action for enabling or disabling project registration through the user interface. Registering External Deliverable Document to Supplier Exchange External deliverable documents created in Capital Projects can be registered with Supplier Exchange by either performing the Register Deliverable with Supplier Exchange action or automatically by the plugin when the document is created in the project. Documents are automatically registered with Supplier Exchange if the project is already registered. You must ensure that the RegisterDeliverable plugin is enabled in RCF. For documents created prior to project registration, one needs manually to register them with Supplier Exchange. To automatically register the deliverables with Supplier Exchange for documents that are created after Connector installation, use the following plug-in details: <plugin applicable_types="external Deliverable Document" class="com.emc.eix.pluggable.plugin.registerdeliverableplugin" name="registerdeliverable" run_on_event="ecs_creation_finished"> <params> <param name="process_immediately" value="false"/> <param name="project_expression" value="${project.r_object_id}"/> </params> <preconditions> <precondition reference="isxchangeenabled"/> </preconditions> </plugin> 24

25 Configuring Capital Projects Connector for Supplier Exchange Where: Plugin parameter process_immediately is applicable only for a super user: When set to true will immediately registers the project with Supplier Exchange. Otherwise, it is registered when the xchange Register Deliverables job runs. Validating the Deliverables / Deliverable Set in Supplier Exchange Validation of deliverables in Supplier Exchange by the Capital Projects Connector is done so that only those documents that are ingested by Capital Projects that satisfy the validation criteria. The different validation criteria for deliverables are: Revision Exists State Validation Status No N/A Valid. The Supplier Exchange deliverable is moved to Accepted state. Supplier Exchange Deliverable is ingested as a new revision after the ingestion job runs subsequently. Yes As Submitted Valid. The Supplier Exchange deliverable is moved to Accepted state. Supplier Exchange Deliverable is ingested as a new version of the revision after the ingestion job runs subsequently. Yes Latest Latest (Under Revision) Old Revision Cancelled Void Superseded Not Valid. The Supplier Exchange deliverable is moved to Rejected state and sends Notification mail to project coordinator. N/A N/A Not Valid: Document exist in Supplier Exchange and not in Capital Projects then validation fails. N/A N/A Invalid: A deliverable set exists in Supplier Exchange which has atleast one match in Capital Projects which fails due to any of the above reasons. N/A N/A Invalid: A deliverable set exists in Supplier Exchange which has atleast one document which has a match in Capital Projects and atleast one document which does not have a match in Capital Projects. The projects that are created in Supplier Exchange through Capital Projects Connector has the Auto Validation of Deliverables feature set to true for all deliverables. Whenever a user submits a deliverable in Supplier Exchange, the deliverables/deliverable set moves to Pending Validation state. 25

26 Configuring Capital Projects Connector for Supplier Exchange The xchange Import Validation job validates the documents in Supplier Exchange that are created by using Deliverable Registration in Capital Projects and that are in Pending Validation state. Ingestion of Submitted Deliverables / Deliverable Set from Supplier Exchange to Capital Projects The submitted deliverables in Supplier Exchange are sent to Capital Projects as an incoming transmittal. The content that deliverables or deliverable set is ingested from Supplier Exchange include primary content, renditions, and comment attachments. If the incoming transmittal created represent a deliverable set, it will have the same name as a deliverable set. Here, the title is the name of the submittal in Supplier Exchange that represents the deliverable set. In the RCF file, you can configure the MarkITAsReceived plug-in to auto complete the incoming transmittal from Supplier Exchange. If you do not want auto completion, you can remove the <plugin name="markitasreceived"> from the RCF schema file. Synchronization of Fields set on Deliverables in Supplier Exchange The metadata of deliverables in Supplier Exchange can be copied into the metadata of the corresponding deliverable in Capital Projects. During ingestion, the content and metadata are retrieved and synchronized with Capital Projects deliverables. The xchange_config.xml file contains the settings for a deliverable. The following are the creation settings for a deliverable. <parent target="saas_beacon_checklistitem" auto_create="true" picklists_profile="" roles_profile=""> <properties> <property target="name" source="object_name" default=""/> <property target="description" source="title" default=""/> <property source="eif_alt_doc_number" target="alternatedocno" default="" sync_options="ingestion" /> <property source="eif_prepared_by" target="submittedby" default="" sync_options="ingestion" /> <property source="eif_prepared_on" target="submitteddate" default="" sync_options="ingestion" data_type="date" /> </properties> </parent> The Capital Projects attributes for Alternate Document Name, Submitted By, and Submitted Date fields for the deliverable in Supplier Exchange are eif_alt_doc_number, eif_prepared_by, and eif_prepared_on. The sync options should be mentioned as follows : ingestion create ingestion, create 26

27 Configuring Capital Projects Connector for Supplier Exchange The allowed options for sync_options attribute are ingestion, create, ingestion, create. If you specify ingestion as a sync option, the field is not set during deliverable registration. The deliverable is created in Supplier Exchange and the fields with ingestion as the sync_option remains empty. Whenever you run the ingestion job to register the deliverable into Capital Projects, the Capital Projects attribute values specified as the source for these fields are set with the values of these fields in Supplier Exchange. If you specify only create as sync_option, or if you do not specify any option, the field in Supplier Exchange is set at the time of deliverable registration. The corresponding attribute in Capital Projects is not overwritten during ingestion. If you specify both ingestion and create as sync_options, the corresponding fields in Supplier Exchange are set at the time of document registration. At the time of ingestion, they are overridden in Capital Projects. Sending General Transmittals to Supplier Exchange In the RCF file, you can configure the delivery mechanism to send the transmittals to Supplier Exchange by using the element. <rcf>\<transmittals>\<distribution>\<delivery_methods>\<delivery_method name= EXH > In Capital Projects: 1. Navigate to Transmittals > Types > General transmittal > Properties 2. On the Settings tab, and edit the Recipient Delivery Method. 3. Add Supplier Exchange Site as one of the delivery methods. When you send the general transmittals, this option will be available as one of the options in the Deliver By list. You must set the company value same as the contract value in Supplier Exchange while sending the general transmittal. The <Validator name= tr_xch_check_recipient> validator checks whether the recipient set in the general transmittal exists in Supplier Exchange. Acknowledging Transmittals sent to Supplier Exchange Transmittals which are required to be acknowledged and are sent to a Supplier Exchange site are marked as acknowledged in Capital Projects, provided they are acknowledged by their Supplier Exchange site recipient. 27

28 Configuring Capital Projects Connector for Supplier Exchange The xchange Acknowledge Transmittals job is periodically run to poll the status of such transmittals from the Supplier Exchange site. The Transmittals that are acknowledged in Supplier Exchange are acknowledged in Capital Projects as well. If there are multiple transmittals created with the same name within different contracts, the transmittal from Capital Projects is considered acknowledged as soon as any one of these multiple transmittals are acknowledged in the Supplier Exchange. Close Deliverable In the RCF file, you can configure the <plugin name=closedeliverable> plug-in to close the deliverable in Supplier Exchange. You can configure the states parameter, which accepts comma separated values. When the external deliverable document reaches any of the states configured in the RCF, the plug-in is fired to delete the deliverable in Supplier Exchange. <plugin name="closedeliverable" run_on_event="ecs_target_state_reached" class="com.emc.eix.pluggable.plugin.deliverablestatechangeplugin" applicable_types="external Deliverable Document"> <params> <param name="states" value="cancelled,void,superseded"/> </params> <preconditions> <precondition reference="isxchangeenabled"/> </preconditions> </plugin> Message Handler Message handlers are responsible for handling specific types of messages. The link between a message and its handler is the message_key. The message_body notification provides the description of the message. In the RCF file, you can configure the following message_keys: 1. In the RCF file, navigate to the /rcf/task_message_management/message_handlers parameter. 2. Locate the respective message_key and update the required description details. Table 1. Message Key Details message_key message_type Description EIX_DELIVERABLE _REGISTER_FAILURE EIX_INCOMING_TR _NOTIFICATION Deliverable Registration Transmittal Notification Message handler for notifications when the registration of deliverable to Supplier Exchange site fails. Message handler for notifications when an incoming transmittal is received and requires processing. 28

29 Configuring Capital Projects Connector for Supplier Exchange EIX_INCOMING_TR _FAILURE EIF_TR_MARK_RECEIVED _SUCCESS Incoming Transmittal Failure Incoming Transmittal Mark as Received success Message handler for notifications when an incoming transmittal fails to import documents from Supplier Exchange to Capital Projects. Message handler for notifications when an incoming transmittal is successfully marked as received. EIF_TR_MARK_RECEIVED _ISSUES Incoming Transmittal Mark as Received Failure Message handler for notifications when the an incoming transmittal fails to mark as received. EIF_TR_REND_COMMENTS _ISSUES EIF_TR_REND_COMMENTS _SUCCESS Rendition/Comment Notification Rendition/Comment Notification Message handler for notifications regarding the failure to add rendition or comment on a deliverable document. Message handler for notifications regarding the renditions or comments added on the document. Jobs in Supplier Exchange The following are the Supplier Exchange jobs: xchange Register Deliverables: Registers all the deliverables in Capital Projects to Supplier Exchange that are in pending registration status. When the process_immediately parameter is set to false in the <plugin name = RegisterDeliverable"> plug-in, process_immediately, the xchange Register Deliverables job registers all the pending external deliverable documents instead of registering them immediately for the superuser. xchange Import Packages: Downloads all the deliverables from Supplier Exchange that are in Accepted state into Capital Projects. These documents are added into the matching document in Capital Projects and an incoming transmittal is created for the same. The parameters for this job are: cancel_any_checkout: If this parameter is set to true, any document that is checked out will be unlocked by the job. By default, this value is set to false. transmittal_limit: Limits the number of incoming transmittals that are created as a part of this job. By default, this value is set to 10. xchange Import Validation: Validates all the deliverables in Supplier Exchange that are in Pending Validation state and that are created during the deliverable registration in Capital Projects. The successfully validated deliverables are moved to Accepted state and the invalid 29

30 Configuring Capital Projects Connector for Supplier Exchange deliverables are moved to Rejected state in Supplier Exchange. The Validation of Deliverables in Supplier Exchange section provides more details on the validation criteria xchange Acknowledge Transmittals: Acknowledges the transmittals that are sent from Capital Projects. This job runs at periodic intervals and tracks the acknowledged transmittals in Supplier Exchange and compares the same in Capital Projects. Configuring Supplier Exchange In Capital Projects, you can configure the auto creation of artifacts in Supplier Exchange by using the xchange_config.xml file located at ECSCONFIG\RCF. To auto create in Supplier Exchange, you have to map the Capital Projects object type and its attributes with the corresponding Supplier Exchange object type and properties. The following sections explain the details to auto create artifacts in Supplier Exchange: Configuring Projects Creation in Supplier Exchange, page 30 Configuring Contract Creation in Supplier Exchange, page 31 Configuring Deliverable Creation in Supplier Exchange, page 32 Configuring Transmittal Creation in Supplier Exchange, page 33 Configuring Roles and Picklist Profile, page 35 Configure Connector to Regulate Clearing of Supplier Exchange Deliverables, page 36 Configuring Projects Creation in Supplier Exchange You can auto create projects in Supplier Exchange by configuring the following XML settings: In the configuration file, navigate to the xchange_configurations/creation settings [target_type = "saas_beacon_engagementspace"] element and map the Supplier Exchange target properties with the Capital Projects source attributes. The following element shows a sample project configuration: <creation_settings entity="project" source_type="eifx_project" target_type="saas_beacon_engagementspace"> <parent target="saas_beacon_engagementspace" auto_create="true" picklists_profile="" roles_profile="engspace_roles"> <properties> <property target="project_code" source="eif_project_ref" default=""/> <property target="name" source="${this.object_name} - Auto Created" default=""/> <property target="description" source="${this.title}" default=""/> <property target="enableautovalidate" source="" default="1"/> </properties> </parent> </creation_settings> The <creation settings> element defines the creation of the project. The source_type defines the Capital Projects project object type and target_type defines the Supplier Exchange project object type that must be created. The <parent> element defines the type in Supplier Exchange that is configured for creation, auto_create defines if the project must be auto created. 30

31 Configuring Capital Projects Connector for Supplier Exchange picklists_profile maps to a picklist profile defined at /xchange_configurations /picklists_profile which defines any picklist properties that must be mapped while creating the projects in Supplier Exchange. The roles_profile maps to any roles that are defined at xchange_configurations/roles _profile which specifies any users in a role that must be added to the target roles in Supplier Exchange. The <property> element defines the mapping of Supplier Exchange target, and Capital Projects source attribute that is required for creating the project. You can define the project_code, name, and description target attributes of Supplier Exchange. Configuring Contract Creation in Supplier Exchange The <match> element for saas_beacon_project defines the matching criteria that will be used to find a matching contract in Supplier Exchange based on the Capital Project attributes specified in the value attribute of the <condition> tag. For example, <creation_settings entity="deliverable" source_type="eifx_deliverable_doc" target_type="saas_beacon_checklistitem"> <match> <condition property="originator" value="${this.eif_originator}"/> <condition property="contract-code" value="${this.eif_contract_number}"/> </match> </creation_settings> Capital Projects Connector verifies the contract in Supplier Exchange as per the following: Precondition eif_originator is not NULL or empty eif_contract_number is not NULL or empty Supplier Exchange Contract Attribute Relationship originator equals eif_originator AND Capital Projects source_type Object Attribute (eifx _deliverable_doc) contract-code equals eif_contract_number If either eif_originator or eif_contract_number are null or empty, these will not be considered when looking for a match. If eif_contract_number is empty, only Contracts with the matching originator, eif_originator values will be considered as a match. The contract-code of the Contract is ignored. 31

32 Configuring Capital Projects Connector for Supplier Exchange Configuring Deliverable Creation in Supplier Exchange You can create a deliverable in Supplier Exchange by configuring the following XML settings: In the configuration file, navigate to the <creation settings entity="deliverable" source type="eifx_deliverable" target_type="saas_beacon_checklistitem"> element and map the Supplier Exchange target properties with the Capital Projects source attributes. The following element shows a sample configuration to create a deliverable: The <creation settings> element defines the creation of the deliverable. The source_type defines the Capital Projects deliverable object type and target_type defines the Supplier Exchange deliverable object type that must be created. The option[name="project_code"] element defines the Capital Projects attribute on the eifx_deliverable object which identifies the Project code of Supplier Exchange to which the deliverable belongs. The <parent> element defines the target type in Supplier Exchange that is configured for creation, auto_create defines if the Supplier Exchange artifact must be auto created. You can define creation of targets saas_beacon_project, saas_beacon_checklist and saas_beacon_checklistitem with respective attribute mapping properties. The picklists_profile attribute maps to a picklist profile defined at /xchange _configurations/picklists_profile/picklist_profile which defines any picklist properties that must be mapped while creating the artifacts in Supplier Exchange. 32

33 Configuring Capital Projects Connector for Supplier Exchange The roles_profile attribute maps to any role defined in /xchange_configurations /roles_profile/role_profile which specifies any users in a role that must be added to the target roles for the artifacts created in Supplier Exchange. The <property> within </parent>/<properties> element defines the mapping of Supplier Exchange target, and Capital Projects source attribute that is required for creating a Supplier Exchange artifact. You can define the submittalidprefix, name, and organization target attributes for the creation of contracts in Supplier Exchange. You can use enabledeliverableset to enable deliverable sets at a contract level and use managedbyconnector to update permissions that user has through Supplier Exchange user interface. You can define the name for the creation of deliverable list {saas_beacon_checklist} in Supplier Exchange. In addition, you can define the description for the creation of deliverable in Supplier Exchange. Note: For additional information, refer to xchange_config.xml file at /ECSCONFIG/RCF path in repository. Configuring Transmittal Creation in Supplier Exchange You can create a transmittal in Supplier Exchange by configuring the following XML settings: In the configuration file, navigate to the xchange_configurations/creation settings [target_type ="saas_beacon_transmittal"] element and map the Supplier Exchange target properties with the Capital Projects source attributes. The following element shows a sample transmittal configuration: 33

34 Configuring Capital Projects Connector for Supplier Exchange The <creation settings> element defines the creation of the transmittal. The source_type defines the Capital Projects transmittal object type and target_type defines the Supplier Exchange transmittal object type that must be created. The <option> tag defines the following: add_contract_member: Defines whether the contract member must be added. project code: Defines the Capital Projects attribute on the eifx_transmittal type which identifies the code of the project to which the transmittal belongs. The <parent> element defines the target type in Supplier Exchange that is configured for creation, auto_create defines if the Supplier Exchange artifact must be auto created. You can define creation of targets saas_beacon_project and saas_beacon_transmittal with respective attribute mapping properties. picklists_profile maps to a picklist profile defined at /xchange_configurations /picklists_profile which specifies any picklist properties that must be mapped while creating artifacts in Supplier Exchange. The roles_profile attribute maps to any role that are defined in xchange_configurations/roles_profile which specifies any users in a role that must be added to the target roles for the artifacts created in Supplier Exchange. The <property> element defines the mapping of Supplier Exchange target, and Capital Projects source attribute that is required for creating a Supplier Exchange artifact. You can define the submittalidprefix, name, and organization target attributes for the creation of contracts in Supplier Exchange. You can use enabledeliverableset to enable deliverable sets at a contract level and use managedbyconnector to update permissions that user has through Supplier Exchange user interface. Also, you can define the name, description, receiveddate, isackrequired, and recipient for the creation of transmittal in Supplier Exchange. 34