SEEBURGER SAP XI Adapter Archiving Module User Guide

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Contents
Contents........................................................................................................................... ...............2 Icons........................................................................................................................................ ........3 Overview................................................................................................................................... ..........4 Purpose............................................................................................................................ ...............4 Implementation Considerations...................................................................................... .................4 Integration............................................................................................................ ...........................4 Features..................................................................................................................... .....................4 Operating Mode................................................................................................................ ..................5 Terminology................................................................................................................................ .....5 System Overview........................................................................................................................... ..6 The Archiving Procedure.................................................................................................. ...............7 Installation.................................................................................................................................... .....12 Overview............................................................................................................ ...........................12 Prerequisites.................................................................................................................................. 12 Procedure............................................................................................................................ ..........12 Result........................................................................................................................ ....................16 Configuration.................................................................................................................................... .17 User Administration.................................................................................................... ...................17 Archiving Job..................................................................................................................... ............18 FileStore Module................................................................................................... ........................18 Reorganization Job...................................................................................................................... ..20 Metadata Enrichment............................................................................................................... .........21 SEEBURGER BIC 1:1-Mapping.................................................................................. ..................21 SAP XI Message Mappings................................................................................................ ...........23 Sample Scenarios..................................................................................................................... ........24 Reception and Archiving of an ANSI Message.................................................................. ............24 Reception and Archiving of an EDIFACT Message with Split.................................................. ......28 Sending a VDA Message................................................................................... ...........................44 Appendix................................................................................................................................ ...........48 Available Metadata Attributes............................................................................................ ............48 Example: User-defined Function for SAP XI Mapping..................................................... ..............49

Page 2

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Icons
Symbol Description Warning Component Example Function Note Recommendation Syntax

Page 3

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Overview
Purpose
The SEEBURGER Archiving module enables users to save documents as files that have been transmitted in an XI message, allocate metadata to them and export them to an external archiving system.

Implementation Considerations
A file system interface for importing documents is required for the integration of external archiving systems over the SEEBURGER archiving module. The SEEBURGER archiving module saves all documents that are to be archived on file system level. The documents are deposited in the following system directory: /usr/sap/<SAPSID>/SYS/global/seeburger/filestore where <SAPSID> denotes the SAP System-ID. It must be ensured that all instances of the SAP Web Application Server have access to this directory, if the XI-system has been installed in a cluster-environment. Please take note that this directory is considered in the back-up strategy. The database user MUST NOT be set to UNICODE!

Integration
The SEEBURGER archiving module is comprised of several components: an XI-module based on the SAP XI Adapter Framework (FileStore-module), a web-frontend for configuring and monitoring, which is integrated in the SEEBURGER workbench, as well as an extended instruction set for the SEEBURGER BIC.

Features
Saving and Archiving of documents that are transmitted within XI-messages Random document format (XML, EDI, binary etc.) Annotation of documents with metadata with the aid of mappings that are executed in the SAP XI Mapper or in the SEEBURGER BIC Definition of dependencies between documents, so that documents and logical processes are archived congruently and completely Generic integration of archiving systems (requirement: file system interface) Integration of several simultaneously operating archive systems

Page 4

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Operating Mode
Terminology
XI-Message An XI-message ist he underlying transmission unit of the XI-transport protocol. An XI-message consists of a message header, forwarding and other technical information, as well as one or more attachments. Attachment An XI-message contains one or several attachments as the carriers of the payload and other information relevant for the business process. Attachments may contain random binary data. One of the attachments can be tagged as the messages main attachment and thus, as the carrier of the actual business document. Main Attachment One of the attachments of an XI-message can be tagged as the messages main attachment and thus, as the carrier of the actual business document. The main attachment is always presented in XML. The XI Integration Engine can only process the main attachment. Document Documents are the primary objects that underlie archiving by the SEEBURGER-Archiving module. They are the result of the generation and processing of XI-messages by the adapter and modules within the XI Adapter Framework. Examples of documents are: the protocol-specific message, as received by the partner the extracted business document in a standard EDI-format the result of the conversion into XML the separate document fragments resulting from a document-split conversion and split protocols etc.

These documents can be packed into the attachments of an XI-message for transport and further processing. In contrast to this, the FileStore-module of the SEEBURER-Archiving module retrieves a document of an XI-messages attachment, in order to deposit it into the operational file-store of the SEEBURGER Archiving module. Documents are uniquely identified over the XI-messages ID and the document ID that is unique to the document within context of the XI-message and is assigned durig the configuration of the FileStore module.

Page 5

SEEBURGER SAP XI Adapter Archiving Module, User Guide

System Overview
The most important components of the SEEBURGER Archiving module are described, as they appear in the illustration, in the following section.

Operational File Store The operational file-store serves as a temporary store for documents, so that they can be annotated with metadata and processed for the long-term archiving. In addition to this, documents within the filestore and their metadata can be searched, viewed and downloaded over the web frontend. Metadata Store The metadata store serves for the annotation of saved documents with metadata and for defining relations between documents. The data is deposited in the SAP-systems database. FileStore-Module The FileStore-module is a module in the sense of the XI Adapter Framework. As such, it can be used in the sender or receiver channels. It is responsible for saving documents to the operational file store and writing the appropriate metadata into the metadata store of the archiving system. The FileStore-module can save a document from exactly one attachment of the passing XI-message. The according instances of the FileStore-module have to be used, if several attachments are to be saved. Web-Frontend The SEEBURGER Archiving Module can be configured over the web-frontend. In addition it provides functions for searching, monitoring and displaying documents contained in the file store and their metadata. Archiving Job (Archiver) The archiving job is an independently running background process that undertakes the export of the documents from the file store into the external archiving system. External Archive-System This is a third party software-system for long-term archiving of documents. Page 6

