ADS Hub
Adobe Document Services (ADS) are installed on the Java stack of SAP NetWeaver and are responsible for PDF document creation and manipulation. ADS is involved in many scenarios of the Business Suite. In most customer installations, ADS is installed on a dedicated Java stack and not part of the ABAP system where the business applications run.
The ADS hub is a concept defining rules to share a central ADS instance between multiple SAP systems. This document is related to the use cases ‘print' and ‘interactive offline scenarios'.
Introduction and Motivation
The advantage of a central system is that ADS can be accessed from multiple ABAP systems and does not need to be installed several times. This setup looks promising with regards to administration and monitoring of the Java stack, but on the other hand it would complicate the system upgrade if ADS could not handle different releases of the clients. In previous shipments (up to NetWeaver 7.0 SP12), ADS was assumed to be of the same release (and support package) version as the ABAP system - or newer. If a customer upgraded his ERP system, for example, he was forced to upgrade the Java stack before or at the same time, which complicated the upgrade process.
An interoperability of different ABAP and Java versions was highly demanded to decouple both systems. Since ADS is called via a Web Service, a first step in this direction was already done right from the beginning. But there are several aspects of interoperability of the Adobe Document Services:
- a syntactical interoperability of the Web Service (the API)
- a semantical interoperability of the Web Service (the functionality)
- a content based interoperability (the form templates)
All of these aspects have their own prerequisites and consequences which are detailed in the following.
Syntactical Interoperability
The syntactical interoperability of the Web Service is given by the flexible definition of the API. It basically consists of one method with two parameters, each a table of name value pairs. One table contains string values, the other table contains xstring values. These parameters are mapped to arrays on Java (string[] and byte[]). All content can be transferred via these parameters, e. g., the application XML data, the printer streams or the PDF, everything fits into the API. Also the working instructions for ADS are transferred as an XML document. New parameters are just represented by XML tags and do not require new parameters of the Web Service. Hence, no enhancement of the API is required in future versions and a syntactical interoperability between ABAP and Java is guaranteed.
Semantical Interoperability
A semantical interoperability is more complicated and requires special attention. Let us first concentrate on a system setup where ADS is equal or newer compared to the ABAP version. As long as the ADS API is backwards compatible, every call will continue to work. Since backwards compatibility is given, no special actions are required from an application point of view. But how could we achieve a real interoperability in both directions? How to handle the combination of a new ABAP release and an old ADS installation?
The general answer is: do not implicitly rely on functionality which is shipped with an ADS version later than NetWeaver 7.0 SP13. This version is the common base of interoperability and defines the feature set which can be used without further efforts. Every application should never use a feature exposed via the ABAP API (PDF Object, Forms Processing Framework) which is not available in 7.0 SP13. If a new feature is requested from an old ADS, two possible reactions are to be expected. A runtime exception could occur since the required processing instruction is not supported. Even worse, ADS could ignore the feature and process the document without it. For some features, that might be acceptable, but in case they are business relevant, ignoring the feature and pretending a successful processing is worse than an exception since no one realizes the situation.
The only possible consequence of this circumstance was to provide a feature test. This test must be called by every application that wants to utilize an ADS feature which is only available later than 7.0 SP13. The decision whether a feature can be ignored or is relevant can only be done by the application. In case the feature test fails, the application must not use the parameter or construct in the ABAP API during the ADS request; if the feature is required from an application point of view, a message needs to be provided to the user that the current system setup does not allow this scenario and the processing must be cancelled. An upgrade of the ADS is required in that case.
The feature test can be executed by calling the static method CL_FP_FEATURE_TEST=>IS_AVAILABLE. The method has one importing parameter, IV_FEATURE, which represents the feature to be tested. The possible values depend on the ABAP release and can be taken from the constants provided by the same class. One example is the so called stitching of PDF documents. This feature is available with a NetWeaver Java 7.20 (ADS 8.20) and could be used from an ABAP system 7.02. The IV_FEATURE value would be CL_FP_FEATURE_TEST=>GC_ASSEMBLE_STITCH, and the method return true or false, depending on the ADS version.
Content based Interoperability
ADS can process form templates which have been created with an Adobe LiveCycler Designer (ALD) with the same or a lower version number. NetWeaver 7.0 SP13 ADS has the internal version number 8.00, which maps to ALD version 8.0.
In case ALD 8.1 is used, an ADS with the same version is required, which is available with NetWeaver 7.0 Enhancement Package 1.
If you want (or need, e. g. for Vista support) to use ALD 8.1 with an ADS version 8.0, you need to specify a target version. This can be done in ALD: Edit -> Form Properties -> Defaults -> Target Version (choose 8.0).
Form developers are only allowed to use a certain version number of ALD if the available ADS installations are on the same or higher version. Otherwise, the target version must be specified appropriately.
Summary
ADS can be installed and used as a central component on the Java stack which is interoperable with different ABAP systems. Special attention has to be paid to new features - their availability has to be checked via a feature test before usage.
The version of the Adobe LiveCycle Designer must fit to the Adobe Document Services, which means that the ADS must be newer or the same version as ALD. Otherwise, the target version must be specified appropriately.
If these prerequisites are met, ADS can be used centrally and upgraded individually from the ABAP systems.
