The service establishes the connection between SAP and the yuuvis® Momentum system and organizes and manages storage and retrieval of documents in both yuuvis® Momentum and SAP.

Characteristics

Function 

The SAP object types are mapped to yuuvis® Momentum object types that are defined in the repositorymanager app schema. The access to yuuvis® Momentum is managed via a technical user account having full access to objects of types defined in the repositorymanager app schema.

Inserting a Document in yuuvis® Momentum by Barcode Upload

The Document and its Data

If a document is inserted into the yuuvis® Momentum system, the corresponding document will be given a barcode and an ArchiveLink version (AL version) is created. The barcode is specified during the capture process (e.g., a barcode label is applied to a document).

The barcode links the document with a business process until the SAP system has linked an SAP business object to the document ID.

At this point it is not yet allowed to set the 'Barcode sent to R3' document flag. All other index data of the document and components need to be already filled in, in particular the unique DocID.

In regular intervals, yuuvis® Momentum REPOSITORYMANAGER determines all documents that have a barcode and no BarcodesenttoR3 flag. For these documents, an entry will be inserted in the barcode file, which is written in the configured Work/Barcode directory.

Reporting the Document to the SAP System

By calling the function WriteBarcodeFile, the REPOSITORYMANAGER service determines in cyclic intervals all barcodes and document IDs that have not yet been reported to the SAP system. The corresponding values of the documents to be reported are written to a file in the Work\Barcode directory by the REPOSITORYMANAGER service. This file contents may look as follows:

<Barcode1> FI <Document-ID1> 20090623 FAX
<Barcode2> FI <Document-ID2> 20090623 FAX
<Barcode3> FI <Document-ID3> 20090623 FAX

Barcode values cannot contain any spaces because the space is used as a separator here.

The documents concerned by this process can be specified using the BarcodesenttoR3 field as otherwise this field's value is set to true. This field will be created in the REPOSITORYMANAGER service by reporting the barcode to the SAP system.

The barcode file is read again and contained information reported to SAP. For each reported document, the BarcodesenttoR3 document flag will then be set in yuuvis® Momentum. This is a sign that the barcode has been reported successfully. Additionally, all information about the sent barcode will be entered in the current barcode file of the Success subdirectory of the Work/Barcode directory. If errors occur, an entry will be made in the current barcode file in the Error directory parallel to the Success directory. There also exists an RDY file in this context.

Referencing a Document in the SAP System

When the barcode is reported to SAP, the document ID and the barcode will be entered into the SAP table BDS_BAR_EX for open external barcodes. This table includes all externally captured documents that own a barcode and are therefore identified by a document ID but could not have been internally assigned to an SAP object and a business process respectively in the SAP system.

Barcode files are exchanged in the <WorkingDirectory> in the barcode subdirectory. If the exchange file has been processed correctly by the content server, the barcodes will be entered in the <WorkingDirectory>\barcode\successful\yyyymmdd.txt file.

If barcodes have not been processed correctly, they will be entered in the <WorkingDirectory>\barcode\error\yyyymmdd.txt file.

A maximum of 5,000 barcodes can be reported in a reporting interval.

Linking a Document to an SAP Object

In the SAP system, a business process (SAP object) can be assigned to a document. For example, the booking of a payment transaction. During this process, the barcode of a business transaction will be filed together with the SAP object ID in the SAP table BDS_BAR_IN of open internal barcodes.

The document ID is referenced with the barcode in the SAP table for the open external barcodes and the barcode is referenced with an SAP object ID in the table for the open internal barcodes. Thus, the SAP object ID and the document ID can be linked. This is done automatically. Thereby, SAP object ID and document ID will be included in the SAP link table TOAXX taking into account the repository. Linking an yuuvis® Momentum document to an SAP process is thus completed. After linking, the barcode is no longer known to the SAP system and can only be searched in the yuuvis® Momentum system.

Data Flow Diagram

The following diagram depicts the data flow when a document is given to the SAP system.

Archiving of Data from the SAP System

