Document Engine Overview

Overview

The Document Engine is deprecated. Customers need to recreate their existing DocEngine Templates with the Document Designer. Upon upgrade to Oracle CPQ 21D, customers will no longer have access to Document Engine administration for the editing of templates. They will, however, retain edit access to the raw XSL templates that Document Engine produced. Print actions using templates created with the Document Engine will continue to function for end users. To learn more about Document Designer, refer to the Document Designer Overview.

The Document Engine powers the Oracle CPQ Proposal Generator and the Oracle CPQ Contract Generator. Users can create professional and customer-friendly proposals and submissions as well as customize and brand proposals for specific products, channel partners or customers. The Document Engine also automates the generation of customized contracts driven from approved and submitted quotes and orders.

Document customization capabilities:

Next Steps:

After you have created and deployed a document in the Document Engine, you must set it up so that it can be used and printed.

  1. Associate the document with a Printer-friendly XSL view.
  2. Create a Commerce Print (or Email) action that refers to the Printer-friendly XSL view.
  3. Add the action to an end-user layout.
  4. Deploy the Commerce action.

Now, the user can click the action and the document from the Document Engine emerges with Oracle CPQ data inserted. For detailed steps, see the topic Document Engine Steps.

Administration

ClosedDocument Engine Structure & Relationships

Document Engine Structure & Relationships

ClosedAccessing the Document Editor

  1. Click Admin to go to the Admin Home Page.

  2. Click Documents under Commerce and Documents.

    The Document Engine Management Center appears.

  3. Click the name of an existing document, or click the pencil icon for a document and then click Open Document Engine.

    The Document Engine appears.

  4. Double-click an item in the Flow tab to edit it.

    The item opens in editing mode.

ClosedUnderstanding the Document Editor

The Document Editor is a visual XSL editor designed for authoring and editing XSL templates. You can produce dynamic and customized commerce documents in either PDF or RTF formats, using the components and features of the Document Editor.

Docment Editor elements

Key Components of Document Editor

ClosedFeatures in a Document

ClosedPages

ClosedLoops

ClosedXSL Snippets

ClosedTool Bar Ribbon

The Tool Bar contains actions that the user can perform on the elements of a Document Page in the Page Design Mode. The actions on the Ribbon are grouped in tabs.

ClosedPage Design Mode

The Page Design Mode is where the user builds and edits Pages. This mode includes a collection of components for authoring and formatting text. The user can also insert dynamic data in the text, which is data that easily and automatically changes to allow for easy customization. Navigation: Document Application Panel > Document Flow Tree > double-click the desired page

Page design in Document Editor

ClosedComponents of Page Design Mode

  • Page Properties Grid: The grid displayed on the left panel stores formatting properties of the page, such as color, font family, font size, font style and so on.
  • Page Design Tool Bar Ribbon: The Tool Bar Ribbon comprises a menu of actions that can be used to edit and format the document pages. The tool bar consists of a set of tabs with groups of actions. Selecting a specific tab switches the tool bar to display the chosen tab with its menu items.
  • Rich Text Editor Region: View and edit the text within a page. Enter dynamic data using the Dynamic Content dialog box. Actions on the Tool Bar Ribbon manipulate the content in this region.
  • Page Vertical & Horizontal Rulers: The vertical and horizontal rulers show the document's dimensions. The unit of measure defaults to the Meas. Units option, set in the View/Options tab of the Document Application panel.
  • Draggable Page Layout/Margins: Change the page dimensions by dragging the margins.
  • Direct Selection Path: The structural building blocks of a document are known as nodes. Click a Node button (highlighted with the red rectangle in the image below) to select an entire node. Use Node buttons to select the exact node to edit or format.

Ad-hoc items

ClosedValidations & Optional Feedback

You can optionally run a validation on page data when saving a page in the Document Engine. When an error is found during validation, you will get an error message. You have the following options after receiving the error message:

  • Save the corruption.
  • Revert to the last saved copy
  • Cancel the save
You can send feedback to the Oracle CPQ development team directly when you get the corruption. Make sure to define the steps to reproduce.

ClosedTo set page validation:

  1. Click Admin to go to the Admin Home Page.

  2. Click Commerce Settings under Commerce and Documents.

    The Commerce Options page opens.

  3. Select Yes for the option Document Engine – Validate Page Data on Save. This is set to NO by default.

    Validation errors dialog

ClosedUpon validation error, you can

  • Save with Errors: Save despite any errors. From this point on, you will encounter this error on this content until it is fixed.
  • Revert to Previous Version: Revert to the last saved state. This will not rollback changes made to content of dynamic items like XSL snippets, simple conditions, loops, clause conditions, row conditions/loops, formatted expressions and others.

  • Cancel: Cancel the operation which caused this validation to fire. You will not lose changes you made.

    The validation is run on complex conditionals.

    The error message is sent to development, even if you don't provide feedback details. Feedback is stored in a database that is periodically analyzed by development.

    This feedback is not a replacement for immediate bug reporting, so turn around time for this would be much longer.
    Revert to last save is not available for new complex conditionals, but becomes available once the complex conditional has been saved for the first time.

