Integration Guide | PUBLIC

SAP Cloud Platform Forms By Adobe

Document Version: CLOUD – 2021-07-04

SAP Forms Service by Adobe for the Neo

Environment
© 2021 SAP SE or an SAP affiliate company. All rights reserved.

THE BEST RUN

Content

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

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

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

1.3 Initial Steps in Your SAP BTP Subaccount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Enabling the SAP Forms Service for Your Subaccount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Assigning Roles to Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4 Connecting Your ABAP System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Configuring the ABAP System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Installing and Configuring the Cloud Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Configure the Destination in Your SAP BTP Subaccount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

1.5 Test Your Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.6 Migration from On-Premise ADS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.7 Configuration Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Upload Fonts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Configure Fonts and Print Information using XDC and XCI Files. . . . . . . . . . . . . . . . . . . . . . . . . 29

Configure Document Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

Manage Job Profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Download Support Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Configure Caching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Data Migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

1.8 Connect a WebDynpro Java Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.9 SAP Forms Service by Adobe REST API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Connection Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Call the REST API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Template Store API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Template Store UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Supportability and Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

REST API Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

1.10 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Data Protection and Privacy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

SAP Forms Service by Adobe for the Neo Environment

2 PUBLIC Content
1 SAP Forms Service by Adobe

Use SAP Forms service to manage print and interactive forms.

The SAP Forms service is a cloud service based on the ADS (Adobe Document Services) component by Adobe.
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 configuration 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 configuration tasks on your
ABAP system, the Cloud Connector, your SAP BTP subaccount, and the ADS configuration 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 39] 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 files. See also: Using the Adobe
LiveCycle Designer [page 83].

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.
● Work with forms in online and offline scenarios.
● Annotate PDF documents and collaborate on PDF document reviews.
● Capture data using forms and import the data directly into the SAP system.
● Allow users to digitally sign PDF documents.
● Embed other file 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).

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 3
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 notification
that the SAP Forms service has been configured for your subaccount (productive use).
● You have enbaled the service for your productive subaccount, see Enabling the SAP Forms Service for Your
Subaccount [page 7].
● 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 prefix XDC/Customer/ to the xdc file name you want
to assign to a SAP device.

Size limits:

For file upload via the configuration tool, some size limits apply. For more information, see Configuration Tool
[page 27].

 Note

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

Enhancements

SAP Forms Service by Adobe for the Neo Environment

4 PUBLIC SAP Forms Service by Adobe
 ● Support of software-based Aztec Barcode. See SAP Note 2699022 .
● Change or create custom locale definitions. See SAP Note 2696301 .
● Support of extended decimal data fields (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 7]
Connecting Your ABAP System [page 10]
Test Your Configuration [page 24]
Migration from On-Premise ADS [page 25]
Configuration Tool [page 26]
Connect a WebDynpro Java Application [page 36]
SAP Forms Service by Adobe REST API [page 39]
Security [page 94]
Data Protection and Privacy [page 95]

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.
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 first edition provides a subset of the already known ABAP PDF Object features. They are addressed by
different URIs (Uniform Resource Identifiers) 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 first 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.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 5
Related Information

Architecture [page 6]
Initial Steps in Your SAP BTP Subaccount [page 7]
Connecting Your ABAP System [page 10]
SAP Forms Service by Adobe REST API [page 39]

1.2 Architecture

SAP Forms service by Adobe: Architecture overview.

You can use the service the SAP Forms service in two different 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:
○ Configuration UI: You use the configuration UI to manage your own fonts, XDC files, 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:

SAP Forms Service by Adobe for the Neo Environment

6 PUBLIC SAP Forms Service by Adobe
1.3 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 7]

● Assigning Roles to Users [page 9]

1.3.1 Enabling the SAP Forms Service for Your Subaccount

Before you can configure 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.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 7
2. Click on the service to access the detail view. The configuration 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 configuration links are enabled.

4. Proceed with the next configuration step: Assigning Roles to Users [page 9].

SAP Forms Service by Adobe for the Neo Environment

8 PUBLIC SAP Forms Service by Adobe
1.3.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 configuration 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 7].

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 Configuration 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

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 9
Related Information

Connecting Your ABAP System [page 10]

Configure the Destination in Your SAP BTP Subaccount [page 22]

1.4 Connecting Your ABAP System

Configure 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 configuration 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

10 PUBLIC SAP Forms Service by Adobe
Learn more about the configuration details for each component in this section.

Related Information

Configuring the ABAP System [page 11]

Installing and Configuring the Cloud Connector [page 19]
Configure the Destination in Your SAP BTP Subaccount [page 22]

1.4.1 Configuring the ABAP System

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

You have to perform several configuration 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, configure SSL on your ABAP System.

 Note

For more information, see Configuring SAP NetWeaver AS for ABAP to Support SSL.

Related Information

Establish the SSL Connection to SAP BTP [page 11]

Configure the RFC Destination [page 13]
Configure the ICF Service on your ABAP System [page 19]

1.4.1.1 Establish the SSL Connection to SAP BTP

Configure your SSL connection to SAP BTP in the ABAP Trust Manager.

To set up an SSL connection between the ABAP system andSAP BTP, you have to import the required security
certificates into AS ABAP.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 11
  Note

We recommend you to create and use your individual SSL Client PSE for importing the required Root CA
certificates. 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 certificates in AS ABAP, see also: Configuring 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 certificate:
○ DigiCert Global Root CA
2. In the ABAP system, open the Trust Manager (transaction STRUST) and navigate to the individual SSL
client PSE you defined before. Double click this entry.
3. Import the certificate:
1. Choose the menu path: Certificate Import .
2. Select the file you downloaded previously and continue.
3. Press Add to Certificate List in the Certificate view. This certificate file will then be listed in the
Certificate List view.
4. Save your changes.

 Note

Due to a switch of root certificates on SAP BTP, certificates on all new SAP BTP data centers and
certificate renewals on the existing data centers use the new root CA issuer DigiCert.

