White Paper

EMC DOCUMENTUM CONTENT SERVICES FOR SAP A Detailed Review

Abstract This white paper provides a detailed review of the EMC® Documentum® Content Services for SAP (CS SAP) functionality and architectural design changes in the 6.5 release. The CS SAP application integrates the Documentum content management system with an SAP R/3 or ECC system. It is an interface to the SAP R/3 or ECC system based on the SAP standard Document Management System (DMS) and ArchiveLink interfaces. This paper provides information about configuration and setup scenarios in the CS SAP application. March 2011

Copyright © 2011 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate 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. All other trademarks used herein are the property of their respective owners. Part Number h8216

EMC Documentum Content Services for SAP A Detailed Review

2

Table of Contents Executive summary.................................................................................................. 4 Audience ............................................................................................................................ 4 Terminology ....................................................................................................................... 4

Documentum Content Services for SAP overview ...................................................... 5 Components ....................................................................................................................... 5 Agent (HVP Worker) ............................................................................................................ 6 WebAdmin ......................................................................................................................... 6

Configuring connections to SAP ............................................................................... 7 SAP server configuration .................................................................................................... 7 SAP user configuration ....................................................................................................... 8 SAP Query .......................................................................................................................... 8 sap_query_type_rfc ........................................................................................................ 9 sap_ query_type_table ................................................................................................... 9 sap_query_type_plm .................................................................................................... 10 sap_query_plm_type_table .......................................................................................... 10

Linking Documentum objects to SAP ...................................................................... 11 Documentum query .......................................................................................................... 11 Link Documentum ............................................................................................................ 11 sap_object_type_archlink ............................................................................................ 13 sap_query_type_plm and sap_query_plm_type_table .................................................. 15 sap_object_type_workflow ........................................................................................... 19 sap_object_type_barcode ............................................................................................ 21 Replicate Documentum .................................................................................................... 22 Link SAP ........................................................................................................................... 23 Replicate SAP ................................................................................................................... 27 Check Document Info Records .......................................................................................... 28

Configuring the “Agent” component ....................................................................... 28 Agents .............................................................................................................................. 28 HVPS ................................................................................................................................ 28 Load balancing............................................................................................................. 29 Jobs .................................................................................................................................. 30

Configuring View ................................................................................................... 31 DmView ............................................................................................................................ 31 Functional flow in DmView............................................................................................ 31

Conclusion ............................................................................................................ 32

EMC Documentum Content Services for SAP A Detailed Review

3

Executive summary EMC® Documentum® Content Services for SAP (CS SAP) is an interface to the SAP R/3 system, which is based on SAP’s standard DMS and ArchiveLink interfaces. Content Services for SAP enables SAP users to easily access and display documents that are stored in the Documentum repository from a variety of SAP modules. It also stores and manages reports and outgoing documents in the Documentum repository. CS SAP enables enterprises to automate document-driven tasks quickly and more efficiently. You can use CS SAP to manage important business documents and content within the context of SAP application objects such as transactions, records, and workflows. The CS SAP modules include: Content Services Archive is a Report Management and Distribution module that enables you to archive reports, documents, and data in the Documentum repository. The reports and archived documents can later be retrieved and viewed by both SAP and Documentum clients. To use CS SAP with HTTP archiving services, install the Archive Services for SAP (AS SAP) application. Content Services Manage enables you to release Documentum documents to SAP and maintain the released documents. Content Services View enables you to view the released Documentum documents from inside the SAP application.

Audience This white paper is intended for EMC support personnel, professional services, developers, QA, and architects. This paper will also be helpful for managers and decision-makers for future development.

Terminology Agent: The component of CS SAP that performs linking in a batch mode. BAPI: SAP term for its business object interface. BAPI is one of the easiest ways to manipulate business objects in SAP. CS SAP: Provides content management functionality in SAP. It is sometimes used as an umbrella term to refer to all products that are related to SAP integration. DMS: SAP’s document management system. Document Info Record (DIR): This is the link or a pointer object created in SAP by the CS SAP product that contains the Document Resource Locator (DRL) to the document stored in Documentum. Documentum Administrator (DA): This application is used for administering the Documentum product and also is the base for the CS SAP WebAdmin.

EMC Documentum Content Services for SAP A Detailed Review

4

Enterprise Integration (EI): This is the DAR file that installs the CS SAP specific Object types on the repository. Manage: The component of CS SAP that performs linking in a manual/interactive mode. Product Lifecycle Management (PLM): Interface provided by SAP to link the object from the external repository to SAP objects. SAP GUI: SAP client interface. Menu-driven tool that directly connects to the SAP server. WebAdmin: Web-based administration tool for CS SAP.

Documentum Content Services for SAP overview Components The following are the components and subcomponents of the CS SAP product: Content Services for SAP server (Content_Services_for_SAP_6.5_server_Windows.zip/tar) Enterprise Integrations Core API (Enterprise_Integrations_Core.zip/tar) — Contains the core API library used by the CS SAP server component. This is packaged as a .zip/ .tar file containing the DAR file and the relevant script files for installing the DAR file using the command line. WebAdmin (dmei_webadmin.zip/.tar) — Contains the WebAdmin administration component that would be installed on DA. HVPS (hvps.zip/tar) — Contains the HVPS Controller, which is used to delegate CS SAP jobs to the available HVP Worker. The HVPS library resides on the Java Method server of the Content Server. It is packaged as a .zip/tar file and contains the HVPS DAR file and relevant script files for installing the DAR file using the command line. HVP Worker (HvpWorker.zip/tar) — Agent that performs DMS operations. It is packaged as a .zip/tar file that contains the HvpWorker.war and hvp.properties files. Custom Installer (dmei_custom_installer.zip/tar) — Used for customizations of Object types in CS SAP.

