SAPXI Archiving En

SEEBURGER SAP XI Adapter – Archiving Module

User Guide

SEEBURGER SAP XI Adapter – Archiving Module, User Guide

ContentsContents........................................................................................................................... ...............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


IconsSymbol Description

Warning

Component

Example

Function

Note

Recommendation

Syntax

Page 3


Overview

PurposeThe 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 ConsiderationsA 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!

IntegrationThe 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


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 message’s 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 message’s 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-message’s attachment, in order to deposit it into the operational file-store of the SEEBURGER Archiving module.

Documents are uniquely identified over the XI-message’s 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


System OverviewThe 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 file-store 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-system’s 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


The Archiving ProcedureArchiving 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 system’s file system interface

While the first step runs synchronously with the XI system’s 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-message’s 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-message’s 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. SEEBURGER’s 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


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 document’s 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


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


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 Description

ArchivingRecordCount Number of documents designated for archiving

ArchivingRecordId0 ... ArchivingRecordId<N> Document IDs of documents designated for archiving, where <N> is the number specified in ArchivingRecordCount

srcContent Document contents

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 system’s 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


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 Description

ARCHIVING_SCRIPTMODE Possible values: PREEXPORT, ERROR

ARCHIVING_ID Unique ID

Export-Script


ARCHIVING_SCRIPTMODE Possible values: EXPORT, ERROR


ARCHIVING_FILE Path of file designated for archiving

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

Post-Export-Skript


ARCHIVING_SCRIPTMODE Possible values: POSTEXPORT, ERROR


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

Page 11


Installation

OverviewThe 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

PrerequisitesThe 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 CD-ROM under:

data/MessageArchiving/DBInstallation/install_ArchivingModule_XI_<OS>.bin (UNIX)

or

data/MessageArchiving/DBInstallation/install_ArchivingModule_XI_Win32.exe (Windows)

respectively.

Page 12


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


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


(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


(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 Store-Module 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).

ResultAfter 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


Configuration

User Administration

Initial Users

The standard users xiuser and xiadmin can be used for work with the web frontend after installation:

Name Role Initial Password

xiuser XIUSER xiuser

xiadmin XIADMIN 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 Rights

XIUSER • Search and view messages

• Change the archiving status of messages

XIADMIN 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


Archiving JobThe 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 Description Status

Archiving System Unique archive system name mandatory

Archiving Mode Archiving mode:

Single: 0

Group: 1

mandatory

Client ID Fixed value: 1

Mapping Name Name of BIC-mapping for creating control file during group archiving

mandatory for group archiving, ignored otherwise

Pre-Script Path to file, which is executed as the pre-export-script

optional

Pre-Script Arguments Command line arguments for the pre-export script

optional

Post-Script Path to file, which is executed as the post-export-script

optional

Post-Script Arguments Command line arguments for the post-export script

optional

Document Types

The following parameters can be set:


Archiving System Name of the archive system as defined under Archiving Systems

mandatory

Client ID Fixed value: 1

Document Type Document Type (used e.g. by the document viewer)

mandatory

Mapping Name Name of BIC-mapping for creating the control file

mandatory

Script Path to file that is executed as the export-script

optional

Script Arguments Command line arguments for the export-script

optional

FileStore ModuleThe 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


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:


documentID In context of the XI-message unique document ID;

Note: Valid characters: a…z, A…Z, 0...9 (no spaces allowed)

Mandatory

documentType Document Type Optional (presetting: “unknown”)

parentID Document ID of parent document

Optional

parentLocation Possible values: internal, external

Must be set to „external“, if parent document was read from another XI-message

Optional (presetting: “internal”)

attachmentName Name of message attachment, from which document is read (also see comment below)

Mandatory (except if in Update-Mode)

archivingStatus Possible values: NONE, READY, PENDING

Optional (presetting: “NONE”)

archivingSystem Archiving System (as configured in the web-frontend)

Mandatory if archivingStatus is set

suppressChildCount Possible values: true, false Optional (presetting: “false”)

styleSheet Name of style sheet to be used by XSLT viewer *)

