SAP Module Routty Cloud - Full configuration guide

Introduction

Description

Routty SAP Package - Routty is a package with various ready to use options to synchronize data between an SAP system and Routty.

It is possible to directly upload master data from SAP to Routty Cloud like companies, vendors or customers.

Documents from Routty (inbound process), including their images, can be downloaded to SAP and processed in various ways (IDOC, store as files, push to Process Director, custom SAP processing). And you can create any kind of Process Director document from the downloaded data, not only an AP document.

You can also transfer billing documents from SAP (Accounts Receivable, outbound process) to Routty Cloud. They are sent together with generated PDF based on the output configuration.

It is possible to send AP documents from the SAP system to Routty, for example for reporting reasons.

You can leverage the options from SAP transaction SM59 for the specification of a proxy connection.

The package can be used as well for customers without a Process Director installation. Documents and images can be for example directly added as an IDOC or handled by custom code.

This document describes how to configure and use Routty SAP Package - Routty Cloud and the specific functions that are delivered with it.

Activation and use of Routty SAP Package - Routty

This chapter will cover end-to-end guide on how to install and configure Routty SAP Package - Routty in your SAP environment.

Transport import

Please check if SAP note 2050393 needs to be applied when you operate on older SAP stacks.

Basis package 740 is required. Older SAP releases require manual adjustments.

Full implementation of Routty SAP Package - Routty is based on SAP ABAP and it is required to import transports provided by Routty to make it available on your SAP system. Transports will be provided as external transports and its import should be done using standard SAP mechanism.

All objects that are carried in transports have prefix ZDYN* and are stored in package ZDYN_WEBSERVICES.

Below are the steps to carry external transport import:

1. Extract the ZIP file in the SAP transport folder (...\TRANS\).

2. The transport files are already in the correct COFILES and DATA subfolders.

3. If it is impossible to extract the transport files directly into the SAP transport folders (for example, because there is no direct access to the file system on the SAP application server), you have to use a binary method to transfer the files (for example, FTP). See SAP OSS note 2050.

4. Start SAP transaction STMS (or use the command line using the TP program).

5. Open the import queue of the SAP system.

6. Go to Extras > Other requests > Add.

7. Add Routty SAP Package transport request to the import queue in the order listed below.

SAP standard configuration

Some of these steps are optional and might only be necessary depending on requirements from the project.

SM59 - Specify destination to Routty

Routty SAP Package uses destinations specified in SM59 instead of direct HTTPS calls.

This option can also be required when you need to communicate across a proxy server.

Depending on the current implementation of Routty, at least two or three destinations are required:

• one for the API (admin-express.routty.io)

• one for blob storage for inbound documents (export.routty.io)

• one for blob storage for outbound documents (import.routty.io)

Create connections of type G (HTTP Connection to external server).

Target Host is the Routty server.

Enter the proxy options if required.

Enable SSL by selecting Active under Logon & Security

SSL Certificates

You need to install SSL certificates to enable the RFC to connect to the server via HTTPS.

For API and document transfer there should be one root certificate from CA GlobalSign.

The certificate will be provided together with installation files for the Routty SAP Package or you can download it from the web site directly. It can be for example the https://import.routty.io/ website.

Verify the certificate branch configured in the RFC source.

Install the certificate in the SAP system using the STRUST transaction in the branch chosen in the RFC source.

Import the certificate and add it to the certification list.

In case the SSL connection cannot be establish you can also try to install intermediate certificates (those between the root one and the site one) or even the site certificate. The last option is however not recommended, since this certificate will be the first to expire and can be replaced by the site administrator.

In case you are receiving errors like: “Server certificate does not match supplied TargetHostname SapSSLSessionStartNB()==SSSLERR_SERVER_CERT_MISMATCH”, the SNI mechanism seems to be inactive. Server Name Indication (SNI) is a TLS extension that enables connections to virtual servers, in which multiple servers for different network names are hosted at a single underlying network address. To enable SNI in the SAP system, switch the following parameter in the RZ11 transaction to TRUE:

icm/HTTPS/client_sni_enabled

FILE - Define logical path

When you use the option to store downloaded document data and the image on the SAP server, you need a logical path for this. If the path needs to be created, you have to do this in transaction FILE.

See instructions in SAP Wiki

WEDI – IDOC configuration

When you want to create an IDOC and you use the delivered standard transformation, you have to create:

The logical system definition for Routty in transaction SALE

Basic Settings->Logical Systems->Define Logical System

And the following partner definition in transaction WE20