For up-to-date information on the domain-specific validity of certificates on SAP BTP, please follow this
SCN blog: Certificate Authority Change .

Result

After importing the certificate, the certificate list and details in ABAP Trust Manager look like this:

SAP Forms Service by Adobe for the Neo Environment

12 PUBLIC SAP Forms Service by Adobe
1.4.1.2 Configure the RFC Destination

Create and configure 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 configure 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 certificate
authentication. Find the procedures for each authentication type below.

Basic Authentication

Tab: Technical Settings

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 13
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 find 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

14 PUBLIC SAP Forms Service by Adobe
Tab: Logon and Security

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

2. In the <User> and <Password> fields, 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 defined 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 certificate store where
you imported the SAP BTP root certificate.
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.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 15
Client Certificate Authentication

1. To configure the Technical Settings of the RFC destination, proceed as described in Basic Authentication
above.
In the field <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 find a list of trusted certificate authorities (CAs), see
Trusted Certificate Authorities for Client Certificate Authentication.
4. Import the private key into your ABAP backend system using transaction STRUST, see Establish the SSL
Connection to SAP BTP [page 11].

 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 find the CN name in the certificate's
<Subject> field in transaction STRUST:

SAP Forms Service by Adobe for the Neo Environment

16 PUBLIC SAP Forms Service by Adobe
 6. In Security Options , select Active to enable SSL and specify the name of the SSL certificate store where
you imported the SAP BTP root certificate.
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 Certificate 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!

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 17
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

18 PUBLIC SAP Forms Service by Adobe
1.4.1.3 Configure 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 configured 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.4.2 Installing and Configuring the Cloud Connector

Download, install, and configure 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 first 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 configuration of the Cloud Connector, see: Initial Configuration.

● For more information about operating the Cloud Connector, see Operations.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 19
Related Information

Configure the Destination in the Cloud Connector [page 20]

1.4.2.1 Configure the Destination in the Cloud Connector

Specifiy 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 configured.

Procedure

1. Open the Cloud Connector administration UI.

2. From your subaccount menu, choose Cloud to On-Premise and select tab Access Control to define 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.

 Note

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

SAP Forms Service by Adobe for the Neo Environment

20 PUBLIC SAP Forms Service by Adobe
  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 specified 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 configuring the destination in your SAP BTP subaccount.

6. Select a <Principal Type> (Kerberos or X.509 Certificate) if you are using principal
propagation, otherwise leave the default value None. 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.

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

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 21
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.

Defined resources:

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

● /sap/bc/fpads (subfolders included)

1.4.3 Configure the Destination in Your SAP BTP Subaccount

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

The destination information you specified for the ABAP system on the Cloud Connector also needs to be stored
in your SAP BTP subaccount.

Procedure

Proceed as follows to configure the destination in your SAP BTP subaccount:

1. Open your subaccount in the SAP BTP cockpit.

2. Select Services.
3. Select SAP Forms Service and in section Service Configuration 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>.

SAP Forms Service by Adobe for the Neo Environment

22 PUBLIC SAP Forms Service by Adobe
 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>
field, you must first set the <Proxy Type> to OnPremise (see step 11).

 Note

The location ID must be specified in the Cloud Connector, see Set up Connection Parameters and
HTTPS Proxy.

10. Under <URL>, specify the Virtual host name you specified 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 specified when you configured the destination
in the Cloud Connector.

11. As <Proxy Type>, choose OnPremise.

12. 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 Configuring Principal Propagation
(Cloud Connector).

13. 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.
14. Save your settings.

 Note

Per default, destination FP_ICF_DATA_<SID> calls the default ABAP client (specified by the profile
parameter login/system_client).In order to use a non-default ABAP client, perform the following steps
in the ABAP system:

1. Call transaction SICF and press Execute.

2. Select the node: default_host sap bc fp .
3. Double-click the node fp and choose Change.
4. Select the tab Logon Data and change the following parameters:
○ <Procedure>: Required with Logon Data
○ <Client>: <number of the client to be called>
5. Save your entries.
6. Perform the same steps in the node fpads.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 23
Result

The specified destination looks like this:

Related Information

Configure the Destination in the Cloud Connector [page 20]

1.5 Test Your Configuration

Using ABAP reports to test your the SAP Forms service configuration.

After finishing all configuration steps, you can use several ABAP reports to test whether the connection is
working fine.

SAP Forms Service by Adobe for the Neo Environment

24 PUBLIC SAP Forms Service by Adobe
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 Configuration in an ABAP Environment.

Result

If all test reports run without issues, your configuration is correct.

In case of problems, see SAP Note 944221 (currently only for configuration on the ABAP back end, for
example ICF service settings).

1.6 Migration from On-Premise ADS

Copy configuration settings or files from your existing NetWeaver ADS installation to the SAP Forms service.

If you already have specific configuration settings or files on your NetWeaver ADS, you can migrate them to the
SAP Forms service.

In NetWeaver, these files are located in the following directories:

● Fonts: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/FontManagerService/fonts/customer
● XDC files: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/lib
● Custom_xfa.XCI file: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/lib
● Credentials: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/TrustManagerService/trust/
credentials
● Job Profiles: /usr/sap/<SID>/SYS/global/AdobeDocumentServices/JobProfiles/Adobe/Print

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 25
Procedure

To do this, use the ADS Configuration Tool.

Related Information

Configuration Tool [page 26]

1.7 Configuration Tool

Use the configuration tool to manage your SAP Forms service settings.

Use the configuration UI to upload, download, or configure:

● Your own fonts

● XDC/XCI files (fonts and print information)
● Document Security (credentials, trusted anchors, certificate revocation lists, passwords)
● Job Profiles (jobs to be used by the application, provided by you or by Adobe)
● Support Files (error logs)
● Caching (maximum cache size)

 Note

These files 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 configuration tool