EMC Documentum Content Services for SAP A Detailed Review

5

Content Services for SAP client View and Manage WebView The client installer installs the client products and establishes the environment needed for the clients to run. The SAP GUI must be installed as a prerequisite. The installing user has the following options: 

Standard user, which installs View



Admin user, which installs View plus Manage

Agent (HVP Worker) The HVP Worker or agent is a Java-based application that is installable on supported application servers. The CS SAP jobs are executed by the HVP Worker. The HVPS Controller running on the method server delegates the jobs to the HVP Worker based on availability and load. HVP Worker accepts the payload and links the specified documents in the Documentum repository with the objects in SAP. The worker communicates with Documentum using the DFC library and SAP R/3 using the SAP JCo library. The method used for the CS SAP jobs is as follows: “com.documentum.ei.doclink.agentJob.DmeiSapAgent” The following figure explains the relationship between the HVPS Controller and the HVP Worker. HVP Worker 1 HVP Controller (CS Java Method Server)

HVP Worker 2

HVP Worker n

Figure 1. Relationship between the HVPS Controller and HVP Worker

WebAdmin The WebAdmin is used to administer CS SAP and perform the following operations: Configure Content Services to archive data from SAP. In addition to WebAdmin, the AS SAP product will be required to perform this operation.

EMC Documentum Content Services for SAP A Detailed Review

6

Configure the CS SAP to link documents and replicate metadata between Documentum and SAP. The Content Services for SAP node in DA contains the following subnodes: The Actions subnode enables you to create the rules to perform document linking, data replicating, and integrity checking functions. The Archive Link subnode enables you to configure archives, Barcodes for Archive Link, and certificate management. The Auto Manage subnode enables you to set up agent configurations, register and de-register HVP Workers, configure jobs to run agents, and monitor job progress. The Clients subnode enables you to configure Content Services for the Content Services Manage and Content Services View client applications. The Documentum subnode has one subnode to enable you to define Documentum queries. The SAP subnode has three subnodes to enable you to define SAP Queries, and configure SAP servers and users to be used by CS SAP.

Configuring connections to SAP Before you use the archive or agent functionality, you must configure the SAP server and user information in CS SAP. Multiple SAP servers and users can be configured in WebAdmin. This allows CS SAP to be used across multiple SAP application servers.

SAP server configuration SAP server configuration is of the sap_server_config type. To connect to a SAP server the following parameters must be configured:

Name — Logical name of the SAP server. An example is “S50 server”. SAP Server Host — This parameter configures the host on which the SAP server is running. It can be an IP address or a hostname. An example is “vmeis50.dctmlabs.com”.

SAP System Name — This is the typical three-letter SAP system name. It is the part of the configuration object that should never be changed, since several programs use this parameter to identify objects linked to a SAP system. An example is “S50”.

System Number — This parameter contains the SAP system number, which is a decimal number from 0 to 99.

The configuration is saved in Cabinet/System/DocLink/SAP/Server in the repository.

EMC Documentum Content Services for SAP A Detailed Review

7

SAP user configuration SAP user configuration is of the sap_user_config type. A SAP user has to be specified to be able to connect to the server. This user must exist in SAP and must have the privileges to execute the action. The configuration object contains the following parameters:

User Name — Description of the user. An example is “S50 user”. SAP User ID — SAP login username. An example is “jindan”. SAP Password — This field is protected and is not directly visible to the user. SAP Client — The three-digit SAP client number for this user is used to connect to the SAP GUI. An example is 731.

SAP Language — The language with which the user connects to SAP. It has the

same functionality as in the SAP GUI. This is required for creating DIRs in SAP. The login language specifies the language of the description attribute. The configuration is saved in Cabinet/System/DocLink/SAP/User in the repository.

SAP Query The action specifies a query that identifies all SAP objects that must be linked to a dynamic Documentum query or to a repository folder. The defined SAP Query is typically associated with a Link SAP Action. The SAP Query configuration object selects the type of query and specifies the query parameters. The configuration is of the sap_query type. The following parameters can be defined:

Query Name — Gives a name to the SAP Query configuration object. This is the string used to reference the query from the action object.

SAP Query Type — Specifies the type of SAP Query being executed. Query Condition Composer — Allows you to specify a list of query parameters to

select all SAP objects that match. The set of query parameters is specified by the Query type configuration and can be added to Query Condition. The syntax is =. The pattern may contain wild card characters or regular expressions only in certain cases. The SAP Query is executed using the SAP JCo library, and the result set is rendered on WebAdmin. The configuration is saved in Cabinet/System/DocLink/SAP/Query in the repository. On installation of the Enterprise Integrations Core.dar file, the following SAP Query types of various custom types will be installed at /System/DocLink/SAP/Bapi in the repository. Descriptions of each follow Table 1.

EMC Documentum Content Services for SAP A Detailed Review

8

Table 1. SAP Query types installed by installation of the EI CORE dar file Documentum Object type

SAP Query types

sap_query_type_rfc

Archive data, Cost center, Financial document, Personnel links, Personnel master, Purchasing Document

sap_query_type_table

Asset Master, Customer, Print list, Vendor, WBS Element

sap_query_type_plm

Asset Master Getlist PLM, Document Info Record PLM, Equipment by short text PLM, Functional location by text PLM, Material by description PLM, Material Master only linking PLM, No object PLM, WBS element only linking PLM

sap_query_plm_type_table

Asset Master PLM, Customer table PLM, EKPO_Table PLM, Vendor Table PLM, WBS element PLM