SEEBURGER SAP XI Adapter Archiving Module, User Guide

The Archiving Procedure

Archiving the documents occurs in two steps: 1. Buffering: depositing the documents in the operational file-store and writing the metadata 2. Exporting: a control file is generated for the archive system and the documents are exported from the file-store into the archive systems file system interface While the first step runs synchronously with the XI systems processing of the messages, exporting is asynchronously executed by a background job of the archiving module. Both steps and their according processes are described in more detail in the following section.

Buffering the Documents

File Store Deposit The documents are deposited in the operational file store with the aid of the FileStore-module. The following module parameters have to be set for this: attachmentName: Name of the XI-messages attachment, from which the document is to be read documentID: The unique document ID within the context of the XI-message

The module generates a unique ID fort he document, under which it is deposited in the operational file store, from the XI-messageID and the documentID. Furthermore the FileStore-module writes the following information to the metadata store: Direction (XI-messages direction: sender channel (IN) or receiver channel (OUT)) Timestamp (time-stamp of deposit in the file store) Document Type (value of optional module parameter documentType, default is unknown) Archiving Status (value of optional module parameter archivingStatus, default is NONE; see below) Archiving System (value of optional module parameter archivingSystem)

Writing Additional Metadata Documents can be annotated with additional metadata in the file store. This can either occur over SAP XI-mappings or SEEBURGER BIC-mappings. SEEBURGERs BIC module disposes over an according command set for writing data sets into the metadata database. An equivalent Java-API is available for the SAP XI-mappings. Archiving Status Each document in the operational file store possesses an archiving status, which can be changed over the archivingStatus parameter of the FileStore module. The following values can be set: NONE: No archiving READY: Document is ready for archiving PENDING: Document is to be archived, but is not ready yet

The PENDING status is set, e.g., when additional metadata is to be written over a mapping to a document in the file store. In this case, after the metadata have been completely written, an additional instance of the FileStore-module will set the document to READY. Beyond this, differentiating between READY and PENDING plays a role for the structuring of tree structures (see the next section). If the archiving status is set to READY or PENDING, then in addition, the archive system has to be specified over the module parameter archivingSystem

Page 7

SEEBURGER SAP XI Adapter Archiving Module, User Guide Defining Document Relations Logically coherent documents can be grouped with the definition of hierarchical relationships. By specifying a parent document during the configuration of the FileStore module, a tree structure will be structured successively. The export of the documents into the archive system can be controlled over this grouping, as the documents of a tree can only be exported, after the tree structure has been generated. The result of this is that logically coherent documents are archived completely and together. The parent document is set with the following module parameter: parentID (parent documents document ID)

If the child document is read from an XI-message that has been generated by a document split with the SEEBURGER Messagesplitter module, then the module parameter parentLocation

has to be set to external. Completed Document Trees Documents designated for archiving are first exported into the archive system, if the document tree structure containing them has been completed. A document tree has been completed, when all contained documents either have the NONE or READY status and the number of child documents coincides with the value of the ExpectedChildren attribute. Every document in the file store possesses the metadata attribute ExpectedChildren. This is a counter that is automatically incremented, when its document ID is used as the parent attribute of another document in a mapping or by the FileStore-module. Automatic incrementation can be suppressed by setting the FileStore-module parameter suppressChildCount

to true. The counter is also increased, if the SEEBURGER BIC-module is used in the split mode and the parameter xiDocumentID

is set. In this case the counter of the document specified in xiDocumentID is increased by the number of attachments generated by the BIC-module. Message-Split If the SEEBURGER BIC-Modul isbeing used in split-mode (together with the SEEBURGER MessageSplitter-Modul) and a parent/child relation is to be established between the origiinal document and the document that resulted from the split, then the following special features apply fort he mechanisms described in the previous section: The additional parameter xiDocumentID must be set on the document ID of the original document for the BIC-module It is compulsory to use at least one FileStore-module, which will establish a relationship to the original document (i.e. parentID has been set and parentLocation = external), in all sender channels of the child messages generated by the SEEBURGER MessageSplitter-module The module parameter o suppressChildCount must be set to true in the first FileStore-module in the mentioned sender channels establishing a relation to the original document.

Exporting Documents
The actual export of the documents into the external archive system occurs over a background job, which is carried out independently in periodic intervals of the filling of the data store and the metadata store. Page 8

SEEBURGER SAP XI Adapter Archiving Module, User Guide This job searches through the metadata store for documents designated for archiving. Separate documents are not regarded, but complete ones are (where a tree may also consist of a single document). The documents contained in a document tree are sorted by the archive system, into which they are to be exported. During further processing of the archive-system-specific document lists there is a distinction for the archiving mode of the archive systems between: single or group mode. Single Mode In single mode each document is handed over to the archive system separately over the file system interface. The procedure is as follows: (1) The archive system-specific control files for each document are generated by executing the configured SEEBURGER BIC-mappings that are located in the web-GUI under Archiving Configuration Document Types. (2) The configured pre-export script file is executed under Archiving Configuration Archiving Systems (3) The export script configured under Archiving Configuration Document Types is executed for each document (that, e.g., hands over the document and the generated control file to the file system interface of the archive system) (4) The post-export script file configured under Archiving Configuration Document Types is executed.

