You are here: Document Engine > Document Engine Overview

Document Engine Overview

OVERVIEW

The Document Engine powers the CPQ Cloud Proposal Generator and the CPQ Cloud 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 CPQ Cloud data inserted. For detailed steps, see Using the Document Engine, Step by Step.

ADMINISTRATION

ClosedDocument 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.

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

ClosedComponents of Page Design Mode


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:

You can send feedback to the CPQ Cloud 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 appears.

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

ClosedUpon validation error, you can


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

If you close the Document Editor without saving your changes, they will be lost.


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 Firebug within Document Engine.
  4. Click the Click an element in the page to inspect button in the upper left-hand corner.
  5. Click the row (or table, or paragraph) with a conditional that was recently altered and may have caused the corruption.

The element you select will be highlighted in the Firebug editor.

  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:


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 CPQ Cloud 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 appears.

  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.

  1. Click Apply Layout.
  2. Save the document.
  3. Test your new watermark.

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

NOTES

RELATED TOPICS

Related Topics Link IconSee Also