1. Open the SAP BTP cockpit.

2. Choose Services.
3. Select SAP Forms Service by Adobe and choose Launch Configuration 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 find your subaccount's technical name in the SAP BTP cockpit:

Global Account Subaccounts Subaccount Tile: Info Icon Technical Name .

SAP Forms Service by Adobe for the Neo Environment

26 PUBLIC SAP Forms Service by Adobe
 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 7].

● Internet Explorer > 10 or

● Chrome browser (recommended)

Restrictions

For file upload via the configuration tool, the following size limits apply:

Max. File Size (per File)

Type Max. Size

Font file 10 MB

Customer XDC/XCI files 1 MB

Job profiles 1 MB

Credential/certificates/CRLs 5 MB

Data migration (.zip) 150 MB

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 27
Max. Storage Size (Total Volume)
Type Max. Size

Fonts 100 MB

XDC/XCI 5 MB

Job profiles 5 MB

Additional Limitations
Type Max. Size

Storage size for error PDFs 10 MB

Size for destination cache 15 MB

Form template size for rendering 20 MB

Input PDF size for PDF operations 10 MB

Related Information

Initial Steps in Your SAP BTP Subaccount [page 7]

Upload Fonts [page 28]
Configure Fonts and Print Information using XDC and XCI Files [page 29]
Configure Document Security [page 30]
Manage Job Profiles [page 31]
Download Support Files [page 32]
Configure Caching [page 33]
Data Migration [page 34]

1.7.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 file to the list.

● Select the fonts file you want to download and choose Download to save or open it.
● To delete a fonts file 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.

SAP Forms Service by Adobe for the Neo Environment

28 PUBLIC SAP Forms Service by Adobe
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 .

1.7.2 Configure Fonts and Print Information using XDC and

XCI Files
Configure fonts and print information for the SAP Forms service.

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

● XDC files 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 configure your own XDC files.
○ Under Adobe XDC File, you can view and download the XDC files that Adobe provides.

● XCI files contain various configurations related to fonts.

○ For XCI files, you can perform the same processing steps as for XDC files.
○ You can only upload one custom_xfa.xci file. 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 files), see also:
Settings Using Additional Print Options in the Help Portal documentation.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 29
1.7.3 Configure Document Security

Configure document security for the SAP Forms service.

In the Document Security section, you can configure the following:

● Credentials: Upload signatures used to sign PDF documents to the server and configure the signatures
with an alias name. You can also create new credentials here.

 Note

The ReaderRights credential is preconfigured for your subaccount. You cannot install or delete
ReaderRights.

 Note

For more information, refer to Installing and Configuring Credentials in the Help Portal documentation..

● Trusted Anchors: Upload certificates required for verifying PDF signatures to the server and configure the
certificates with an alias name. You can also create new certificates here.
● Certificate Revocation Lists (CRL):
○ Manage a list of revoked signatures.
○ Upload a new list to the server from your local machine and define URLs for these CRL files.
○ You can configure the CRL Invalidation Period to customize how CRL files are fetched from URLs.
For example, if you set its value to 0, the CRL file is fetched from the URL for every request. If you set
the value to -1, the CRL is not fetched from the URL.
● Passwords: Configure passwords required to protect rendered PDF files 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

30 PUBLIC SAP Forms Service by Adobe
1.7.4 Manage Job Profiles

Configure job profiles for the SAP Forms service.

You can add job profiles for different jobs that the application can use. Choose Job Profiles in the left pane and
expand a node in the Details pane to view job profiles in the system.

Some predefined Job Profiles are available in the Adobe folder. In addition, you can upload XML files containing
custom job profiles.

● To view the contents of a job profile, select the profile and choose Show Job Profile Content.
○ To view job profile templates provided by Adobe, expand the Adobe node and double-click a template.

● First, select the row JobProfiles. Then, choose Create Folder to create a folder to upload a custom profile.
○ To upload a custom job profile, choose Upload and browse to the folder containing the XML file that
specifies the custom profile.

● Choose Download to download a job profile to your system.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 31
1.7.5 Download Support Files

Configure system error logs and download support files.

You can use the Configuration UI to download PDF files containing system error logs.

 Note

Important:

Support files 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 files may contain your business data. For more information on data security, see:
Data Storage Security.

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

● Choose Support Files in the left pane to view the PDF files containing error logs.

● To download a PDF file, select it in the Details section and choose Download.

You can also configure the size of the folder that contains the error files.

● Choose Configure Folder Size and drag the slider to configure the folder size.

SAP Forms Service by Adobe for the Neo Environment

32 PUBLIC SAP Forms Service by Adobe
  Note

You can configure the size to a maximum of 10 MB. If the combined size of the error files exceeds the set
size, the oldest files are replaced by the most recent error files that are stored in the folder. If you reduce the
folder size, older error files will be deleted until the folder size is reached.

1.7.6 Configure Caching

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

To configure the cache for the destination folder using the configuration UI, perform the following steps:

● Choose Configure Destination Cache Size to configure the size of the destination folder cache.

 Note

You can configure the cache size to a maximum of 15 MB.

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

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 33
1.7.7 Data Migration

Upload or download your configuration data for data migration purposes.

You can use the configuration UI to download or upload your configuration data.

Choose Data Migration in the left navigation pane of the configuration 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 files for XDC and XCI settings
● Document Security: certificates, credentials, Certificate Revocation Lists (CRLs)

SAP Forms Service by Adobe for the Neo Environment

34 PUBLIC SAP Forms Service by Adobe
  Note

You cannot download the alias names. After uploading downloaded files you have to re-enter the
corresponding alias names manually.

● Job Profiles: customer job profiles

● Support Files: setting for storage size of error.pdf files

 Note

Error.pdf files and passwords will not be downloaded.

● Caching: setting for destination cache size

 Note

You can only download the files that you uploaded previously. Predefined data are not downloaded.