Group Mode All documents designated for the archive system are handed over to the archive system together and with a mutual control file in group mode. The procedure is as follows: (1) The mutual control file is generated by executing the SEEBURGER BIC-mappings configured under Archiving Configuration Archiving Systems in the web-GUI. (2) The pre-export script file configured under Archiving Configuration Archiving Systems is executed (3) The export script file configured under Archiving Configuration Document Types is executed for each document (4) The post-export script file configured under Archiving Configuration Archiving Systems is executed.

Page 9

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Generating the Control File The format of the control file is determined by the archive system. Above all they contain index information, under which the documents can be searched in the archive system. The control files are generated with the aid of SEEBURGER BIC-mappings. These mappings can access the document designated for archiving, as well as the data in the metadata store. The following parameters are handed over to the mapping: Parameter Name ArchivingRecordCount ArchivingRecordId0 ... ArchivingRecordId<N> Description Number of documents designated for archiving Document IDs of documents designated for archiving, where <N> is the number specified in ArchivingRecordCount Document contents

srcContent

In single mode ArchivingRecordCount has the value 1 and the Document ID of the document designated for archiving is handed over with ArchivingRecord0. The parameter srcContent contains the document designated for archiving itself in single mode. The document is contained in the root of the document tree in group mode. Additional parameters can be configured under Archiving Configuration Archiving Systems bzw. Archiving Configuration Document Types in the Mapping Parameters field. The format of the string that has to be entered here is: <key1>=<value1>; <key2>=<value2>; (no concluding semi-colon) Scripts Any application which can also be started from the operating systems command line can be specified as pre-export, export and post-export script files. We recommend using script files in a suitable script language, e.g., UNIX shell scripts. Command line arguments can be configured, so that generically parameterised scripts can be generated. The handing over of data between archiving module and script occurs over environment variables. In principle the scripts are executed in one of two modes, which is defined over the ARCHIVING_SCRIPTMODE environment variable. The modes PREEXPORT, EXPORT and POSTEXPORT correspond to the normal case, i.e. the preparation and export into the archive system. The script is carried out in the ERROR mode, in case an error has occurred after the script was executed. In this case the script is executed again, so that it has the opportunity to clean up (e.g. deleting existing files and directories).

Page 10

SEEBURGER SAP XI Adapter Archiving Module, User Guide The value of the ARCHIVING_ID environment variable is the same for all script calls required for the processing of the document tree. This provides the possibility of, e.g. creating temporary files and directories that contain this ID and therefore can be employed beyond the scripts limits, i.e. by the pre-export and post-export scripts. The following environment variables are set during the call of the scripts: Pre-Export-Script Variable Name ARCHIVING_SCRIPTMODE ARCHIVING_ID Export-Script Variable Name ARCHIVING_SCRIPTMODE ARCHIVING_ID ARCHIVING_FILE Description Possible values: EXPORT, ERROR Unique ID Path of file designated for archiving Description Possible values: PREEXPORT, ERROR Unique ID

ARCHIVING_CONTROLFILE Path of the control file (only in single mode) Post-Export-Skript Variable Name ARCHIVING_SCRIPTMODE ARCHIVING_ID Description Possible values: POSTEXPORT, ERROR Unique ID

ARCHIVING_CONTROLFILE Path of the control file (only in group mode)

Page 11

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Installation
Overview
The installation of the archiving solution is comprised of the following steps, which are described in more detail in the following sections: 1. Preparation of the database: creating a user 2. Database installation and import of the initial files with the aid of a separate installation program 3. Creating a database connection in the SAP J2EE Engine with the aid of the Visual Administrator 4. Installation of the web-frontend (to trace messages and configuration of the archive systems) and the File Store-module ((integrating the archiving solution into the XI adapter channel): SeeXIMessageArchiving.sca 5. Installation of the SEEBURGER Workbench (central point of entry for all SEEBURGER GUIs): SeeXIWorkbench.sda

Prerequisites
The following files are required for the installation: install_ArchivingModule_XI_<OS>.bin (UNIX) or install_ArchivingModule_XI_Win32.exe (Windows) respectively SmartiDS_<DBMS>.xml SeeXIMessageArchiving.sca SeeXIWorkbench.sda The following information is required for the DBMS: Product in use (Oracle, Microsoft SQL Server or MaxDB) DBMS-Server and Port Path to a suitable JDBC-driver, if the available standard drivers are not suitable

Procedure
(1) Preparation of the Database We recommend using the same database as used by the XI-system (The database name usually coincides with the SAP System-ID). A new user called SEEMTDB has to be created for this database. As this is specific to the employed DBMS, we will not go any further at this point. The user must possess the rights to create and alter tables, views and indices within his database schema. Additionally the user MUST NOT be set to UNICODE! (2) Installation of Database Tables A separate installation program is used for filling the database. This is located on the installation CDROM under:
data/MessageArchiving/DBInstallation/install_ArchivingModule_XI_<OS>.bin (UNIX) or data/MessageArchiving/DBInstallation/install_ArchivingModule_XI_Win32.exe (Windows) respectively.

Page 12

SEEBURGER SAP XI Adapter Archiving Module, User Guide The program must be started from the installation CD-ROM. It guides the user through various dialogues in the installation process. It will prompt for the name and password and the information, which was specified under Requirements of the user that was created under (1). After starting the installation program a selection between (german and english). Afterwards a short introduction follows.

Press Install and select your DBMS:

The database driver is specified in the next step. The standard driver is sufficient in most cases. Only specify an individual (your own) driver, if an error occurs with the standard driver. Page 13

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Caution: Should you have made a mistake during the selection of the database and clicked the Previous button, please be advised that the standard driver will not be refreshed. This can be corrected by clicking Restore Default File. Now specify the data and the database connection and utilise the user created under (1).

The Installation program will now create according tables and views. End the program by clicking done.

Page 14

SEEBURGER SAP XI Adapter Archiving Module, User Guide

(3) Configuring the Data Source in the SAP J2EE Engine The Visual Administrator of the SAP J2EE Engine is used to configure the data source. Proceed as follows: 1. Start the J2EE Engine Visual Administrator 2. Open the corresponding server node in the navigation tree 3. Select the node Services JDBC Connector 4. Select the node Resources DataSources on the Runtime tab 5. Press the key Import DataSources from XML in the toolbar ( ) and select one of the files SmartiDS_MaxDB.xml, SmartiDS_MSSQL.xml or SmartiDS_Oracle depending on the employed DBMS. These files are located on the installation CD-ROM under data/MessageArchiving/datasources 6. Customise the configuration parameters for the data source SmartiDS: Replace the values for the following parameters on the Main tab: Database URL (replace <hostname> and <database-name>) User (as created under (1)) Password (as created under (1)) )