Optional

fileType File name extension for attachment if downloaded as file from the web-frontend (e.g. “pdf”, “xml”)

Optional

client Name of system 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


Reorganization JobThe 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

• it is not part of a document tree, and its status is either “NONE” or “ARCHIVED”

or

• all documents of the containing tree have reached the maximum hold-back time and have either the status “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


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

SEEBURGER BIC 1:1-MappingThe 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 Description

archiveXI „true“ or „false“

determines if metadata is written by mapping

xiDocumentID Document ID, corresponds to the DocumentID of the FileStore Module

mtPartner Partner as additional information in the Web Frontend

mtState Message status; possible values:

• SUCCESS

• PENDING

• ERROR

mtSender Sender, for input analogous to Partner.

mtReceiver Receiver, for output analogous to Partner

mtInterface Corresponding message description in the Web Frontend

mtAdditional Additional Information

mtfree13

mtfree14

mtfree15

mtfree16

mtfree17

Freely usable metadata attributes

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

The attributes are read from the message as follows:

Page 21


ANSIX12

Meta-data Field Message Field Description

Sender(Message) ISA:I06 Interchange Sender ID

Receiver(Message) ISA:I07 Interchange Receiver ID

Reference(Message) ISA:I12 Interchange Control Number

Timestamp(Message) ISA:I08 Interchange Date

EDIFACT


Sender(Message) UNB:S002.0004 Sender identification

Receiver(Message) UNB:S003:0010 Recipient identification

Reference(Message) UNB:0020 Interchange control reference

Timestamp(Message) UNB:S004.0017 Date of preparation

InhouseVDA


Sender(Message) XX1:CUSTOMER_NR

Receiver(Message) XX1:SUPPLIER_NR

Reference(Message) XX1:TRANSFER_NR_NEW

Timestamp(Message) XX1:TRANSSMISION_DATE

Tradacom


Sender(Message) STX:FROM.FRNM Name

Receiver(Message) STX:UNTO.TONM Name

Reference(Message) XXXHDR:FIL:FLNG File Generation Number (wenn möglich)

Timestamp(Message) STX:TRDT.DATE Date

Page 22


SAP XI Message MappingsThe 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

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

• data/MessageArchiving/api/messagearchiving-api-javadoc.zip

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

Screenshot

Page 23


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


Module Chain

Number Module Name Type Module Key Description

1 localejbs/Seeburger/FileStore Local Enterprise Bean 1_MT_EDI 1)

2 localejbs/CallBicXIRaBean Local Enterprise Bean 2_Converter 2)

3 localejbs/Seeburger/FileStore Local Enterprise Bean 3_MT_LOG 3)

4 localejbs/Seeburger/FileStore Local Enterprise Bean 4_MT_XML 4)


5 localejbs/CallSapAdapter Local Enterprise Bean 0 6)

1) Archiving of original message2) 1:1-Mapping for generation of XML document3) Archiving of BIC log file4) Archiving of generated XML document5) Update of archiving record of original message6) Handing over to XI Adapter Framework

Module Configuration

1_MT_EDI (FileStore Module)

Module Key Parameter Name Parameter Value Description

1_MT_EDI attachmentName MainDocument a)

1_MT_EDI documentID EDI_Interchange b)

1_MT_EDI documentType ANSIX12_850_V4010 c)

1_MT_EDI archivingSystem easyArchive d)

1_MT_EDI archivingStatus PENDING e)

a) Name of message attachment to be storedb) In context of the XI-message unique document IDc) Document Type (evaluated e.g. by the document viewer)d) Name of archiving systeme) Archiving status

Page 25


2_Converter (BIC Module)


2_Converter destSourceMsg MainDocument a)