Partner No. ROUTTY
Partn. Type LS

For Inbound parameters. create a new entry for:
Message type: INVOIC
Process code: INVL

Other process code than the default INVL can be used, for instance when a third party logic already exists for document processing. Process code can be created or edited in the WE42 transaction.

From the SPRO customizing tree you have to maintain several values for the combination LS ROUTTY in case standard logic is to be used.

For each company code you have to maintain the EDI program parameters in transaction OBCE

You have to assign the external company code to an internal value

and maintain a GL account for Goods/services

For tax code determination settings need to be applied in transaction OBCD:

For automatic partner determination the external supplier ID from Routty need to be entered as EIKTO number for the corresponding company code (Correspondence) of transaction XK02 (vendor master data maintenance).

Archive link customizing

For archiving the image you have to create an entry in transaction OAC3 for the used archive document type.

For IDOC storage entries for business object IDOC.
For the Process Director AP entries for /COCKPIT/B.
For Process Director other document types the corresponding ones (e.g. /EBY/PDPA for remittance documents).

And in additional for the posted/target business objects (e.g. BKPF, BUS...).

SAP authorizations

Users who want to configure and/or run synchronizations need authorization for the following transactions:

Process Director configuration

When the data should be passed to Process Director some Process Director configuration needs to be added. For creating a PD AP document the required configurations are attached and can be imported using the report /EBY/PDBO_CONFIG_DUMP for Object type IV.

Routty_config.xml

Customer external data models

The configuration included in the embedded XML files will generate the following entries in transaction /EBY/PDBO_VDMOC for the to be created Object type.

When the XML file content is not used or other Process Director Object types should be created, the entries have to be created manually.

For IV the following entries are required.

When entries exist, it will be possible to map COCKPIT fields to the corresponding levels
and to map custom fields to custom header fields using the Process Director mapping functionality configured in transaction /EBY/PDBO_VMAPC (see next chapter).

Configuration for other optional document types as remittance documents or delivery notes (DN) will be similar.

Mapping instructions

The embedded XML files contain also all required entries of transaction /EBY/PDBO_VMAPC where for the corresponding Object type the field mapping needs to be applied.
Origin XB has to be used. Mapping ID by default is ROUTTY but can be changed in the corresponding configuration started from transaction ZDYN_WS_ROUTTY_EXP or directly using ZDYN_WS_REX_TMAP.

NOTE: Only the fields available in the technical field list for MST_DOCUMENT can be mapped.
Essential is that the GUID field is properly mapped to block the creation of duplicates!

Custom header fields are stored in the external table CUSTOM as NAME/VALUE pairs.
They can be mapped using Check field and Check value to control the source and target fields.

For example:
Mapping field value from custom field ZFIELD1 to the PD AP field ZDYN_FREEFIELD01 is done using:

Always using the pattern
Node ID = CUSTOM
Check field = NAME
Check value = custom field name
External field name = VALUE

External field names in the mapping configuration equal the internal fieldnames for AP with a few exceptions (CURRENCY, STCEG)

Mapping functions can be used as required. 

Authorizations

The following authorizations are required in the SAP system to allow the user, in context of which the Routty SAP Packing is run, to create Process Director documents.

They are not specific to the Routty SAP Package in any sense, only to the Process Director itself.

Object: S_RFC

RFC_TYPE: FUGR

RFC_NAME: /COCKPIT/EDI_RFC, /COCKPIT/IM_RFC, /COCKPIT/INTERFACE, /COCKPIT/MA_RFC, /COCKPIT/SWC_NOTE, /COCKPIT/WB_RFC, /COCKPIT/WB_RFC46, /COCKPIT/WC_RFC, RFC1, RFCH, SDIF, SDIFRUNTIME, SM02, STFC, SYST, SYSU

Object: S_TCODE

TCD: /COCKPIT/1

Object: S_ARCHIVE

ACTVT: all
APPLIC: all
ARCH_OBJ: *

Object: F_LFA1_APP

ACTVT: 03, 08
APPKZ: all

Object: F_LFA1_BEK

ACTVT: 03, 08
BRGRU: *

Object: F_LFA1_BUK

ACTVT: 03, 08
BUKRS: *

Object: F_LFA1_GEN

ACTVT: 03, 08

Object: F_LFA1_GRP

ACTVT: 03, 08
KTOKK: *

Object: M_BEST_BSA

ACTVT: 03, 08, 09
BSART: *

Object: M_BEST_EKG

ACTVT: 03, 08, 09
EKGRP: *