sap_query_type_rfc The SAP Query types Archive data, Financial document, Personnel links, and Purchasing document invoke the ARCHIV_GET_CONNECTIONS BAPI based on the query parameters specified. ARCHIV_GET_CONNECTIONS queries the TOA01 SAP table based on the following Object types: ARCHIVE for Archive data BKPF for Financial document PREL for Personnel links EKPO for Purchasing document Cost center invokes the BAPI_COSTCENTER_GETLIST BAPI and Personnel master invokes the BAPI_EMPLOYEE_GETLIST BAPI. The query_parameters are of the =, syntax. On execution of the SAP query, results are displayed as an array of strings to Documentum. The result_parameters are of the syntax =,, and . sap_ query_type_table The query_parameters and result_parameters are of the syntax =. The following are the SAP Query types for sap_query_type_table and the respective SAP table that is queried for each type. Table 2. SAP table queried by various SAP Query types for sap_query_type_table SAP Query type

SAP table queried

Asset Master

ANLA

Customer

KNA1

Print list

TOADL

WBS Element

PRPS

EMC Documentum Content Services for SAP A Detailed Review

9

sap_query_type_plm sap_query_type_plm follows a concept similar to that of sap_query_type_rfc for query_parameters and result_parameters. The sap_object_type, key_attributes, and methods are relevant for Link Documentum action rules. The following table mentions the BAPIs invoked and the associated SAP Object for the various SAP Query types. The SAP transaction can be used to view the SAP object. Table 3. SAP Query types, BAPI s, and the associated SAP Object SAP Query type

BAPI

Associated SAP Object

SAP transaction

Asset Master Getlist PLM

BAPI_FIXEDASSET_GETLIST

ANLA

AS03

Equipment by short text PLM

BAPI_EQUI_GETLIST

EQUI

IE03

Functional location by text PLM

BAPI_FUNCLOC_GETLIST

IFLOT

IL03

Material by description PLM

BAPI_MATERIAL_GETLIST

MARA

MM03

Note: To verify the objects in SAP, use transaction se16 and enter the table name as TCLO. This table will give the transaction for various Object types as mentioned in the above table. sap_query_plm_type_table sap_query_plm_type_table is different from sap_query_type_table as, instead of querying the SAP table directly, it invokes RFC_READ_TABLE, passing the table name as the import parameter. The following are the SAP tables queried for the sap_query_plm_type_tablequery type. The SAP transaction can be used to view the SAP objects. Table 4. SAP Query type and SAP table association SAP Query type

SAP table

SAP transaction

Asset Master PLM

ANLA

AS03

Customer table PLM

KNA1

XD03

EKPO_Table PLM

EKPO

ME23

Vendor Table PLM

LFA1

XK03

WBS element PLM

PRPS

CJ13

EMC Documentum Content Services for SAP A Detailed Review

10

Linking Documentum objects to SAP Documentum query The action object specifies a query that selects the complete set of objects to be linked. The query can be any valid DQL query. The DQL query string is stored in a query object of the type dm_query in the repository at /System/Doclink/DCTM/Query. When the action is configured, the object name of the query object must be specified.

Link Documentum The rules defined in the Link Documentum action configuration determine the documents in the Documentum repository that need to be linked to the specified SAP objects. In the action configuration screen, the following can be configured:

SAP Object Type — Type to which the documents should be linked. Binding rules — Specifies the format and version of documents to be released to SAP.

Map Rules — Documentum parameters used to set DIRs in SAP. The key parameters are used to identify the SAP object to be linked to.

Link Documentum action configuration are of the type sap_action_link_doc_object saved at /System/DocLink/SAP/Action in the repository.

EMC Documentum Content Services for SAP A Detailed Review

11

Documentum Read Agent and action configuration Execute DCTM Query associated with the action

Reads map rules to identify SAP object (Object key and object type) for DIR and forms request value map for DIR

sap_link_relation exists?

Yes Exit with NOOP message

No Creates sap_link_relation with relevant DIR metadata

SAP Invokes BAPI_DOCUMENT_CREATE

Establishes JCO connection to SAP erver Creates DIR link and object links

Figure 2. Functional flow for Link Documentum execution The following are procedures that need to be performed when specific actions are called: 1. Check rules parameter Checks include validating the user input with the object model, ensuring that mandatory parameters like the object key are specified. 2. Execute the Documentum query Execute the Documentum query associated to the action. 3. Find match in SAP For each Documentum object, find the related SAP object. 4. Check the relation object Check if the relation object (sap_link_relation) exists for the specific Documentum object. If “Verify Object links” is checked, then the objects that are linked are revisited and metadata changes are refreshed.

EMC Documentum Content Services for SAP A Detailed Review

12

If “verify object link” is set, then the following scenarios are possible: The relation object will be deleted if the DIR does not exist in SAP, but the relation objects exist. Relation objects are sap_link_relation entries for the DIR. During the next run of the agent the relation object and relevant DIR will be created. Error messages will be displayed if the relation object does not exist but the DIR exists. It should be noted that the sap_link_relation object contains a reference to the document object that is linked. Hence, if the Documentum object is deleted, the sap_link_relation entry will no longer be available. If new links are specified in the action rules, they will be added to the existing DIR. Existing object links are retained as is in the DIR. If both the DIR and relation object do not exist, no change will be required. 5. Create a link If not already linked, create the DIR and sap_link_relation object. For creation of the DIR link, the metadata is passed to a structure DOCUMENTDATA in SAP where DATACARRIER1 = DOCUMENTUM, WSAPPLICATION1 = DCM, DOCFILE1 = . Based on the flow description for Link Documentum, the following table provides an analysis of the SAP Object types used in the Link Documentum action. Descriptions of each follow Table 5. Table 5. Object types available for Link Documentum action Documentum Object type

WebAdmin Object types