2_Converter destTargetMsg MainDocument b)

2_Converter mappingName See_E2X_ANSIX12_850_V4010 c)

2_Converter logAttID ConverterLog d)

2_Converter xiDocumentID EDI_Interchange e)

2_Converter archiveXI true f)

2_Converter mtPartner TestPartner g)

2_Converter mtState SUCCESS h)

2_Converter mtSender TestSender i)

2_Converter mtReceiver TestReceiver j)

2_Converter mtInterface IM_ANSIX12_850_V4010 k)

2_Converter mtAdditional AdditionalInfo l)

2_Converter mtfree13 FreeText13 m)

2_Converter mtfree14 FreeText14 n)

2_Converter mtfree15 FreeText15 o)

2_Converter mtfree16 FreeText16 p)

2_Converter mtfree17 FreeText17 q)

a) Name of source messageb) Name of destination messagec) Name of mapping to be executedd) Name of message attachemnt which carries the BIC log filee) Document ID of document for which metata is writtenf) Metadata is written by mapping if this parameter is set to “true“g) Displayed as Partner in the Web Frontendh) Status of R/3 processing, default value: SUCCESS; can be used on possible response from R/3i) Displayed as Sender in the Web Frontendj) Displayed as Receiver in the Web Frontendk) Displayed as Interface in the Web Frontendl) Additional information; to be used at willm) Additional information; to be used at willn) Additional information; to be used at willo) Additional information; to be used at willp) Additional information; to be used at willq) Additional information; to be used at will

Page 26


3_MT_LOG (FileStore Module)


3_MT_LOG attachmentName ConverterLog a)

3_MT_LOG documentID ConverterLog b)

3_MT_LOG documentType ConverterLog c)

3_MT_LOG parentID EDI_Interchange d)

3_MT_LOG archivingSystem easyArchive e)

3_MT_LOG archivingStatus READY f)

a) Name of message attachment to be stored, generated by mappingb) In context of the XI-message unique document IDc) Document Type (evaluated e.g. by the document viewer)d) Document ID of parent documente) Name of archiving systemf) Archiving status

4_MT_XML (FileStore Module)


4_MT_XML attachmentName MainDocument a)

4_MT_XML documentID XML_ANSIX12_850_V4010 b)

4_MT_XML documentType XML_ANSIX12_850_V4010 c)

4_MT_XML parentID EDI_Interchange d)

4_MT_XML archivingSystem easyArchive e)

4_MT_XML archivingStatus READY f)




5_MT_EDI documentID EDI_Interchange a)

5_MT_EDI archivingStatus READY b)

a) In context of the XI-message unique document IDb) New archiving status

Page 27


Reception and Archiving of an EDIFACT Message with Split

Parent Channel: Screenshot

Page 28


Parent Channel: Module Chain

Page 29


Number Module Name Type Module Key Descr.


2 localejbs/SeeClassifier Local Enterprise Bean 2_Classifier 2)


4 localejbs/Seeburger/MessageSplitter Local Enterprise Bean 4_Split 4)

5 localejbs/Seeburger/FileStore Local Enterprise Bean 5_MT_ACK 5)

6 localejbs/Seeburger/FileStore Local Enterprise Bean 6_MT_CLASS 6)


Page 30



Page 31


1) Storage of original message2) Determination of message tpye by Classifier module3) 1:1-Mapping for generation of XML acknowledgement4) Forwarding of XML message to new communication channel by Splitter module5) Storage XML acknowledgement6) Storage of Classifier log file7) Storage of BIC log file8) Handing over to XI adapter framework

Parent Channel: Module Configuration


Page 32




1_MT_EDI documentID EDI_Interchange b)

1_MT_EDI documentType EDI c)


Page 33



Page 34


a) Name of message attachment to be storedb) In context of the XI-message unique document IDc) Document Type (evaluated e.g. by the document viewer)d) Name of archiving systeme) Archiving status

