Using the PDF Widget

Use the PDF widget to provide a PDF document with application data. You can embed the PDF document in a custom form or open it in a new browser window.

The widget includes standard PDF document features, such as printing and saving to file. This means users can have a printed version of application data, and can e-mail a saved version of the PDF document containing the application data to others.

The document presented to users is based on a template added to the PDF widget on your form. You can map fields in your application to fields in the template, or you can provide static values. For guidelines, refer to Field Mapping Rules.

The following guidelines apply to the PDF widget:

PDF templates created with Adobe® Acrobat® 9 Pro, Adobe® Acrobat® X Pro, and Adobe® Acrobat® XI Pro are supported. The PDF documents must be PDF version 1.4 or later.
To view PDF documents and use their features, users must have Adobe® Reader® installed on their computers. To view PDF documents in preview mode or test your process app, you must have this application installed as well. If this application is not installed, a link to the Adobe Reader download page is displayed.
To view PDF documents inside of an SBM form, users must use a browser that supports the Adobe Acrobat plug-in, as well as have Adobe Reader installed. Mozilla Firefox and Microsoft Internet Explorer support the Adobe Acrobat plug-in and display PDF documents as expected. It is highly recommended that users use the latest versions of Firefox or Internet Explorer and the Adobe Acrobat plug-in.
Note that the Adobe Acrobat plug-in is not compatible with Google Chrome and Microsoft Edge. See the Adobe website for information on which browsers are compatible with the Adobe Acrobat plug-in.
In preview mode, the PDF template is displayed, but the input fields are not populated with runtime data.
The input field names can contain a maximum of 128 characters.
To support Unicode characters, make sure that "plain text" is not enabled for fields during the creation of the PDF document.
If the number of characters in a text field is too large, scroll bars appear so users can see all of the text. However, if this text field is mapped to an input field in a PDF template, the extra text is truncated and cannot be seen. Similarly, if users add an image that is too large for the mapped input field, it will not be displayed in the PDF document.
To prevent this, make sure the input field in the template is large enough to accommodate the expected amount of text or an image.
By default, the PDF widget supports application data that contains rich text. For details, see Rich Text Support.
Users can manually edit a PDF document after it has been populated by SBM field values. Note that any changes will not be synchronized back to SBM.

For a sample template, refer to S137510 in the Knowledgebase at serena.com.

Field Mapping Rules

All SBM field types can be used in the PDF widget, except for Summation and Secondary Owner.

All special fields are supported. These fields are available from the string builder tool. (For more information, see Using the String Builder Tool.) Special fields include the following:

_height
_width
_ProjectID
_RecordID
_TableID

The following PDF field types are supported:

Check Box
Drop-down List/Combo Box
List Box
Radio Button
Text

SBM fields can be mapped to any PDF field type, but the values must match exactly. For example:

If you are mapping a SBM Single Selection field to a PDF List Box field type, you must create the field with the same values in each application. For example, if you add Defect, Enhancement, and Internal Task as values for a Single Selection field called "Request Type" in SBM Composer, you must enter the same values as list items in the List Box field in the PDF form.
Similarly, if you are mapping a SBM Single Selection field to a PDF Radio Box field type, the values must match. If you add Vacation, Sick, and Jury Duty as values for a Single-Selection field called "Time-Off Type" in SBM Composer, you must enter the same values as item names in the PDF form.

Note: An exception to this rule is when you map a SBM Binary field to a Check Box PDF field type that is used to toggle between two settings. In this situation, the mapping is handled internally, and the values do not have to match. There is no adverse effect if the PDF form requires values of "On" and "Off", and the SBM Binary field requires "Yes" and "No."

Rich Text Support

The PDF widget automatically displays application data using rich text in addition to plain text. Rich text is available for Memo and Journal fields.

Note:

To display rich text in the PDF widget, you must map Memo and Journal fields to PDF text fields with the Multi-line property enabled.
For Journal fields, only the first entry appears in the resulting PDF. Additional information about the author of that entry (including the name, user icon, and date/time stamp) is not included.

To disable rich text, set the RichTextEnabled option to false in the config.properties file, located in the following directory:

installationDirectory\Serena\SBM\Common\Tomcat x.x\server\default\webapps\DocGenerator\WEB-INF\classes

The following rich text options are supported:

Font
Font size
Font color
Background color
Bold
Italic
Strikethrough
Underline
Superscript/subscript
Hyperlinks
Bullet list
Source code

Note: In Serena Work Center and SBM User Workspace, users can click the source code option in the Rich Text Editor to manually insert HTML tags. If users use this option to insert a table, the table is displayed in the PDF document with fixed-width columns, even if the table columns in SBM were specified with different widths.

The following fonts are supported:

Arial Black
Courier
Courier New
Comic Sans MS
Helvetica
Impact
Lucinda Grande
Lucinda Sans
Tahoma
Times
Times New Roman
Verdana

If a non-supported font is used, the PDF widget uses the default font specified in the config.properties file. By default, Arial is used.

Plain Text Formatting

For plain text output by the PDF widget, you can customize the formatting by editing the html_formatter.properties file, located in the following directory:

installationDirectory\Serena\SBM\Common\Tomcat x.x\server\default\webapps\DocGenerator\WEB-INF\classes

This file contains the HTML tags used in PDF documents and their default values. See the file for instructions on how to customize these values.

Error Messages

The following error messages could be generated during the configuration of the PDF widget.

PDF Template does not contain field with name.
PDF Template contains field of unknown type.
Invalid values.
No field mapping found in the PDF Template.
Unable to read fields from PDF Template.

To correct these problems, modify or replace the PDF document being used as the template.