Object: M_BEST_EKO

ACTVT: 03, 08, 09
EKORG: *

Object: M_BEST_WRK

ACTVT: 03, 08, 09
WERKS: *

Object: M_RECH_WRK

ACTVT: all
WERKS: *

Main Report

Configuration

On the top of the report screen which is started by transaction ZDYN_WS_ROUTTY_EXP you have 6 buttons to start various configuration maintenance dialogs.

ZDYN_WS_REX_TGEN General configuration

Transaction ZDYN_WS_REX_TGEN or the first button in the report opens a maintenance dialog for the general configuration.

This configuration data contains settings for each activity in the Routty module.

For the combination of SAP system ID and configuration ID, you can specify:

ZDYN_WS_REX_TMAP Process Director configuration (for inbound document)

Transaction ZDYN_WS_ROUTTY_TMAP or the second button in the report opens a maintenance dialog for the optional special settings when transferring the data to Process Director.

By default, when nothing is configured or an empty value is entered, an AP document is created (Object type IV) using Origin XB and Mapping ID ROUTTY is used.

In case a different document type should be created (Object type) or a different Mapping ID should be used, a corresponding entry needs to be placed here which then has to be configured in the Process Director mapping configuration and the external data model configuration.

Note: for e.g. remittance document handling Object type PA has to be used, for delivery notes DN,...

ZDYN_WS_REX_TARC Archive configuration (for inbound document processed as IDoc)

Transaction ZDYN_WS_REX_TARC or the third button in the report opens a maintenance dialog for the optional archive link settings where you select the Archive Document type to be used for images.

Only required when you have more than one archive document type defined for PDF or you don't pass the documents to PD.

ZDYN_WS_REX_TARI Outbound documents output configuration

Transaction ZDYN_WS_REX_TARI or the forth button in the report opens a maintenance dialog with configuration specific for the outbound document (billing document, accounts receivable) output logic.

Parameters taken from the NACE transaction can be specified:

Those parameters allows the report to find the information based on which XML and PDF for outbound document will be created, like for example SAP smartform that will be used to generate PDF output.

Only the an entry with application (usually V3) is obligatory.

ZDYN_WS_CXMPC Outbound documents – structure mapping

Transaction ZDYN_WS_CXMPC or the fifth button in the report opens a maintenance dialog for outbound documents to modify the way SAP fields in structures are mapped to the output structures.

The maintenance view shows standard configuration (blue color) and customer entries (black color). The standard configuration is provided by default. You can modify it by adding new or deactivating existing entries as customer entries.

ZDYN_WS_CXMLC Billing documents – XML mapping

Transaction ZDYN_WS_CXMLC or the sixth button in the report opens a maintenance dialog for outbound documents to modify the way the output structures are mapped to the output XML.

The maintenance view shows standard configuration (blue color) and customer entries (black color). The standard configuration is provided by default. You can modify it by adding new or deactivating existing entries as customer entries.

ZDYN_WS_CDOC Output document types (not available on the screen)

Transaction ZDYN_WS_CDOC opens a maintenance dialog for output document type definitions.

The content is provided in the standard. Customer entries can be added here as well.

ZDYN_WS_CALS Aliases for mapping (not available on the screen)

Transaction ZDYN_WS_CALS opens a maintenance dialog for aliases used in structure to XML mappings in transaction ZDYN_WS_CXMPC.

The content is provided in the standard. Customer entries can be added here as well.

Report options

The report offers the following functions for a configured combination of SAP system ID and configuration ID (general configuration).

Communication

ID – configuration set ID, obligatory for all the activities

Message level – the amount of messages generated. For normal work in background level 0 or 1 is recommended. For debugging – level 2. In this last level the call stack is also included:

All generated messages can be stored in an Application log, which is recommended for background processing, by selecting the checkbox Appl. log enabled.

Application Log Object ZDYN_ROUTTY is defined with Subobject:

• SYNC for master data population to Routty

• DOCUMENTS for inbound and outbound documents from and to Routty

Activity

Check Connection: Only tries to ping the configured Routty server
Result: Message PONG when connection is correctly established:

Master data: Is pushing SAP master data to Routty for the selected Company Code

Retrieve documents: Gets documents (inbound) ready for download from Routty and processes them as defined in the general configuration

Send documents: Generates data for billing documents (outbound, Accounts Receivable) in XML format with embedded PDF file.

Send AP documents: Generates data for AP documents (outbound, Accounts Payable) in XML format.

Master data

When selecting option Master data you get a selection screen where various SAP data can be synchronized to Routty.