2_MT_CLASS (Classifier Module)

Page 35



2_MT_CLASS destSourceMsg MainDocument a)

2_MT_CLASS showInAuditLog true b)

Page 36


2_MT_CLASS attID classifierAdditionalInfo c)

Page 37


a) Name of file which is to be processedb) Display of result in monitorc) Handing over of classifier result as attachment


Page 38





3_Converter mappingName AUTO c)

3_Converter classifierAttID classifierAdditionalInfo d)

3_Converter setSourceEncodingFromClassifier true e)

3_Converter split true f)

3_Converter logAttID ConverterLog g)

3_Converter xiDocumentID EDI_Interchange h)

3_Converter archiveXI true Fi

3_Converter mtPartner TestPartner j)

3_Converter mtState SUCCESS k)

3_Converter mtSender TestSender l)

3_Converter mtReceiver TestReceiver m)

3_Converter mtInterface functionalACK n)

3_Converter mtAdditional AdditionalInfo o)





3_Converter mtfree17 FreeText17 ot)

a) Name of source messageb) Name of destination messagec) Automatic search of mapping depending on message formatd) Name of classifier attachmente) Automatic determination of source file encodingf) Indicates message splitg) Name of log file for later archivingh) Document ID of document for which metadata is writteni) Metadata is written by the mapping if this parameter is set to “true”j) Displayed as Partner in the Web Frontendk) Status of R/3 processing, default value: SUCCESS; can be used on possible response from R/3l) Displayed as Sender in the Web Frontendm) Displayed as Receiver in the Web Frontendn) Displayed as Interface in the Web Frontend (in this case the channel result is a Functional Acknowledgement)o) Additional information; to be used at willp) Additional information; to be used at will

Page 39


5_MT_ACK (FileStore Module)


5_MT_ACK attachmentName MainDocument a)

5_MT_ACK documentID EDI_ACK b)

5_MT_ACK documentType FunctionalAcknowledgement c)

5_MT_ACK parentID EDI_Interchange d)

5_MT_ACK archivingSystem easyArchive e)

5_MT_ACK archivingStatus READY f)

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

6_MT_CLASS (FileStore Module)


6_MT_CLASS attachmentName classifierAdditionalInfo a)

6_MT_CLASS documentID EDI_CLASS b)

6_MT_CLASS documentType Classifier c)

6_MT_CLASS parentID EDI_Interchange d)

6_MT_CLASS archivingSystem easyArchive e)

6_MT_CLASS archivingStatus READY f)

a) Name of message attachment to be stored, generated by Classifierb) In context of the XI-message unique document IDc) Document Type (evaluated e.g. by the document viewer)d) Document ID of parent documente) Name of archiving systemf) Archiving status

Page 40







7_MT_LOG parentID EDI_Interchange d)






8_MT_EDI documentID EDI_Interchange a)



Page 41


Child Channel: Screenshot

Child Channel: Module Chain

No Module name Typ Module key Descr.



1) Storage of XML document2) Handing over to XI adapter framework

Page 42


Child Channel: Module Configuration


1_MT_XML attachmentName MainDocument a)

1_MT_XML documentID XML_ORDERS_UN_D96A b)

1_MT_XML documentType XML_ANSIX12_850_V4010 c)

1_MT_XML parentID EDI_Interchange d)

1_MT_XML parentLocation external e)

1_MT_XML archivingSystem easyArchive f)

1_MT_XML archivingStatus READY g)

1_MT_XML suppressChildCount true h)

a) Name of message attachment to be stored, generated by mappingb) In context of the XI-message unique document IDc) Document Type (evaluated e.g. by the document viewer)d) Document ID of parent documente) Parent document is located in another XI messagef) Name of archiving systemg) Archiving statush) ExpectedChildren-attribute of parent document is not incremented

Page 43


Sending a VDA Message

Screenshot

Module Chain

Number Module Name Type Module Key Descprition