Receipts (documents), print lists, and reorg data (data backups) may be stored. In this case, the document ID is transferred to the yuuvis® Momentum system. Barcodes are not transferred here.

Requirements

The REPOSITORYMANAGER service requires the yuuvis® Momentum core services (version 2021 Autumn or later) and the corresponding infrastructure.
>> yuuvis® Momentum Requirements

Additionally, the service requires:

• ActiveMQ
• Space for PersistentVolumeClaim, 10 GB recommended

Installation

The service is delivered as docker container image. For the deployment to the yuuvis® Momentum cluster, you need a deployment and a service script as shown in the example code blocks below. The parameters have to be adjusted according to your own cluster. However, please use the /working-dir path for the PersistentVolumeClaim.

apiVersion: v1
kind: Service
metadata:
  namespace: $NAMESPACE
  labels:
    app: yuuvis
    name: repositorymanager
    yuuvis: "true"
  name: repositorymanager
spec:
  ports:
    - name: "http"
      port: 80
      targetPort: 8010
      nodePort: 30036
  type: NodePort
  selector:
    name: repositorymanager

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-repositorymanager
  namespace: $NAMESPACE
spec:
  storageClassName: local-path
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 2Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: $NAMESPACE
  labels:
    app: yuuvis
    name: repositorymanager
  name: repositorymanager
spec:
  replicas: 1
  selector:
    matchLabels:
      name: repositorymanager
  template:
    metadata:
      labels:
        name: repositorymanager
    spec:
      containers:
        - name: repositorymanager
          image: docker.optimal-systems.org/team-kookaburra/$CI_PROJECT_NAME:commit-$CI_COMMIT_SHORT_SHA
          imagePullPolicy: Always
          env:
            - name: JAVA_OPTS
              value: -Xmx128m
            - name: SPRING_CLOUD_CONFIG_URI
              value: "http://configservice/config"
            - name: SPRING_PROFILES_ACTIVE
              value: prod,docker,kubernetes
          ports:
            - containerPort: 8010
          volumeMounts:
            - name: storage
              mountPath: /working-dir
      volumes:
        - name: storage
          persistentVolumeClaim:
            claimName: data-repositorymanager
      restartPolicy: Always
      imagePullSecrets:
        - name: osgitlab

Configuration

Configure Kubernetes Cluster

Following steps should be performed:

• Expose the REPOSITORYMANAGER service via a Kubernetes Node port to the local network. In the example configuration shown in the code block below, the REPOSITORYMANAGER service will be accessible in the local network by the IP address 10.11.0.139:30036).

  Example Kubernetes cluster configuration Expand source

  kind: Service
  apiVersion: v1
  metadata:
   name: repositorymanager
   namespace: yuuvis
   selfLink: /api/v1/namespaces/yuuvis/services/repositorymanager
   uid: b6d587ee-a412-4678-a3bc-c3fd544825da
   resourceVersion: '58178661'
   creationTimestamp: '2021-01-12T12:57:18Z'
   labels:
     app: yuuvis
     name: repositorymanager
     yuuvis: 'true'
   annotations:
   field.cattle.io/publicEndpoints: >-
  [{"addresses":"10.11.0.139"],"port":30036,"protocol":"TCP","serviceName":"yuuvis:repositorymanager","allNodes":true}]kubectl.kubernetes.io/lastapplied-configuration: >
  {"apiVersion":"v1","kind":"Service","metadata":{"annotations":{},"labels":{"app":"yuuvis","name":"repositorymanager","yuuvis":"true"},"name":"repositorymanager","namespace":"yuuvis"},"spec":{"ports":[{"name":"http","nodePort":30036,"port":80,"targetPort":8010}],"selector":{"name":"repositorymanager"},"type":"NodePort"}}
  spec:
   ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 8010
      nodePort: 30036
   selector:
     name: repositorymanager
   clusterIP: 10.43.32.201
   type: NodePort
   sessionAffinity: None
   externalTrafficPolicy: Cluster
  status:
   loadBalancer: {}