If you choose Upload Data, you can browse for the files to be uploaded. When uploading files, keep in mind the
following upload behavior:

● If you upload a file that already exists in the target tenant, the file will be overwritten.

 Note

Uploading Support File settings overwrites the size configuration only. Existing error.pdf files are not
changed.

 Note

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

● When uploading files that don't exist in the target tenant, other existing files won't be touched.
● After uploading downloaded files from Document Security, you have to re-enter the corresponding alias
names manually.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 35
1.8 Connect a WebDynpro Java Application

Import a certificate and configure the required templates to connect your WebDynpro Java application to the
forms service.

The following procedure describes the required steps for connecting a WebDynpro Java application to the
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.

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 file into the AS Java keystore:
1. Open https://www.digicert.com/digicert-root-certificates.htm in your web browser
and download the following certificate:
○ DigiCert Global Root CA
2. In NWA, goto: Configuration Security Certificate and Keys .
3. In the Key Storage view, select WebServiceSecurity:

SAP Forms Service by Adobe for the Neo Environment

36 PUBLIC SAP Forms Service by Adobe
 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. Configure Basic Authentication:

1. In the NWA, choose SOA Technical Configuration 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.
2. If the template exists, highlight the element and check the field <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:

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 37
 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 Certificates, select Accept Certificates in Keystore View.
7. Select WebServiceSecurity from the dropdown list.
8. Choose Finish to save your entries:

4. Configure Client Certificate Authentiation:

1. Download a private key that is trusted by SAP BTP. To find a list of trusted certificate authorities (CAs),
see Trusted Certificate Authorities for Client Certificate Authentication.
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 Certificate.
2. In the Details section, enter the imported <Private Key> for <Keystore View>
WebServiceSecurity.
3. In section SSL Server Certificates, select Ignore server certificates (insecure).
4. Choose Finish to save your entries.

SAP Forms Service by Adobe for the Neo Environment

38 PUBLIC SAP Forms Service by Adobe
 5. Check your configuration as described in SAP Note 1443819

1.9 SAP Forms Service by Adobe REST API

Get started with the SAP Forms service REST API and find 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 different URIs (Uniform Resource Identifiers) 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 different ADS domains:

● ADS Get requests

● ADS Set requests
● ADS Render requests

Each request is always related to a pdf file 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 sufficient 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 39
Related Information

Connection Setup [page 40]

Call the REST API [page 44]
Template Store API [page 45]
Template Store UI [page 55]
Supportability and Troubleshooting [page 62]
REST API Scenarios [page 69]

1.9.1 Connection Setup

Configure 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 preconfigured destination to connect to the Adobe Document
Services (ADS) of the SAP Forms service.

SAP Forms Service by Adobe for the Neo Environment

40 PUBLIC 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 41
Finalize the Destination

The SAP Forms service destination ADS is partly preconfigured for your subaccount. To use it, you must finalize
it by defining 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 Certificate Authentication.
○ Basic Authentication
Specify <User> and <Password>.

 Note

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

SAP Forms Service by Adobe for the Neo Environment

42 PUBLIC SAP Forms Service by Adobe
 ○ Client Certificate Authentication
1. Provide a private key that is trusted by SAP Cloud Platform. To find a list of trusted certificate
authorities (CAs), see Trusted Certificate Authorities for Client Certificate Authentication.
2. Choose Certificates 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 43
  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.9.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.

SAP Forms Service by Adobe for the Neo Environment

44 PUBLIC SAP Forms Service by Adobe
To find out the available features, read the documentation of the ADS REST API Specification available under:

● https://adsrestapiformsprocessing-<yoursubaccount>.<yourregionhost:
[xxx.]hana.ondemand.com>/ads.restapi/

 Note

See also: Regions and Hosts.

You can directly access the documentation via your subaccount:

Go to Your subaccount on SAP BTP cockpit and choose Services → Forms Service by Adobe → ADS REST API
Specification.

Related Information

Implement a Simple REST Client in Java [page 80]

1.9.3 Template Store API

Use the SAP Forms service template store REST API to save templates and schemas.

The SAP Forms service REST API provides several URIs to save templates and schemas. Multiple resources
allow different operations, for example the form resource, template resource and schema resource. The form
resource serves as the parent entity, while templates and schemas are always sub-entities. This means that
you must always create a form first.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 45
Based on this form, you can save templates or a schema in subsequent steps.

A form can have several template files, but contains only one schema file at a time. The basic idea is to have
templates in different language versions and a schema that can always be mapped to each of the templates.
We recommend that you follow this suggested storage structure to organize templates and schemas.

SAP Forms Service by Adobe for the Neo Environment

46 PUBLIC SAP Forms Service by Adobe
Related Information

Versioning [page 47]

Storage Entities [page 48]
Call the Template Store: Examples [page 54]
Template Store UI [page 55]

1.9.3.1 Versioning

How to manage different versions for documents using the SAP Forms service template store.

Versioning is supported by the storage service and lets you have different versions of one single document. You
can only set versions for objects like schemas or templates. Every updatable entity holds a major version,
which is increased with every update. The entity with the highest version number in a version series is always
the latest version.

Old versions are stored in the service. You can access or delete them via the object ID only, while access via the
entity name always points to the latest version.

If an entity has multiple versions, you cannot delete the latest version without adding the query parameter ?
allVersions=true. Otherwise an error is returned to the client.

Example: Http DELETE /forms/myTestForm/templates/myTestTemplate?allVersions=true

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 47
1.9.3.2 Storage Entities
Access storage entities in the SAP Forms service template store.

Three different storage entities exist: forms, templates and schemas. When a new cloud account subscribes to
the storage system, a personal storage space is assigned. This space can store forms, templates and files. It
also ensures account data separation. You can create, modify and delete every storage entity in your account
space.

You can access entities either

● via a unique ID that is generated on creation, or

● via a unique user-defined pathname (for example, <form name>/<template name>) expressed in the
URI.