a) 1:1-Mapping for generation of XML document and writing of metadatab) Storage of original messagec) Storage of BIC log filed) Storage of generated XML mesagee) Update of archiving statusf) Handing over to communication adapter

Page 44


Module Configuration





1_Converter saveSourceMsg XML_VDA4905 c)

1_Converter mappingName See_X2E_VDA4905 d)

1_Converter logAttID ConverterLog e)

1_Converter xiDocumentID VDA4905 f)

1_Converter archiveXI true g)

1_Converter mtPartner TestPartner h)

1_Converter mtState SUCCESS i)

1_Converter mtSender TestSender j)

1_Converter mtReceiver TestReceiver k)

1_Converter mtInterface IM_VDA4905 l)

1_Converter mtAdditional AdditionalInfo m)






1_Converter vdaDelimiter CRLF n)

a) Name of source messageb) Name of destination messagec) Name of source message for archiving componentd) Name of mapping to be executede) Name of log file for later archivingf) Document ID of document for which metadata is writteng) Metadata is written by the mapping if this parameter is set to “true”h) Displayed as Partner in the Web Frontendi) Status of R/3 processing, default value: SUCCESS; can be used on possible response from R/3j) Displayed as Sender in the Web Frontendk) Displayed as Receiver in the Web Frontendl) Displayed as Interface in the Web Frontendm) Additional information; to be used at willn) The lines in the message are completed by CRLF (CRLF, CR or LF)

Page 45





2_MT_EDI documentID VDA4905 b)

2_MT_EDI documentType VDA4905 c)



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






3_MT_LOG parentID VDA4905 d)




4_MT_XML (FileStore Module)


4_MT_XML attachmentName XML_VDA4905 a)

4_MT_XML documentID XML_VDA4905 b)

4_MT_XML documentType XML_VDA4905 c)

4_MT_XML parentID VDA4905 d)

4_MT_XML archivingSystem easyArchive e)

4_MT_XML archivingStatus READY f)


Page 46




5_MT_EDI documentID VDA4905 a)



Page 47


Appendix

Available Metadata AttributesWeb Frontend FileStore

Module Parameter

BIC Mapping Parameter

Java API Database table

XI Message ID 1) 1) 4) cMessageID

DocumentID documentID xiDocumentID 4) cObjectID

Time 1) MESSAGE_DATETIME cMessageDateTime

Direction 1) DIRECTION cDirection

Archiving Status archivingStatus ARCHIVING_STATUS cArchivingStatus

Archiving System

archivingSystem ARCHIVING_SYSTEM cArchivingSystem

Document Type documentType MESSAGE_TYPE cMessageType

Partner mtPartner PARTNER cPartner

DT Sender mtSender FREE1 cFree1

DT Receiver mtReceiver FREE2 cFree2

DT Interface mtInterface FREE3 cFree3

Sender (Message)

2) FREE6 cFree6

Receiver (Message)

2) FREE7 cFree7

Reference (Message)

2) FREE8 cFree8

Timestamp (Message)

2) FREE9 cFree9

Message Type 2) FREE10 cFree103) FREE11 cFree11

Info (Message) 2) FREE12 cFree12

Free information mtfree13 FREE13 cFree13





Testflag 2) TEST_FLAG cTestFlag

State R/3 2) STATUS cStatus

1) automatically from XI message

2) automatically from document

3) automatically: Split state

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

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

Page 48


Example: User-defined Function for SAP XI Mappingimport 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: " + parentID);

try {

MTMasterXI master = new MTMasterXI();

master.setField(MTMasterXI.FREE1,

(String)map.get(StreamTransformationConstants.SENDER_PARTY));


(String)map.get(StreamTransformationConstants.RECEIVER_PARTY));


(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.writeRecord(messageID, documentID);

} catch (MTException ex) {

trace.addWarning(ex.toString());

}

return "1";

}

Page 49