sap_object_type_archlink

Cost center, Financial document, Personnel master, Purchase order

sap_query_type_plm

Asset Master Getlist PLM, Document Info Record PLM, Equipment by short text PLM, Functional location by text PLM, Material by description PLM, Material Master only linking PLM, No object PLM, WBS element only linking PLM

sap_query_plm_type_table

Asset Master PLM, Customer Table PLM, EKPO_Table PLM, Vendor Table PLM, WBS element PLM

sap_object_type_workflow

Image assign sap workflow

sap_object_type_barcode

Barcode SAP 4.5

sap_object_type_archlink The object model for sap_object_type_archlink defines key_attributes, parameter_defaults, and parameters. The parameters syntax is =, .

EMC Documentum Content Services for SAP A Detailed Review

13

Following is the configuration required at SAP: 1. Define the Content Repository with Document Area as ArchiveLink in the oac0 transaction in the SAP GUI. 2. Create a Document Type at the oac2 transaction in the SAP GUI and assign a Doc class value to it. Doc class is the dm_format of the document that you require to link (for example, FAX, PDF, DOC). 3. Create an association of Document Type and Content Rep. ID to the ObjectType in the oac3 transaction at SAP. At oac3, the TOA01 relationship table is also specified, which indicates that on execution of Link Documentum, an entry will be created in the TOA01 table. Table 6. Relationship between Documentum Object type, SAP Object type, and SAP Document type Object type

SAP Object type

SAP Document type

Cost center

BUS0012

FIIINVOICE

Financial Document

BKPF

FIIINVOICE

Personnel master

PREL

HRIMASTERD

Purchase order

EKKO

MEOORDER

For example, for Financial Document, the Admin creates a Link Documentum action. The map rules will have three key parameters: CompanyCode, DocumentNumber, and FiscalYear. These three parameters will constitute the OBJECT_ID in SAP, which actually determines to which Financial Invoice the dm_document will be linked. The ArchiveId available in map rules is not relevant and need not be specified as it depends on the configuration in oac3 in SAP. The following is the operation that is executed on the SAP system for a Link Documentum action of a financial document. When the ARCHIV_CONNECTION_INSERT BAPI is executed passing the parameters defined in the mapped rules: 

An entry is created in the TOA01 table with ARCHIV_ID in oac0. DocumentType (AR_OBJECT) and ObjectType (SAP_OBJECT) are mapped in oac3.



AR_DATE is the value of the execution date. The date format supported in Documentum 6.5 onward is yyyy-mm-dd.



MANDANT is the client number of the SAP user.



DOC_TYPE assumes the value of Doc. The Class is assigned at oac2.



OBJECT_ID is a key value with a combination of CompanyCode, DocumentNumber, and FiscalYear.



ARC_DOC_ID is the DRL value in the :/DCTM format, which will pass this value to AS SAP when you attempt to view the document.

EMC Documentum Content Services for SAP A Detailed Review

14

The following is the operation that is executed on the Documentum system when the sap_link_relation entry is created: 

parent_id is the i_chronicle_id of the document being linked.



child_id is the r_object_id of the document being linked.



effective_date is the date of creation of the link with the timestamp as 12:00 AM.



sap_object_key is set as the value of

@@ 

sap_doc_id is set as the value of DCTM. This sap_doc_id is the DRL value passed from SAP to Documentum, to open the linked document by reading values from sap_link_relation.



sap_exclusive_link is set to 0 for the Archive Link.

To view the attachment to the Financial Invoice: 1. Navigate to transaction fb03 for a document, for example, Document Number 100000000, Company Code 1000, and FiscalYear 2000. 2. If the Generic Object Services are enabled, obtain the Attachment List and double-click on the attachment to request AS SAP to open the document. The attachment title at SAP assumes the DocumentType description provided at oac2. The same concept is followed for other Object types like Cost center, Personnel master, and Purchase order. sap_query_type_plm and sap_query_plm_type_table The Object types sap_query_type_plm and sap_query_plm_type_table work on the concept of creating DIR object for the particular type depending on the values assigned to the key_attributes variable in the map rule during action configuration. The syntax for key_attributes for object model sap_query_type_plm is =. The syntax for key_attributes for object model for sap_query_plm_type_table is =,. The CS SAP job invokes the SAP functional module BAPI_DOCUMENT_CREATE. On successful execution of the job, a DIR is created in the “DRAW” table. The DIR can be verified in the SAP GUI using the cv04n transaction. The object links will specify the SAP object to which the document has been linked. The following table describes the key attributes and related SAP tables for the various SAP PLM Object types.

EMC Documentum Content Services for SAP A Detailed Review

15

Table 7. Key attributes and SAP Table related to the SAP Object types in WebAdmin SAP Object type in WebAdmin

Key attribute

SAP table

Asset Master Getlist PLM, Asset Master PLM

CompanyCode (length 4), Asset (length 12), SubNumber (length 4)

ANLA

Equipment by short text PLM

Equipment

EQUI

Functional location by text PLM

FunctionalLocation

IFLOT

Material by description PLM

Material

MARA

Customer Table PLM

Customer

KNA1

EKPO_Table PLM

Document_Number (max length 10), Item_Number (max length 5)

EKPO

Vendor Table PLM

Vendor (max length 10)

LFA1

WBS element PLM

InternalProjectItemNumber

PRPS

Note: “No object PLM” requires mapping for the DocumentNumber key attribute. Other key attributes, if not mapped, assume default values such as DocumentType=DRW, DocumentVersion=00, and DocumentPart=000. No object PLM creates only a DIR link and does not link it to any SAP object. The WBS element PLM contains the InternalProjectItemNumber key attribute, which creates an object link with the corresponding WBS Element. For detailed analysis, consider a business scenario of Material by description PLM. For creation of DIR, there are various variable parameters available (for example, DocumentType, DocumentNumber, DocumentVersion, DocumentPart, and Description). For the DIR, specify the following built-in parameters: 