You can use those identifiers within a REST API render call, if you reference a template from the storage by
using one of those identifiers. Thus, you need to send the data xml file only.

In addition to a few properties that are generated during creation, each entity in memory has an additional set
of properties that you can read and modify. Those properties let you organize the entities in an appropriate
way.

Related Information

Forms [page 49]

SAP Forms Service by Adobe for the Neo Environment

48 PUBLIC SAP Forms Service by Adobe
Templates [page 50]
Schema [page 51]
Naming Restrictions [page 52]
Pagination [page 52]
Filtering [page 53]
Render a PDF Using a Template Entity from Storage [page 53]

1.9.3.2.1 Forms

How to use the forms entities in the SAP Forms service template store.

Forms are the basic entities of the storage system. You must create them before storing any templates or a
schema. They don’t support versioning.

 Note

When you delete a form, all templates and the schema that refer to this form are also deleted.

Properties set by the user

Property Description Mandatory

formName Limited to 30 characters and should Yes

contain letters and digits only.

formName String

note String

Properties set by the system

Property Description

creationDate Date on which the entity was created.

lastModificationDate Last modification date of the form.

managedBy Account ID of the subscribed account.

Related Information

Naming Restrictions [page 52]

Pagination [page 52]
Filtering [page 53]

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 49
1.9.3.2.2 Templates

How to use the templates entities in the SAP Forms service template store.

You can store multiple templates as part of a form. The language of a template must be unique and is defined
as a mandatory field. Therefore, you can update or create the language property only once per form. Template
versioning is supported.

The JSON that needs to send and define to store a new form has various mandatory and optional properties:

Properties set by the user

Property Description Mandatory

xdpTemplate Template content encoded as BASE64 Yes

String.

templateName Limited to 30 characters and should Yes

contain letters and digits only.

description String

note String

locale String, Restricted to ISO-639 language

code.

language Unique string, one template language Yes

per form entity.

masterLanguage String

businessArea String

businessDepartment String

Properties set by the system

Property Description

objectId Unique identifier.

versionNumber Automatically incremented on update.

isLatestVersion True or false.

contentLength Length of the file content.

mimeType Standard mime type of the template.

creationDate Date on which the entity was created.

lastModificationDate Last modification date of the form.

managedBy Account ID of the subscribed account.

SAP Forms Service by Adobe for the Neo Environment

50 PUBLIC SAP Forms Service by Adobe
Related Information

Naming Restrictions [page 52]

Pagination [page 52]
Filtering [page 53]
Render a PDF Using a Template Entity from Storage [page 53]

1.9.3.2.3 Schema

How to use the schema entity in the SAP Forms service template store.

There is only one schema per form, which you can usually map to the templates stored in the corresponding
form entity. Make sure that you use the correct mapping, as there is no mechanism to prove the matching of
schema and template. You can use schema and template to perform further modifications in the Adobe
LiveCycle Designer.

A schema can have multiple versions.

Properties set by the user

Property Description Mandatory

xsdSchema Schema content encoded in BASE64 Yes

String

schemaName Limited to 30 characters and should Yes

contain letters and digits only.

note String

Properties set by the system

Property Description

objectId Unique identifier.

versionNumber Automatically incremented on update.

isLatestVersion True or false.

creationDate Date on which the entity was created.

lastModificationDate Last modification date of the form.

managedBy Account ID of the subscribed account.

Related Information

Naming Restrictions [page 52]

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 51
Pagination [page 52]
Filtering [page 53]

1.9.3.2.4 Naming Restrictions

Overview of naming restrictions in the SAP Forms service template store.

Restrictions on naming apply to each storage unit. Therefore, only unicode letters or numbers are allowed for a
name.

Examples for naming entities:

Name Allowed

null No

“” No

““ No

“abc” Yes

“ab c” No

“ab2c” Yes

“ab_c” Yes

1.9.3.2.5 Pagination

How to use pagination in the SAP Forms service template store.

To avoid long-timed requests, you can use pagination. For this purpose, query parameters are available to
retrieve templates or forms:

Parameter Description

?limit Amount of elements which should be returned.

?offset The starting element.

SAP Forms Service by Adobe for the Neo Environment

52 PUBLIC SAP Forms Service by Adobe
1.9.3.2.6 Filtering

How to use filters in the SAP Forms service template store.

You can use the ?select query parameter to limit the information that should be returned to the user. Possible
values:

Value Description

xdpTemplate Returns only the template content as Base64 string.

templateData Returns template data that can be modified by the user.

templateMetaData Returns template metadata which is generated by the sys­

tem.

templateVersions Returns information about the template versions.

xsdSchema Returns only the schema content as Base64 string.

schemaData Returns schema data that can be modified by the user.

schemaMetaData Returns schema metadata that is generated by the system.

schemaVersions Returns information about the schema versions.

1.9.3.2.7 Render a PDF Using a Template Entity from

Storage

Add the ?templateSource query parameter in a REST API render request to reference a template from
storage.

This parameter can have different values:

● storageId
● storageName
● sapStorageId
● sapStorageName.

Example:

 Sample Code