ClosedSupported Node Types

Content in the Rich Text Editor is organized in a way similar to the way HTML is structured. This not only helps in providing structure to pages in a document, but also allows for enhanced functionality.

Example: Depending on where the cursor is in the Editor, different options are available to use. Similarly, depending on the Node Type that is selected, specific ribbon tabs are shown/hidden. This reveals what actions can be performed on a given node type.

ClosedBest Practices

  • While working in the Document Engine Editor, click the Save button button to save your work.
If you close the Document Editor without saving your changes, they will be lost.
  • When possible, use standard functionality instead of XSL.
  • Make backups; right-click a page in the Document Flow Tree panel and select Copy. Optional: Right-click the copy and click Rename.
  • After modifying a document page through a Web Developer tool and saving the changes, reload/reopen the page before making any further changes. This ensures that the HTML changes made using the Web Developer tool are properly reflected in the document XSL.

Troubleshooting

ClosedFixing corrupt documents

Corrupted file error messages are sometimes caused by deleting/altering tables, rows, or conditionals.

To fix a corrupt document:

  1. Open the corrupted file in Document Engine.
  2. Navigate to the area where an item was recently deleted/edited prior to the file corruption.
  3. Open a Web Developer tool within Document Engine.
  4. Click the row (or table, or paragraph) with a conditional that was recently altered and may have caused the corruption.
  1. Examine the element's HTML to determine if it is causing the problem.
  2. Once the corrupted element has been located, right-click the element and select Delete Element.

You will need to rebuild the table (or row) that had been there.

When deleting items in Document Engine, begin with the innermost element (for example, dynamic data, XSL snippets, complex conditionals) and then work outwards (for example, row, table).
To avoid this problem in the future, delete elements properly by using the buttons provided within Document Engine.

ClosedMobile Documents

When printing or previewing a document on a mobile device:

  • iOS 8: Formatting in DOCX files is stripped from a preview. To see the complete formatting, use iOS functionality to open the document in an installed app, such as Word or Pages, instead.
  • Android: Oracle CPQ recommends using Google Docs to open DOCX files on Android devices. While other applications may produce acceptable results, this functionality was tested using Google Docs.

Use Cases

ClosedUse Case: Displaying a Conditional Watermark

Let's say you need to display a background "DRAFT" image for quotes that are in a pending state. We recommended that you define a global main_doc variable to point to your header attributes. You can only define it once in the document, so if main_doc is already defined, don't define it again.

  1. Before starting the Document Engine, upload an image to the Oracle CPQ File Manager to use as the watermark.
Make sure that the image that you use is a valid image that the FO processor can read.

  1. Click Admin to go to the Admin Home Page.

  2. Click Documents under Commerce and Documents.

    The Document Editor List page opens.

  3. Click the name of the quote document you want to edit.
  1. In the Document Flow Tree panel, click Add and choose Add XSL.

The Flow XSL Snippet dialog box opens.

  1. Copy and paste the code below into the dialog box.

<xsl:variable name="main_doc" select="/transaction/data_xml/document[@data_type=0]"/>

<xsl:variable name="watermark">

<xsl:choose>

<xsl:when test="$main_doc/quoteStatus_q = 'Pending">/bmfsweb/pm/image/Proposal/watermark.jpg</xsl:when>

<xsl:otherwise></xsl:otherwise>

</xsl:choose>

</xsl:variable>

An <xsl:choose> statement is basically an IF/ELSE IF/ELSE block.

The processor will retrieve the value of the first <xsl:when> conditional statement that is true. In this case, we are returning the URL of the watermark if the watermark should be displayed.

  1. Replace the image URL to point to your watermark image.
  2. Change the logic of the text to one that you need for your application. In the example, we are checking for the main document commerce attribute with variable name quoteStatus_q and seeing if it equals the text "Pending".

Your implementation may be different. You can add more <xsl:when> statements if you need to.

  1. Name and save the Snippet.

  1. Double-click the page where you want to place the watermark.
  2. Select Edit Layout from the Home tool bar to open the Layout Editor.
  3. Click the Body tab.

  4. In the Value column of the Image property, enter {$watermark}. It is important to enter the {$} brackets as well, since this tells the processor that the image URL is contained in an XSL variable called {$watermark}. Now the page layout will read the global watermark variable.

    Add watermark

  1. Click Apply Layout.
  2. Save the document.

  3. Test your new watermark.

    Watermark example

    The watermark image will only appear in the document output when printed and will not be displayed inside of the page editor.

Notes

Documents are deployed separately from Commerce. To view the latest changes in a document on a Print/Email/Preview action, you must first deploy the document. New documents must be deployed before they can be linked or accessed in the Printer-Friendly XSL views.

If content that is stored in a secure File Manager folder is referenced, the path must be updated.
Document Engine now includes the capability to format all CPQ-supported currencies (as long as the symbol is supported by the font).

Only the deployed version of a document is available for download or migration.

Global elements, like Content Library and Complex Conditionals, will be migrated every time a document is migrated.
Bulk upload of an existing document using the Add action is not supported.

Related Topics

Related Topics Link IconSee Also