SAP Module AP Essentials - Full configuration guide

Introduction

Dynatos Webservices APS/RSO is a package with various ready to use options to synchronize data between a SAP system and AP Essential (APS) formerly known as ReadSoft Online (RSO).

It's possible to directly upload master data from SAP to the APS/RSO system like Currencies, Payment Terms, General Ledger Accounts, Cost Centers, Projects, internal Orders, Vendors, Customers, Company Codes as Buyers and generic data types.

Purchase order data including information about delivered and invoiced item quantities can be synchronized to the APS/ReadSoft Online system.

Ready for download processed document data including their images can be downloaded to SAP and processed in various ways (IDOC, store as files, push to Process Director, custom SAP processing).

Using this package it's possible to replace the windows service tool ReadSoft Online Connect and the SAP master data extraction reports.

In addition you can leverage the options from SAP transaction SM59 for the specification of a proxy connection. And you can create any kind of Process Director document from the downloaded data, not only an AP document.

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

The package was created to mitigate limitations faced in several projects and to add the missing functionality.

This document describes how to configure and use Dynatos Webservices APS/RSO and the specific functions that are delivered with it.

Activation and use of Dynatos Webservices APS/RSO

This chapter will cover end-to-end guide on how to install and configure Dynatos Webservices RSO 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 as the transport import will end with errors.

Full implementation of Dynatos Webservices APS/RSO is based on SAP ABAP and it’s required to import transports provided by Dynatos 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 main package ZDYN_WEBSERVICES and various subpackages.

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 Dynatos Webservices APS/RSO transports requests one by one to the import queue in the order listed below.

License installation

To be able to work with the solution, you need a valid license key for product key O which you need to install using transaction ZDYN_LICENSE. You can maintain the license directly in each system.

There is a demo license available which doesn’t work in production environments and a test license with a defined validity period.

SAP Standard Configurations

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

SM59 - Specify destination to APS/RSO

We recommend to use a destination specified in SM59 instead of direct HTTPS calls.

This option you have to use as well, when you need to communicate across a proxy server.

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

Target Host is services.readsoftonline.com

Enter the proxy options if required.

Enable SSL by selecting Active under Logon & Security

Frequently you have to import in transaction STRUST current certificate for *.readsoftonline.com to the certificate list used above (e.g. SSL Client Standard).
You can down the certificate using your browser when you access the User interface.

In STRUST Transaction you select the corresponding certificate list.
Then you use the upload icon.

After upload and switching to change mode, you add it to the selected certificate list and save the new list.

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 RSONLINE in transaction SALE

Basic Settings->Logical Systems->Define Logical System

And the following partner definition in transaction WE20

Partner No. RSONLINE
Partn. Type LS

For Inbound parmtrs. 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 RSONLINE 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 APS/RSO 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 an PD AP or other PD documents the required configurations are attached and can be imported using the report /EBY/PDBO_CONFIG_DUMP for Object type IV, DN, OR or PA.

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 you don't use the XML file content 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 order confirmations will be like this. For others (DN or PA) the same.

Mapping instructions

The embedded XML files contain as well 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 RSO but can be changed in the corresponding configuration started from transaction ZDYN_WS_RSO or directly using ZDYN_WS_RSO_TPDMAP.

NOTE: Only fields available in the technical field list for MST_DOCUMENT and RSO fields 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.

Main Report

Configuration

On the top of the report screen which is started by transaction ZDYN_WS_RSO you have 5 buttons to start the different configuration maintenance dialogs and an info button showing version and license information.

ZDYN_WS_RSO_TGEN General configuration

Transaction ZDYN_WS_RSO_TGEN or the first button from the left in the report opens the maintenance dialog for the general configuration.

For the combination of SAP system ID, API Key (from APS/RSO), APS/RSO Admin User Name and External ID (usually the Company Code) you maintain:

ZDYN_WS_RSO_TARC Archive configuration

Transaction ZDYN_WS_RSO_TARC or the 3rd button in the report opens the 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_RSO_TPDMAP Process Director related configuration

Transaction ZDYN_WS_RSO_TPDMAP or second button in the report opens the 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 RSO 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_RSO_TCUST APS/RSO custom master data

Transaction ZDYN_WS_RSO_TCUST or forth button in the report opens the maintenance dialog for the optional special settings to define custom master data for APS/RSO to enable drop down value lists in the verification screen.

You define the external name of the master data.
Optionally you can assign a SAP domain that has fixed values (no value table).