7. Save the changes (

Note: Be sure that the data source parameters are correct. Also check whether the pre-set drivers and data source classes match the JDBC-driver used as the SYSTEM_DRIVER. Erroneously configured data sources lead to interferences in the SAP J2EE Engine.

Page 15

SEEBURGER SAP XI Adapter Archiving Module, User Guide (4) Installation of the Web-Front end and the File Store-Module Install the web-frontend for the configuration and display of the archived messages and the File StoreModule for use in the XI adapter channels. For this deploy the file SeeXIMessageArchiving.sca with the SAP Software Deployment Manager (SDM). (5) Installation of the SEEBURGER Workbench If not yet available, install the SEEBURGER Workbench. The SEEBURGER Workbench contains links to all SEEBURGER web-applications. Deploy the file SeeXIWorkbench.sda with the SAP Software Deployment Manager (SDM).

Result
After successful installation, the configuration of the archiving solution may now follow. This is comprised of creating users, configuring the archiving job and using the FileStore-module in the adapter channels. The web frontend can be started from the Archiving link in the SEEBURGER Workbench which can be accessed at http://<host>:<port>/seeburger where <host> and <port> are the hostname and TCP port of the J2EE engine.

Page 16

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Configuration
User Administration
Initial Users
The standard users xiuser and xiadmin can be used for work with the web frontend after installation: Name xiuser xiadmin Role XIUSER XIADMIN Initial Password xiuser xiadmin

After the first logon a new password has to be assigned.

Creating New Users

New users can be created by the xiadmin besides the initial users. Proceed as follows to do this: Logon as xiadmin Select Administration in the menu bar Select Users Create in the left menu Enter User ID, Login name and Password on the User details tab Select the user role on the User Roles tab

User Roles
The following roles can be assigned to the users: Role XIUSER Rights XIADMIN Search and view messages Change the archiving status of messages

Same rights as XIUSER and in addition: Creating and deleting users and role allocation Configuration of the archiving job Changing of runtime parameters Change of the execution plan of the background jobs Changing of the log settings

Page 17

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Archiving Job
The archiving job can be configured with the aid of the web-frontend under the menu option Archiving Configuration. Every document intended for archiving is archived in exactly one archive system. The way, in which the documents are prepared for archiving depends on the type of document and the employed archive system. Configuration parameters that only depend on the archive system are set in the Archiving Systems section, while parameters, which depend on the archive system, as well as the type of document are set in the Document Types section.

Archiving Systems
The following parameters can be set: Name Archiving System Archiving Mode Description Unique archive system name Archiving mode: Single: 0 Group: 1 Client ID Mapping Name Name of BIC-mapping for creating control file during group archiving Fixed value: 1 mandatory for group archiving, ignored otherwise Status mandatory mandatory

Pre-Script Pre-Script Arguments Post-Script Post-Script Arguments

Path to file, which is executed as optional the pre-export-script Command line arguments for the optional pre-export script Path to file, which is executed as optional the post-export-script Command line arguments for the optional post-export script

Document Types
The following parameters can be set: Name Archiving System Description Name of the archive system as defined under Archiving Systems Document Type (used e.g. by the document viewer) Name of BIC-mapping for creating the control file Path to file that is executed as the export-script Status mandatory

Client ID Document Type Mapping Name Script Script Arguments

Fixed value: 1 mandatory mandatory optional

Command line arguments for the optional export-script

FileStore Module
The FileStore-module can be used in sender and receiver channels. It can be used several times within one channel, even when the document ID is the same. We have to differentiate between two operational modes here: Page 18

SEEBURGER SAP XI Adapter Archiving Module, User Guide The first instance of the FileStore module in a module chain (referring to the same document ID) must first read the document from a message attachment and deposit it in the operational file store. The module parameter attachmentName must be set for this. This is the save-mode. Further instances referencing the same document ID do not require this parameter to be set. They work in the update-mode, in which only metadata attributes of the document are set and changed. This mode is used, e.g., for setting the attribute archivingStatus from PENDING to READY. The following module parameters exist for the FileStore-module: Name documentID Description In context of the XI-message unique document ID; Note: Valid characters: az, AZ, 0...9 (no spaces allowed) documentType parentID parentLocation Document Type Document ID of parent document Possible values: internal, external Must be set to external, if parent document was read from another XI-message attachmentName Name of message attachment, from which document is read (also see comment below) Possible values: NONE, READY, PENDING Archiving System (as configured in the web-frontend) Possible values: true, false Name of style sheet to be used by XSLT viewer *) File name extension for attachment if downloaded as file from the web-frontend (e.g. pdf, xml) Name of system client Mandatory (except if in UpdateMode) Optional (presetting: NONE) Mandatory if archivingStatus is set Optional (presetting: false) Optional Optional Optional (presetting: unknown) Optional Optional (presetting: internal) Status Mandatory

