PDF-Generierung mit dem SAP Forms Service by Adobe

Willkommen zur Schritt-für-Schritt-Anleitung für den SAP Forms Service by Adobe! Diese Anleitung richtet sich speziell an SAP Cloud Entwickler, die das Potenzial des SAP Forms Service nutzen möchten, um professionelle, ansprechende PDF-Dokumente zu generieren.

Unter Verwendung des Bookshop Example der SAP Mentors werden Sie lernen, wie Sie den SAP Forms Service einsetzen, um automatisierte und dynamische Produktdokumente zu erstellen, die sowohl informative Inhalte als auch ein ansprechendes Layout bieten. Durch die Verwendung dieser Technologie können Sie die Erstellung und Verwaltung von Dokumenten erheblich vereinfachen, während Sie gleichzeitig die Benutzererfahrung verbessern.

In den folgenden Abschnitten werden Sie die notwendigen Schritte kennenlernen, um den SAP Forms Service zu aktivieren, zu konfigurieren und produktive Formulare zu generieren. Diese Anleitung hilft Ihnen, das erforderliche Know-how zu erlangen, um ansprechende Produktblätter für das Bookshop Example zu erstellen.

Voraussetzungen

Um die Anleitung erfolgreich zu befolgen und den SAP Forms Service by Adobe nutzen zu können, benötigen Sie die folgenden Voraussetzungen:

1. SAP BTP Subaccount: Sie müssen über einen SAP BTP Subaccount verfügen, der Ihnen entweder als Entwickler mit der Berechtigung „Destination Administrator“ oder als Subaccount-Administrator zugeordnet ist. Diese Anleitung kann auch mit einem SAP Trial Account befolgt werden. Erfahren Sie hier, wie Sie Zugriff auf einen SAP BTP Trial Account erhalten.
2. Zugang zu Business Application Studio: Stellen Sie sicher, dass Sie Zugang zu einer Business Application Studio Instanz haben, und dass Ihr Nutzer die Berechtigung „Business_Application_Studio_Developer“ besitzt. Erfahren Sie hier, wie Sie das SAP Business Application Studio einrichten.
3. Entitlements im Subaccount: Ihr Subaccount muss über die folgenden Berechtigungen verfügen:
   • SAP Forms Service by Adobe free oder standard
   • SAP Forms Service by Adobe default (dies ist wichtig, da Sie sonst nicht auf die Benutzeroberfläche zur Konfiguration zugreifen können)
   • SAP Forms Service by Adobe API free oder standard

Erfahren Sie hier, wie Sie Entitlements im SAP Cloud Cockpit verwalten können.

In diesem Tutorial arbeiten wir mit dem Free Service Plan, der es Ihnen erlaubt, bis zu 200 Dokumente pro Monat mit Wasserzeichen zu generieren. Sollten Sie den Standard Service Plan verwenden, entfallen die Wasserzeichen. Beachten Sie jedoch bitte, dass Kosten für die Generierung von Dokumenten mit dem Standard Service Plan anfallen können.

Service-Aktivierung

Um den SAP Forms Service by Adobe zu aktivieren, müssen Sie im SAP BTP Service Marketplace je eine Instanz gemäß den oben genannten Entitlements anlegen. Befolgen Sie die folgenden Schritte:

1. Anmeldung im SAP BTP Cockpit:
   • Melden Sie sich im SAP BTP Cockpit an.
   • Wählen Sie den entsprechenden Subaccount aus, in dem Sie den Service aktivieren möchten.
2. Navigieren zum Service Marketplace:
   • Klicken Sie im linken Navigationsmenü auf „Services“.
   • Wählen Sie „Service Marketplace“ aus.
3. SAP Forms Service by Adobe suchen:
   • Im Service Marketplace sehen Sie eine Liste aller verfügbaren Services. Geben Sie im Suchfeld „SAP Forms Service by Adobe“ ein, um den Service schnell zu finden.
