Offline Adobe Interactive Forms Integration Using SAP NetWeaver PI ABAP Mapping_V1.0

Offline AdobeInteractive FormsIntegration usingSAP NetWeaver PIABAP Mapping

Released only for SAP internal

Document Version 1.0, July 2008

MDM SDS

Offline Adobe Interactive Forms Integration using SAP NetWeaver PI ABAP Mapping

Page 2

History

Date Author Version Comment11/07/2008 Matthias Allgaier 1.0 Document created


Page 3

Table of content

1 Overview.................................................................................................................................. 41.1 Business Example .....................................................................................................................................41.2 Architecture................................................................................................................................................5

1.2.1 Adobe Document Services (ADS)........................................................................................................51.2.2 PI Solution ..........................................................................................................................................5

2 PI Configuration...................................................................................................................... 72.1 Form Builder ..............................................................................................................................................72.2 Design: Integration Repository .................................................................................................................8

2.2.1 Message Type: MT_PDF_BINARY......................................................................................................82.2.2 Adobe XSD-Structure: External definition ............................................................................................92.2.3 IDoc structure: ORDERS.ORDERS04 .................................................................................................92.2.4 Message Mapping: MM_PDF_2_IDOC_ORDERS04.........................................................................102.2.5 Interface Mapping: IM_PDF_2_IDOC_ORDERS04............................................................................10

2.3 Integration Directory................................................................................................................................112.3.1 Mail Sender Communication Channel: IMAP4 ...................................................................................112.3.2 Mail Sender Communication Channel: PayloadSwapBean ................................................................122.3.3 IDoc Receiver Channel .....................................................................................................................122.3.4 Receiver Determination.....................................................................................................................13

3 ABAP Mapping: ZCL_PDF2XML.......................................................................................... 144 Runtime: PI Message Monitor.............................................................................................. 15

Offline Adobe Interactive Forms Integration Using SAP NetWeaver PI ABAP Mapping

1 Overview

1.1 Business ExampleThrough a combination of Adobe and SAP technologies, Interactive Forms based on Adobe softwareallows enterprises to eliminate redundant and inaccurate data and improve the speed with which theycan respond to customer needs and changing business requirements.

This document describes a business example where interactive PDF forms are generated and sent outto end users via E-Mail. The forms can be pre-populated with information stored in the SAP applicationbased on the user’s role in the business process. End users can then add supplementary information orupdate existing information directly in the interactive form – in our case offline.

After the end user enters data into the form, the data can be validated for appropriate format, usingclient- or server-side validation. Also, calculations - such as current interest rate or overtime premium -can be made. After completing the interactive form offline within its mail client software (e.g. MicrosoftOutlook) the end user can submit the form to be sent back again to the SAP Backend System (in ourcase to create sales orders):

ORDERS.ORDERS05

Mail Server

SAP NetWeaver PI/XI

SAP ERP 4.7

Mail-Adapter

IDoc Adapter

Mail Account

PDF

Sales Order

Mail Client e.g. Outlook

PDF

Internet/Intranet/Extranet

ORDERS.ORDERS05

Mail Server

SAP NetWeaver PI/XI

SAP ERP 4.7

Mail-Adapter

IDoc Adapter

Mail Account

PDFPDF

Sales Order

Mail Client e.g. Outlook

PDFPDF

Internet/Intranet/Extranet

In domain of Master Data Management (MDM) this solution approach could e.g. be used in order tomaintain master data offline and replicate it to a central backend system (e.g. Master Data Server).

The crucial part of such an interface is the conversion of the binary PDF document to a structured XMLdocument that can further be used to interface with the backend systems (e.g. via IDoc/ALE).

In this document we describe a solution for this transformation using a generic SAP NetWeaver PI ABAPMapping based on Adobe Document Services (ADS) technology.


Page 5

1.2 Architecture