archivingStatus archivingSystem suppressChildCount styleSheet fileType

client
*)

Optional

The viewer components are only available with the SEEBURGER Message Tracking for SAP XI product. The style sheets for the XSLT viewer have to be placed in the directory /usr/sap/<SAPSID>/SYS/global/seeburger/filestore-xslt If no style sheet name is provided, the Form Viewer will be used to display the message. The value MainDocument must be specially treated for the module parameter attachmentName. In this case, the document will not be read from an attachment by this name, but will be read from the main attachment of the XI-message, which may have a different name.

Page 19

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Reorganization Job
The reorganization job runs periodically and deletes old documents from the metadata and filestore. A document is deleted if it has reached its maximum hold-back time and or all documents of the containing tree have reached the maximum hold-back time and have either the status NONE or ARCHIVED it is not part of a document tree, and its status is either NONE or ARCHIVED

The default hold-back time for documents is 180 days.

Changing the Hold-Back Time

The hold-back time for documents can be configured with the aid of the web-frontend: Logon as xiadmin Select Administration in the menu bar Select Custom Jobs | Overview in the left menu Select Reorganisation Click Next Change the value of the DAYS parameter by entering it into the first row of the parameter table

Page 20

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Metadata Enrichment
Note: Please note that the attributes cFree18 cFree20 are reserved for internal purposes and therefore must not be used.

SEEBURGER BIC 1:1-Mapping

The metadata of documents designated for archiving may be enriched by the 1:1-Mapping executed by the SEEBURGER BIC. The following parameters can be passed to the BIC mapping as BIC module parameters: Paramter Name archiveXI xiDocumentID mtPartner mtState Description true or false determines if metadata is written by mapping Document ID, corresponds to the DocumentID of the FileStore Module Partner as additional information in the Web Frontend Message status; possible values: mtSender mtReceiver mtInterface mtAdditional mtfree13 mtfree14 mtfree15 mtfree16 mtfree17 Depending on the message type the following metadata attributes are set automatically if the metadata enrichment is activated (parameter archiveXI is set to true): Sender(Message) Receiver(Message) Reference(Message) Timestamp(Message) Message Type SUCCESS PENDING ERROR

Sender, for input analogous to Partner. Receiver, for output analogous to Partner Corresponding message description in the Web Frontend Additional Information Freely usable metadata attributes

The attributes are read from the message as follows:

Page 21

SEEBURGER SAP XI Adapter Archiving Module, User Guide

ANSIX12
Meta-data Field Sender(Message) Receiver(Message) Reference(Message) Timestamp(Message) Message Field ISA:I06 ISA:I07 ISA:I12 ISA:I08 Description Interchange Sender ID Interchange Receiver ID Interchange Control Number Interchange Date

EDIFACT
Meta-data Field Sender(Message) Receiver(Message) Reference(Message) Timestamp(Message) Message Field UNB:S002.0004 UNB:S003:0010 UNB:0020 UNB:S004.0017 Description Sender identification Recipient identification Interchange control reference Date of preparation

InhouseVDA
Meta-data Field Sender(Message) Receiver(Message) Reference(Message) Timestamp(Message) Message Field XX1:CUSTOMER_NR XX1:SUPPLIER_NR XX1:TRANSFER_NR_NEW XX1:TRANSSMISION_DATE Description

Tradacom
Meta-data Field Sender(Message) Receiver(Message) Reference(Message) Timestamp(Message) Message Field STX:FROM.FRNM STX:UNTO.TONM XXXHDR:FIL:FLNG STX:TRDT.DATE Description Name Name File Generation Number (wenn mglich) Date

Page 22

SEEBURGER SAP XI Adapter Archiving Module, User Guide

SAP XI Message Mappings

The user-defined functions of SAP XI Message Mappings can also be used for the metadata enrichment of documents designated for archiving. For that purpose the following Java archives must be imported into the Integration Repository (located in the same software component version as the mapping itself): data/MessageArchiving/api/messagearchiving-api.jar data/Tools/deploy/SeeXICommonCollection.jar data/MessageArchiving/api/messagearchiving-api-javadoc.zip

The documentation of the API (Javadoc) is located in the following ZIP file:

In the appendix you find an example of a user-defined function definition.

Screenshot

Page 23

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Sample Scenarios
In the following examples the document IDs are accentuated in terms of color to facilitate the understanding of document relationships as follows: (Root-) Documents References to (Root-) Documents

Reception and Archiving of an ANSI Message

Screenshot

Page 24

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Module Chain
Number 1 2 3 4 5 5
1) 2) 3) 4) 5) 6)

Module Name localejbs/Seeburger/FileStore localejbs/CallBicXIRaBean localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore localejbs/CallSapAdapter

Type Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean

Module Key 1_MT_EDI 2_Converter 3_MT_LOG 4_MT_XML 5_MT_EDI 0

Description
1) 2) 3) 4) 5) 6)

Archiving of original message 1:1-Mapping for generation of XML document Archiving of BIC log file Archiving of generated XML document Update of archiving record of original message Handing over to XI Adapter Framework

Module Configuration
1_MT_EDI (FileStore Module) Module Key 1_MT_EDI 1_MT_EDI 1_MT_EDI 1_MT_EDI 1_MT_EDI
a) b) c) d) e)