• Create an DNS A in DNS Hoster: A Record saprm.con.yuuvis.org points to Reverse proxy (213.61.129.160).

• Configure the Revers Proxy: Configure the Reverse proxy to redirect requests for saprm.con.yuuvis.org to the Kubernetes Service on 10.11.0.139:3006

Configure Cluster Firewall

The REPOSITORYMANAGER service, more precisely barcode functionality, needs access directly from the pod there it's running to the SAP system. For this reason firewall entry needs to be added, on cluster level, to allow communication to the SAP system.

Provide to cluster administrator the IP:port info of the SAP system that will have a RFC connection for the barcode functionality to work properly. The configurations have to be carried out on the KGS Administration Page that is accessed via the following address: http://<host>/repositorymanager/cs/

The default port is 8010, the user name is admin, and the password is admin.

After logging in, you can change the login credentials via OSGi > Configuration > Application Framework Management Console:

Go to Main > KGS SAP Connector.

An SAP connector is required for the RFC configuration later on.

In the Configuration Editor, configure a debug level between 0 and 4. For productive systems, value 0 is usually set.

The barcode scenario is set up using the following steps.

• Create a bridge connection via Main > KGS SAP Connector > Bridge Status > Generate Bridge.
  

• Create a connection via Main > KGS SAP Connector > Add config.
  

• Edit the connection via Main > KGS SAP Connector > Edit. The following entries need to be made: Description, SAP AS Host, SAP System Number, SAP Client, SAP User, SAP User Password, SAP Language
  
• Configure the repositories via Main > Contentserver4ArchiveLink > Edit and adjust the values in the following tabs:
  • License - Specify the KGS-license key.
  • Barcode - Tick the Enable Barcode checkbox.
  • Protocol - For normal work mode, untick all checkboxes.
  • Common - Adjust only the debug level if necessary.
  • Security
    • Configure the default security level for the communication between SAP and embedded tomcat:
      0 - no suage of certiicate
      1 - certificate is used, but not validated
      2 - certificate is used and validated
      We recommend level 2 for productive systems.
    • Specify the clients that should be allowed to change the certificate via Allowed CSAdmin Clients. Avoid the usage of a wildcard. Specify only the needed IP addresses instead.
  • RFC - Choose one of the connections you configured before.
  • Components - Usually no changes needed. In case you see a need, please contact your OS or KGS consultant.
  • Backend - Usually no changes needed. In case you see a need, please contact your OS or KGS consultant.
  • Content - Usually no changes needed. In case you see a need, please contact your OS or KGS consultant.
  • Index Export - If barcode upload is used, the time period for requesting new barcodes could be adapted here. Please ensure that the period in productive systems is long enough to avoid overlapping runs (1800 s recommended). 
  • ILM - Set ILM for the ILM Repository. Enter user and password of an existing SAP account that should be used for the connection.
• Assign a configuration at repository level or global level via Main > ContentServer4ArchiveLink > Edit > RFC > RFC Connection Name. The barcode configuration you create will be assigned. To use barcode synchronization from multiple SAP systmes, remove any global barcode configuration and use the configuration at repository level instead.
  • Repository level:
    
  • Global level:
    
• Enable barcode via Main > ContentServer4ArchiveLink > Edit Configuration > Barcode > Enable barcode.
  
• Define the barcode timer via Main > ContentServer4ArchiveLink > Edit Configuration > Index Export > BarcodeTimer. Recommended: 60 (seconds)
  
• SAPMimeExtensionLookup needs to be enabled for correctly assigning file formats to document types. Enable SAPMimeExtensionLookup via Main > ContentServer4ArchiveLink > Edit Configuration > Common > SAPMimeExtensionLookup
  

Adjust Service Configuration

In case of a standard installation, the service configuration parameters are specified in the corresponding application.yml file and are set to reasonable defaults. Those default values can be overwritten by specifying a different value in the repositorymanager-prod.yml configuration file. Especially, the parameters configuring the ActiveMQ connection have to be adjusted:

• spring.activemq.broker-url
• spring.activemq.user
• spring.activemq.password

Note: KGS/CS-Admins should limit the free access for SAP-systems to ensure that only relevant SAP systems can store data to an certain tenant.

Parameters of the repositorymanager-prod.yml configuration file:

The following code block shows an example configuration.

repository-manager:
  barcode:
    cntType2docType: Image/TIFF=FAX|application/pdf=PDF
    default-docType: TIF
    
core:
  api:
    url: https://client.con.yuuvis.org
    username: root
    password: optimal
    tenant: default

spring:
  activemq:
    broker-url: tcp://repositorymanager-mq:61616
    user: admin
    password: admin

Configure the App Schema

The REPOSITORYMANAGER service requires the repositorymanager app schema shown in the code block below. It is imported to yuuvis® Momentum via the endpoint POST /api/system/apps/{app}/schema.

The app schema contains the document object type definitions archiveLinkComponent and ilmObject.

Properties of 'archiveLinkComponent'

Objects of type archiveLinkComponent will be used both for documents (logical placeholders) and components (actual documents with content). It contains metadata related to ArchiveLink documents and ArchiveLink components.

Properties of 'ilmObject'

The objects of type ilmObject have the common ILM properties (URL and properties table), as well as a content length property and a type property.

SSL Configuration

Valid for: yuuvis® Momentum REPOSITORYMANAGER version 7.x

As a general rule, a certificate for data consistency and security must be imported and the repositorymanager-prod.yml configuration file must be modified accordingly, the certificate needs to be integrated in yuuvis® Momentum service-manager, and corresponding adaptations must be made to the SAP SSL configuration to communicate with SAP.

Certificate

The free software OpenSSL can be used to generate a certificate for development and test systems. For example, once OpenSSL has been installed, the following commands can be executed to generate a certificate. The first commands define an individual password for the certificate and its parameters.

set pass=pass:optimal
set caSubj=/C=DE/ST=DE-DE/L=Berlin/CN=localhost

openssl genrsa -des3 -passout %pass% -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt -subj %caSubj% -passin %pass%
openssl pkcs12 -inkey ca.key -in ca.crt -export -out ca.p12 -passin %pass% -passout %pass%

Executing them will create the ca.crt, ca.key, and ca.p12 files.

Copy the ca.p12 file to the directory specified in the repositorymanager-prod.yml configuration file. Example:

\service-manager\apps\repositorymanager

The repositorymanager-prod.yml Configuration File

The repositorymanager-prod.yml configuration file in the \services\service-manager\config\ directory must have the following entries added to it:

eureka:
  instance:
    ip-address: localhost
    hostname: localhost
    non-secure-port-enabled: false
    secure-port-enabled: true
    secure-port: ${server.port}
    statusPageUrl: https://localhost:${eureka.instance.secure-port}/manage/info
    healthCheckUrl: https://localhost:${eureka.instance.secure-port}/manage/health
    secureHealthCheckUrl: https://localhost:${eureka.instance.secure-port}/manage/health
    homePageUrl: https://localhost:${eureka.instance.secure-port}/

server:
  ssl:
    enabled: true
    key-store-type: PKCS12
    key-store: <Path_service-manager>/apps/repositorymanager/ca.p12
    key-store-password: optimal
    key-alias: '1'
    enabled-protocols: 'TLSv1.2,TLSv1.3'

security:
  require-ssl: true

Following this, the 'REPOSITORYMANAGER' microservice must be restarted.

Integration in yuuvis® Momentum service-manager

A certificate can be integrated using the command prompt or using tools such as KeyStore Explorer.

Command prompt:

• Execute the following commands in the command prompt:

  <Path_service-manager>\jdk\bin\keytool ^
      -importkeystore -srckeystore <Path_service-manager>\apps\archiveservice\ca.p12 ^
      -srcstorepass optimal -destkeystore <Path_service-manager>\jdk\jre\lib\security\cacerts ^
      -srcstoretype PKCS12 -deststoretype JKS ^
      -deststorepass changeit

  Adjustments:

  -importkeystore -srckeystore	Path to the certificate
  -srcstorepass	Password for the certificate
  -deststorepass	Password for certificate administration Default: changeit