DocumentNumber — SAP DIR number. For example: DocumentNumber=”%s”,r_object_id If it is not specified, the chronicle ID is used to define the document number.



DocumentDescription — Description attribute of DIR. For example: DocumentDescription=”%s”,object_name.

If it is not specified, the object_name is used by default. 

DocumentType — SAP document type. For example: DocumentType=”DOC” “DRW” is the default value.



DocumentVersion — An explicit numeric two-digit document version. “00” is the default value.



DocumentPart — A three-digit document part number can be specified. “000” is the default value.

The mapping assigned to the key attribute Material will determine the object link created at SAP.

EMC Documentum Content Services for SAP A Detailed Review

16

On successful execution of the CS SAP job: 

DIR will be created on SAP at the cv04n transaction.



Within DIR, there will be an object link specifying the Material object to which the document is linked.

On the Documentum side, a sap_link_relation entry is created with the following specifications: 

parent_id is the i_chronicle_id of the document being linked.



child_id is the r_object_id of the document being linked.



effective_date is the date of creation of the link (with a timestamp as 12:00

AM for the 6.5 SP3 version of Content Server and 12:00 AM+ GMT timezone for the 6.5 SP2 version of Content Server). 

description by default as object_name of the document being linked.



sap_object_key is set as the value of

@@@. 

sap_doc_id is set as the value of DCTM. This sap_doc_id is the DRL value passed from SAP to Documentum, to open the linked document by reading values from sap_link_relation.



sap_exclusive_link is set to 1, which is a relation between the DIR and the dctm object.

Note: The Link Documentum job of PLM types does not validate if the object links are valid at SAP. This is not a limitation, but the basic underlying implementation principle. To view the linked document: 1. Navigate to transaction mm03 and search for the material. 2. Navigate to Additional Data and click the Document data tab. This will provide the list of documents linked to the specific MARA object. 3. Double-click on any Linked Document to launch the cv04n transaction, which provides details of the DIR. Another configuration that is available for a Link Documentum action and can be used for PLM types is Binding Rules, which includes Format Binding and Version Binding. Format binding This controls the a_content_type of the document being released to SAP. In sap_link_relation, the attribute sap_format_binding will have values as per the format configured in the Link Documentum action. The default value is “Best Format”, which means that the specified format of the document is well supported. This scenario becomes relevant when you have a rendition document imported for the document to be linked. For example, *.gif will have rendition documents such as *.tiff, *.jpeg. If the format specified in the Format Binding rules is JPEG, then the

EMC Documentum Content Services for SAP A Detailed Review

17

document released to SAP will be in the *.jpeg format. The sap_link_relation table entry will have JPEG as the value for sap_format_binding. Version binding This controls the version of the document being released to SAP. In sap_link_relation, the attribute child_label will have values as per the version configured in the Link Documentum action. Consider a case where you have version 1.0 as the parent. A minor of that document is versioned to 1.1 and the DRAFT or APPROVED label is applied, after which the job is executed against this version. After execution of the job, increment the version to 1.2; the default label will be set to CURRENT. The following will be the result of execution of the job with the various version binding options: 

dms_selected_version: This is the default setting, by means of which only the specific version of the document is linked during execution. So as per the case above, if version 1.1 of the document is linked, any version changes made to the document will not be visible from SAP and version 1.1 of the document will be opened when viewed from SAP. The sap_link_relation will have parent_id = and child_id = .



dms_all_versions: In this case, when you attempt to open the document from SAP, the entire version list, that is, 1.0, 1.1, and 1.2 versions of the documents, will be displayed in DmView. The sap_link_relation will have both parent_id and child_id set to .



CURRENT: As per the case above, though the job is executed for version 1.1, the document that opens is the version that displays CURRENT as the label, that is, 1.2 in this case. The sap_link_relation will have both the parent_id and child_id set to and child_label set to CURRENT. Note that no two versions of the document can have the label as CURRENT. Only the latest version will be marked as CURRENT.



DRAFT/APPROVED: As per the case above, version 1.1 opens up through dmview when you attempt to access the document from SAP GUI. The sap_link_relation will have both parent_id and child_id set to , and child_label set to DRAFT or APPROVED. Note that no two versions of the document can have the label DRAFT or APPROVED. Only the latest version is marked as CURRENT. So the label DRAFT or APPROVED would be applied when version 1.1 was CURRENT. Since the version is incremented to 1.2 CURRENT, applying the label DRAFT or APPROVED to 1.2 will remove the same from version 1.1.

Inherit links This option is relevant when you require to carry forward the object links from the previous version of the document to the next version. An example is a job that was executed to link document version 1.0 to Material P-100. Now, increment the version of the document to 1.1, and define mapping as INHERIT_LINKS=1 and Material to be

EMC Documentum Content Services for SAP A Detailed Review

18

