SAP Forms Service by Adobe for the Neo Environment

Integration Guide | PUBLIC

2024-07-12

SAP Forms Service by Adobe for the Neo

Environment

THE BEST RUN 

Content

1 SAP Forms Service by Adobe...................................................3

1.1 Use Cases..................................................................5

1.2 Architecture.................................................................6

1.3 Administration...............................................................7

Initial Steps in Your SAP BTP Subaccount......................................... 8

Connecting Your ABAP System................................................ 11

Connect a WebDynpro Java Application ......................................... 26

Migration from On-Premise ADS...............................................29

Conguring Backup........................................................30

1.4 Conguration Tool........................................................... 30

Upload Fonts.............................................................33

Congure Fonts and Print Information using XDC and XCI Files......................... 34

Congure Document Security.................................................35

Manage Job Proles........................................................36

Download Support Files.....................................................37

Congure Caching.........................................................38

Data Migration........................................................... 39

1.5 SAP Forms Service by Adobe REST API.............................................41

Connection Setup.........................................................42

Call the REST API......................................................... 46

Template Store API........................................................ 47

Template Store UI......................................................... 57

Supportability and Troubleshooting.............................................64

REST API Scenarios........................................................71

1.6 Security...................................................................96

Data Protection and Privacy..................................................97

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

Content

1 SAP Forms Service by Adobe

Use SAP Forms service to manage print and interactive forms.

Note

This documentation refers to SAP BTP, Neo environment. If you are looking for information about the

SAP Forms service in the Cloud Foundry environment, see SAP Forms Service by Adobe (Cloud Foundry

Environment).

The SAP Forms service is a cloud service based on Adobe Document Services (ADS). It is hosted on SAP

BTP (Neo environment). Since the SAP Forms service provides virtually the same features, you can use it as

an alternative to ADS based on SAP NetWeaver and call it from an application running on an ABAP or Java

backend system.

Note

See also: Adobe Document Services for Form Processing (SAP NetWeaver).

Using the SAP Forms service, SAP manages the complete service for you and is responsible for all patches and

updates.

After performing the conguration tasks to connect your ABAP system to the SAP Forms service, you can start

using the service immediately without the need to manage any additional hardware resources.

As a system administrator, learn more in the following sections about the required conguration tasks on your

ABAP system, the Cloud Connector, your SAP BTP subaccount, and the ADS conguration tool.

If you want to consume SAP Forms service from your own application developed and hosted on SAP BTP, you

can use the SAP Forms Service by Adobe REST API [page 41] to call the service.

Note

Using the SAP Forms service REST API for your Cloud application requires you to provide your own form

templates (using the Adobe LiveCycle Designer), as well as your own data les. See also: Using the Adobe

LiveCycle Designer [page 86].

For detailed information on the SAP Forms service scenarios, see: Use Cases [page 5].

Features

The capabilities of the SAP Forms service enable you to:

• Create interactive forms that look exactly like their paper counterparts.

• Annotate PDF documents and collaborate on PDF document reviews.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 3

• Capture data using forms and import the data directly into the SAP system.

• Allow users to digitally sign PDF documents.

• Embed other le formats inside PDF documents as attachments.

For more information on the SAP Forms service's capabilities and pricing, see also SAP Forms Service by

Adobe (SAP Discovery Center).

Prerequisites

• You have a consumer subaccount on SAP BTP, which is subscribed to the SAP Forms service.

• On your own subaccount, you have a user ID that is registered with SAP ID service. See Assigning

Members in the Neo Environment.

• You have purchased the license for the SAP Forms service by Adobe and received an e-mail notication

that the SAP Forms service has been congured for your subaccount (productive use).

• You have enbaled the service for your productive subaccount, see Enabling the SAP Forms Service for Your

Subaccount [page 8].

• You operate an ABAP system based on version SAP NetWeaver 7.0 SP13 or higher.

Restrictions

Not supported:

• Parallelization

• HSM (Hardware Security Module) / MS-CAPI (Microsoft CryptoAPI) credentials for digital signatures

(including USB hardware token)

• Custom Identity Provider (supported instead: SAP ID service, see Prerequisites)

• ABAP test report FP_PDF_TEST_28

Supported with restrictions:

• Direct access to graphic URLs on customer internal server networks is not supported.

Note

Find a workaround for accessing internal graphic URLs using the Cloud Connector in SAP Note

2171542

• NW 7.0, NW 7.01: in ABAP report RSPO0022, add the prex XDC/Customer/ to the xdc le name you want

to assign to a SAP device.

Size limits:

For le upload via the conguration tool, some size limits apply. For more information, see Conguration Tool

[page 32].

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Note

For more details and the current list of known restrictions, see also SAP Note 2171547 .

Enhancements

• Support of software-based Aztec Barcode. See SAP Note 2699022 .

• Change or create custom locale denitions. See SAP Note 2696301 .

• Support of extended decimal data elds (AFLE). See SAP Note 2699015 .

• Availability of SAP Monotype Fonts: Arial and Times New Roman (normal, bold, italic, bold/italic).

See also the SAP Forms service release notes.

Related Information

Use Cases [page 5]

Architecture [page 6]

Initial Steps in Your SAP BTP Subaccount [page 8]

Connecting Your ABAP System [page 11]

Test Your Conguration [page 25]

Migration from On-Premise ADS [page 29]

Conguration Tool [page 30]

Connect a WebDynpro Java Application [page 26]

SAP Forms Service by Adobe REST API [page 41]

Security [page 96]

Data Protection and Privacy [page 97]

1.1 Use Cases

Learn how your applications can call the SAP Forms service by Adobe to generate print or interactive PDF

forms.

There are currently two use cases for calling the SAP Forms service:

1. The SAP Forms service is called directly by an application running on a NetWeaver-based ABAP or Java

backend.

The application running on the ABAP backend uses the ABAP PDF Object, also known as the Forms

Processing Runtime. Java applications make use of the Java PDF Object. The ABAP backend can be an

on-premise system or a cloud-based system.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 5

Example: Applications on Business Suite, S/4HANA on-premise edition, S/4HANA cloud edition.

2. The second use case is following the RESTful service principle. The SAP Forms service is not called directly.

Instead, the application calls the SAP Forms service REST API via HTTP.

The rst edition provides a subset of the already known ABAP PDF Object features. They are addressed by

dierent URIs (Uniform Resource Identiers) where each URI supports data and document exchange in a

JSON format. The SAP Forms service REST API delivers a comprehensive description and is easy to test.

Similar to the rst use case, the application calls the REST API via an SAP BTP subaccount that must be

subscribed to the SAP Forms service.

Example: Services/applications running on SAP BTP.

Related Information

Architecture [page 6]

Initial Steps in Your SAP BTP Subaccount [page 8]

Connecting Your ABAP System [page 11]

SAP Forms Service by Adobe REST API [page 41]

1.2 Architecture

SAP Forms service by Adobe: Architecture overview.

You can use the service the SAP Forms service in two dierent scenarios:

1. Calling the SAP Forms service from an application running on an ABAP or Java backend.

In this use case, there are three sections where you connect your ABAP system to the SAP Forms service:

• Conguration UI: You use the conguration UI to manage your own fonts, XDC les, credentials, and so

on.

• Web Service: Your ABAP system calls the SAP Forms service in a web service using an SSL

connection.

• Destination Service: the SAP Forms service calls back to the ABAP system to retrieve the form

template, using a secure connection in the Cloud Connector.

2. Calling the SAP Forms service from an application through the the SAP Forms service REST API via HTTP.

The diagram below shows examples (scenarios 1 and 2) for these use cases:

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.3 Administration

Initial Steps in Your SAP BTP Subaccount [page 8]

Enable the SAP Forms service for your subaccount and per-

form basic role assignment.

Connecting Your ABAP System [page 11] Congure AS ABAP, the Cloud Connector, and your SAP BTP

subaccount to enable communication with theSAP Forms

service.

Connect a WebDynpro Java Application [page 26] Import a certicate and congure the required templates to

connect your WebDynpro Java application to the SAP Forms

service.

Migration from On-Premise ADS [page 29] Copy conguration settings or les from your existing Net-

Weaver ADS installation to the SAP Forms service.

Conguring Backup [page 30] Create a backup of your SAP Forms service conguration

data.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 7

1.3.1Initial Steps in Your SAP BTP Subaccount

Enable the SAP Forms service for your subaccount and perform basic role assignment.

• Enabling the SAP Forms Service for Your Subaccount [page 8]

• Assigning Roles to Users [page 10]

1.3.1.1 Enabling the SAP Forms Service for Your

Subaccount

Before you can congure the SAP Forms service, you must enable the service in your SAP BTP subaccount.

Prerequisites

You must have a valid license for the SAP Forms service, see Pricing & Packaging

(SAP Extension Suite).

Procedure

Once you are logged on to the SAP BTP cockpit, you can use a self-service to enable the SAP Forms service

from your subaccount.

Note

If you use the SAP Forms service from more than one subaccount, the following steps apply to each of

these subaccounts.

1. From your subaccount, choose Services from the navigation panel to access the list of available services.

The SAP Forms service is still in status Not enabled.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

2. Click on the service to access the detail view. The conguration links at the bottom of the screen are still

disabled. To activate them, press Enable.

3. After a short processing time, the service and the conguration links are enabled.

4. Proceed with the next conguration step: Assigning Roles to Users [page 10].

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 9

1.3.1.2 Assigning Roles to Users

How to assign roles to users for the SAP Forms service in your SAP BTP subaccount.

Your subaccount user needs a basic role assignment to be able to work with the SAP Forms service:

• The role ADSAdmin is required for calling the conguration tool of the SAP Forms service.

• The role ADSCaller is required for calling the web service of the SAP Forms service.

Prerequisites

The SAP Forms service must be enabled for your subaccount, see Enabling the SAP Forms Service for Your

Subaccount [page 8].

Procedure

To enable access to the web service of the SAP Forms service, do the following:

1. Open the SAP BTP cockpit for your subaccount that is subscribed to the SAP Forms service.

2. Choose Services.

3. Select SAP Forms Service and in section Service Conguration of the detail view choose the link SAP

Forms Service (Roles & Destinations).

4. Choose Roles in the navigation pane on the left-hand side. On the Roles screen, the roles ADSAdmin and

ADSCaller are displayed.

5. Select ADSAdmin to see the users assigned to this role in the frame below.

Note

This could be either your user for the Service Marketplace (s user) or your user for the SAP Community

Network (SCN user).

6. Choose Assign to add new users.

7. Repeat all steps for the role ADSCaller.

Result

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Related Information

Connecting Your ABAP System [page 11]

Congure the Destination in Your SAP BTP Subaccount [page 23]

1.3.2Connecting Your ABAP System

Congure AS ABAP, the SAP Cloud Connector, and your SAP BTP subaccount to enable communication with

the SAP Forms service.

To establish the connection between the SAP Forms service and your ABAP system, you need to perform

several conguration steps on AS ABAP, the Cloud Connector, and your SAP BTP subaccount.

The key task is to specify and map the required destinations for RFC/HTTP communication.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 11

Tip

If you want to connect the SAP Forms service to more than one ABAP system, we recommend that you

create one subaccount per ABAP system. Like this, you can easily check the consumption of form requests

per ABAP system in the BTP cockpit on subaccount level.

Learn more about the conguration details for each component in this section.

Related Information

Conguring the ABAP System [page 12]

Installing and Conguring the Cloud Connector [page 20]

Congure the Destination in Your SAP BTP Subaccount [page 23]

Test Your Conguration [page 25]

1.3.2.1 Conguring the ABAP System

Setting up the SSL connection, RFC destination, and HTTP communication in AS ABAP.

You have to perform several conguration steps in your ABAP system to use it with the SAP Forms service.

Prerequisites

The communication between the ABAP system and SAP BTP must use SSL.

• If not already done, congure SSL on your ABAP System.

Note

For more information, see Conguring SAP NetWeaver AS for ABAP to Support SSL.

Related Information

Establish the SSL Connection to SAP BTP [page 13]

Congure the RFC Destination [page 14]

Congure the ICF Service on your ABAP System [page 20]

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.3.2.1.1 Establish the SSL Connection to SAP BTP

Congure your SSL connection to SAP BTP in the ABAP Trust Manager.

To set up an SSL connection between the ABAP system and SAP BTP, you have to import the required security

certicates into AS ABAP.

Note

We recommend you to create and use your individual SSL Client PSE for importing the required Root CA

certicates. For more information, refer to the Help Portal documentation Creating Individual SSL Client

PSEs.

Procedure

Perform the following steps to set up the SSL connection to the SAP BTP:

Note

For more information about managing certicates in AS ABAP, see also: Conguring SAP NetWeaver AS for

ABAP to Support SSL.

1. Open https://www.digicert.com/digicert-root-certificates.htm in your web browser and

download the following certicates:

• DigiCert Global Root CA

• DigiCert Global Root G2

2. In the ABAP system, open the Trust Manager (transaction STRUST) and navigate to the individual SSL

client PSE you dened before. Double click this entry.

3. Import the certicates:

1. Choose the menu path:

Certicate Import .

2. Select the les you downloaded previously and continue.

3. Press Add to Certicate List in the Certicate view. These certicate les will then be listed in the

Certicate List view.

4. Save your changes.

Note

Due to a switch of root certicates on SAP BTP, certicates on all new SAP BTP data centers and

certicate renewals on the existing data centers use the new root CA issuer DigiCert.

For up-to-date information on the domain-specic validity of certicates on SAP BTP, please follow this

SCN blog: Certicate Authority Change .

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 13

Result

After importing the certicates, the certicate list and details in ABAP Trust Manager look like this:

1.3.2.1.2

Congure the RFC Destination

Create and congure an RFC destination for the SAP Forms service in AS ABAP.

To access the web service of the SAP Forms service, you need to create and congure an RFC destination.

Note

For more information, see also: Maintaining Remote Destinations.

Procedure

The SAP Forms service supports two authentication types for logon: basic authentication and client certicate

authentication. Find the procedures for each authentication type below.

Basic Authentication

Tab: Technical Settings

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1. Log on to the central instance host of your SAP NetWeaver AS ABAP.

2. Call transaction SM59.

3. Choose Create or select an existing SAP Forms service connection to change it.

4. On tab Technical Settings, enter at least the following:

• RFC destination : ADS

• Connection type : G

• Description

5. Choose Enter.

6. Choose the Technical Settings tab and enter at least the following:

• <Target Host>

The host name is a combination of the SAP Forms service subaccount name and your subaccount's

technical name:

adsformsprocessing-<yoursubaccount:technicalname>.<yourregionhost:

[xxx].hana.ondemand.com>

Note

You can nd your subaccount's technical name in the SAP BTP cockpit:

Global Account Subaccounts Subaccount Tile: Info Icon Technical Name .

The complete domain name for the target host (region host) [xxx].hana.ondemand.com

depends on the data center (region) that is assigned to your subaccount, see Regions and Hosts

Available for the Neo Environment.

Example: for region Europe (Frankfurt), the region host is eu2.hana.ondemand.com.

• <Service No.>

Enter 443, which is the default SSL port of the SAP BTP service.

• <Path Prefix>

Enter the string /ads.web/AdobeDocumentServicesSec/Config?style=rpc

Note

All entries are case-sensitive.

Note

Ignore the warning Query String Not Allowed by pressing Enter.

• Specify also the HTTP proxy parameters if an HTTP proxy is required for your ABAP system to access

the internet.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 15

Tab: Logon and Security

1. Choose the Logon/Security tab and select Basic Authentication.

2. In the <User> and <Password> elds, enter the same user as is used in your subaccount (S-User), and

the password.

Note

This user must be assigned to the role ADSCaller. Enter the same password you dened on the SAP

ID service for this user.

Caution

Do not use a Technical Communication User for the SAP Forms service authentication.

3. In Security Options , select Active to enable SSL and specify the name of the SSL certicate store where

you imported the SAP BTP root certicate.

4. Save your entries.

Note

If you perform the connection test in SM59, you get an HTTP 500 error. You can ignore this error message.

To test the connection, use the ABAP test report FP_PDF_TEST_00 instead.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Client Certicate Authentication

1. To congure the Technical Settings of the RFC destination, proceed as described in Basic Authentication

above.

In the eld <Target Host>, you must include the domain .cert into the

URL string: adsformsprocessing-<yoursubaccount:technicalname>.cert.<yourregionhost:

[xxx].hana.ondemand.com>

2. Choose the Logon/Security tab and select Do Not Use a User.

3. Provide a private key that is trusted by SAP BTP. To nd a list of trusted certicate authorities (CAs), see

Trusted Certicate Authorities for Client Certicate Authentication.

4. Import the private key into your ABAP backend system using transaction STRUST, see Establish the SSL

Connection to SAP BTP [page 13].

Note

To set up the SSL connection, we recommend that you create your own PSE (personal security

environment). The new private key must import this PSE.

5. Assign the CN name of the private key to the ADSCaller role. You can nd the CN name in the certicate's

<Subject> eld in transaction STRUST:

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 17

6. In Security Options , select Active to enable SSL and specify the name of the SSL certicate store where

you imported the SAP BTP root certicate.

7. Save your entries.

Note

If you perform the connection test in SM59, you get an HTTP 500 error. You can ignore this error

message. To test the connection, use the ABAP test report FP_PDF_TEST_00 instead.

Basic Authentication and Client Certicate Authentication

1. Choose the Special Options tab.

2. In section HTTP Setting, select HTTP 1.1 as HTTP version.

Note

Using HTTP 1.0, the connection will not work!

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Result

If the connection test (using ABAP report FP_PDF_TEST_00) is successful, you see the version information

from the SAP Forms service:

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 19

1.3.2.1.3 Congure the ICF Service on your ABAP System

Set up the ICF service in AS ABAP to enable HTTP communication with the SAP Forms service.

In the ABAP system, an active ICF service is required to enable communication between AS ABAP and the the

SAP Forms service destination service through the Cloud Connector.

Procedure

Perform the following steps:

Note

These steps might not be required if you have already congured the destination and ICF service on your

ABAP system for the ADS running on SAP NetWeaver AS Java.

1. Create the service user ADS_AGENT in your ABAP system:

Creating the Service User for Communication with ADS

2. Activate the ICF service:

Activating the ICF Service

1.3.2.2 Installing and Conguring the Cloud Connector

Download, install, and congure the SAP Cloud Connector for secure communication between the SAP Forms

service and the ABAP system.

The SAP Cloud Connector (Cloud Connector) provides a secure connection between the services running on

SAP BTP and the on-premise system. The Forms scenario uses this connection for callbacks of the SAP Forms

service to the ABAP system. Some use cases transfer template and runtime data using this channel.

Form templates are stored in the ABAP system and also cached on ADS. ADS loads the template from the

ABAP system when the form is rendered the rst time and also when the template was updated. An ICF service

of the ABAP system performs this process using path /sap/bc/fp. If you use bundling of forms, the runtime

data is transferred using the path /sap/bc/fpads.

Note