SAP Configuration

• Call the 'STRUST' transaction.

• Go to 'SSL Client Standard'.

• Switch to the Edit mode.

• Click the Import button.

• Specify the certificate.

• Select 'Add to Certificate List'.

• Save the configuration.

In addition, the host name of the respective SAP system must be edited such that the host name of the imported certificate is mapped to the IP address of the server for which the certificate was issued.

AL and ILM Connections

For AL and ILM connections, the HTTP server inputs must correspond to the hostname of the certificate, not the IP address.

In the 'Logon&Security' section, enable the 'SSL active' option and select the appropriate certificate list into which you have previously imported the certificate.

For configuration details, refer to the SAP documentation.

Configuration of the SAP System

Valid for: yuuvis® Momentum REPOSITORYMANAGER version 7.x

To connect the SAP system with the HTTP content server and make all necessary settings, we recommend following the SAP guidelines using the SPRO transaction under Netware > Application Server > Basis Services > ArchiveLink.

For customizing the interface for print lists and outbound documents, we recommend attending the SAP course BIT615.

For filing reorg data, we recommend attending the SAP course BIT660.

The main transactions required to establish a connection are listed below:

Transaction OAC0 defines one or several repositories.

This and all further activities within the SAP system have to be undertaken by the SAP system administrator or another authorized user of the customer.

These activities include:

• For the first time:

  • Creation of a communication user (SU01) with the corresponding authorizations (SAP_BC_ENDUSER, SAP_BC_SRV_ARL_ADMIN, SAP_BC_SRV_ARL_USER, SAP_BC_SRV_COM_ADMIN)

  • ArchiveLink: maintenance of basic settings (OAG1)

  • Creation of number range intervals (OANR) for print lists

  • Create log (OAA3) or import prepared transports from OPTIMAL SYSTEMS with the log.

  • Creation of an archive device (name ARCH) as output device (SPAD), assignment of the SAP ArchiveLink archiver, hostspool access method (I: archiver)

• One or several times; depending on how many content repositories have to be defined:

  • Creation of a content repository (OAC0)
    DocArea – ArchiveLink
    Filing method – HTTP content server
    Log – OPTIMALA
    Version no. – 0046 or 0047
    http script – cs/contentserver
    Output device – ARCH
    HTTP server – name or IP address of the server on which yuuvis® Momentum REPOSITORYMANAGER is running
    Port number – The port used to access yuuvis® Momentum REPOSITORYMANAGER (default: 8010).

  • After successful configuration of yuuvis® Momentum REPOSITORYMANAGER, the certificate (OAC0/CSADMIN) has to be sent and activated for each repository.

Organizational Notes

Valid for: yuuvis® Momentum REPOSITORYMANAGER version 7.x

The environment will need to be configured specifically in order to run yuuvis® Momentum REPOSITORYMANAGER properly in a compliant and high-performance manner.

• The objects/resources should be archived using the yuuvis® Momentumarchiving actions to ensure that they cannot be changed or deleted. This action should be run at least once a day to ensure that the documents can be deleted on the exact day they should be deleted.

• Retention periods are propagated to supported storage systems such as NetAPP vis the yuuvis® Momentum standard mechanism. If, on the SAP side, the retention time is still unknown, nothing is propagated and the media configuration defines the retention time for an object.

• To ensure that the retention time is specific to the object, the retention time for the media should be set to the minimum, which is usually 1 day.

• ILM documents should only be deleted using the ILM interface, which is why only the technical user should have this right.

• AL documents should only be deleted using the AL or ILM interface, which is why only the technical user should have this right. Even if the expiration date is in the past, data needs to be retained until the deletion command is issued by SAP.

• The option Check retention period when deleting must be enabled in the media configuration.