When you select a domain the values that get synchronized to APS/RSO are taken from the SAP domain.

ZDYN_WS_RSO_TCUSVAL APS/RSO custom master data values

Transaction ZDYN_WS_RSO_TCUSVAL which is the fifth button in the report, enables you to define manually values for the defined custom data external names. A translation is not offered as it’s not supported in APS/RSO. But values can be defined for each external ID. Entries can be deactivated for future use.

Info button

The button on the right side open a screen with version and license information.

Report options

The report offers the following functions for a configured combination of APS/RSO Admin user and External Partner ID wich is usually equal to a SAP Company Code (general configuration)

You can specify a different Message level for analytical purposes (0 is default).

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

Application Log Object ZDYN_RSO is defined with Subobject

• SYNC for master data population to APS/ReadSoft Online

• DOCUMENTS for documents downloads from APS/ReadSoft Online

Check Login: Only tries to establish a connection using the values entered for the selected User Name / External Partner ID combination.

Master data: Is pushing SAP master data to APS/ReadSoft Online for the selected External Partner ID (by default Company Code if not overruled later on)

Read APS Documents: Gets documents ready for download and is processing them as defined in the general configuration

Master data

When selecting option Master data you get a selection screen after pressing enter where various SAP data can be synchronized to APS/ReadSoft Online.

All changes will generate 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.

Master data will be synchronized taking the corresponding APS/ReadSoft Online configuration into account. (customer or buyer level)

Buyer account will be identified using the external ID in the APS/RSO definition of the buyer.
For proper identification of Buyers a unique external ID is required.

Available options for master data synchronization

Data type	Description
Company Code	In combination with the flag Create buyer/seller, for the selected company codes a buyer (seller for Accounts Receivable) is created in APS/RSO using the company code as external ID. Has to be done once before synchronizing master data on buyer level for these new buyers. Without the flag, filtering master data by company code is not done using the external ID as company code value but the selected company codes. Note: if nothing is entered the External ID is used as company code value
Language by priorities	Used in specific master data that includes language dependent description, like Cost Center, G/L Account, Currency, Terms of Payment and Tax Code. The current user logon language will be used if this field is empty. Multiple values are possible, where the first one from the top has the highest priority, so when a text for this language is available, it will be used, otherwise the next language is considered.
Currency	Selected currencies are pushed to APS/RSO. When checked, all existing entries are deleted before the synchronization. Note: better only populate currencies you handle on APS documents not all SAP values or use the APS/RSO default list
Payment Terms	Selected payment terms are pushed to APS/RSO. When checked, the selected values will replace all existing entries. Note: it is not possible to simply delete all entries
General Ledger Accounts	Selected GL-Accounts from the selected company codes are pushed to APS/RSO. When checked, all existing entries are deleted before the synchronization. A group can be specified to populate the corresponding value in APS/RSO. You can select a SAP accounting group or enter a free text value, this value is not used for the selection in SAP. Note: when group should be populated, for each group a separate synchronization needs to be performed
Cost Center	Selected cost centers from the selected company codes are pushed to APS/RSO. When flagged, all existing entries are deleted before the synchronization.
WBS element	Selected WBS elements from the selected company codes are pushed to APS/RSO as Projects. For delta synchronizations the date of last change should be used. Then the selected WBS elements are filtered if they are new or have been changed since the selected date. When checked, all existing entries are deleted before the synchronization.
Order	Selected internal orders from the selected company codes are pushed to RSO as custom master type Order. For delta synchronizations the date of last change should be used. Then the selected internal orders are filtered if they are new or have been changed since the selected date. When checked, all existing entries are deleted before the synchronization.
Vendor	Selected vendors from the selected company codes are pushed to APS/RSO. When Marked for deletion is selected, those suppliers accounts are synchronized as inactive. Without the flag, they are ignored. When Insert bank details is selected, the bank accounts of the selected vendors are synchornized as well. For delta synchronizations the date of last change should be used. Then the selected vendors are filtered if they are new or have been changed since the selected date. When checked, all existing entries are deleted before the synchronization.
Purchasing Documents	Selected purchase orders from the selected company codes are pushed to APS/RSO. For an initial load the document creation date can be used as selection criteria. For delta synchronizations the date of last change should be used. For cleanup of old data select an old date range and tick the Delete selected data checkbox. Note: all variants require a separate synchronization run
Customer	Selected customers from the selected company codes are pushed to APS/RSO. When Marked for deletion is selected, those customer accounts are synchronized as inactive. Without the flag, they are ignored. For delta synchronizations the date of last change should be used. Then the selected customers are filtered if they are new or have been changed since the selected date. When checked the selected entries are deleted in APS/RSO.
Custom master data	Domain values or configured entries for the selected External Name are synchronized. When checked, all existing entries for this External Name are deleted before the synchronization. Note: a separate synchronization for each external name needs to be performed