4. Instanz erstellen:
   • Klicken Sie auf den „SAP Forms Service by Adobe“-Eintrag.
   • Wählen Sie die Option „Instanz erstellen (Create)“ aus.
   • Wählen Sie im nächsten Schritt den gewünschten Plan aus. Für unsere Anleitung wählen Sie entweder den „free“ oder „standard“ Plan.
5. Einstellungen konfigurieren:
   • Geben Sie einen aussagekräftigen Namen für die Instanz ein. Dies hilft Ihnen, die Instanz später leichter zu identifizieren.
   • Überprüfen Sie die voreingestellten Parameter und passen Sie diese nach Bedarf an.
6. Instanz bestätigen:
   • Klicken Sie auf „Erstellen“, um die Instanz zu generieren.
   • Warten Sie, bis das System die Instanz erfolgreich erstellt hat. Das kann einige Minuten dauern.
7. Wiederholen für die SAP Adobe Forms Benutzeroberfläche: Wiederholen Sie den Prozess, um eine Applikations-Instanz für den „SAP Forms Service by Adobe“ zu erstellen, und wählen Sie den Plan default aus.
8. Wiederholen für die API-Instanz: Wiederholen Sie den Prozess, um eine separate Instanz für den „SAP Forms Service by Adobe API“ zu erstellen, und wählen Sie ebenfalls den gewünschten Plan aus (free oder standard).
9. Erstellen einer Destination-Instanz und Service Key:
   • Erstellen Sie eine Service-Instanz des Destination Service mit Service Plan „lite“
   • Klicken Sie auf die erstellte Instanz. Im Bereich „Service Keys“ klicken Sie auf „Create“. Geben Sie als Namen „Business_Application_Studio“ an.
10. Überprüfung: Nach der Erstellung beider Instanzen sollten Sie diese in der Liste unter „Instanzen und Abonnements“ im Service Marketplace finden.

Konfiguration der Destination

Um den SAP Forms Service by Adobe in einer Applikation nutzen zu können, müssen Sie zunächst einen Service Key für die „SAP Forms Service by Adobe API“-Instanz anlegen und anschließend eine Destination erstellen. Befolgen Sie die Schritte, um diese Konfiguration abzuschließen.

1. Service Key erstellen:
   • Klicken Sie auf den Namen der „SAP Forms Service by Adobe API“ Instanz.
   • Klicken Sie auf die Schaltfläche „Service Key erstellen“.
   • Geben Sie einen aussagekräftigen Namen für den Service Key ein und bestätigen Sie die Erstellung, indem Sie auf „Erstellen“ klicken.
   • Warten Sie, bis der Service Key generiert wurde. Laden Sie die Service-Key-Textdatei herunter, indem Sie auf die drei Punkte (⋯) am Ende der Zeile klicken und dann „Download“ (⭳) wählen.
2. Destination erstellen:
   • Klicken Sie im linken Navigationsmenü auf „Connectivity“ und dann auf „Destinations“.
   • Klicken Sie auf die Schaltfläche „Neue Destination“.
   • Geben Sie im Feld Name beinen eindeutigen Namen für Ihre Destination ein, z. B. „Adobe_Forms_Service_API“.
   • Geben Sie im Feld URL die API-URI ein, die Sie aus dem zuvor erstellten Service Key erhalten haben.
   • Wählen Sie im Feld Authentication „OAuth2ClientCredentials“.
   • Kopieren Sie Client ID und Client Secret aus dem Service Key.
   • Geben Sie im Feld Token Service URL die URL aus dem uaa-Knoten ein und hängen „/oauth/token“ an (<uaa-url>/oauth/token).

Konfiguration des PDF-Templates

Um den SAP Forms Service by Adobe vollständig nutzen zu können, benötigen Sie ein XDP-Template zur Generierung von PDF-Formularen. Dieses Template definiert das Layout und die Struktur Ihres Dokuments. Der nächste Schritt besteht darin, das XDP-Template im Template Store des Forms Service by Adobe hochzuladen. Befolgen Sie die nachstehenden Schritte:

1. Navigieren zu den Templates:
   • Klicken Sie im linken Navigationsmenü auf „Services -> Instances and Subscriptions“ und folgenden Sie dem Link der Applikation „Forms Service by Adobe“. Es öffnet sich die Benutzeroberfläche des Forms Service by Adobe.

     

   • Klicken Sie auf die Schaltfläche „Template Store“ oder „Templates verwalten“, um den Template Store zu öffnen.
2. Neues Template hochladen:
   • Klicken Sie auf die Schaltfläche „Formular anlegen“.
   • Geben Sie einen Namen für das Formular an, z.B. „Produktblatt“ und bestätigen Sie mit „anlegen“.
   • Navigieren Sie zum neu angelegten Formular. Im Abschnitt „Vorlagen“ wählen Sie „hochladen“.
   • Ein Eingabefeld öffnet sich, in dem Sie Ihre XDP-Datei auswählen und einen Namen vergeben können. Für unser Beispiel nutzen Sie bitte die bereitgestellte Vorlage und nutzen die Bezeichnung „Produktblatt_V1“.

Implementierung und Generierung mithilfe des Form Service by Adobe

Diese Anleitung führt Sie durch die Schritte, um den SAP Forms Service by Adobe in Ihrem Projekt zu nutzen. Sie werden lernen, wie Sie ein neues Projekt mithilfe des CAP-Templates anlegen, eine benutzerdefinierte Aktion zur PDF-Generierung implementieren und diese Aktion in einer SAP Fiori App hinzufügen.

1. Devspace im Business Application Studio starten
   • Melden Sie sich im SAP Business Application Studio an: SAP Business Application Studio.
   • Wählen Sie den Devspace aus, in dem Sie arbeiten möchten, und starten Sie diesen.
2. Neues Projekt mithilfe des CAP-Templates anlegen
   • Im Business Application Studio klicken Sie auf das Hamburger-Menü  (☰)  und wählen Sie „File“ -> „New Project from Template“.
   • Wählen Sie das „CAP Project“-Template im Templategenerator aus. Bestätigen Sie mit „Start“.
   • Geben Sie dem Projekt einen sprechenden Namen.
   • Wählen Sie unter „Add sample content to your project“ die Option „Extended Sample with UI“ aus.
   • Das Projekt wird mit der notwendigen Struktur und den grundlegenden Dateien angelegt.
3. Custom Action im Service zur PDF-Generierung anlegen
   • Navigieren Sie zu Ihrer Service-Datei (z. B. cat-service.cds).
   • Fügen Sie an der Entität Books eine neue benutzerdefinierte Aktion hinzu, um die PDF-Generierung auszulösen:

     actions {
           function printPdf() returns LargeString;
     }

   • Definieren Sie zwei neue Abhängigkeiten zu fs.promises und path

const path = require('path')
const fs = require('fs').promises;
const { executeHttpRequest } = require('@sap-cloud-sdk/http-client');

• • Definieren Sie die Logik zur Generierung des PDFs in der entsprechenden Handler-Datei (z. B. cat-service.js):

  // Function to convert XML to Base64
  function xmlToBase64(xmlString) {
      // Convert XML string to Buffer
      const buffer = Buffer.from(xmlString, 'utf-8');
      // Encode Buffer to Base64
      return buffer.toString('base64');
  }
   
  // Function to fill XML with data
  async function fillXMLData(bookId) {
      let xmlData = await fs.readFile(path.join(__dirname, 'templates/books-template.xml'), 'utf8');
      const bookColumns = "{texts[locale='de'].title as title, texts[locale='de'].descr as descr, author.name as authorName, genre.texts[locale='de'].name as genreName, price, currency.code as currency}"
      const bookData = await SELECT.one.from(Books).columns(bookColumns).where({ ID: bookId })
      for (let property in bookData) {
        xmlData = xmlData.replace(`{${property}}`, bookData[property])
      }
      return xmlData
    }

    this.on('printPdf', 'Books', async req => {
      const xmlData = await fillXMLData(req.params[0])
      const settings = {
        "xdpTemplate": "Base64 String",
        "xmlData": xmlToBase64(xmlData),
        "formType": "print",
        "formLocale": "de_DE",
        "taggedPdf": 1,
        "embedFont": 0,
        "changeNotAllowed": false,
        "printNotAllowed": false
      }

      let pdf;
      try {
        const form = await executeHttpRequest({
          destinationName: 'Adobe_Forms_Service_API'
        }, {
          method: 'GET',
          url: "/v1/forms/Produktblatt",
          data: settings
        })
        settings.xdpTemplate = form.data.templates[0].xdpTemplate
        pdf = await executeHttpRequest(
          {
            destinationName: 'Adobe_Forms_Service_API'
          }, {
          method: 'POST',
          url: "/v1/adsRender/pdf",
          data: settings
        }
        );
      } catch (e) {
        console.error(e);
      }
      return pdf.data.fileContent
    })

