- SAP Managed Tags:
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:
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.
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.
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:
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:
Starting 2024 the live sessions have moved to a new platform: You can find them via this new direct link on learning.sap.com. You still need a corresponding subscription in order to register for the live session.
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 fwys for more blog posts about SAP Customer Experience Solutions – Integration and Extensibility topics.
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
Basic Preparation
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!
Update Data Connection
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.
Data Binding Menu
Local Preview
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:
Excerpt of a sample XML
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:
Data Binding of the Recipient Field
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:
Hierarchy, Design View and XML for the Ship-To-Address
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:
Live Sessions (UPDATE 2024!)
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:
Starting 2024 the live sessions have moved to a new platform: You can find them via this new direct link on learning.sap.com. You still need a corresponding subscription in order to register for the live session.
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 fwys for more blog posts about SAP Customer Experience Solutions – Integration and Extensibility topics.