All changes will be reflected in corresponding messages (number of entries Added, Changed, Deleted).
When nothing is selected for a data type, no synchronization is triggered.

Value helps exist to simplify entering selection criteria.

For company code specific master data, including company code themselves, the Company Code field needs to contain their set. Also, for such data the company code themselves need to be synchronized not later than the data that depends on them. For example to synchronize vendors, the company codes need to be synchronized before or together with vendors.

Two other settings are general as well:

Note: When using the current date as Date of last change, the day before is used as selection criteria to enable a proper selection of all modifications using a scheduled report run using the current date as value.

The customers and vendors can also be stored in files.

In the selected folder CSV files will be created, separate for customers and vendors. Depending on the number of objects multiple files can be created with 5000 entries each.

The Test flag is transferred to the entries in the file to mark them in Routty.

Mapping SAP - Master data

Suppliers

Receive documents

While using this option, documents from Routty that are ready for download are processed according the general configuration import option.

No additional filter is available.

Test options

There are various options available that can help during implementation and testing phases.

Do not send feedback

Normally, when a document is retrieved without errors a feedback is send to the Routty system, which changes its status there. Such a document will not be available during the next request anymore. It is possible to suppress it for test purposes, such that the same document would be available many times and the data flow in SAP could be verified and improved.

Skip attachments

The archiving system in SAP may not be ready at the initial phase of implementation. Errors can be raised in such cases. To avoid them, attachments can be temporarily skipped.

Get from local file

For testing purposes a local file with XML document can be used instead of actual documents from Routty.

In this case the process runs according to the configuration, only the document will be taken from the file. The file name will be taken as the document GUID.

Store in local file

The data being sent from Routty can be stored in a local file. It can be then reviewed or used as a data source for the Get from local file option. The file name will be created based on the document GUID. This way the file can be used multiple times to verify the process on the SAP side without interaction with Routty.

Send documents

After having selected this option, selection criteria are displayed:

The documents can be selected based on document number, company code, customer number and various other criteria.

Creation date is obligatory to ensure valid document selection.

Numbers can be provided as single or multiple values. Ranges are also allowed.

To protect against duplication in Routty, a mechanism is implemented that stores all the document numbers sent during the last 3 years (activated by default by the Use register flag).

Additionally, the report won’t select documents older than 3 years.

Optionally, a PDF can be generated and embedded in the data sent to Routty (Include PDF flag).

It’s possible to decide whether attachments are added (Add attachments flag) and whether they are required (Require attachment flag, the document won’t be taken if it has no attachments).

Additional selection criteria are available in the dynamic section for billing document and customer data:

The values entered can also be stored in selection screen variants.

After the documents have been sent, messages are display (here with log level 1):

The documents can also be stored in files.

In this folder separate XML files will be created for each document.

Send AP documents

This activity can be used to report AP invoices posted in your system to governmental institutions.

After having selected this option, selection criteria are displayed:

The documents can be selected based on document number, company code, fiscal year and various other criteria.

Numbers can be provided as single or multiple values.

To protect against duplication in Routty, a mechanism is implemented that stores all information about the documents (number, company code and fiscal year) sent during the last 3 years (activated by default by the Use register flag).

Additionally, the report won’t select documents older than 3 years.

The values entered can also be stored in selection screen variants.

After the documents have been sent, messages are display (here with log level 1):

The documents can also be stored in files.

In this folder separate XML files will be created for each document.

Report for documents sent

Documents sent with the flag Use register checked can be reviewed in a report available in transaction ZDYN_WS_ROUTTY_EXP_O.

The DocumentNo column is a hotspot and allows to jump to the VF03 or FB03 transaction, depending on the document type. The sold-to party column is a hotspot as well and redirects to the XD03 transaction.

Enhancements

Enhancement Options

In case of special requirements the following options for project specific adjustments are available.

Custom XSLT transformations

It is possible to simply copy the standard XSLT transformations ZDYN_ROUTTY_IV_TO_PD* in package ZDYN_WS_ROUTTY_BASE using transaction SE80 or XSLT_TOOL.

The copied transformation can be adjusted to extract additional Routty fields, either by population of the custom field tab or by direct population of any fields available (see subsections below).

The adjusted transformation can be tested in SAP transaction XSLT using a downloaded XML example data file from Routty as input and the View HTML as output.

The new transformation has to be entered then in the general configuration as Transformation or Attachment transformation.