Request: /adsRender/pdf?templateSource=storageName
Input: {"xdpTemplate": "<formName>/<TemplateName>","xmlData": "<XML
Data File as BASE64 String>"}
In JSON, add: “xdpTemplate”:”<formName>/<templateName>”.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 53
1.9.3.3 Call the Template Store: Examples

Find examples how to call the SAP Forms service template store.

You can enter the examples in postman. Each URI is protected by OAuth2.0.

Step 1: Create a Form

 Sample Code

Method: POST
URI: <landscape>/ads.restapi/v1/forms
Input: {
"formName": "TestForm",
"description": "Test Description",
"note": "Test Note"
}
Response: {
"creationDate": "2018-11-13T16:47:04.990Z",
"lastModificationDate": "2018-11-13T16:47:04.990Z",
"managedBy": "<accountId>"
}

Step 2: Create a Template

 Sample Code

Method: POST
URI: <landscape>/ads.restapi/v1/forms/TestForm/templates
Input: {
"xdpTemplate": "VGhpcyBpcyBhIHRlc3QgdGVtcGxhdGU=",
"templateName": "TestTemplate",
"description": "Test Description",
"note": "Test Note",
"locale": "DE",
"language": "DE",
"masterLanguage": "DE",
"businessArea": "IT",
"businessDepartment": "IT Test"
}
Response: {
"objectId": "<objectId>",
"versionNumber": "1",
"isLatestVersion": true,
"contentLength": "23",
"mimeType": "application/vnd.adobe.xdp+xml; charset=UTF-8",
"creationDate": "2018-11-13T16:52:17.929Z",
"lastModificationDate": "2018-11-13T16:52:17.929Z",
"managedBy": "<accountId>"
}

SAP Forms Service by Adobe for the Neo Environment

54 PUBLIC SAP Forms Service by Adobe
Step 3: Update a Template

 Sample Code

Method: PUT
URI: <landscape>/ads.restapi/v1/forms/TestForm/templates/TestTemplate
Input: {
"xdpTemplate": "VGhpcyBpcyBteSB1cGRhdGVkIHRlc3QgdGVtcGxhdGU=",
"templateName": "TestTemplateNew",
"description": "Test Description New",
"note": "Test Note",
"locale": "EN",
"masterLanguage": "EN",
"businessArea": "IT New",
"businessDepartment": "IT Test New"
}
Response: {
"objectId": "RTZ6buZ3RSJogGCge1gi99_WDmT8zTkdYMU1J5otkpU",
"versionNumber": "2",
"isLatestVersion": true,
"contentLength": "32",
"mimeType": "application/vnd.adobe.xdp+xml;charset=UTF-8",
"creationDate": "2018-11-13T16:55:23.115Z",
"lastModificationDate": "2018-11-13T16:55:23.318Z",
"managedBy": "<accountId>"
}

1.9.4 Template Store UI

Use the SAP Forms service template store UI to create forms and assign templates and schemas to them.

Instead of directly using the REST API interface by sending HTTP REST calls, you can use the template store UI
to manage your forms easily, assigning different language versions of templates and a schema to a form.

 Note

Your storage space is restricted to 1 GB max.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 55
Assign User Roles

To manage forms, templates and schemas via the template store UI, your user must be assigned to the role
StorageUIAdmin:

1. From your subaccount in the cloud cockpit, choose Services SAP Forms by Adobe and open the link
REST API Roles & Destinations in the service overview.

2. Make sure your user is assigned to the role StorageUIAdmin. From the Roles screen, select the
predefined role StorageUIAdmin and check the table Individual Users below. If your user is not assigned,
choose Assign, enter your <User ID> in the pop-up window, and press Assign again.

SAP Forms Service by Adobe for the Neo Environment

56 PUBLIC SAP Forms Service by Adobe
Next Steps

● Manage Forms, Templates and Schemas [page 57]

● Configure the Template Store UI [page 60]

1.9.4.1 Manage Forms, Templates and Schemas

The SAP Forms service template store UI lets you create new forms and assign them to one ore more
templates, as well as to a schema of your choice.

To manage forms, templates and schemas via the template store UI, proceed as follows:

Prerequisites

● Your user is assigned to the role StorageUIAdmin, see Assign User Roles [page 56].
● You have opened the template store UI (from your subaccount in the cloud cockpit, choose Services
SAP Forms Service by Adobe and open the link REST API Template Store UI in the service overview).

Assign a Template

1. To assign a template to a form:

1. Choose an existing form from the forms (or favorites) overview list, or
2. Create a new form by choosing Create Form in the header bar, and enter a <Form Name> in the pop-up
window.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 57
  Note

Only alphanumeric characters and the '_' (underscore) character are allowed.

(Optional) You can leave an additional note for the form in section Optional Data that is displayed in the
forms (or favorites) list. When you are done, press Create.

2. Choose tab Templates in the detail view of the selected form and press the icon Add Template.

 Note

<Template Name> and <Language> are unique identifiers. One form can have different language
versions of one template.

3. In the pop-up window, enter a <Template Name> and browse for the .xdp template file you want to use for
the template.
4. In the field <Language>, use the drop-down list to choose a language for your template.
5. (Optional) Use the fields in section Optional Data to enter additional information for the template: <Note>
(description), <Locale> (country code, for example EN), <Master Language> (original language of the
template), and <Business Area> (description of the work area the template is used for).
6. Press Add.

Assign a Schema

1. To assign a schema to the form, choose tab Schema in the detail view and press the icon Add Schema.

SAP Forms Service by Adobe for the Neo Environment

58 PUBLIC SAP Forms Service by Adobe
 2. In the pop-up window, browse for the .xsd schema file you want to assign to your form.
3. (Optional) Use the field <Note> in section Optional Data to enter additional information for the template.
4. Choose Add.

Versioning

1. Click on a template/schema you would like to update and press the Update button.
2. In the pop-up window, select the new file and enter the data to be updated.
3. Add the updated template/schema.
4. In the templates/schema overview, the old version is still displayed in a tree view.

 Note

Single old versions of a template can always be deleted. If you delete the newest version, all old
versions are also deleted.

Template:

Schema:

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 59
1.9.4.2 Configure the Template Store UI

Customize the SAP Forms service template store UI to adjust it to your needs.

Prerequisites

● Your user is assigned to the role StorageUIAdmin, see Assign User Roles [page 56].
● You have opened the template store UI (from your subaccount in the cloud cockpit, choose Services
SAP Forms Service by Adobe and open the link REST API Template Store UI in the service overview).

SAP Forms Service by Adobe for the Neo Environment

60 PUBLIC SAP Forms Service by Adobe
Create Favorites

1. To move a form to your favorites list, select it from the overview and choose the icon Save Form to Favorites
in the header bar of the detail view.

2. The form is added to the Favorite Forms list in the forms overview.

3. To remove forms from the favorites list, select Save Form to Favorites again.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 61
Modify the Template Overview

1. Go to the template overview and select Table Settings.

2. Select the columns to be displayed.

3. Press Ok.

1.9.5 Supportability and Troubleshooting

Implement supportability functions and analyze issues for the SAP Forms service.

This section provides information related to the SAP Forms service by Adobe. It is directed to SAP developers
and support teams who work with applications for generating print or interactive PDF forms by using the
Adobe Document Services. Read the below prerequisites and guidelines for the usage of the SAP Forms
service.

SAP Forms Service by Adobe for the Neo Environment

62 PUBLIC SAP Forms Service by Adobe
 ● As a developer, implement the supportability functions into your application to ensure that your
application can be supported. If you need to analyze problems, follow the instructions given in section
Analyze Issues.
● As a supporter, check the supportability functions of the application and follow the same instructions
mentioned in Analyze Issues.

Related Information

First Steps [page 63]

Analyze Issues [page 65]

1.9.5.1 First Steps

If you want to analyze and troubleshoot errors occurring in your application that are related to the SAP Forms
service REST API, perform the initial steps described below:

Implement Supportability Functions

The SAP Forms service REST API provides supportability functions that help to analyze connectivity issues or
render problems. Error messages and Error.PDF in the response streams inform about the reason of issues.
The possibility of setting traces helps to better understand the root causes.

To call the SAP Forms service REST API in your application you must implement a handling of error messages
and response streams that are provided by the REST API.

In detail you need to:

● process the JSON response

● catch and store the Error.PDF
● use a function to set a trace level (value 0 to 2).

In case of HTTP 200 response code, a TraceString node will be added to the resulting JSON, showing additional
runtime information.

Trace level options:

● 0 = no trace information (default)

● 1 = processing time information
● 2 = full trace information including the generation of a PDF file with additional information

The following sections provide more details and examples explaining the JSON structure.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 63
Process the JSON Response

The JSON response contains responses and error messages from the SAP Forms service. Depending on the
feature called by the user the JSON output will vary. See the documentation of the REST API for each feature
under:

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

 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 file. 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 file, 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.

SAP Forms Service by Adobe for the Neo Environment

64 PUBLIC 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.9.5.2 Analyze Issues

The following section provides an overview of different 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 fields

● 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 specific 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 65
HTTP Code HTTP Text Error Cause

401 Unauthenticated This can be caused by wrong OAuth

credentials or missing OAuth configura-
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 Conflict Mandatory fields in the JSON are miss­

ing or file 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 66]