For more information about bundling, see Bundling Form Templates in a Call.

The Cloud Connector is available for Linux and Windows. You can install it on the application server of your

ABAP system or on separate hardware. The prerequisite is that it is in the same network as your ABAP system.

• For more information about installing the Cloud Connector, see Installation.

• For more information about initial conguration of the Cloud Connector, see: Initial Conguration.

• For more information about operating the Cloud Connector, see Administration.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Related Information

Congure the Destination in the Cloud Connector [page 21]

1.3.2.2.1 Congure the Destination in the Cloud Connector

Specify the target ABAP system in the Cloud Connector.

In the SAP BTP subaccount, the "real" (internal) host information of the ABAP system is not visible. A virtual

host name is used instead. In the Cloud Connector, you perform the mapping between the virtual and internal

host name.

Prerequisite

The Cloud Connector is installed and initially congured.

Procedure

1. Open the Cloud Connector administration UI.

2. From your subaccount menu, choose Cloud to On-Premise and select tab Access Control to dene the

destination information:

1. Add (+) a new entry. The Add System Mapping dialog opens.

2. As <Back-end Type>, leave the default value ABAP System and choose Next:

3. Select HTTP or HTTPS as <Protocol> and press Next.

4. Enter an <Internal Host> and <Internal Port>. <Internal Host> is the host address of your

ABAP system and <Internal Port> is your ICM HTTP(S) port.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 21

Note

The <Internal Host> corresponds to the ABAP system you want to connect to the Cloud

Connector.

Note

To display the host name of your AS ABAP, log on to AS ABAP and call transaction SICF. In the main

menu, choose Goto Port Information . The information is displayed on a screen, where the

HTTP port is specied under Services.

Choose Next.

5. Specify the <Virtual Host>: <virtual hostname>:<virtual port>. Any entry for <Virtual

Host> and for <Virtual Port> is OK.

Note

You should remember your entries for <virtual hostname>:<virtual port>, because you

need them later when conguring the destination in your SAP BTP subaccount.

6. Select <Principal Type> X.509 Certificate (Strict Usage). Choose Next.

7. Optionally, you can enter a <Description> for your system mapping. Choose Next.

8. Check the summary of your entries and select Check Internal Host, if you want to verify the internal

host name you entered before.

3. Choose Finish.

Now you can see your mapping in section Mapping Virtual to Internal System in the list of mapped systems. To

add accessible resources for your mapping, do the following:

1. Highlight the row with the Virtual and Internal hosts you just added .

Note

After adding resources, the resources accessible on the internal host will be displayed in section

Resources Accessible On... below the list of mapped systems.

2. Choose Add (+) in the Resources Accessible On... section.

3. Enter for <URL path> : /sap/bc/fp/.

4. For <Access Policy> choose Path and all sub-paths.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

5. Press Save.

6. Repeat the steps by adding a second resource and enter the additional <URL path> /sap/bc/fpads/.

Result

The screenshot below shows the mapping of a virtual host to an internal host (this is the ABAP system) and the

resources used on the ABAP system.

Dened resources:

•

/sap/bc/fp/ (subfolders included) and

• /sap/bc/fpads/ (subfolders included)

1.3.2.3 Congure the Destination in Your SAP BTP

Subaccount

Enter ABAP destination data for SAP Forms Service in yourSAP BTP subaccount.

The destination information you specied for the ABAP system on the Cloud Connector also needs to be stored

in your SAP BTP subaccount.

Procedure

Proceed as follows to congure the destination in your SAP BTP subaccount:

1. Open your subaccount in the SAP BTP cockpit.

2. Select Services.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 23

3. Select SAP Forms Service and in section Service Conguration of the detail view choose the link SAP

Forms Service (Roles & Destinations).

4. Select Destinations.

5. Choose New Destination....

6. As a name, enter FP_ICF_DATA_<SID>, where <SID> is the system ID of your ABAP system.

7. For <Type> , choose HTTP.

8. (Optional) Enter any <Description>.

9. (Optional) If you are using more than one Cloud Connector for your subaccount, you can enter the

<Location ID> of the Cloud Connector to which the data should be routed. To see the <Location ID>

eld, you must rst set the <Proxy Type> to OnPremise (see step 11).

Note

The location ID must be specied in the Cloud Connector, see Set up Connection Parameters and

HTTPS Proxy.

10. Under <URL>, specify the Virtual host name you specied in the Cloud Connector for your ABAP system

before.

Note

The URL string looks like this: http://<virtual host name>:<virtual port>. Enter the values

for <virtual host name>, and <virtual port> as specied when you congured the destination

in the Cloud Connector.

11. (Optional) If you want to dene a specic client as target within the ABAP system, you can congure it as

additional property.

1. In the Additional Properties section, choose New Property.

2. Select the property sap-client from the dropdown list.

3. As value, enter the desired client, for example, 001.

Note

Per default, destination FP_ICF_DATA_<SID> calls the default ABAP client (specied by the prole

parameter login/system_client).

12. As <Proxy Type>, choose OnPremise.

13. For <Authentication>, choose BasicAuthentication or PrincipalPropagation.

Note

For more information on principal propagation (user propagation), see Principal Propagation

Authentication (destination in your SAP BTP subaccount) and Conguring Principal Propagation

(Cloud Connector).

14. Enter ADS_AGENT as a user and enter the password. Use the same password that is used for the

<ADS_AGENT> in your ABAP system.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

15. Save your settings.

Result

The specied destination looks like this:

Related Information

Congure the Destination in the Cloud Connector [page 21]

1.3.2.4 Test Your Conguration

Using ABAP reports to test your the SAP Forms service conguration.

After nishing all conguration steps, you can use several ABAP reports to test whether the connection is

working ne.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 25

Procedure

Call the following ABAP test reports:

• FP_PDF_TEST_00

• FP_CHECK_DESTINATION_SERVICE

• FP_TEST_03

• FP_TEST_IA_01

• FP_CHECK_HTTP_DATA_TRANSFER

Note

For more information, see also: Checking ADS Conguration in an ABAP Environment.

Result

If all test reports run without issues, your conguration is correct.

In case of problems, see SAP Note 944221 (currently only for conguration on the ABAP back end, for

example ICF service settings).

1.3.3Connect a WebDynpro Java Application

Import a certicate and congure the required templates to connect your WebDynpro Java application to the

SAP Forms service.

The following procedure describes the required steps for connecting a WebDynpro Java application to the SAP

Forms service.

Note

This procedure applies for SAP NetWeaver releases as of version 7.5.

Prerequisites

You have applied SAP note 2708581

to the AS Java.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Procedure

1. Open the NetWeaver Administrator (NWA) UI of your AS Java.

2. Establish the SSL Connection to SAP BTP by importing a root CA le into the AS Java keystore:

1. Open https://www.digicert.com/digicert-root-certificates.htm in your web browser

and download the following certicate:

• DigiCert Global Root CA

2. In NWA, goto: Conguration Security Certicate and Keys .

3. In the Key Storage view, select WebServiceSecurity:

4. In Details of view ‘WebServiceSecurity’ at the bottom of the screen, choose Import Entry:

5. In the popup, select entry type X.509 Certificate and import DigiCertGlobalRootCA.crt:

3. Congure Basic Authentication:

1. In the NWA, choose

SOA Technical Conguration Destination Template Management .

2. Check if there is an entry ConfigPort_Document.

1. If it does not exist, create a new template by choosing New in the Destinations section.

Choose the following values: Type = WSDL Destination, Name = ConfigPort_Document (case

sensitive), URL = https://adsformsprocessing-<tenant id>.<landscape>/ads.web/

AdobeDocumentServices/Config?wsdl&mode=ws_policy&style=document.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 27

2. If the template exists, highlight the element and check the eld <Destination Type> in the

detail view below, tab General. In case the value is WSIL, delete the template and create a new one

according to step 3.b.a.

3. If the template exists with <Destination Type> WSDL, modify the URL string according to step

3.b.a by choosing Edit in the detail view:

3. Choose the

Security tab and select HTTP Authentication from the Authentication dropdown list.

4. Select the option User ID/Password (Basic).

5. In the Details section, enter a user/password combination that is assigned to the role ADSCaller.

6. In section SSL Server Certicates, select Accept Certicates in Keystore View.

7. Select WebServiceSecurity from the dropdown list.

8. Choose Finish to save your entries:

4. Congure Client Certicate Authentiation:

1. Download a private key that is trusted by SAP BTP. To nd a list of trusted certicate authorities (CAs),

see Trusted Certicate Authorities for Client Certicate Authentication.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

2. In the Key Storage view WebServiceSecurity (see step 2), choose Import Entry.

3. In the popup, select entry type PKCS#12 Key Pair and import the chosen private key:

4. Create or adjust a second destination template SecureConfigPort_Document (see step 3). As

URL string, enter https://adsformsprocessing-<tenant id>.cert.<landscape>/ads.web/

AdobeDocumentServicesSec/Config?wsdl&mode=ws_policy&style=document.

1. On the Security tab, choose the option X.509 Client Certicate.

2. In the Details section, enter the imported <Private Key> for <Keystore View>

WebServiceSecurity.

3. In section SSL Server Certicates, select Ignore server certicates (insecure).

4. Choose Finish to save your entries.

5. Check your conguration as described in SAP Note 1443819

1.3.4Migration from On-Premise ADS

Copy conguration settings or les from your existing NetWeaver ADS installation to the SAP Forms service.

If you already have specic conguration settings or les on your NetWeaver ADS, you can migrate them to the

SAP Forms service.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 29

In NetWeaver, these les are located in the following directories:

• Fonts: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/FontManagerService/fonts/customer

• XDC les: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/lib

• Custom_xfa.XCI le: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/lib

• Credentials: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/TrustManagerService/trust/

credentials

• Job Proles: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/JobProles/Adobe/Print

Procedure

To do this, use the ADS Conguration Tool.

Related Information

Conguration Tool [page 30]

1.3.5Conguring Backup

Create a backup of your SAP Forms service conguration data.

To create a backup of your SAP Forms service conguration data, use the download procedure described in

Data Migration [page 39].

1.4 Conguration Tool

Use the conguration tool to manage your SAP Forms service settings.

Use the conguration UI to upload, download, or congure:

• Your own fonts

• XDC/XCI les (fonts and print information)

• Document Security (credentials, trusted anchors, certicate revocation lists, passwords)

• Job Proles (jobs to be used by the application, provided by you or by Adobe)

• Support Files (error logs)

• Caching (maximum cache size)

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Note

These les and settings are stored on SAP BTP in an area that is reserved exclusively for your tenant and

can only be accessed by members of your subaccount.

To access the conguration tool

1. Open the SAP BTP cockpit.

2. Choose Services.

3. Select SAP Forms Service by Adobe and choose Launch Conguration Tool in the detail view of the

service.

or, alternatively, enter the following URL in your browser:

https://adsformsprocessing-<yoursubaccount:technicalname>.<yourregionhost:

[xxx].hana.ondemand.com>/ads.web/ui/customer/index.html

Note

You can nd your subaccount's technical name in the SAP BTP cockpit:

Global Account Subaccounts Subaccount Tile: Info Icon Technical Name .

The complete domain name for the target host (region host) [xxx].hana.ondemand.com depends on the

data center (region) that is assigned to your subaccount, see Regions (section Regions and Hosts Available

for the Neo Environment).

Example: for region Europe (Frankfurt), the region host is eu2.hana.ondemand.com.

Prerequisites

• Your user is assigned to the role ADSAdmin.

See also: Initial Steps in Your SAP BTP Subaccount [page 8].

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 31

• Chrome browser (recommended)

Restrictions

For le upload via the conguration tool, the following size limits apply:

Max. File Size (per File)

Type

Max. Size

Font le

25 MB

Customer XDC/XCI les 2 MB

Job proles 1 MB

Credential/certicates/CRLs 5 MB

Data migration (.zip) 150 MB

Max. Storage Size (Total Volume)

Type

Max. Size

Fonts

150 MB

XDC/XCI 20 MB

Job proles 5 MB

Additional Restrictions

Type

Max. Size

Storage size for error PDFs 10 MB

Size for destination cache 15 MB

Form template size for rendering / data size for attaching to

PDF

20 MB

Input PDF size for PDF operations 10 MB

Related Information

Initial Steps in Your SAP BTP Subaccount [page 8]

Upload Fonts [page 33]

Congure Fonts and Print Information using XDC and XCI Files [page 34]

Congure Document Security [page 35]

Manage Job Proles [page 36]

Download Support Files [page 37]

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Congure Caching [page 38]

Data Migration [page 39]

1.4.1Upload Fonts

Upload and download fonts for PDF rendering with the SAP Forms service.

In the Fonts section, you can upload and download fonts required for PDF rendering.

• Press Upload to add a new fonts le to the list.

• Select the fonts le you want to download and choose Download to save or open it.

• To delete a fonts le from the list, select it and choose Delete.

• To update a font, just upload the new version of the font. The system will ask you if the existing font should

be overwritten.

Note

Font operations may take some time.

The SAP Forms service supports the following font types:

• OpenType

(.otf)

• TrueType

(.ttf)

• PostScript

Type 1 (.pfb, .pfm)

Note

Find the complete list of supported fonts in SAP note 2018817

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 33

1.4.2Congure Fonts and Print Information using XDC and

XCI Files

Congure fonts and print information for the SAP Forms service.

In the XDC, XCI Administration section, you can manage various XDC and XCI les.

• XDC les contain print information, such as printer details and page layout information required to render

documents in various print formats, including PDF.

• Under Customer XDC File, you can upload, download, display, and congure your own XDC les.

• Under Adobe XDC File, you can view and download the XDC les that Adobe provides.

• XCI les contain various congurations related to fonts.

• For XCI les, you can perform the same processing steps as for XDC les.

• You can only upload one custom_xfa.xci le. The name must be exactly as given here (case sensitive).

Note

Find more information in the Help Portal documentation about Mapping Fonts and Changing the Default

PDF Version.

Note

For details about setting printer options in your ABAP system (without modifying XDC les), see also:

Settings Using Additional Print Options in the Help Portal documentation.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.4.3Congure Document Security

Congure document security for the SAP Forms service.

In the Document Security section, you can congure the following:

• Credentials: Upload signatures used to sign PDF documents to the server and congure the signatures

with an alias name. You can also create new credentials here.

Note

The ReaderRights credential is precongured for your subaccount. You cannot install or delete

ReaderRights.

Caution

You cannot use the ReaderRights credential for digital signing.

Note

For more information, refer to Installing and Conguring Credentials in the Help Portal documentation..

• Trusted Anchors: Upload certicates required for verifying PDF signatures to the server and congure the

certicates with an alias name. You can also create new certicates here.

• Certicate Revocation Lists (CRL):

• Manage a list of revoked signatures.

• Upload a new list to the server from your local machine and dene URLs for these CRL les.

• You can congure the CRL Invalidation Period to customize how CRL les are fetched from URLs.

For example, if you set its value to 0, the CRL le is fetched from the URL for every request. If you set

the value to -1, the CRL is not fetched from the URL.

• Passwords: Congure passwords required to protect rendered PDF les with their alias names.

Note

A password must be at least 6 characters long. The maximum length is 255 char.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 35

1.4.4Manage Job Proles

Congure job proles for the SAP Forms service.

You can add job proles for dierent jobs that the application can use. Choose Job Proles in the left pane and

expand a node in the Details pane to view job proles in the system.

Some predened Job Proles are available in the Adobe folder. In addition, you can upload XML les containing

custom job proles.

• To view the contents of a job prole, select the prole and choose Show Job Prole Content.

• To view job prole templates provided by Adobe, expand the Adobe node and double-click a template.

• First, select the row JobProles. Then, choose Create Folder to create a folder to upload a custom prole.

• To upload a custom job prole, choose Upload and browse to the folder containing the XML le that

species the custom prole.

• Choose Download to download a job prole to your system.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.4.5Download Support Files

Congure system error logs and download support les.

You can use the Conguration UI to download PDF les containing system error logs.

Note

Important:

Support les will only be created and available, if the folder size is larger than 0 MB. The default size of the

folder is 0 MB.

Note

Important:

Be aware that support les may contain your business data. For more information on data security, see:

Data Storage Security.

For security reasons, you should delete stored Error.PDF les on a regular basis.

• Choose Support Files in the left pane to view the PDF les containing error logs.

• To download a PDF le, select it in the Details section and choose Download.

You can also congure the size of the folder that contains the error les.

• Choose Congure Folder Size and drag the slider to congure the folder size.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 37

Note

You can congure the size to a maximum of 10 MB. If the combined size of the error les exceeds the set

size, the oldest les are replaced by the most recent error les that are stored in the folder. If you reduce the

folder size, older error les will be deleted until the folder size is reached.

1.4.6Congure Caching

Set the cache size for the SAP Forms service destination folder or delete the forms/destination cache.

To congure the cache for the destination folder using the conguration UI, perform the following steps:

• Choose Congure Destination Cache Size to congure the size of the destination folder cache.

Note

You can congure the cache size to a maximum of 15 MB.

• Choose Clear Cache to delete the cache for PDF forms or the destination cache.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.4.7Data Migration

Upload or download your conguration data for data migration purposes.

You can use the conguration UI to download or upload your conguration data.

Choose Data Migration in the left navigation pane of the conguration UI to access the Download and Upload

functions:

If you choose Download Data, the following data will be downloaded:

• Fonts: custom fonts

• XDC, XCI Administration: customer les for XDC and XCI settings

• Document Security: certicates, credentials, Certicate Revocation Lists (CRLs)

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 39

Note

You cannot download the alias names. After uploading downloaded les you have to re-enter the

corresponding alias names manually.

• Job Proles: customer job proles

• Support Files: setting for storage size of error.pdf les

Note

Error.pdf les and passwords will not be downloaded.

• Caching: setting for destination cache size

Note

You can only download the les that you uploaded previously. Predened data are not downloaded.

If you choose Upload Data, you can browse for the les to be uploaded. When uploading les, keep in mind the

following upload behavior:

• If you upload a le that already exists in the target tenant, the le will be overwritten.

Note

Uploading Support File settings overwrites the size conguration only. Existing error.pdf les are not

changed.

Note

Uploading Caching information only overwrites the cache size setting, not the cached content.

• When uploading les that don't exist in the target tenant, other existing les won't be touched.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

• After uploading downloaded les from Document Security, you have to re-enter the corresponding alias

names manually.

1.5 SAP Forms Service by Adobe REST API

Get started with the SAP Forms service REST API and nd a collection of typical use cases.

The SAP Forms service REST API provides a subset of known ABAP PDF Object features. They are addressed

by dierent URIs (Uniform Resource Identiers) where each URI supports data and document exchange in a

JSON format. The application calls the SAP Forms service REST API via HTTP.

The interface is separated into three dierent ADS domains:

• ADS Get requests

• ADS Set requests

• ADS Render requests

Each request is always related to a pdf le entity as part of input our output payload (wrapped in a JSON and

added to the HTTP request body). As this part of the REST API is built upon the ADS soap service, each request