Parameter Name attachmentName documentID documentType archivingSystem archivingStatus

Parameter Value MainDocument EDI_Interchange ANSIX12_850_V4010 easyArchive PENDING

Description
a) b) c) d) e)

Name of message attachment to be stored In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Name of archiving system Archiving status

Page 25

SEEBURGER SAP XI Adapter Archiving Module, User Guide 2_Converter (BIC Module) Module Key 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter 2_Converter
a) b) c) d) e) f) g) h) i) j) k) l)

Parameter Name destSourceMsg destTargetMsg mappingName logAttID xiDocumentID archiveXI mtPartner mtState mtSender mtReceiver mtInterface mtAdditional mtfree13 mtfree14 mtfree15 mtfree16 mtfree17

Parameter Value MainDocument MainDocument See_E2X_ANSIX12_850_V4010 ConverterLog EDI_Interchange true TestPartner SUCCESS TestSender TestReceiver IM_ANSIX12_850_V4010 AdditionalInfo FreeText13 FreeText14 FreeText15 FreeText16 FreeText17

Description
a) b) c) d) e) f) g) h) i) j) k) l) m) n) o) p) q)

Name of source message Name of destination message Name of mapping to be executed Name of message attachemnt which carries the BIC log file Document ID of document for which metata is written Metadata is written by mapping if this parameter is set to true Displayed as Partner in the Web Frontend Status of R/3 processing, default value: SUCCESS; can be used on possible response from R/3

Displayed as Sender in the Web Frontend Displayed as Receiver in the Web Frontend Displayed as Interface in the Web Frontend Additional information; to be used at will Additional information; to be used at will Additional information; to be used at will Additional information; to be used at will Additional information; to be used at will Additional information; to be used at will

m) n) o) p) q)

Page 26

SEEBURGER SAP XI Adapter Archiving Module, User Guide 3_MT_LOG (FileStore Module) Module Key 3_MT_LOG 3_MT_LOG 3_MT_LOG 3_MT_LOG 3_MT_LOG 3_MT_LOG
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value ConverterLog ConverterLog ConverterLog EDI_Interchange easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by mapping In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

4_MT_XML (FileStore Module) Module Key 4_MT_XML 4_MT_XML 4_MT_XML 4_MT_XML 4_MT_XML 4_MT_XML
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value MainDocument XML_ANSIX12_850_V4010 XML_ANSIX12_850_V4010 EDI_Interchange easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by mapping In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

5_MT_EDI (FileStore Module) Module Key 5_MT_EDI 5_MT_EDI

a) b)

Parameter Name documentID archivingStatus

Parameter Value EDI_Interchange READY

Description
a) b)

In context of the XI-message unique document ID New archiving status

Page 27

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Reception and Archiving of an EDIFACT Message with Split

Parent Channel: Screenshot

Page 28

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Parent Channel: Module Chain

Page 29

SEEBURGER SAP XI Adapter Archiving Module, User Guide Number 1 2 3 4 5 6 7 Module Name localejbs/Seeburger/FileStore localejbs/SeeClassifier localejbs/CallBicXIRaBean localejbs/Seeburger/MessageSplitter localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore Type Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Module Key 1_MT_EDI 2_Classifier 3_Converter 4_Split 5_MT_ACK 6_MT_CLASS 7_MT_LOG Descr.
1) 2) 3) 4) 5) 6) 7)

Page 30

SEEBURGER SAP XI Adapter Archiving Module, User Guide 8 localejbs/CallSapAdapter Local Enterprise Bean 0
8)

Page 31

SEEBURGER SAP XI Adapter Archiving Module, User Guide

1) 2) 3) 4) 5) 6) 7) 8)

Storage of original message Determination of message tpye by Classifier module 1:1-Mapping for generation of XML acknowledgement Forwarding of XML message to new communication channel by Splitter module Storage XML acknowledgement Storage of Classifier log file Storage of BIC log file Handing over to XI adapter framework

Parent Channel: Module Configuration

1_MT_EDI (FileStore Module)

Page 32

SEEBURGER SAP XI Adapter Archiving Module, User Guide Module Key 1_MT_EDI 1_MT_EDI 1_MT_EDI 1_MT_EDI Parameter Name attachmentName documentID documentType archivingSystem Parameter Value MainDocument EDI_Interchange EDI easyArchive Description
a) b) c) d)

Page 33

SEEBURGER SAP XI Adapter Archiving Module, User Guide 1_MT_EDI archivingStatus PENDING
e)

Page 34

SEEBURGER SAP XI Adapter Archiving Module, User Guide

a) b) c) d) e)

Name of message attachment to be stored In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Name of archiving system Archiving status

2_MT_CLASS (Classifier Module)

Page 35

SEEBURGER SAP XI Adapter Archiving Module, User Guide Module Key 2_MT_CLASS 2_MT_CLASS Parameter Name destSourceMsg showInAuditLog Parameter Value MainDocument true Description
a) b)

Page 36

SEEBURGER SAP XI Adapter Archiving Module, User Guide 2_MT_CLASS attID classifierAdditionalInfo
c)

Page 37

SEEBURGER SAP XI Adapter Archiving Module, User Guide

a) b) c)

Name of file which is to be processed Display of result in monitor Handing over of classifier result as attachment

3_Converter (BIC Module)

Page 38

SEEBURGER SAP XI Adapter Archiving Module, User Guide Module Key 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter 3_Converter
a) b) c) d) e) f) g) h) i) j) k) l)

