Input

Due to it’s design, tia® Document Router does not require input in any particular format.

Input can be served by a file system location or via REST.

The tia® Document Router is capable to extract information required for linking to SAP or Salesforce out if an delivered index file or can derive it from document file name.

To-PDF-Functionality allows converting and archiving in one step.

Output (Archiving System)

tia® Document Router uses the standarized SAP ArchiveLink protocol for the transfer of the documents to the archiving system. Therfore all archive or document management solutions which are SAP ArchiveLink certified are fully supported. This applies to all SAP releases (ArchiveLink 3.1 and higher).

In addition to that KGS offers to all archive manufacturers which are not previously certified by SAP an SDK in order to enable their software solutions to use the SAP ArchiveLink therefore the KGS-OMS-Connector.

To protect network communications with the archiving system, tia® Document Router utilizes a security process in which URL’s within the HTTP communication are being encrypted for transfer.

Public and private key encryption of this type as applied to direct communication from SAP, prevents unauthorized access to the archived documents.

Linking

SAP-Linking

Each document will be transferred in to the archiving system by tia® Document Router.

After successfully archiving the document tia® Document Router will execute relevant entries in SAP’s internal tables required in order to search and display the archived document from within SAP.

tia® Document Router ensures that documents are being managed in accordance with the SAP ArchiveLink protocol by safeguarding the links to the relevant SAP business objects.

Access and display of archived documents in SAP is performed in the same way as for data which has been edited and dispatched using SAP’s own tools (SAPScript).

Salesforce-Linking

After archiving, tia® Document Router can link to Salesforce, too. This can happen in addition to SAP-Linking or instead of SAP-Linking. (deprecated)

Sample installation via webapps-folder

After downloading tia® Document Router, unzip the content of the downloaded zip-archive into <Webserver-installation-folder>/webapps folder.

The zip-archive contains tia® Document Router in form of a war-container, which will be automatically decompressed by Apache Tomcat Webserver.

After Tomcat has finished decompressing the war-container, you may restart Tomcat webserver once.

tia® Document Router uses the standard SAP ArchiveLink protocol in order to communicate with any ArchiveLink certified DMS. To enable the SAP ArchiveLink functionality, KGS provides an SAP transport, which has to be imported into the connected SAP systems.

Interfaces

An interface describes the type of input data tia® Document Router receives. The following types of interfaces are supported by tia® Document Router.

Streamserve

The Streamserver interfaces is used by output management systems (OMS) of the type streamserve. The input format of the index files is being defined like this.

<SAP Business Object>,<SAP AL Doc-Type>, <SAP Repository>, <SAP Object Key>, <SAP SysID>, <doc file file>

Example:

VBRK,SDOINVOICE,T1,095092046,U8P,strs234BA33A41676152310144089686720.pdf

RDI