is handled within a HTTP POST request and the URIs themselves include sucient information to describe how

the message is processed: For example, POST /pdf/adsGet/attachments. The User sends a PDF (POST

pdf/…) to get via the ADS (…/adsGet/…) functionality all pdf attachments (pdf/…/attachments).

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 41

Related Information

Connection Setup [page 42]

Call the REST API [page 46]

Template Store API [page 47]

Template Store UI [page 57]

Supportability and Troubleshooting [page 64]

REST API Scenarios [page 71]

1.5.1Connection Setup

Congure a destination in the SAP BTP cockpit to connect your application to the SAP Forms service via REST

API.

The SAP Forms service REST API uses a precongured destination to connect to the Adobe Document

Services (ADS) of the SAP Forms service.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Assign the User to the ADSCaller Role

To call the SAP Forms service, you need a user who is assigned to the role ADSCaller.

1. Go to the main screen of your subaccount in the SAP BTP cockpit and choose Services from the main

menu.

2. Select the tile SAP Forms Service by Adobe and choose the link SAP Forms Service by Adobe (Roles and

Destinations).

3. Check, which user is assigned to the ADSCaller role.

Note

By default, the user who enabled the service is assigned to the ADSCaller role.

4. You can also enter a new user and assign this user to the ADSCaller role.

5. Press Save.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 43

Finalize the Destination

The SAP Forms service destination ADS is partly precongured for your subaccount. To use it, you must nalize

it by dening the authentication.

1. Go to the main screen of your subaccount in the SAP BTP cockpit and choose Services from the main

menu.

2. Select the tile SAP Forms Service by Adobe and choose the link Destination for SAP Forms Service by

Adobe REST API.

3. The Destinations screen opens. Press the Edit button of the SAP Forms service destination ADS.

4. Specify the <Authentication> method. Two authentication types are supported: Basic Authentication

and Client Certicate Authentication.

• Basic Authentication

Specify <User> and <Password>.

Note

The user must be the same user that you assigned to the ADSCaller role.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

• Client Certicate Authentication

1. Provide a private key that is trusted by SAP Cloud Platform. To nd a list of trusted certicate

authorities (CAs), see Trusted Certicate Authorities for Client Certicate Authentication.

2. Choose Certicates and upload your private key.

3. Select the ADS destination and change the URL to:

https://adsformsprocessing-<yoursubaccount:technicalname>.cert.<yourregionhost:

[xxx].hana.ondemand.com>

4. Select Authentication type ClientCertificateAuthentication.

5. Choose your previously uploaded private key in <Key Store Location> and enter the private

key’s password in <Key Store Password>.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 45

Note

The user (CN value) of your private key must be the same user that you assigned to the

ADSCaller role.

5. Press Save.

Note

Using the button Check Connection

always returns an “Internal Server Error” message. You can ignore this message:

1.5.2Call the REST API

Get access to the SAP Forms service REST API.

The base URL for calling the API features is:

• https://adsrestapiformsprocessing-<yoursubaccount>.<yourregionhost:

[xxx.]hana.ondemand.com>/ads.restapi/v1/

Note

See also: Regions and Hosts.

Besides rendering request errors, the general Error JSON will always have the same structure.

Example: Response (Error)

HTTP 500

{ "message": "Internal API or ADS Error",

"results": "Short description of error",

"traceString": "Detailed description about what exactly went wrong",

"errorLevel": "ADS or API Error Level" }

Catch and Store the Error.PDF

When the SAP Forms service fails to generate an output, it returns an Error.pdf le. The REST API provides this

Error.pdf as part of the JSON response (HTTP 500). This is restricted to the rendering feature of the service.

The Error.PDF contains information that is useful to analyze and to reproduce the issue if needed. Parts are, for

example, the template le, the runtime xml data and trace information.

Example: Response (Error.pdf)

HTTP 500

{ "message": "Internal ADS Rendering Error",

"results": "Error during rendering of PDF file",

"traceString": "Detailed description about what exactly went wrong",

"errorLevel": "ADS Error Level",

"errorPDF": "V2hvIGluIHRoZSB3b3JsZCB3aWxsIGRlY29kZSB0aGlzIFN0cmluZz8=" }

Implement a Function to Set the Trace Level

If the output of the returned PDF is not as expected, for example if there are problems with pagination or

layout, or if the trace information contained in the Error.pdf is not detailed enough, set a higher trace level.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

The recommendation is to set a trace level value of 2. The REST API will return a JSON response that contains a

PDF with additional information or if no PDF can be created at all, a detailed trace.

Example: Request with TraceLevel

POST

https://adsrestapiformsprocessing-<yoursubaccount>.[xxx.]hana.ondemand.com/

ads.restapi/v1/adsRender/pdf?TraceLevel=2

Content-Type: application/json

{ "template" : "VGhpcyBjb3VsZCBiZSB5b3VyIHRlbXBsYXRl",

"data" : "VGhpcyBjb3VsZCBiZSB5b3VyIGRhdGEgZmlsZQ=="}

1.5.5.2 Analyze Issues

The following section provides an overview of dierent issue types related to the SAP Forms service REST API

that may occur in your application. Basically, you can distinguish between internal API errors and internal ADS

errors (i.e. errors related directly to the ADS component of the SAP Forms service).

Issue Types

The primary piece of information helping to understand and correct the problem is usually included in the

response error JSON. Within the JSON, detailed information about the corresponding processing issue is

shown.

To analyze, check the response strings in JSON from the API. The message in the response JSON tells you, if

it’s an ADS error or an API error. This could be Internal API Errors or Internal ADS Errors.

Internal API Errors

• Corrupted JSON or missing mandatory JSON elds

• BASE64 encoding issues in Input JSON

• SAP Forms service connection issues, e.g. wrong destination

• SAP Forms service REST API connection issues

Internal API Errors are usually assigned a specic HTTP Error Code. Besides the information included in the

JSON, this code may help to interpret the error cause:

HTTP Code HTTP Text Error Cause

500 Internal Server Error Due to unexpected behavior or ADS is-

sues, the API is not able to process the

request.

400 Bad Request The JSON send to the API is corrupted

and does not follow the usual format.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 67

HTTP Code HTTP Text Error Cause

401 Unauthenticated This can be caused by wrong OAuth

credentials or missing OAuth congura-

tion.

404 Not Found The URL which is accessed is not avail-

able.

406 Not Acceptable The API is not able to respond to the

Accept Header of the API request.

409 Conict Mandatory elds in the JSON are miss-

ing or le content is not encrypted by

BASE64.

415 Unsupported Media Type The Media Type send to the API is not

application/json.

Internal ADS Errors

• PDF Rendering issues

• Unexpected Output

• Other Errors

Internal ADS Errors are always assigned to an HTTP 500 status code.

The following information describes the recommended action for each error type.

Related Information

Error Types [page 68]

1.5.5.2.1 Error Types

Internal API Error - Corrupted JSON or missing mandatory JSON elds

HTTP 400 - Bad Request or HTTP 409 - Conict

If you receive an error, proceed as follows:

1. Follow the instructions stated in the JSON Error response to detect missing mandatory elds or formatting

issues.

2. Check your application:

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1. Is a JSON envelope send as Content-Type: application/json within the request?

2. Is the JSON envelope formatted correctly?

3. Are all mandatory elds included in the JSON?

3. Correct your application by adding missing elds to the JSON input of your request or correcting the JSON

format.

Internal API Error - BASE64 encoding issues in the JSON input

HTTP 409 - Conict

If you receive an error, proceed as follows:

1. Identify and x all wrong BASE64 strings based on the information given in the JSON error response.

2. Check your application:

1. Does the BASE64 string contain the expected BASE64 string set?

2. Is the BASE64 string length valid?

3. Is the BASE64 encoding technique correctly applied?

3. Correct your application.

Internal API Error - SAP Forms Service by Adobe connection issues

HTTP 500 – Server Error

If you receive an error, do the following checks in the SAP BTP cockpit of the consumer subaccount. The

required check may depend on the error message.

1. Is destination ADS dened?

2. Is an authentication dened for the destination ADS?

3. Are the authentication credentials valid?

4. Is the destination able to contact the SAP Forms service?

Note

See also OAuth Setup using the Postman Client [page 78]

5. Correct the URL.

Note

The Base URL for the calling features of the SAP Forms service

REST API is: https://adsrestapiformsprocessing-<yoursubaccount>.<yourregionhost:

[xxx.]hana.ondemand.com>/ads.restapi/v1/ (see also: Regions and Hosts).

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 69

Internal API Error - SAP Forms Service by Adobe REST API connection issues

HTTP 401 - Unauthorized or HTTP 404 – Not Found

If you receive a not found error, do the following checks:

1. Is the URL pointing to the API valid? Check, if the name of the consumer subaccount <yoursubaccount> is

correct. See step 4.

2. Correct the URL according to the available REST resources in the documentation.

3. Check if the SAP Forms service REST API works by opening the API documentation

in your browser. Example: https://adsrestapiformsprocessing-<yoursubaccount>.

[xxx.]hana.ondemand.com/ads.restapi/

4. You will receive a response, if you enter the correct URL and the SAP Forms service REST API is up and

running.

In case you receive an error message, create a message under BC-SRV-FP-NEO.

If you receive an unauthorized error, do the following checks:

1. Did you include the OAuth Token to the Authorization part of the http header?

2. If the token is not available yet, follow the instructions in OAuth Setup using the Postman Client [page 78].

Internal ADS errors - PDF Rendering issues

HTTP 500 – Server Error