Similarly, the ZDYN_ROUTTY_TO_IDOC_V2 transformation can be improved to populate additional segments, use a different logical system or create a totally different IDOC.

Custom field tab

Custom fields can be added to the TAB_CUSTOM segment in the standard XSL transformation.

<!-- add here some custom fields -->
    <TAB_CUSTOM>
       <CUSTOMVALUES>
           <NAME>ZZFIELDNAME</NAME>
           <VALUE>ThisISaValue</VALUE>
     </CUSTOMVALUES>
    </TAB_CUSTOM>

Additional entries <CUSTOMVALUES><NAME>...</NAME><VALUE>...</VALUE></CUSTOMVALUES>

can be added here.

There is already a logic implemented in the standard transformation, where header fields DIMENSION1 to DIMENSION8 are automatically added to the TAB_CUSTOM, with NAME equal DIMENSIONx.

Such fields can be mapped in PD, where for example for DIMENSION1 field the mapping can look like this (Process Director mapping configuration):

Custom item fields ZFIELD1-ZFIELD6 are also handled. They are automatically mapped in the standard transformation as DIMENSION1-6 fields and can be then used in the Process Director mapping configuration.

When standard Z*/DIMENSTION* field mechanism is used, no transformation copy is required – the mechanism is handled by the existing transformation.

Additional standard/custom fields

If the PDAP application is present in the SAP system, it is also possible to directly use fields in the XSLT transformation that exist in the PDAP data structures. It is possible to use this mechanism on header, item, account and tax data levels, with fields available in the following structures:

/COCKPIT/SACCT_EXT

/COCKPIT/SHDR_EXT
/COCKPIT/SITEM_EXT

/COCKPIT/STAX_EXT

If for example PurchaseInvoiceHeader/BvTyp field is provided from Routty, it could be mapped like this in the XSLT transformation:

    <BVTYP>
      <xsl:value-of select="PurchaseInvoiceHeader/BvTyp"/>
    </BVTYP>

and the following way in the PDAP mapping (Process Director mapping configuration):

This mechanism requires a modified transformation copy, as it works with specific fields that do not exist in the standard transformation.

Access to the fields is described in Technical information for custom logic, XSLT transformation and for field mapping.

Custom class

It is possible to create a project specific class that inherits from the standard class ZDYN_CL_REST_ROUTTY_EXP. So simply create a new class and use ZDYN_CL_REST_ROUTTY_EXP as a superclass.

In this class the required methods can be redefined to implement custom logic.

Especially for implementing a new SAP BAPI call logic, method TRANSFER_DATA_TO_SAP needs to be redefined.

This new class can be selected in the general configuration to replace the standard implementation class.

Technical information for custom logic, XSLT transformation and for field mapping.

Structure of attribute MST_CONFIG

Structure of attribute MST_PDIV_DOCUMENT

Structure of attribute table MST_PDIV_DOCUMENT-TAB_ITEM

Structure of attribute table MST_PDIV_DOCUMENT-TAB_ACCOUNT

Structure of attribute table MST_PDIV_DOCUMENT-TAB_TAX

Structure of attribute table MST_PDIV_DOCUMENT-TAB_CUSTOM

Access to dynamic fields is available through the MO_PDIV_DOCUMENT object reference.

For example:

  mo_pdiv_document->set( EXPORTING ic_name = 'FIELDNAME'
                                   i_value = lc_value ).

  mo_pdiv_document->get( EXPORTING ic_name = 'FIELDNAME'
                         IMPORTING e_value = lc_value ).

It contains all the fields from the MST_PDIV_DOCUMENT structure plus all the fields from /COCKPIT/S*_EXT structures mentioned in Additional standard/custom fields.

Useful helper methods

ZDYN_CL_MSG=>ADD_MSG

ZDYN_CL_MSG=>ADD_SYSMSG

CT_MESSAGES is only optional in those methods. You can get all the added messages later with ZDYN_CL_MSG=>GET_MESSAGES as well.

ZDYN_CL_MSG=>ADD_ BAPIRET_MSG

ZDYN_CL_REST_ROUTTY_EXP->ARCHIVE_ATTACHMENT_DATA

This method is archiving the attachments from attribute table MR_ATTACHMENT->MT_ATTACHMENTS using SAP ARCHIVE LINK technology and connecting the archive document to the specified SAP business object IC_SAP_OBJECT with object identifier IC_OBJECT_ID.

Data process

General flow

Communication between SAP Package and Routty is done via HTTPS REST calls.

SAP Package has full access to the SAP system as it is installed inside SAP.

Inbound process

Outbound process