linked to P-101. As INHERIT_LINKS is set to 1, version 1.1 will be linked to P-100 as well as the new object link, that is, P-101. sap_object_type_workflow The out-of-the-box object model for the Image Assign SAP workflow contains sap_task as ARCHIV_PROCESS_RFC_INPUT. Execution of this job creates a work item in the Inbox of the SAP user and does not trigger a workflow. The sap_container is defined, which contains the set of parameters to be passed to SAP during the job execution workflow. The syntax is =. There is a special attribute DRL that needs to be specified as Drl=ARC_DOC_ID in sap_container. Note: The variable name must be set to “Drl”, the sap container definition should be set to Drl=ARC_DOC_ID, and mapping must be set to key.Drl=”%s”,Drl. Custom types can be created using the dmei_custom_installer tool of type sap_object_type_workflow with sap_task as the task numbers in SAP, for example, TS00007869. Except ARCHIV_PROCESS_RFCINPUT, if there are any custom RFCs like ZARCHIV_PROCESS_RFCINPUT or custom tasks like TS00007869, CS SAP invokes the SAP_WAPI_START_WORKFLOW BAPI and passes the custom RFC/ BAPI as an import parameter to this BAPI. Presently, CS SAP does not differentiate custom RFCs with custom tasks and considers any custom sap_task in the Image Assign SAP Workflow to trigger a workflow. ARCHIV_PROCESS_RFC_INPUT expects four mandatory parameters: ARCHIV_ID, DOC_TYPE (Object type), AR_OBJECT (document type), and ARC_DOC_ID (DRL in the format :/DCTM) to the structure DOCUMENT_ENTRY in SAP. The work item title takes the value of the description of DocumentType in SAP configured in the oac2 transaction. Configuration for incoming workflow at SAP 1. Set the content repository and doctype. Execute the following transactions from the SAP GUI: oac0 - Create a content repository (do not specify any protocol) An example is Content Rep = SI (the same archive configuration should be created at CS SAP Webadmin ArchiveLink > Archive). Test the connection from SAP GUI to the content repository and send the certificate. oac2 - Create a document type for an incoming invoice, say, FAX An example is doctype=ZNJ_SI_IIN, descr= incoming invoice, Doc. class=FAX. oac3 - Define the link to the content repository An example is Object type = BKPF, document type = ZNJ_SI_IIN (Document type created by oac2), Link status =X, Storage System = SI (Content repository created by oac0),link/Relationship=TOA01).

EMC Documentum Content Services for SAP A Detailed Review

19

oack - Check the customization (optional) 2. Complete the workflow settings. soa0 - Assign Workflow Document Types An example is Document type=, Object type= BKPF, task=TS00007869 method=CREATE oaca - Workflow parameter definition An example is Document type= , Parameter=TRANSACTIONCODE, Content=FB10 oaws - Configure workflow action items (create an entry in DCM1) An example is doctype=>, Ob=US agentID=, check "storing for subsequent entry" "store and enter", "assign and then Store" oag1 - enable ECLViewer (if required) 3. Create the archive in CS SAP. From the CS SAP WebAdmin, proceed as follows: i. Select ArchiveLink > Repositories. ii. Create a repository configuration and activate the certificate at ArchiveLink > Certificates. iii. Create an archive with the same name as the repository created in SAP using the oac0 transaction. Note: The AS SAP application should be running. 4. Configure CS SAP. i.

Create the Documentum query.

ii.

Create the Link Documentum action with the SAP Object type Image Assign Workflow. Map rules: o key.DocumentType = o key.ObjectType=BKPF o key.ArchiveID= o key.Drl= “%s”,Drl

iii.

Create the agent for this action for the SAP system that you configured.

iv.

Create the job for this agent.

EMC Documentum Content Services for SAP A Detailed Review

20

v.

Execute the job.

5. Check the workflow items in the Inbox. i.

Execute the transaction sbwp from the SAP GUI.

ii.

Navigate to the Inbox. The work item appears in the workflow.

iii.

Click the ArchiveLink link in the right corner below to open the linked document from the repository using the AS SAP get request.

The sap_link_relation created will have the following values: 

sap_object_type set as Sap Workflow



sap_doc_id as the DRL value



parent id as the i_chronicle_id of the document being linked



child_id as the r_object_id of the document being linked

The sap_container definition for sap_task TS0007869 will be set as follows: 

ObjectType=DOC_TYPE



DocumentType=DOCUMENTTYPE



Description=DESCRIPTION



DocumentClass=DOCUMENTCLASS



ArchiveId=ARCHIV_ID



Drl=ARC_DOC_ID

sap_object_type_barcode This creates a barcode entry in SAP. The barcode is created as an external barcode at the oam1 transaction. The following is an example of creating a barcode action configuration. 1. In the CS SAP WebAdmin, select ArchiveLink > Archive. Create an archive configuration with the following settings: 

Archive Name: Barcode 4.5(BQ)



Archive ID: BQ



SAP Document Type: FAX (Tiff)



Documentum Type: sap_incoming_invoice

EMC Documentum Content Services for SAP A Detailed Review

21



Map Rules: FOLDER=”/SAP/Archive/BQ” and a_content_type=tiff will get added automatically when the user clicks OK to save.

2. Create the same corresponding Content Repository configuration on the SAP system using the transaction oac0. 3. Ensure that AS SAP is running. Click Test Connection on the SAP system. 4. Import a .tiff image and save EMC.tif into the repository using DA. 5. From WebAdmin, select Documentum > Query. Create a query, for example, r_object_id, object_name, r_creation_date from dm_document where folder ('/Temp/test') and object_name='EMC.tif'. 6. Create a Link Documentum action with the following parameters: 

SAP Object Type: Barcode SAP 4.5



Documentum Query: Query name created in step 5



Format: Best Format



Version: dms_selected_version (default)



MAP RULES: i.

key.Barcode=”%s”, object_name

ii.

key.ContentRepository=”BQ”

iii.

key.Drl=”%s”, Drl

iv.

key.ArchiveDate=”%s”, r_creation_date

v.

key.DocumentClass=FAX

7. Select Auto Manage > Agent and configure the agent on the required server. Select the appropriate user configuration for the job to run. 8. From the SAP system, execute the transaction oam1. For barcodes, click Display all Barcodes (spectacle icon). 9. Click Execute. 10. Click the Display Document button or press F5.