• Legen Sie im srv-Ordner einen Unterordner templates an. Erstellen Sie darin die Datei mit books-template.xmlfolgendem Inhalt:

<?xml version="1.0" encoding="UTF-8"?>
<BOOK>
    <AUTHOR>
        <NAME>{authorName}</NAME>
    </AUTHOR>
    <TITLE>{title}</TITLE>
    <DESCRIPTION>{descr}</DESCRIPTION>
    <GENRE>{genreName}</GENRE>
    <PRICE>{price}</PRICE>
    <CURRENCY>{currency}</CURRENCY>
</BOOK>

Aufruf der PDF-Generierung im Frontend

1. Fügen Sie eine Custom Action im Header der Books Detail Page innerhalb der Browse-App hinzu, indem Sie in der Datei manifest.json folgenden Code Snippet hinzufügen:

   "BooksDetails": {
             "type": "Component",
             "id": "BooksDetailsList",
             "name": "sap.fe.templates.ObjectPage",
             "options": {
               "settings": {
                 "entitySet": "Books",
                 "content": {
                   "header": {
                     "actions": {
                       "BooksExt": {
                         "press": "bookshop.ext.BooksExt.onPrintSheet",
                         "visible": true,
                         "enabled": true,
                         "requiresSelection": false,
                         "text": "Produktblatt herunterladen"
                       }
                     }
                   }
                 }
               }
             }
           }

2. Erstellen Sie den Unterordner ext im Ordner webapp der Browse-App.
3. Legen Sie die Datei BooksExt.js im Unterordnet ext an. Füllen Sie diese mit dem folgenden Snippet:

sap.ui.define([
    "sap/m/MessageToast"
], function (MessageToast) {
    'use strict';
    return {
        onPrintCV: async function (event) {
            const book = await event.getBinding().getBoundContext().requestObject()
            const path = event.getBinding().getPath()
            //Request PDF Printing
            const action = 'CatalogService.printPdf(...)'
            const actionContext = event.getBinding().getModel().bindContext(`${path}/${action}`)
            await actionContext.invoke()
            const pdf = await actionContext.requestObject()
            //Create filename
            const date = new Date;
            const options = { year: 'numeric', month: '2-digit', day: '2-digit' };
            const formattedDate = new Intl.DateTimeFormat('de-DE', options).format(date);
            //Open PDF in new browser window for download
            const uri = `data:application/pdf;base64,${pdf.value}`
            const downloadLink = document.createElement('a')
            downloadLink.href = uri
            downloadLink.download = `${book.title}_${formattedDate}.pdf`
            document.body.appendChild(downloadLink)
            downloadLink.click()
            document.body.removeChild(downloadLink)
            MessageToast.show("PDF downloaded successfully.");
        }
    };
});

{
    "requires": {
        "destinations": {
          "binding": {
            "type": "cf",
            "apiEndpoint": "<API Endpoint>",
            "org": "<Org Name>",
            "space": "<Space Name>",
            "instance": "productprint-destination",
            "key": "Business_Application_Studio",
            "resolved": false
          },
          "kind": "destinations",
          "vcap": {
            "name": "destinations"
          }
        }
      }
  }

Herzlichen Glückwunsch! Sie haben erfolgreich ein Dokument mit dem Form Service by Adobe generiert!