Recommendations for the synchronization of purchase orders.

Initial load with selection of purchase documents

• using number ranges

• using Created on date range

All matching purchase orders for the selected company code are pushed to APS/RSO

Delta run selecting only changed purchase documents

• using number ranges

• using Date of last change

All new, changed purchase orders or orders where a delivery or invoice entry has happened are synchronized to APS/RSO
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.

Cleanup run to remove obsolete data from APS/RSO

• using number ranges

• using a Created on date range from the past

Those historical purchasing documents are then removed from the APS/RSO system.
Note: accidentally deleted orders can be added using the initial load variant

General Note: when using the Delete all records flag "only" maximum 1000 entries are deleted.
When there have been more, run the report with this flag multiple times.

Read APS/RSO Documents

When using this option, documents from APS/ReadSoft Online that are ready for download for the customer account or when configured in APS/RSO for the buyer account connected to the external ID are processed according the general configuration import option.

Ticking the checkbox Mark for deletion will flag processed documents as deleted in APS/ReadSoft Online.

Note: this should be done only for early tests. Those documents are not used to improve the auto learning in APS. And they are not counted regarding the license counter. So only for initial tests.

Selecting the option Flag for Archive e-Mail will download the e-mail that generated the document and pass it with mimetype message/rfc822 to the archive. A corresponding archive document type needs to be defined and used for the business object to enable archiving of the e-mail.

When selecting the option Create archive file, the received attachments are archived. This might be required when the email has multiple attachments or the original attachment is converted into the configured format of the output document.

In addition ther are several test options which might be used during the initial configuration.

Enhancements

Enhancement Options

For special requirements the following options for project specific adjustments are available:

Custom XSLT transformations

It is possible to simply copy the standard XSLT transformations in package ZDYN_WS_RSO using transaction SE80

The copied transformation can be adjusted to extract additional APS/RSO 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 APS XML 2.0 example data file from APS/ReadSoft Online as input and use the View HTML as output.

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

Similarly, the ZDYN_RSO_TO_IDOC 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>

Multiple entries

<CUSTOMVALUES><NAME>...</NAME><VALUE>...</VALUE></CUSTOMVALUES>

can be used here in the transformation.

In general, there is already a logic implemented in the standard transformation that custom header fields, where the type name starts with header_, are automatically added to the TAB_CUSTOM using the uppercased string after header_ as NAME.

For example, header_addinf_u will be added as ADDINF_U and can be used like this in the mapping (Process Director mapping configuration).

Custom item fields ZFIELD1-ZFIELD6 are also handled. They are automatically mapped in the standard transformation the following way, if you specify the custom field like this:

It can be then used in the Process Director mapping configuration.

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 LIT_ZFIELD1-ZFIELD6 are also handled. They are automatically mapped in the standard transformation as ZFIELD1-ZFIELD6 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:valueof select="Documents/Document/
HeaderFields/HeaderField[Type='BvTyp']/Text"/>
</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_TOOLS_RSO. So simply create a new class and use ZDYN_CL_REST_TOOLS_RSO as 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_ACCOUNT

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

Structure of IS_DOCUMENT in various method interfaces

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

ARCHIVE_ATTACHMENT_DATA

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

Useful helper class ZDYN_CL_MSG

Adds messages of various formats to the current message collector.

System message:       zdyn_cl_msg=>add_sysmsg( ).

Direct message:       zdyn_cl_msg=>add_msg( EXPORTING ic_msgty    = 'S'
                                      ic_msgid    = 'ZDYN_WS'
                                      ic_msgno    = '024'
                                      ic_msgv1    = lst_arc-filename ).

Message in BAPIRETURN format:
    zdyn_cl_msg=>add_bapiret_msg( ist_bapiret = lst_message
                                  ii_level    = zdyn_cl_msg=>con_message_level_1 ).

System diagram

Communication between SAP Package and APS/ReadSoft Online via HTTPS REST calls

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