Parameter Name destSourceMsg destTargetMsg mappingName classifierAttID setSourceEncodingFromClassifier split logAttID xiDocumentID archiveXI mtPartner mtState mtSender mtReceiver mtInterface mtAdditional mtfree13 mtfree14 mtfree15 mtfree16 mtfree17

Parameter Value MainDocument MainDocument AUTO classifierAdditionalInfo true true ConverterLog EDI_Interchange true TestPartner SUCCESS TestSender TestReceiver functionalACK AdditionalInfo FreeText13 FreeText14 FreeText15 FreeText16 FreeText17

Description
a) b) c) d) e) f) g) h) Fi j) k) l) m) n) o) o) o) o) o) ot)

Name of source message Name of destination message Automatic search of mapping depending on message format Name of classifier attachment Automatic determination of source file encoding Indicates message split Name of log file for later archiving Document ID of document for which metadata is written

Metadata is written by the mapping if this parameter is set to true Displayed as Partner in the Web Frontend Status of R/3 processing, default value: SUCCESS; can be used on possible response from R/3 Displayed as Sender in the Web Frontend Displayed as Receiver in the Web Frontend

m) n)

Displayed as Interface in the Web Frontend (in this case the channel result is a Functional Acknowledgement)
o) p)

Additional information; to be used at will Additional information; to be used at will

Page 39

SEEBURGER SAP XI Adapter Archiving Module, User Guide 5_MT_ACK (FileStore Module) Module Key 5_MT_ACK 5_MT_ACK 5_MT_ACK 5_MT_ACK 5_MT_ACK 5_MT_ACK
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value MainDocument EDI_ACK FunctionalAcknowledgement EDI_Interchange easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by MainMapping (Acknowledgement) In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

6_MT_CLASS (FileStore Module) Module Key 6_MT_CLASS 6_MT_CLASS 6_MT_CLASS 6_MT_CLASS 6_MT_CLASS 6_MT_CLASS
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value classifierAdditionalInfo EDI_CLASS Classifier EDI_Interchange easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by Classifier In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

Page 40

SEEBURGER SAP XI Adapter Archiving Module, User Guide

7_MT_LOG (FileStore Module) Module Key 7_MT_LOG 7_MT_LOG 7_MT_LOG 7_MT_LOG 7_MT_LOG 7_MT_LOG
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value ConverterLog ConverterLog ConverterLog EDI_Interchange easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by mapping In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

8_MT_EDI (FileStore Module) Module Key 8_MT_EDI 8_MT_EDI

a) b)

Parameter Name documentID archivingStatus

Parameter Value EDI_Interchange READY

Description
a) b)

In context of the XI-message unique document ID New archiving status

Page 41

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Child Channel: Screenshot

Child Channel: Module Chain

No 1 2
1) 2)

Module name localejbs/Seeburger/FileStore localejbs/CallSapAdapter

Typ Local Enterprise Bean Local Enterprise Bean

Module key 1_MT_XML 0

Descr.
1) 2)

Storage of XML document Handing over to XI adapter framework

Page 42

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Child Channel: Module Configuration

Module Key 1_MT_XML 1_MT_XML 1_MT_XML 1_MT_XML 1_MT_XML 1_MT_XML 1_MT_XML 1_MT_XML
a) b) c) d) e) f) g) h)

Parameter Name attachmentName documentID documentType parentID parentLocation archivingSystem archivingStatus suppressChildCount

Parameter Value MainDocument XML_ORDERS_UN_D96A XML_ANSIX12_850_V4010 EDI_Interchange external easyArchive READY true

Description
a) b) c) d) e) f) g) h)

Name of message attachment to be stored, generated by mapping In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Parent document is located in another XI message Name of archiving system Archiving status ExpectedChildren-attribute of parent document is not incremented

Page 43

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Sending a VDA Message

Screenshot

Module Chain
Number 1 2 3 4 5 6
a) b) c) d) e) f)

Module Name localejbs/CallBicXIRaBean localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore localejbs/Seeburger/FileStore localejbs/CallSapAdapter

Type Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean Local Enterprise Bean

Module Key 1_Converter 2_MT_EDI 3_MT_LOG 4_MT_XML 5_MT_EDI 0

Descprition
2) 1) 3) 4) 5) 6)

1:1-Mapping for generation of XML document and writing of metadata Storage of original message Storage of BIC log file Storage of generated XML mesage Update of archiving status Handing over to communication adapter

Page 44

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Module Configuration
1_Converter (BIC Module) Module Key 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter 1_Converter
a) b) c) d) e) f) g) h) i) j) k) l)

Parameter Name destSourceMsg destTargetMsg saveSourceMsg mappingName logAttID xiDocumentID archiveXI mtPartner mtState mtSender mtReceiver mtInterface mtAdditional mtfree13 mtfree14 mtfree15 mtfree16 mtfree17 vdaDelimiter

Parameter Value MainDocument MainDocument XML_VDA4905 See_X2E_VDA4905 ConverterLog VDA4905 true TestPartner SUCCESS TestSender TestReceiver IM_VDA4905 AdditionalInfo FreeText13 FreeText14 FreeText15 FreeText16 FreeText17 CRLF

Description
a) b) c) d) e) f) g) h) i) j) k) l) m) m) m) m) m) m) n)

Name of source message Name of destination message Name of source message for archiving component Name of mapping to be executed Name of log file for later archiving Document ID of document for which metadata is written Metadata is written by the mapping if this parameter is set to true Displayed as Partner in the Web Frontend