1.9.5.2.1 Error Types

Internal API Error - Corrupted JSON or missing mandatory JSON fields

HTTP 400 - Bad Request or HTTP 409 - Conflict

If you receive an error, proceed as follows:

1. Follow the instructions stated in the JSON Error response to detect missing mandatory fields or formatting
issues.
2. Check your application:

SAP Forms Service by Adobe for the Neo Environment

66 PUBLIC 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 fields included in the JSON?
3. Correct your application by adding missing fields to the JSON input of your request or correcting the JSON
format.

Internal API Error - BASE64 encoding issues in the JSON input

HTTP 409 - Conflict

If you receive an error, proceed as follows:

1. Identify and fix 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 defined?

2. Is an authentication defined 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 76]

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 67
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-CLD.

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 76].

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 files are attached to it.
○ Form layout file (.xdp file)
○ XML data file
○ Trace file

SAP Forms Service by Adobe for the Neo Environment

68 PUBLIC SAP Forms Service by Adobe
 4. Extract the layout file and the XML data file from the PDF for checking. Open the layout file in the
standalone Adobe LiveCycle Designer and try to fix. You can also preview the layout with the XML file.
5. If you cannot fix 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 file (.xdp file)
○ XML data file
○ Trace file
○ 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 fix the root cause of the error.

1.9.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 different ways to setup OAuth:

Retrieving an OAuth Token in Java [page 70]

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 69
OAuth Setup using the Postman Client [page 76]

 Note

If you use a different client, refer to the corresponding product-specific 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 80]

Adobe LiveCycle Designer

Provide your own form templates using the AdobeLiveCycle Designer: Using the Adobe LiveCycle Designer
[page 83]

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 90]

1.9.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 specific implementation, retrieving the OAuth credentials may require a different
procedure.

SAP Forms Service by Adobe for the Neo Environment

70 PUBLIC SAP Forms Service by Adobe
Steps

● Register an OAuth Client in the Cockpit [page 71]

● Implement an OAuth Client in Java [page 72]
● Full Example Implementation [page 75]

1.9.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 field <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 71
Next Steps

Implement an OAuth Client in Java [page 72]

Full Example Implementation [page 75]

1.9.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 :

SAP Forms Service by Adobe for the Neo Environment

72 PUBLIC 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 configuration 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 define 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 73
 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 75]

SAP Forms Service by Adobe for the Neo Environment

74 PUBLIC SAP Forms Service by Adobe
1.9.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 75
 e.printStackTrace();
}
return result;
}
public static void main(String[] args) {
OAuthClient oauthClient = new OAuthClient();
String res = oauthClient.callService();
System.out.println(res);
}
}

1.9.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 configure OAuth using the Postman client.

Steps

● Register the OAuth Client in the Cockpit (Postman) [page 76]

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

1.9.6.2.1 Register the OAuth Client in the Cockpit

(Postman)
Register the OAuth client in the SAP BTP cockpit.

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 different OAuth client, enter the product-specific 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.

SAP Forms Service by Adobe for the Neo Environment

76 PUBLIC 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, e.g. https://
www.getpostman.com/oauth2/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 77
Next Steps

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

OAuth Token Administration (Postman) [page 80]

1.9.6.2.2 Get the OAuth Access Token (Postman)