The JSON response contains am Error.PDF, when the SAP Forms service detected a render problem.

If you receive such problem, proceed as follows:

1. Call the SAP Forms service REST API by sending the application request again, but set trace level to 2. This

will request the generation of a PDF with additional information. Extend the URL as follows (example):

POST

https://adsrestapiformsprocessing-<yoursubaccount>.[xxx.]hana.ondemand.com/

ads.restapi/v1/adsRender/pdf?TraceLevel=2

Content-Type: application/json

{ "template" : "RXJyb3I=",

"data" : "RXJyb3I=" }

The SAP Forms service REST API returns the JSON including the PDF with additional information and the

response of the ADS. The SAP Forms service REST API adds a TraceString to the PDFOut.PDF with detailed

Information about the response from ADS.

{ "name" : "PDFOut.PDF",

"file" : "VGhpcyBpcyByYW5kb20gb3V0cHV0IGZpbGU=",

"traceString" : "Example Trace String" }

2. If the application displays the PDF in Adobe Reader, you can also download the PDF from there.

3. Open the PDF and check, if following les are attached to it.

• Form layout le (.xdp le)

• XML data le

• Trace le

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

4. Extract the layout le and the XML data le from the PDF for checking. Open the layout le in the

standalone Adobe LiveCycle Designer and try to x. You can also preview the layout with the XML le.

5. If you cannot x by changing the layout or data, open a message under BC-SRV-FP and attach the

Error.PDF or PDF with additional information. Here is the complete list of information we need to help you:

• Form layout le (.xdp le)

• XML data le

• Trace le

• ERROR.PDF or the PDF with additional information

6. Don’t forget to describe the problem in detail, for example if an output in the PDF is not as expected, mark

this in a screenshot.

Internal ADS errors - Unexpected Output

HTTP 200 - OK

If the responded PDF does not look like as expected, you request a PDF with additional information. This helps

you analyzing.

1. Call the SAP Forms service REST API by sending the application request again, but set trace level to 2. This

will request the generation of a PDF with additional information.

2. Follow the same procedures as described in Internal ADS errors - PDF Rendering issues above.

Internal ADS errors – Other Errors

HTTP 500 - Server

Always have a look at the JSON traceString tag of the SAP Forms service REST API response, if you receive an

internal ADS Error. It contains a description of the problem. Try to identify and x the root cause of the error.

1.5.6REST API Scenarios

Find a collection of typical scenarios that help you use the SAP Forms service REST API.

OAuth Setup

The SAP Forms service REST API requires OAuth for authentication.

The following scenarios describe two dierent ways to setup OAuth:

Retrieving an OAuth Token in Java [page 72]

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 71

OAuth Setup using the Postman Client [page 78]

Note

If you use a dierent client, refer to the corresponding product-specic documentation and apply the

settings accordingly.

Java REST Client

Create a simple REST client in Java that calls the SAP Forms service REST API and process the JSON response

entity: Implement a Simple REST Client in Java [page 83]

Adobe LiveCycle Designer

Provide your own form templates using the AdobeLiveCycle Designer: Using the Adobe LiveCycle Designer

[page 86]

HTML5 Integration

Learn how to integrate the template store API into an HTML5 application running in the SAP BTP Neo

environment: Integrate the REST API in an HTML5 Application [page 92]

1.5.6.1 Retrieving an OAuth Token in Java

Use a Java OAuth client to retrieve OAuth credentials for the SAP Forms service REST API.

This example uses the Java Apache HttpComponents to generate an OAuth token from the SAP BTP OAuth

service.

Note

Depending on your specic implementation, retrieving the OAuth credentials may require a dierent

procedure.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Steps

• Register an OAuth Client in the Cockpit [page 73]

• Implement an OAuth Client in Java [page 74]

• Full Example Implementation [page 77]

1.5.6.1.1 Register an OAuth Client in the Cockpit

Follow these steps to register an OAuth client in the SAP BTP cockpit.

1. Go to the main page of your subaccount in the SAP BTP cockpit and choose Security → OAuth.

2. Go to the Clients tab. Here you can register new clients that are authorized to use the SAP Forms service

REST API.

3. Press the button Register New Client.

4. Enter a <Name> (<any name>) and <Description> (<optional>).

5. For <Subscription> select the entry formsprocessing/adsrestapi from the drop down list.

6. In <Authorization Grant>: select Client Credentials from the drop down list.

7. In eld <Secret>, enter a <secret of your choice>.

8. Adjust the <Token Lifetime> according to your needs (leave empty or enter a preferred value).

9. Press Save.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 73

Next Steps

Implement an OAuth Client in Java [page 74]

Full Example Implementation [page 77]

1.5.6.1.2 Implement an OAuth Client in Java

Create a Java OAuth client to retrieve OAuth credentials for the SAP Forms service REST API.

An Apache HTTPClient java object is used to establish the communication between client/OAuth server and

SAP BTP. This client helps you to send and consume the information that you need to retrieve the access

token.

HttpClient httpClient = HttpClientBuilder.create().build();

The communication between client and OAuth Server is based on an httpPost request. You can retrieve the

OAuth token by accessing the Token Endpoint URL which can be found in the SAP BTP cockpit.

Logon to the cockpit and choose Security OAuth Tab: Branding Section: OAuth URLs :

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

By sending the httpPost request to this URL a valid token will be returned as a response. You can use this token

for further requests sent to the REST API.

String tokenEndpoint = “https://oauthasservices-<yoursubaccount-id>.

[xxx.]hana.ondemand.com/oauth2/api/v1/token”;

HttpPost httpPost = new HttpPost(tokenEndpoint);

The token endpoint is protected by Basic Authentication. The <client ID> serves as user name and <client

secret> as password.

Note

Use the conguration of the previously created OAuth client.

The credentials must be encoded with BASE 64 and added to the header of HTTP Post object.

String base64Credentials = Base64.getEncoder().encodeToString((client_id +

":" + client_secret).getBytes());

httpPost.addHeader("Authorization", "Basic " + base64Credentials);

It is required that you dene the grant type parameter and the scope within the request. Add the parameters to

the HTTP body of the request as content-type: “application/x-www-form-urlencoded”.

String grant_type = "client_credentials";

String scope = "generate-ads-output";

httpPost.addHeader("Content-Type", "application/x-www-form-urlencoded");

StringEntity input = null;

try {

input = new StringEntity("grant_type=" + grant_type +

"&scope=" + scope);

httpPost.setEntity(input);

} catch (UnsupportedEncodingException e) {

e.printStackTrace();

}

The HTTP response message from the server can be interpreted by the HttpResponse object after executing

the POST request.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 75

HttpResponse response = null;

try {

response = httpClient.execute(httpPost);

} catch (IOException e) {

e.printStackTrace();

}

HttpResponse includes the message entity which has been returned by the REST API. Therefore, we should

unwrap this response object to process the JSON entity accordingly.

We convert the response InputStream to a String using Apaches IOUtils:

String result = null;

try {

result = IOUtils.toString(response.getEntity().getContent(), "UTF-8");

} catch (IOException e) {

e.printStackTrace();

}

return result;

The returned String is a JSON. It includes the actual access token:

{

"access_token":"abcabcabcabcabcabcabcabcabc00",

"token_type":"Bearer",

"expires_in":5184000,

"scope":"generate-ads-output"

}

Dealing with Proxies

In case your requests are sent through a proxy, add the following code lines to your httpPost object before

sending the actual request:

HttpHost target = new HttpHost("proxy", 8080, "http");

RequestConfig config = RequestConfig.custom().setProxy(target).build();

httpPost.setConfig(config);

Next Step

Full Example Implementation [page 77]

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.5.6.1.3 Full Example Implementation

Find a full example implementation for retrieving an OAuth token in Java.

Sample Code

import java.io.IOException;

import java.io.UnsupportedEncodingException;

import java.util.Base64;

import org.apache.commons.io.IOUtils;

import org.apache.http.HttpHost;

import org.apache.http.HttpResponse;

import org.apache.http.client.HttpClient;

import org.apache.http.client.config.RequestConfig;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.entity.StringEntity;

import org.apache.http.impl.client.HttpClientBuilder;

