Data Binding Basics for Print Forms
In my live sessions about print form adaptation with the Adobe LiveCycle Designer, data binding is a frequently requested and crucial topic. Especially in scenarios with complex tables and multi-level data structures. That’s why I decided to underline the sessions with some blog posts.
Most topics of the live sessions and blogs focus on the Adobe LiveCycle Designer (ALD) itself. So, they are applicable for several SAP cloud solutions where Adobe Document Services (ADS) are used. For system-related topics, I refer to either SAP Sales/Service Cloud (in former times SAP Cloud for Customer, C4C) or SAP Business ByDesign (ByD). Print form maintenance and output management is handled similarly in these two solutions.
I recommend reading this blog series in the order as stated below. You can find the registration information for my live sessions at the bottom of this blog.
List of print form blogs:
- How to get XML data for local preview of print forms without output history
- Data Binding Basics for Print Forms (this blog)
- Data Binding with Repeating Items and Simple Tables in Print Forms
- Data Binding with Repeating Items and Complex Tables in Print Forms
- Building Tables with Scripts
Download Sample Data
Let’s start with the basics and some easier cases to have everyone on the same page.
For data binding, it’s crucial to know the data model of the objects that you’re working with. In my opinion, it’s the best and also the easiest way to download the XML data of a sample document from the system and review. This helps you to become familiar with its structure and find the fields and values that you are looking for. If you are not familiar with downloading XML data from the system, you should first read my blog about it.
Update the Data Connection
Furthermore, when working on data bindings, I recommend to always update the data connection to ensure that the Adobe LiveCycle Designer has the latest data structure information available. This way the ALD supports you with the binding menu and doesn’t show false warnings of fields that are bound to “unknown” data nodes.
Update the data connection from the Data View palette, by right-clicking on the Data Connection entry and choosing Connection Properties...
In the Connection Properties dialog, choose the MainSchema.xsd that is part of the zip file when downloading the print form from the Form Template Maintenance work center. This file links all other xsd files. So, don’t delete them!
After updating the data connection, we can use the binding menu and can be sure that it contains the latest data structure. If you added extension fields to the respective print form, they would also appear in the menu.
I highly recommend previewing modifications made to the print form every once in a while with the sample data that you have downloaded. That’s a crucial feature of the Adobe LiveCycle Designer and it saves you much effort in comparison to uploading the print form to the cloud solution for previewing changes.
As a reminder (it’s also mentioned in my other blog), you can assign the XML file for local preview as follows: Menu File -> Form Properties -> tab Preview -> choose the downloaded XML.
Binding of Simple Fields
Before we start with more complex topics like tables, let’s begin with an easy example to explain the general procedure. The following screenshot is an excerpt of a sample XML file:
Let’s assume we want to show the ID of this delivery note and the full name of the receiver of the goods. The ID is simple as it’s one of the first fields in the XML. The full name of the goods receiver can be found in the subnode ProducRecipientParty, in the field FormattedName.
You can usually find several Party nodes inside the XML representing the different involved parties of the document. Other common examples for involved parties are: BuyerParty, SellerParty, ProductRecipientParty, ResponsibleEmployeeParty, etc.
Hint: Always look at these parties from the view of your company. In a sales document such as a sales quote or sales order, the buyer is your customer/client. If you want to order goods from your supplier and send a purchase order to them, you are the buyer.
We could add two fields to the form and bind them as follows:
- Binding of the ID field: $.DeliveryNote.ID
- Binding of the Recipient field: $.DeliveryNote.ProductRecipientParty.FormattedName
If you compare these binding paths to the data XML you will notice that the XML root element (the one with the namespace declaration) is not mentioned in the path. Instead, the binding path starts with DeliveryNote and navigates through the XML tree using dots (.) as separators.
The result could look like this:
If you want to bind multiple fields to XML nodes that share the same parent, you can wrap them in a subform and bind the subform to the parent node. Although that doesn’t save us any effort, I still like this approach as it’s close to the data structure and it’s cleaner in my opinion. And the binding paths of the sub-fields are displayed shorter which makes them easier to read and find mistakes…
The following screenshot shows the parent subform approach for the example of the delivery note’s ship-to-address. The XML that contains the postal address lines on the right, and the text fields wrapped in a parent subform on the left:
As we can see in the XML, the address information is stored in the ShipToLocation node under FormAddress and it is split amongst several PostalRegulationsCompliantAddressLines, each with the according prefix First, Second, etc.
In the form hierarchy we have the frmShipToAdd subform as the parent, bound to $.DeliveryNote.ShipToLocation.FormAddress. Underneath we have a text field per address line. The first one has the binding $.FirstPostalRegulationsCompliantAddressLine.Description, the second one $.SecondPostalRegulationsCompliantAddressLine.Description, and so on and so forth. If we omitted the parent subform or didn’t bind it, we would have to write the whole binding path starting with $.DeliveryNote.ShipToLocation… for every text field. With the parent subform each text field’s binding path starts directly with the $.First, $.Second, etc. part.
Some background knowledge on addresses: The correct representation for postal addresses are generated by the system. That means we don’t need to take care about concatenating single parts of an address or include line breaks, etc. on our own. That’s already done by the system. We only need to display the single lines. And that might be the surprise: Maybe you expected a single field with line breaks. However, the address lines come in separate fields, each with a different name. So, we have to bind every single field.
Alright, that’s enough for the basics. Continue reading in the next blog about Data Binding with Repeating Items and Simple Tables in Print Forms.
In case you have questions, feel free to ask them in my live session:
As already mentioned at the beginning of this post, I’m delivering monthly live sessions with a changing agenda on the topic of print form adaptation. If you are interested and would like to join, here are some details:
The live session is available on SAP Learning Hub. You need a subscription with access to the SAP Customer Experience learning resources in order to register for the live session.
There are two ways to access to the registration page of the live session (as well as the schedule of the next occurrences):
- You can use the following direct link, but please remember you need to be logged in on SAP Learning Hub first to use the link!
Direct link: Live Sessions – SAP Customer Experience: C4C Extensibility
- Alternatively you can go to SAP Learning Hub, and search for “Print Form Adaptation with Adobe LiveCycle Designer”. Look for a webinar with the headline “Live Sessions – SAP Customer Experience: C4C Extensibility” and the code: (LS_CX_C4CEXT_EN / EXPERT_LED) under “Learning Content”
If you want to get informed about the next blogs of this series or updates on the live session, please follow this blog post by clicking on the green “follow” button on the left. You can also follow me Felix Wyskocil for more blog posts about SAP Customer Experience Solutions – Integration and Extensibility topics.