Configure 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. In <Auth URL> enter the Authorization Endpoint URL you have copied before.
5. In <Access Token URL> enter the Token Endpoint URL you have copied before.
6. In <Client ID> enter the ID from the client you have registered in the SAP BTP cockpit before.
7. Under <Scope>, enter generate-ads-output.

 Note

This entry is mandatory!

SAP Forms Service by Adobe for the Neo Environment

78 PUBLIC SAP Forms Service by Adobe
 8. Press the button Request Token.
9. The SAP BTP Authorization Endpoint page opens. Press Authorize.

10. In Postman choose the newly created Token.

11. Under Add token to select Header from dropdown list.
12. Press the button Use Token.
13. You have now created a token. Postman will use it for each request to the SAP Forms service REST API.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 79
Next Step

OAuth Token Administration (Postman) [page 80]

1.9.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):

1.9.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.

SAP Forms Service by Adobe for the Neo Environment

80 PUBLIC SAP Forms Service by Adobe
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");

The API is protected by OAuth2. For configuration details, see Configuring 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;

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 81
 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 fit best to your implementation.

Dealing with Proxies

In case requests being sent behind a proxy please add following configuration 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 {

SAP Forms Service by Adobe for the Neo Environment

82 PUBLIC SAP Forms Service by Adobe
 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 {
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.9.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.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 83
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 84]

1.9.6.4.1 Create a Simple Template with Generated Sample

Data

In this short and simplified example, we will demonstrate how to create a template and a sample data file
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.

1. Open the LiveCycle Designer.

2. Select New Form.

SAP Forms Service by Adobe for the Neo Environment

84 PUBLIC SAP Forms Service by Adobe
 3. Select Use a blank form and press Next.

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 fields
2. Date/time field
3. Time field
We will use these objects to demonstrate the sample data generation and data binding.

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

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 85
7. Select Preview Generate Preview Data… .

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

SAP Forms Service by Adobe for the Neo Environment

86 PUBLIC SAP Forms Service by Adobe
 Content of the generated data xml file:

In the next steps, this file 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….

10. Select Sample XML Data and press Next.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 87
11. Choose the previously created data xml file and choose Finish to integrate the data xml.

(Confirm the prompt about the clearance of Use Name data bindings).
12. On the Data View you should now find the data nodes from the data xml file. These nodes can be bound to
the fields on the template’s Design View.

SAP Forms Service by Adobe for the Neo Environment

88 PUBLIC SAP Forms Service by Adobe
 13. Bind the data node TextField1 to field <TextField1>: click on the field, then, in the Object tab choose
Binding and create a new data binding Data Binding (Open, Save, Submit). Choose Use DataConnection
TextField1 .

14. Confirm the binding and select Update all related properties. Press Ok.

15. Repeat the data binding for all remaining fields accordingly.
16. For every data node bound to a field you will find a new tag/symbol in the Data View.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 89
17. Save the template as Adobe XML Form (*xdp).
18. Send template and data file via a render request to the REST API (within the pre-defined JSON structure).
19. The resulting PDF will include all template fields and dummy data.

 Note

It is the responsibility of the application implementing the REST Service to maintain and provide the XML
data structure that fits 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 file.

1.9.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.

SAP Forms Service by Adobe for the Neo Environment

90 PUBLIC 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 91]
● Map your destination to the HTML5 application and secure the destination: Set Up your HTML5
Application [page 93]

1.9.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 filled, otherwise choose: Regenerate ID>

Authorization Grant Client Credentials

Secret <enter a new secret>

Confidential <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 91
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 <your Client ID>

Token Service Password <your Client Secret>

 Note

You can find 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 configuration using the button Check Connection. A popup Response returned: "200: OK"
should show up.

Next Step

Set Up your HTML5 Application [page 93]

SAP Forms Service by Adobe for the Neo Environment

92 PUBLIC SAP Forms Service by Adobe
1.9.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 file of your HTML5 application.

2. 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 file 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": [

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 93
 "/ads.restapi/"
]
}

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 effect, you must logout and login into the SAP BTP cockpit.

1.10 Security

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

Topic More Information

Assign specific authorizations to subaccount users for the Assigning Roles to Users [page 9]
SAP Forms service.

Use the Cloud Connector for secure communication be­ Installing and Configuring the Cloud Connector [page 19]
tween the SAP Forms service and the ABAP system.

Set up an SSL connection between the ABAP system and Configuring the ABAP System [page 11]
SAP BTP for communicaton with the SAP Forms service.

Protect your business data when downloading support files. Download Support Files [page 32]

Configure credentials, certificates and passwords for your Configure Document Security [page 30]
PDF documents.

For data migration, download security-relevant configuration Data Migration [page 34]
files.

Set up an OAuth client when using the the SAP Forms REST API Scenarios [page 69]
service REST API.

To integrate the Template Store REST API into an HTML5 ap­ Integrate the REST API in an HTML5 Application [page 90]
plication, protect the destination used.

Make sure you comply with applicable data protection and Data Protection and Privacy [page 95]
privacy laws for processing personal or sensitive data.

SAP Forms Service by Adobe for the Neo Environment

94 PUBLIC SAP Forms Service by Adobe
General Recommendations

● 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.10.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 specific 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. Definitions and other terms used in this documentation are not
taken from a specific legal source.

SAP Forms Service by Adobe for the Neo Environment

SAP Forms Service by Adobe PUBLIC 95
Important Disclaimers and Legal Information

Hyperlinks
Some links are classified 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 a 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 officially 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 sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence 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.

Gender-Related Language
We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.

SAP Forms Service by Adobe for the Neo Environment

96 PUBLIC Important Disclaimers and Legal Information
SAP Forms Service by Adobe for the Neo Environment
Important Disclaimers and Legal Information PUBLIC 97
www.sap.com/contactsap

© 2021 SAP SE or an SAP affiliate company. All rights reserved.

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
affiliate 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 specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate 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 affiliate 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