public class OAuthClient {

private String tokenEndpoint = "https://oauthasservices-

<subaccountuser>.[xxx.]hana.ondemand.com/

oauth2/api/v1/token";

private String client_id = "myclient_id";

private String client_secret = "mysecret";

private String grant_type = "client_credentials";

private String scope = "generate-ads-output";

public String callService() {

/* HTTPCLIENT AND HTTPPOST OOBJECT */

HttpClient httpClient = HttpClientBuilder.create().build();

HttpPost httpPost = new HttpPost(tokenEndpoint);

/* AUTHENTICATION CREDENTIALS ENCODING */

String base64Credentials =

Base64.getEncoder().encodeToString((client_id + ":"

+ client_secret).getBytes());

/* HEADER INFO */

httpPost.addHeader("Authorization", "Basic " + base64Credentials);

httpPost.addHeader("Content-Type", "application/x-www-form-

urlencoded");

/* PROXY CONFIG */

HttpHost target = new HttpHost("proxy", 8080, "http");

RequestConfig config =

RequestConfig.custom().setProxy(target).build();

httpPost.setConfig(config);

/* OAUTH PARAMETERS ADDED TO BODY */

StringEntity input = null;

try {

input = new StringEntity("grant_type=" + grant_type + "&scope=" +

scope);

httpPost.setEntity(input);

} catch (UnsupportedEncodingException e) {

e.printStackTrace();

}

/* SEND AND RETRIEVE RESPONSE */

HttpResponse response = null;

try {

response = httpClient.execute(httpPost);

} catch (IOException e) {

e.printStackTrace();

}

/* RESPONSE AS STRING */

String result = null;

try {

result = IOUtils.toString(response.getEntity().getContent(),

"UTF-8");

} catch (IOException e) {

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 77

e.printStackTrace();

}

return result;

}

public static void main(String[] args) {

OAuthClient oauthClient = new OAuthClient();

String res = oauthClient.callService();

System.out.println(res);

}

1.5.6.2 OAuth Setup using the Postman Client

Set up a Postman OAuth client to retrieve OAuth credentials for the SAP Forms service REST API.

In this example, you will learn how to congure OAuth using the Postman client.

Steps

• Register the OAuth Client in the Cockpit (Postman) [page 78]

• Get the OAuth Access Token (Postman) [page 80]

• OAuth Token Administration (Postman) [page 82]

1.5.6.2.1 Register the OAuth Client in the Cockpit

(Postman)

Learn how to register an OAuth client in the SAP BTP cockpit. The following procedure uses the Postman client

as example.

Note

If you use a dierent OAuth client, enter the product-specic data accordingly.

1. Go to the main page of your subaccount in the SAP BTP cockpit and choose Security → OAuth.

2. Go to the Clients tab. Here you can register new clients that are authorized to use the SAP Forms service

REST API.

3. Press the button Register New Client.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

4. Enter <Name> and <Description> of the OAuth client used.

5. For <Subscription> select the entry formsprocessing/adsrestapi from the drop down list.

6. In <Redirect URI>: enter the redirect URL of the OAuth client you use, for example,

https://

oauth.pstmn.io/v1/browser-callback.

7. Adjust the <Token Lifetime> according to your needs.

8. Press Save.

The following screenshot of the SAP BTP cockpit shows the usage of Postman as client:

8. Make a copy of the ID. You will need it later in Postman.

9. Go to the tab Branding.

10. Make a copy of the URLs for <Authorization Endpoint> and <Token Endpoint>.

You will need to enter these URLs later in your OAuth client:

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 79

Next Steps

Get the OAuth Access Token (Postman) [page 80]

OAuth Token Administration (Postman) [page 82]

1.5.6.2.2 Get the OAuth Access Token (Postman)

Congure an OAuth client to get an access token.

Learn how to get an access token using the Postman client.

Note

For other OAuth clients, please refer to the corresponding product documentation.

1. In Postman, go to Authorization and select OAuth 2.0 as Type

2. Press button Get new Access Token.

3. Enter any name for Token Name.

4. Enter a Callback URL, for example https://oauth.pstmn.io/v1/browser-callback.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

5. In Auth URL enter the Authorization Endpoint URL you have copied before.

6. In Access Token URL enter the Token Endpoint URL you have copied before.

7. In Client ID enter the ID from the client you have registered in the SAP BTP cockpit before.

8. Under Scope, enter generate-ads-output.

Note

This entry is mandatory!

9. Press the button Request Token.

10. The SAP BTP Authorization Endpoint page opens. Press Authorize.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 81

11. In Postman choose the newly created Token.

12. Under Add token to select Header from dropdown list.

13. Press the button Use Token.

14. You have now created a token. Postman will use it for each request to the SAP Forms service REST API.

Next Step

OAuth Token Administration (Postman) [page 82]

1.5.6.2.3 OAuth Token Administration (Postman)

Access the OAuth token administration for the Postman client in the SAP BTP cockpit.

The newly created token is visible in the Token Management of the SAP BTP cockpit .

1. Go to the main page of your subaccount in the SAP BTP cockpit and choose Security → OAuth.

2. Go to the tab Branding.

3. Choose the End User UI URL. The following screen appears (example):

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.5.6.3 Implement a Simple REST Client in Java

Create a simple Java REST client that calls the SAP Forms service REST API and process the JSON response

entity.

In this example, you will learn how to send an ADS Render Request to the REST API and process the REST

response accordingly.

Rest Libraries in Java

There are numerous possibilities and libraries which can help to create a simple REST client in Java. In this

example, we are using the Apache HttpComponents. This library provides a wide toolset for the creation and

maintenance of low-level Java components focused on HTTP and associated protocols. Following packages are

required:

import org.apache.http.HttpHost;

import org.apache.http.HttpResponse;

import org.apache.http.client.HttpClient;

import org.apache.http.client.config.RequestConfig;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.entity.StringEntity;

import org.apache.http.impl.client.HttpClientBuilder;

import org.apache.commons.io.IOUtils;

Example Code

As the communication between client and server is done via HTTP we create an Apache HTTPClient. This client

side HTTP transport library can transmit and receive HTTP messages.

HttpClient httpClient = HttpClientBuilder.create().build();

In the next step, we create an HttpPost Object. This object enables an HTTP Post request. Thus, a target URL

and head information should be added as well as the actual JSON input.

HttpPost request = new HttpPost("<<BASE PATH>>/adsRender/pdf");

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 83

The API is protected by OAuth2. For conguration details, see Conguring OAuth 2.0.

The OAuth token must be added to the header of every request send to the service.

request.addHeader("authorization", "BEARER " + <<OAuth Token>>);

Data input and output is always wrapped in JSON envelope. For this reason, content-type should be always

application/json.

request.addHeader("content-type", "application/json");

The JSON input string can be mapped to a StringEntity object which is added as an entity to the POST request.

StringEntity input = null;

try {

input = new StringEntity(<<JSON String>>);

} catch (UnsupportedEncodingException e) {

e.printStackTrace();

}

request.setEntity(input);

The HTTP response message from the server can be interpreted by the HttpResponse object after executing

the post request.

HttpResponse response = null;

try {

response = httpClient.execute(request);

} catch (IOException e) {

e.printStackTrace();

)

Encode and Interpret the REST API Response

HttpResponse includes the message entity which has been returned by the REST API. Therefore, we should

unwrap this response object to process the JSON entity accordingly.

We convert the response InputStream to a String using Apaches IOUtils:

String result = null;

try {

result = IOUtils.toString(response.getEntity().getContent(), "UTF-8");

} catch (IOException e) {

e.printStackTrace();

}

The resulting String now includes the JSON returned from the REST Service. This is just one possibility to

convert the HTTP response. Of course, any other method can be applied in to t best to your implementation.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Dealing with Proxies

In case requests being sent behind a proxy please add following conguration to your HttpPost object.

HttpHost proxy = new HttpHost("<<proxy host>>", <<port>>, "<<http/https>>");

RequestConfig config = RequestConfig.custom().setProxy(proxy).build();

request.setConfig(config);

Full Example Implementation

Sample Code

package com.sap.formsprocessing.rest;

import java.io.IOException;

import java.io.UnsupportedEncodingException;

import org.apache.commons.io.IOUtils;

import org.apache.http.HttpHost;

import org.apache.http.HttpResponse;

import org.apache.http.client.HttpClient;

import org.apache.http.client.config.RequestConfig;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.entity.StringEntity;

import org.apache.http.impl.client.HttpClientBuilder;

public class RestClient {

public String callService() {

/* TARGET URL AND JSON */

String url = "<<base url>>/ads.restapi/v1/adsRender/pdf";

String json = "<<your json (please find the Example JSON in the

content section)>>";

/* HTTPCLIENT AND HTTPPOST OOBJECT */

HttpClient httpClient = HttpClientBuilder.create().build();

HttpPost request = new HttpPost(url);

/* ADD HEADER INFO */

request.addHeader("authorization", "Bearer <<token>>");

request.addHeader("content-type", "application/json");

/* PROXY CONFIG */

HttpHost target = new HttpHost("proxy", 8080, "http");

RequestConfig config =

RequestConfig.custom().setProxy(target).build();

request.setConfig(config);

/* JSON AS STRINGENTITY */

StringEntity input = null;

try {

input = new StringEntity(json);

} catch (UnsupportedEncodingException e) {

e.printStackTrace();

}

request.setEntity(input);

/* SEND AND RETRIEVE RESPONSE */

HttpResponse response = null;

try {

response = httpClient.execute(request);

} catch (IOException e) {

e.printStackTrace();

}

/* RESPONSE AS JSON STRING */

String result = null;

try {

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 85

result = IOUtils.toString(response.getEntity().getContent(),

"UTF-8");

} catch (IOException e) {

e.printStackTrace();

}

return result;

}

public static void main(String[] args) {

RestClient restClient = new RestClient();

String response = restClient.callService();

System.out.println(response);

}

1.5.6.4 Using the Adobe LiveCycle Designer

Use the Adobe LiveCycle Designer to provide your own form templates for the SAP Forms service REST API.

Adobe LiveCycle Designer supports you in creating templates for interactive and print forms by providing a

wide set of design functions.

Find more information in this section how to install and use the Adobe LiveCycle Designer.

Download and Installation

To download and install or update the Adobe LiveCycle Designer, follow the instructions in SAP note

2187332

(download and installation of version 11.0).

Related Information

Create a Simple Template with Generated Sample Data [page 86]

1.5.6.4.1 Create a Simple Template with Generated Sample

Data

In this short and simplied example, we will demonstrate how to create a template and a sample data le

binding using the Adobe LiveCycle Designer.

Note

This example does not include all capabilities of the LiveCycle Designer. It can be used as a starting point

for later development.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1. Open the LiveCycle Designer.

2. Select New Form.

3. Select Use a blank form and press Next.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 87

4. On the next page choose Finish, the template overview will open.

5. Add objects from the object library to the design view via drag and drop.

1. Several text elds

2. Date/time eld

3. Time eld

We will use these objects to demonstrate the sample data generation and data binding.

6. On the top menu bar, select File Form Properties .

7. Select Preview Generate Preview Data… .

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

8. In the next view select an appropriate le path and le name and generate the data xml-le.

Content of the generated data xml le:

In the next steps, this le will be integrated into LiveCycle Designer’s Data View:

9. Close the Form Properties window and select the Data View tab next to the Design View. Right-Click below

the Data View tab and choose New Data Connection….

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 89

10. Select Sample XML Data and press Next.

11. Choose the previously created data xml le and choose Finish to integrate the data xml.

(Conrm the prompt about the clearance of Use Name data bindings).

12. On the Data View you should now nd the data nodes from the data xml le. These nodes can be bound to

the elds on the template’s Design View.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

13. Bind the data node TextField1 to eld <TextField1>: click on the eld, then, in the Object tab choose

Binding and create a new data binding Data Binding (Open, Save, Submit). Choose Use DataConnection

TextField1 .

14. Conrm the binding and select Update all related properties. Press Ok.

15. Repeat the data binding for all remaining elds accordingly.

16. For every data node bound to a eld you will nd a new tag/symbol in the Data View.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 91

17. Save the template as Adobe XML Form (*xdp).

18. Send template and data le via a render request to the REST API (within the pre-dened JSON structure).

19. The resulting PDF will include all template elds and dummy data.

Note

It is the responsibility of the application implementing the REST Service to maintain and provide the

XML data structure that ts the preferred PDF template. External data that you may want to include in a

resulting PDF must be transferred in this XML structure accordingly. Otherwise, it is not possible to render

a PDF based on template and data le.

1.5.6.5 Integrate the REST API in an HTML5 Application

Learn how to integrate the template store API into your HTML5 Application running in the SAP BTP Neo

environment.

Prerequisites

1. You are subscribed to the SAP Forms service.

2. You are familiar with App Descriptor concept of HTML5 applications, see: Application Descriptor File.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

Steps

• Create a new client and a destination for the template store API: Create an OAuth Client and a Destination

[page 93]

• Map your destination to the HTML5 application and secure the destination: Set Up your HTML5

Application [page 95]

1.5.6.5.1 Create an OAuth Client and a Destination

Create an OAuth client and a destination for the SAP Forms service template store REST API.

Create a new OAuth Client

1. Open the SAP BTP cockpit and choose Security OAuth .

2. Select the tab Clients, choose Register New Client and enter the following:

Field

Value

Name <anything>

Description <anything>

Subscription formsprocessing/adsrestapi

ID <already lled, otherwise choose: Regenerate ID>

Authorization Grant Client Credentials

Secret <enter a new secret>

Condential <tick the box>

Token Lifetime 60 minutes (or leave it empty)

3. Save the value for <Secret>, as you will use it later. In this example, it will be referred to as Client

Secret.

Create a Destination to the Template Store API

We now use the created client to connect to the template store via a destination.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 93

1. Open the SAP BTP cockpit and choose Connectivity Destinations .

2. Press the button New Destination and enter the following:

Field Value

Name <anything> (in this example we use templateAdmin)

Type HTTP

Description <anything>

URL https://adsrestapiformsprocessing-

<yoursubaccount:technicalname>.<yourreg

ionhost:[xxx].hana.ondemand.com>/

ads.restapi/

Proxy Type

Internet

Authentication OAuth2ClientCredentials

Client ID <your Client ID>

Client Secret <your Client Secret>

Token Service URL https://oauthasservices-

<yoursubaccount:technicalname>.<yourreg

ionhost:[xxx].hana.ondemand.com>/

oauth2/api/v1/token?

grant_type=client_credentials&scope=gen

erate-ads-output

Token Service User

Token Service Password <your Client Secret>

Note

You can nd your subaccount's technical name in the SAP BTP cockpit:

Global Account Subaccounts Subaccount Tile: Info Icon Technical Name .

The complete domain name for the target host (region host) [xxx].hana.ondemand.com depends

on the data center (region) that is assigned to your subaccount, see Regions and Hosts Available for

the Neo Environment.

Example: for region Europe (Frankfurt), the region host is eu2.hana.ondemand.com.

3. Save the destination.

4. Check the conguration using the button Check Connection. A popup Response returned: "200: OK"

should show up.

Next Step

Set Up your HTML5 Application [page 95]

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

1.5.6.5.2 Set Up your HTML5 Application

Map your destination to an HTML5 application and protect the destination by assigning user roles.

Map the Destination to your HTML5 Application via Application Descriptor

1. Open the neo-app.json le of your HTML5 application.

Set the property authenticationMethod to saml.

3. Add a new route:

Sample Code

{

"path": "/ads.restapi", (the template store will be mapped to this

path in your url)

"target": {

"type": "destination",

"name": "templateAdmin" (Name of Destination you created)

"description": "templateAdmin"

}

4. Save the changes and commit them to the HTML5 application repository.

5. After activating the changes, open the following URL in a Web browser to test the destination:

https://<html5-app-name>-

<accountname>.dispatcher.<landscape>.sap.hana.ondemand.com/ads.restapi/

6. You should now see the swagger documentation of the template store API.

Protect the Destination in your HTML5 Application

By default, every SAP BTP user who knows the above-mentioned URL can access the template store API.

Therefore, we recommend that you protect the destination using roles.

1. Open the neo-app.json le of your HTML5 application and add following object to the property

securityConstraints:

Sample Code

{

"permission": "<name of your role>",

"description": "Access Forms by Adobe",

"protectedPaths": [

"/ads.restapi/"

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 95

]

}

2. Save the changes and commit them to the HTML5 application repository.

3. Open your HTML5 application in the SAP BTP cockpit and choose Overview. You will see the new role in

Application Permissions.

4. Press Edit and make required changes.

5. If you want to use a custom role, navigate to Roles and create a new role. The role will then appear in the

dropdown menu of Application Permissions.

Note

For the changes to take eect, you must logout and login into the SAP BTP cockpit.

1.6 Security

Find an overview of security measures for the SAP Forms service by Adobe.

Topic

More Information

Assign specic authorizations to subaccount users for the

SAP Forms service.

Assigning Roles to Users [page 10]

Use the Cloud Connector for secure communication be-

tween the SAP Forms service and the ABAP system.

Installing and Conguring the Cloud Connector [page 20]

Set up an SSL connection between the ABAP system and

SAP BTP for communicaton with the SAP Forms service.

Conguring the ABAP System [page 12]

Protect your business data when downloading support les. Download Support Files [page 37]

Congure credentials, certicates and passwords for your

PDF documents.

Congure Document Security [page 35]

For data migration, download security-relevant conguration

les.

Data Migration [page 39]

Set up an OAuth client when using the the SAP Forms

service REST API.

REST API Scenarios [page 71]

To integrate the Template Store REST API into an HTML5

application, protect the destination used.

Integrate the REST API in an HTML5 Application [page 92]

Make sure you comply with applicable data protection and

privacy laws for processing personal or sensitive data.

Data Protection and Privacy [page 97]

General Recommendations

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

• For a maximum security level, make sure you use appropriate virus and malware protection software when

uploading or downloading data via the SAP Forms service, in addition to the virus scan provided by SAP.

• We recommend that you use Adobe Reader only in sandbox (default) mode.

1.6.1Data Protection and Privacy

Make sure that you comply with applicable data protection and privacy laws if you are processing any personal

or sensitive data through the SAP Forms service.

Note

SAP does not provide legal advice in any form. SAP software supports data protection compliance

by providing security features and data protection-relevant functions, such as blocking and deletion of

personal data. In many cases, compliance with applicable data protection and privacy laws is not covered

by a product feature. Furthermore, this information should not be taken as advice or a recommendation

regarding additional features that would be required in specic IT environments. Decisions related to data

protection must be made on a case-by-case basis, taking into consideration the given system landscape

and the applicable legal requirements. Denitions and other terms used in this documentation are not

taken from a specic legal source.

Caution

The SAP Forms service does not provide the technical capabilities to support the collection, processing,

and storage of sensitive personal data.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe

PUBLIC 97

Important Disclaimers and Legal Information

Hyperlinks

Some links are classied by an icon and/or a mouseover text. These links provide additional information.

About the icons:

• Links with the icon

: You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your

agreements with SAP) to this:

• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.

• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using

such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this

information.

Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any

advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within

the control or responsibility of SAP.

Beta and Other Experimental Features

Experimental features are not part of the ocially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by

SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use

the experimental features in a live operating environment or with data that has not been suciently backed up.

The purpose of experimental features is to get feedback early on, allowing customers and partners to inuence the future product accordingly. By providing your

feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example Code

Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax

and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of

example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free Language

SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities,

genders, and abilities.

PUBLIC

SAP Forms Service by Adobe for the Neo Environment

Important Disclaimers and Legal Information

SAP Forms Service by Adobe for the Neo Environment

Important Disclaimers and Legal Information

PUBLIC 99

www.sap.com/contactsap

No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP

aliate company. The information contained herein may be changed

without prior notice.

Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.

National product specications may vary.

These materials are provided by SAP SE or an SAP aliate company for

informational purposes only, without representation or warranty of any

kind, and SAP or its aliated companies shall not be liable for errors or

omissions with respect to the materials. The only warranties for SAP or

SAP aliate company products and services are those that are set forth

in the express warranty statements accompanying such products and

services, if any. Nothing herein should be construed as constituting an

additional warranty.

SAP and other SAP products and services mentioned herein as well as

their respective logos are trademarks or registered trademarks of SAP

SE (or an SAP aliate company) in Germany and other countries. All

other product and service names mentioned are the trademarks of their

respective companies.

Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.

THE BEST RUN 