Replicate Documentum The DIRs created by Link Documentum can be updated by running a Replicate Documentum job. You can choose to either update an existing DIR or create a new DIR. In the Action configuration screen, configure the following:

SAP Object Type — Create/update SAP objects of the type specified here. Object Key — This rule verifies if the object exists in SAP. If the update object checkbox is selected, this indicates that the SAP object will only be updated if the conditions are met as specified in Update Conditions.

EMC Documentum Content Services for SAP A Detailed Review

22

Map Rules — Mapping used to create/update DIR attributes in SAP. Replicate Documentum action configurations are of the type sap_action_link_dctm_data and saved at /System/DocLink/SAP/Action in the Documentum repository. You must create or update the DIR metadata at SAP using Replicate Documentum so that the SAP Object type available is Document Info Record PLM. Proceed as follows when this Replicate Documentum is called: 1. Check the rules parameter In this step, all checks are performed. Some are related to validating the user input with the data model, ensuring that mandatory parameters like the object key are specified. 2. Execute the DCTM query The DCTM query is executed and the action handler is executed for every DCTM object found. For each object, apply the mapping rules to find the related SAP object. 3. Check the “create object” flag If “create object” is enabled, the action handler attempts to find an object in SAP where the key attribute defined matches the associated Documentum attribute. If there is no match, a new object of the specified configured type is created. The attribute values of the new SAP objects are determined by the mapping rules. Essentially, the values returned by the DCTM query are assigned to the new SAP objects. If an update condition is also configured, the update does not occur. 4. Check the update flag If the object exists or if the “create object” flag is not set, and an update condition is configured and update object is enabled, verify if the condition matches. If it matches, the existing attribute map must be applied to the SAP object.

Link SAP This configuration object of type sap_action_link_query saved at /System/DocLink/SAP/Action specifies several parameters that can be customized to link SAP objects to dynamic parameterized Documentum queries. The following can be configured in the Action configuration screen: The SAP Query that returns the SAP objects. The Documentum query that returns the documents to be linked to each of the SAP objects returned by the SAP Query. $ARG parameters are passed to the DQL at runtime. The Map Rules that determine the linking of the Documents in the repository against the SAP objects returned by the SAP Query.

EMC Documentum Content Services for SAP A Detailed Review

23

Documentum

Read Agent and action configuration

Execute SAP Query associated with the action

Reads map rules to identify SAP object linked to DCTM Query and forms request value map for DIR

Yes

sap_link_relation exists?

Exit with NOOP message

No Create 2 sap_link_relation; with DIR and object link metadata

SAP Invokes BAPI_DOCUMENT_CREATE

Establishes JCO connection to SAP Server Creates DIR link and links it to SAP object

Figure 3. Functional flow for Link SAP execution

EMC Documentum Content Services for SAP A Detailed Review

24

Proceed as follows when Link SAP is called: 1. Check the rules parameter Checks related to validating the user input with the data model are implemented, ensuring that mandatory parameters like the object key that are specified are performed. 2. Execute the SAP Query The SAP Query is executed and the action handler is executed for every SAP object found. All SAP object attributes are passed to the action handler. 3. Check the relation object Check if the relation object (sap_link_relation) exists for the particular Documentum object being linked. The handler verifies if the object is already linked. A DIR is created in SAP if a link for this document does not exist. If a link exists, the link is verified in case the “verify object links” flag is set. If the flag is not set, the SAP object is ignored and the next one is processed. If the “verify object links” flag is set, then the following are the possible scenarios: 

Both relation objects will be deleted if the DIR does not exist in SAP, but the relation objects exist. Relation objects are those that are specific to the DIR and business object link. During the next run of the agent, the relation object and relevant DIR will be created.



An error message will be displayed if the relation object does not exist, but DIR exists.



If new links are specified in the action rules, they will be added to the existing DIR. Existing links are retained as is in the DIR.



If both the DIR and relation object does not exist, nothing will be changed.

4. Create a link If not already linked, create the DIR, link it to the SAP object, and create the sap_link_relation object. During DIR creation, the field values must be calculated based on the mapping rules (as in “Link Documentum”). The documents to be linked are based on the query parameter associated with the action. The query object is of the type dm_query and may contain parameters such as “$ARG1”, ..., “$ARGn”. The variables will then be replaced when the query is executed. The following is an example of a Documentum query: select r_object_id,object_name from dm_document where folder('/Temp/test') and any keywords='$ARG1' During the execution, the $ARG1 is replaced with the parameter returned from the SAP query. Consider that the mapping is configured such that $ARG1 is mapped

EMC Documentum Content Services for SAP A Detailed Review

25

to Material. Then, for each material number returned by the SAP query, the Documentum query will be constructed by replacing $ARG1 with the material number. For example, the above mentioned Documentum query will be: select r_object_id,object_name from dm_document where folder('/Temp/test') and any keywords=’I-1100’ In this example I-1100 is one of the material numbers. The other mapping attributes are:

DocumentNumber — If mapping is not specified, it is defaulted to an auto-

generated number at SAP during DIR creation. Checking the “verify object link” flag can be used to avoid duplicity of links.

DocumentDescription — Description attribute of DIR at SAP. DocumentType — By default, DocumentType assumes the value DRW at SAP. The new document types can be created at SAP through dc10 transaction. On the Documentum side: Two sap_link_relation entries are created. 