The SAP Raw Data Interface (RDI) is the standard protocol by SAP to deliver the data of outgoing documents to an external OMS. The RDI file contains all information required by tia® Document Router in order to store the image file in an external DMS (defined within SAP using standard ArchiveLink customizing as well as linking the archived documend to an SAP Business Object in order to allow an user to access the archived image using SAP ArchiveLink functionality. Information like the ContentRepository, Object Type as well as the ObjectID will be contained within the RDI file.

B4Activator

The B4Activator interface is specifically designed for transfering multiline index data with attachments and table data to SAP (e.g. to be processed further by KGS Activator). The first line within the index file contains information regarding the main document with ContentRepository, SAP (Workflow) document type as well as the image filename. All attributes are being separated by semicolon ( ; ).

Generic DataInterface definition

In addition to the already mentioned interface definitions Streamserve, RDI and B4Activator theres also a more generic index format specification, which allows you setup an INI file which holds various sections each describing a specific index format fitting your requirements. The generic DataInterface approach is being described further in the following section DR4 - Defining DataInterfaces, SIDMappings and Archive Link Mappings .

In order to use tia® Document Router you may provide a configuration file that contains the DataInterface definition, as well as the ArchivingSystem definition and a configuration file that contains the SIDMapping definition.

These three definitions follow a certain structure that will be described in the following sections.

DataInterface definition

The data interface describes the data and positions of data which will be used in the linking process. Index files contain these values and needs to fit the definition. Regularly, the DataInterface is derived from the structure defined from the index file content.

An DataInterface can be defined in 2 types:

• Separator based (variable length)

• fixed length

When using a DataInterface for sets with variable length, it’s necessary to define the separator, which will be used in order split the value data stream and retrieve the values.

Keyname is the name of the variable defined within a DataInterface. The Key type has to be defined as one of the following types. Separator defines a symbol, that will be used when splitting the index file content. Number in Set defines the position of the value within the index file. Default Value can be defined as a fallback or as a static value when no value was found within the index file.

In case of a set with fixed length Length defines the length in characters of the value expected within the index file.

The following Key types are being supported by tia® Document Router.

The following separators are being supported.

• A semikolon → ;

• A comma → ,

• A vertical bar → |

• A hashtag → #

Special fields

Fields can reuse values of other fields.

For example in a scenario where no index file exist, all for archive and link relevant information are fetched from file name. So you need to split up the file name an maybe join if you want create additional information for e.g. linking.

Sub-Value by Position

[positionBasedSchema]
FileName          = f          ||     |0   |
ArchiveType       = C          ||     |0   |N1
DOC_TYPE          = c          ||     |0   |
SAP_OBJECT        = B          ||     |0   |BKBF
AR_OBJECT         = T          ||     |0   |ZFILENAME
ObjectID          = O          ||     |0   |@Filename[1,18]
SYS_ID            = S          ||     |0   |@Filename[20,22]
MANDANT           = M          ||     |0   |@Filename[24,26]

• ObjectID is an sub string of Filename. It uses position 1 until 18 of it.

Sub-Value by Separator

[separatorBaseSchema]
ImageFileName     =  f  |,  |0  |
CONTREP           =  C  |,  |0  |@ImageFileName[_,1]
ARCHDOCID         =  D  |,  |0  |@ImageFileName[_,2]

• field ImageFileName is split by _ and then position 1 is used for CONTREP and position 2 for ARCHDOCID

Join

[joinSchema]
FileName          = f          ||     |0   |
ArchiveType       = C          ||     |0   |N1
DOC_TYPE          = c          ||     |0   |
SAP_OBJECT        = B          ||     |0   |BKBF
AR_OBJECT         = T          ||     |0   |ZFILENAME
ObjectID          = O          ||     |0   |@Filename[1,18]
SYS_ID            = S          ||     |0   |@Filename[20,22]
MANDANT           = M          ||     |0   |@Filename[24,26]
another           = X          ||     |0   |@ObjectID@MANDANT

• here the field another which is used while linking is a concatenation of the contents of ObjectId and Mandant.

ArchiveLink Connection mapping

It’s often necessary to define one or many connections to the archiving system, so tia® Document Router knows how to communicate with the archive and where to exactly archive the processed documents.

For that reason you may want to define the connection parameters for the archiving system.

The definition file has to be placed in config folder. (defined in instance common tab)

The definition file name can be configure in Archiving tab via config item AL Connection Mapping File.

The file follows this format:

You may define multiple archiving systems in one definition file.

SIDMapping definition

In document router 4 the SID mapping for linking does not exist anymore via SID mapping file (SIDMappingDefFile).

Instead you can use in schema definition the S like in this example

[foobarInstance]
SYSID                                                   =       X       |;        |1          |
MANDANT                                                 =       X       |;        |2          |
CONTREP                                                 =       C       |;        |3          |
LoginCL                                                 =       S       |;        |0          |@SYSID@MANDANT

Example Schemata

• here the index files gives mandant and contrep and the LoginCL variable then contains the SAP connector instance id

or this:

[foobarInstance]
CONTREP                                                 =       C       |;        |1         |
LoginCL                                                 =       S       |;        |2         |

• in this example the index file directly contains the SAP Connector instance id.

As you see, LoginCLis connected to the Variable S. We see it is concatenated from 2 others. So in index file, the concatenation from place 1 and 2 gives the variable value of LoginCL. This value is pointing to an existing SAP-Connector instance with this name.

Real Example

The Document Router is configured with index-Files. Those .idx-Files contain following lines:

Q80;105;XY;

Q80;103;ND;

Q80;134;NF;

Following the previous given Schemata-Example this would mean:

• Q80 = SYSID

• 105,103,134 = MANDANT

• XY,ND,NF = CONTREP

In the Schema above is in Line 5 following configured as “S” (SIDLinking) : @SYSID@MANDANT whereas @SYSID is on place 1 and @MANDANT is on place 2

That means, the DocumentRouter 4.x will concatinate Field 1 and Field 2 and try to find a SAP-Connector-Instance with that Name. In this Example with those three different Index-Files the Document Router tries to call SAP-Connector-Instance:

• Q80105

• Q80103

• Q80134

Means: If those Connections are available (and configured in the SAP-Connector), the DR will Link to those individual SAP-Configurations.

tia® Document Router is being shipped with the option to create a protocol that includes the information of processed documents.

In order to open the protocol click on
Main → Protocol Writer

This will lead you to the KGS Protocol Writer, which is shipped together with DocumentRouter.

In case you have enabled protocolling, you may see a list of entries representing documents that have been processed so far, similar to the example below.

Protol Writer will provide you with the following information.

For further information to the KGS Protocol Writer plugin please consult KGS Protocol Writer Plugin .

The tia® Document Router logs into several files:

• global logging using KGS Logger Plugin (Logger.txt)

• instance logging

DR global logging using KGS Logger Plugin

The DR is logging like any other KGS OSGi bundle using the KGS Logger Plugin.

The general configuration of it can be found using the UI by clicking
OSGi → Configuration → KGS File Logger.

Beside log file location and name, other settings can be set. For further description of this plugin please consult: KGS Logger Plugin

The configuration of the plugin contains details about where an how to log. The log level has to be set inside the global DocumentRouter configuration:
OSGi → Configuration → Global DocumentRouter Configuration

Please Consider that other KGS plugins do log into that file file as well.

DR instance logging

Every KGS DocumentRouter instance has its own log file. This can be configured inside DocumentRouter instance inside common tab.

Relevant for logging are the follwing fields:

• LogDirectory (where the log files will be stored)

• LogFilename (how the log file base name is)

• Debug (log level 0..4 while 4 means debug and 0 none)

• KeepLogfileDays (for log file rotation)

Further information about the fields can be found in DR4 - Tab - Common

About

The DR is capable to inform email recipients on several events. This section explains how this feature is working and which configuration items exists.

Content

Introduction

Since DR 3.1.32 the DR has not anymore its own SMTP implementation. It uses an KGS common approach, now. This approach is realized by the usage of the KGS SMTP Connector .

Configuration

In order to use it, we need to choose the instances configured in SMTP Connector plugin by configuring a comma separated list of KGS SMTP Connector instances.

see:

• DR4 - SMTP - TAB

How it works

In KGS SMPT connector plugin you can configure instances. Every instance contains beside the SMTP credentials topics and email recipients. I will call it a tupel.

The DR configures to which of this tupels it will propagate all of its events.

So we need to configure these:

• configure an recipient list and the topics to be covered in KGS SMTP Plugin as an instance

• configure the DR so, that it sends its events to this SMTP instance

Events

The DR is producing some events. E.g. if the has happen an SAP error. These events are mapped to topics. The event is a topic. It is a one by one relation. Ergo every event is send to its own topic.

Topics

The DR is producing these topics:

Related Articles and Links

• KGS SMTP Connector

Content

Overview

The multipart interface can accept multipart messages (https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html ) with files for a configured and started DocumentRouterInstance.

Each part is saved as a file using the filename from the Content-Disposition header. An index file is created according its schema definition. Each Part is handled individually.

It is possible that some parts can be saved and other parts are rejected for multiple reasons.

The files are archived directly (synchrone). They are temporarily stored in a temp folder, which is deleted after request is handled.

Interface

X-index-<key> Header

The X-index-<Key> headers are used to build the idx file. Any number of headers per part is allowed. Make sure that X-Index header fields do have all keys required by schema file (field position > 0)

A special order of the fields is not required.

Example:

The idx files contains only the values.

field names in Content-Disposition header can’t be changed.

Example for Postman

You can use this sample with postman:

Example 2 for Postman

URI

HTTP POST http://localhost:8090/KGSAdmin-DR-4.0.7/documentrouter?CREATE&instanceName=IndexFileBased

Headers

Content-Type: multipart/form-data; boundary=0kao5EFK-fUENGjSjSlfk3DnForlirbP4

Body

--0kao5EFK-fUENGjSjSlfk3DnForlirbP4
Content-Disposition: form-data;  name="file1"; fileName="fileone.pdf"
Content-Type: application/pdf
Content-Length: 3
X-index-ImageFileName: fileone.pdf
X-index-repository: FI
x-index-SAP_OBJECT_ID: 100019000000002021
Content-Transfer-Encoding: binary

abc
--0kao5EFK-fUENGjSjSlfk3DnForlirbP4
Content-Disposition: form-data;  name="file2"; fileName="filetwo.pdf"
Content-Type: application/pdf
Content-Length: 3
X-index-repository: FI
X-index-ImageFileName: filetwo.pdf
x-index-SAP_OBJECT_ID: 100019000000002021
Content-Transfer-Encoding: binary

abc
--0kao5EFK-fUENGjSjSlfk3DnForlirbP4--

Cache Directory and config

Multipart request can contain files of any size. All files bigger than a certain value will be saved in the cache directory and deleted after processing in: <Instance WorkDirectory>/multipartcache. Make sure that the DocumentRouter has read and write permissions. In certain scenarios it could make sense to change the cache size to prevent to many files in memory and a possible out of memory exception. Configure the default value in bytes in the Instance Config in “Common”-Tab:

When the file exceeds this value it is not stored in memory but saved in the cache directory.

Possible Return Codes

 [{
        "statuscode": <errorCode>,
        "message": <error Message>,
        "filename": <Filename that could not be processed>
 }]

Response Bodies

201

[
    {
        "statuscode": 201,
        "message": ""
    },
    {
        "statuscode": 201,
        "message": ""
    }
]

400

503

{
    "statuscode": 503,
    "message": "DR instance IndexFileBased not running."
}