1.2.1 Adobe Document Services (ADS)Since SAP NetWeaver (Web) Application Server 6.40 (SAP NetWeaver 04), Adobe document services(ADS) have been available. This is a set of runtime services deployed on the Application Server thatprovide a range of form and document creation and manipulation functions. The key capabilities of theADS are the creation of documents in PDF and various print formats from XML form templates andcurrent system data, and the extraction of user-entered data from interactive PDF forms for renderingand generating Adobe Forms. SAP has also provided a single programmatic interface called PDFDocument Object (or PDF Object) that enables developers to communicate with ADS. PDF Object isavailable both in ABAP as well as Java.

1.2.2 PI SolutionThis document outlines a solution on how an interactive PDF form submitted by the end user can be sentto NetWeaver PI via E-Mail, transformed into an IDoc structure and finally be posted to a SAP backendsystem using IDoc/ALE technology:

SAP ERPMailServer

SAP NetWeaver PI/XI

IDocAdapter

Mail

Account

PDFMail

AdapterGraphicalMapping

ABAPMapping

ADS API (ABAP)

Adobe Document Services (ADS)

ALE

Inbound

Sales

Order

IMAP4 RFCPDF

PDF

XML

XML

IDoc XML

1

2 3

4 5

6

SAP ERPMailServer

SAP NetWeaver PI/XI

IDocAdapter

Mail

Account

PDFPDFMail

AdapterGraphicalMapping

ABAPMapping

ADS API (ABAP)

Adobe Document Services (ADS)

ALE

Inbound

Sales

Order

IMAP4 RFCPDF

PDF

XML

XML

IDoc XML

1

2 3

4 5

6

Solution in detail:

1. The end user completes the interactive PDF form and sends it via E-Mail back to the backendsystems. The mail address is defined during form design. It is recommended to create a maildedicated mail account that is linked to a Mail-Sender-Adapter within PI (e.g. using IMAP4protocol). Since the PDF form is sent as an attachment to PI the PDF the PayloadSwapBean(delivered by SAP) is used within the Mail Sender Adapter in order to bring the PDF attachmentto the main message payload within PI for further processing.

2. First an ABAP Mapping is used in order to convert the binary PDF form into a Adobe specificXML representation. For this purpose the ADS Services are used – this services run on the PIServer. In general this ABAP mapping is generic so it could be used for different PDF forms.

3. The ADS API returns an Adobe specific XML document containing the information from the PDFdocument.

4. Afterwards a graphical mapping is used to map the Adobe specific XML structure to the actualtarget format, in this case to a standard ORDERS05 IDoc structure.

5. The IDoc is sent to the IDoc Receiver Adapter and posted to the SAP ERP Backend System.

6. Within SAP ERP a Sales Order is created by ALE inbound processing.


Page 6

Notes:

This paper does not describe in detail how a PDF form designed, generated and sent out to end users.(Please refer to the Adobe/SAP documentation for further details).

Within the next chapter we concentrate on the essential development and configuration steps (nocomplete step-by-step description). For additional information please refer to the SAP/Adobedocumentation.

We assume that ADS is installed on SAP NetWeaver PI.


Page 7

2 PI Configuration

2.1 Form BuilderThe first step for an offline scenario is to design a form using transaction SFP. This topic has beencovered in detail in other How-To documents and is also explained in details in SAP documentation.

It includes following steps: Create an interface Create a form object Finally create the layout of the form and activate the form

Form Interface

Form Context


Page 8

Form Layout

2.2 Design: Integration Repository

2.2.1 Message Type: MT_PDF_BINARYThis message type represents the binary PDF document that will be received via Mail-Sender-Adapter.


Page 9

2.2.2 Adobe XSD-Structure: External definitionThe Adobe specific XML structure representing the PDF Form is imported as an external definition:

2.2.3 IDoc structure: ORDERS.ORDERS04This IDoc structure is imported from the SAP ERP backend system and is used in order to create thesales order.


Page 10

2.2.4 Message Mapping: MM_PDF_2_IDOC_ORDERS04Graphical Mapping that transforms the Adobe specific XML structure to an IDoc structure:

2.2.5 Interface Mapping: IM_PDF_2_IDOC_ORDERS04As described in the first chapter the actual transformation of the binary PDF document is done using twoPI mappings:

A) ABAP Mapping that transforms the binary PDF document to an Adobe specific XML structure (will bedescribed in detail in chapter 3)

B) Graphical Mapping that transforms the Adobe specific XML structure to an IDoc structure

Both mappings are encapsulated within following interface mapping:


Page 11

2.3 Integration DirectoryFor the configuration we assume that two business services/business systems have been set up – onerepresenting the Mail-Server that is used for receiving incoming Mails from the end users and onerepresenting the SAP ERP System to receive Purchase Orders via IDoc/ALE technology.

2.3.1 Mail Sender Communication Channel: IMAP4Configuration of the Mail-Sender Adapter to retrieve incoming mails from the connected Mail-Server,using IMAP4 protocol:


Page 12

2.3.2 Mail Sender Communication Channel: PayloadSwapBeanSince the PDF form is sent as an attachment to PI the PayloadSwapBean (delivered by SAP) is usedwithin the Mail-Sender-Adapter in order to bring the PDF attachment to the message payload within PIfor further processing:

2.3.3 IDoc Receiver ChannelThe IDoc adapter is used to post IDoc to SAP ERP Backend.


Page 13

2.3.4 Receiver DeterminationFollowing Screenshots captures the relevant receiver determination:

Note: In the above scenario an additional receiver has been set up in order place the binary PDFdocument to an archive server using the File-Adapter (not mandatory).


Page 14

3 ABAP Mapping: ZCL_PDF2XMLFollowing ABAP Mapping is used to convert the binary PDF form to an Adobe specific XML documentthat could be used for further processing (ABAP class ZCL_PDF2XML). The mapping is generic so it isnot form specific and could be used for multiple use cases. For the actual conversion it uses ADS APIprovided by Adobe.

Within Integration Repository it is referenced in the Interface Mapping (see chapter 2.2.5 -IM_PDF_2_IDOC_ORDERS04).

method if_mapping~execute.

* Declarationsclass cl_fp definition load.

* ADS APIdata: lr_fp type ref to if_fp, lr_pdfobj type ref to if_fp_pdf_object, lr_fpex type ref to cx_fp_runtime.

* Binary PDF document (Input) and XML document (Output)data: lv_pdf type xstring, lv_xml_data type xstring.

lv_pdf = source.

* get FP reference lr_fp = cl_fp=>get_reference( ).

* Call ADS API for conversion (5 steps)try.

* 1) create PDF Object lr_pdfobj = lr_fp->create_pdf_object( connection = 'ADS' ).

* 2) set documentcall method lr_pdfobj->set_documentexporting

pdfdata = lv_pdf.

* 3) tell PDF object to extract datacall method lr_pdfobj->set_task_extractdata( ).

* 4) execute, call ADScall method lr_pdfobj->execute( ).

* 5) get the data-context in XML formatcall method lr_pdfobj->get_dataimporting

formdata = lv_xml_data.

catch cx_fp_runtime_internal into lr_fpex.* PERFORM error USING lr_fpex 'INTERNAL ERROR'.

catch cx_fp_runtime_system into lr_fpex.* PERFORM error USING lr_fpex 'SYSTEM ERROR'.

catch cx_fp_runtime_usage into lr_fpex.* PERFORM error USING lr_fpex 'USAGE ERROR'.

endtry.

result = lv_xml_data.

endmethod.


Page 15

4 Runtime: PI Message MonitorFollowing screenshot shows the PI Message Monitor (SXMB_MONI):

Window 1: Received binary PDF formWindow 2: Generated IDoc in IDoc-XML format containing the PDF content within XML tags

Documents

Offline Adobe Interactive Forms Integration Using SAP NetWeaver PI ABAP Mapping_V1.0