One for DIR link with the following attributes: o parent_id and child_id equal to the r_object_id of the Documentum query o child_label set to CURRENT o effective_date will be date of creation of the link with the timestamp as 12:00 AM o description will be object_name of Documentum query o sap_object_type as Document info record o sap_object_key as @@@ HVPS. This follows the concept that multiple objects of HVP Worker are actually being created in the repository for a single instance of HVP Worker running on an application server. This will spawn multiple threads of HVP Worker and will behave similar to multiple HVP Workers deployed for different instances of application servers. Note: There is an issue when you try to register the same worker URL using File > New > Register HVP Worker in WebAdmin. As a workaround, register workers with a dummy URL and then edit them back to the same valid URL using the Properties option. The following is the procedure when a job is executed: 1. A dm_hvp_job object (log file) is created and the method server logs the build information of HVP Controller (hvps.dar) and doclink (EI Core DAR) in the controller log. 2. The request parameters like docbase_name, user_name, module_name (com.emc.hvp.control.job.impl.HvpController), job_id, agent_name, and method_trace_level are read and execution of the method starts. 3. The action name from the agent and the action_type as sap_action_link_doc_object for Link Documentum, sap_action_link_dctm_data for Replicate Documentum, sap_action_link_query for Link SAP, and sap_action_link_sap_data for Replicate SAP are read. 4. Based on action type, the activity definition is processed and the activity name is set as LinkDctmActivity or LinkSapActivity, and so on. 5. Controller reads the dm_hvp_worker objects registered and sends a request to one of the available workers and sets that worker availability to FALSE.

EMC Documentum Content Services for SAP A Detailed Review

29

6. Controller receives the response from the worker as “success” or “failure” and this completes processing of the request. Controller sets the worker availability to TRUE. When HVP Worker receives a request from controller it: Logs the worker build information into the activity log file. Loads the task definition and starts processing of activity definition. Reads the agent configuration from the agent and identifies the type of action. Reads the action configuration and obtains SAP server and SAP user information from the agent configuration. Forms a request value map based on map rules and default values. Establishes a connection with the SAP server via the JCo library. Verifies if sap_link_relation exists; if not, then it executes the relevant functional module/BAPI as per the SAP Object type in the action configuration. Creates a DIR or link. Uploads the log file to the repository. Places the HVP Worker back into the available pool. Disconnects from the SAP server and return the success or failure message to the HVP Controller.

Jobs One or more agents can be associated to a CS SAP job and scheduled accordingly. The CS SAP jobs are dm_jobs created in the /Administrator folder (actually the home cabinet of the repository user). From there it is picked up automatically by the job manager. The name of the method used is as follows: “com.documentum.ei.doclink.agentJob.DmeiSapAgent” When the job is executed, a trace file is written to the folder “/System/HVPS/JOBS”. The trace files are not versioned. All trace files will be viewed as 1.0 CURRENT. The normal log information includes the following information: 

Software version and build number



Rules



SAP server and repository



Errors and warnings



End of operation information with time stamp

The dm_LogPurge job will not remove the items in Cabinet/System/HVPS/JOBS as it is a Content Server-specific tool and not associated with CS SAP jobs. From 6.5 SP3 onward, if you delete the CS SAP object from WebAdmin, the relevant log files will be deleted from the repository automatically.

EMC Documentum Content Services for SAP A Detailed Review

30

The Trace Level specified in the job configuration by WebAdmin has no relevance. The trace level details depend on the log levels set in the hvp.properties of the HVP Controller and HVP Worker. Set hvp.log.level=DEBUG in hvp.properties for detailed log information. Until 6.5 SP2, it was not mandatory to have the hvp.properties file configured on the Content Server machine. If the hvp.properties file was absent, the default log path would be C:\Documentum. Starting with CS SAP 6.5 SP3, the setting of the DOCUMENTUM environment variable needs to be validated and you must ensure that the hvp.properties is present at the DOCUMENTUM environment variable path. The job logs created in the file system depend on the absolute path set for hvp.log.base in the hvp.properties file. The log file that is generated is created in the “job name” folder. On restarting the method server or application server, the activity logs are cleared from the file system. An hvps base directory (.hvps) is created on the Content Server machine and hvp worker machine at {user-home} containing activitycontextids and work folders. In Windows, the location is C:\Document and Settings\Administrator\.hvps. This hvps base directory path is configurable by adding –Dhvps.base= to the JAVA_OPTS setting of application server. Setting a job to the “Active” state implies that the job would run as per the schedule. If you require running the job on-demand or manually, set it to “Inactive”. A job can be scheduled to start on a defined date (Activation Date) and to expire on a defined date (Expiration Date). The format of the date is “day, month, year” and the format of the time is “hours: minutes: seconds”. Note: For additional troubleshooting in case of job failures, refer to the “Troubleshooting” section in the EMC Documentum Content Services for SAP Administration Guide.

Configuring View DmView DmView is the client software for CS SAP. DmView enables you to view the content stored in Documentum from SAP. DmView can be launched from SAP. DmView also integrates with WebTop and WebView. Both WebTop and WebView are launched by DmView. Users can only edit the content if WebTop integration is used. Functional flow in DmView DmView receives the request from SAP as a DRL to display content. This DRL can be used to locate and deliver content from the repository. DmView uses the DMCL client library to interact with the repository. To call WebTop from DmView, the WebTop application requires a URL to be built with the following information:

EMC Documentum Content Services for SAP A Detailed Review

31

Ticket — Ticket information, which is a function of the session ID. Username — Username for the repository. ObjectId — ObjectId is a parameter used to identify the document being requested.

Format — The format of the document. It is used to launch the correct viewer. The view component can be configured from CS SAP WebAdmin at Clients > View > DocLink Viewer Configuration. For details, refer to the EMC Documentum Content Services for SAP Administration Guide.

Conclusion Customers can leverage EMC Documentum Content Services for SAP for linking documents in Documentum to various SAP objects as explained in this white paper.

EMC Documentum Content Services for SAP A Detailed Review

32