Status of R/3 processing, default value: SUCCESS; can be used on possible response from R/3 Displayed as Sender in the Web Frontend Displayed as Receiver in the Web Frontend Displayed as Interface in the Web Frontend Additional information; to be used at will The lines in the message are completed by CRLF (CRLF, CR or LF)

m) n)

Page 45

SEEBURGER SAP XI Adapter Archiving Module, User Guide 2_MT_EDI (FileStore Module) Module Key 2_MT_EDI 2_MT_EDI 2_MT_EDI 2_MT_EDI 2_MT_EDI
a) b) c) d) e)

Parameter Name attachmentName documentID documentType archivingSystem archivingStatus

Parameter Value MainDocument VDA4905 VDA4905 easyArchive PENDING

Description
a) b) c) d) e)

Name of message attachment to be stored (result of mapping) In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Name of archiving system Archiving status

3_MT_LOG (FileStore Module) Module Key 3_MT_LOG 3_MT_LOG 3_MT_LOG 3_MT_LOG 3_MT_LOG 3_MT_LOG
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value ConverterLog ConverterLog ConverterLog VDA4905 easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by mapping In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

4_MT_XML (FileStore Module) Module Key 4_MT_XML 4_MT_XML 4_MT_XML 4_MT_XML 4_MT_XML 4_MT_XML
a) b) c) d) e) f)

Parameter Name attachmentName documentID documentType parentID archivingSystem archivingStatus

Parameter Value XML_VDA4905 XML_VDA4905 XML_VDA4905 VDA4905 easyArchive READY

Description
a) b) c) d) e) f)

Name of message attachment to be stored, generated by mapping In context of the XI-message unique document ID Document Type (evaluated e.g. by the document viewer) Document ID of parent document Name of archiving system Archiving status

Page 46

SEEBURGER SAP XI Adapter Archiving Module, User Guide 5_MT_EDI (FileStore Module) Module Key 5_MT_EDI 5_MT_EDI
a) b)

Parameter Name documentID archivingStatus

Parameter Value VDA4905 READY

Description
a) b)

In context of the XI-message unique document ID New archiving status

Page 47

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Appendix
Available Metadata Attributes
Web Frontend FileStore Module Parameter
1)

BIC Mapping Parameter

1)

Java API

Database table

XI Message ID DocumentID Time Direction Archiving Status Archiving System Document Type Partner DT Sender DT Receiver DT Interface Sender (Message) Receiver (Message) Reference (Message) Timestamp (Message) Message Type Info (Message) Free information Free information Free information Free information Free information Testflag State R/3
1) automatically from XI message 2) automatically from document 3) automatically: Split state

4) 4)

cMessageID cObjectID cMessageDateTime cDirection cArchivingStatus cArchivingSystem cMessageType cPartner cFree1 cFree2 cFree3 cFree6 cFree7 cFree8 cFree9 cFree10 cFree11 cFree12 cFree13 cFree14 cFree15 cFree16 cFree17 cTestFlag cStatus

documentID
1) 1)

xiDocumentID

MESSAGE_DATETIME DIRECTION ARCHIVING_STATUS ARCHIVING_SYSTEM MESSAGE_TYPE mtPartner mtSender mtReceiver mtInterface

2)

archivingStatus archivingSystem documentType

PARTNER FREE1 FREE2 FREE3 FREE6 FREE7 FREE8 FREE9 FREE10 FREE11 FREE12 FREE13 FREE14 FREE15 FREE16 FREE17 TEST_FLAG STATUS

2)

2)

2)

2) 3) 2)

mtfree13 mtfree14 mtfree15 mtfree16 mtfree17

2) 2)

4) as parameter of readRecord()/writeRecord()

Note: The attributes cFree18 cFree20 are reserved for internal purposes and therefore must not be used.

Page 48

SEEBURGER SAP XI Adapter Archiving Module, User Guide

Example: User-defined Function for SAP XI Mapping

import com.seeburger.smarti.bismt.api.*; public String writeMT(String a, String b, String c, String d, String e, Container container) { MappingTrace trace = container.getTrace(); Map map = container.getTransformationParameters(); String messageID = (String)map.get(StreamTransformationConstants.MESSAGE_ID); String parentID = // not used here; may be used for parent record updates (String)map.get(StreamTransformationConstants.REF_TO_MESSAGE_ID); String documentID = "EDIFACT_XML"; trace.addWarning("MessageID: " + messageID); trace.addWarning("ParentID: try { MTMasterXI master = new MTMasterXI(); master.setField(MTMasterXI.FREE1, (String)map.get(StreamTransformationConstants.SENDER_PARTY)); master.setField(MTMasterXI.FREE2, (String)map.get(StreamTransformationConstants.RECEIVER_PARTY)); master.setField(MTMasterXI.FREE3, (String)map.get(StreamTransformationConstants.INTERFACE)); master.setField(MTMasterXI.FREE6, a); master.setField(MTMasterXI.FREE7, b); master.setField(MTMasterXI.FREE8, c); master.setField(MTMasterXI.FREE9, d); master.setField(MTMasterXI.FREE10, e); master.setField(MTMasterXI.FREE13, "Additional Information 13"); master.setField(MTMasterXI.FREE14, "Additional Information 14"); master.setField(MTMasterXI.FREE15, "Additional Information 15"); master.setField(MTMasterXI.FREE16, "Additional Information 16"); master.setField(MTMasterXI.FREE17, "Additional Information 17"); master.writeRecord(messageID, documentID); } catch (MTException ex) { trace.addWarning(ex.toString()); } return "1"; } " + parentID);

Page 49