Understanding JSON-Based Mapping Contract Templates

Tokens, also known as variables, defined in the document template sections or inherited from clauses, can be bound to Salesforce object fields or input JSON data. The data is merged into document template sections when the final contract document is generated.

There are two types of contract document templates, based on how token mapping occurs:

• Templates with object-based mappings have existed since Vlocity CMT V11. Each token in a contract document section is mapped to an SFDC object field. The supported objects are Contract, Opportunity, Order, and Quote.

• Templates with JSON-based mappings were introduced in Summer '17, Major release, Version 100.0. 890.26 and Summer '17, Minor release, Version 100.0.900.72-73. Data in JSON format can come from any source and can be mapped to tokens using Omnistudio Data Mapper, Omniscript, Apex code, or other available tools.

Note

Using Document Generation in Vlocity Government, you cannot use object-based templates. You must use JSON-based templates. Object-based template apply only to specific objects, such as Contract, Opportunity, Order, and Quote.

In Vlocity Communications, Media, and Energy Winter '18, Minor release, Version 101.2.900.151, templates based on Microsoft Word and Microsoft PowerPoint documents must be JSON-based.

Object-based mapping document templates have some limitations.

• The data to extract and merge into the template must exist in SFDC objects, so documents cannot be generated from data captured during a Vlocity session.

• Vlocity supports only Contract, Opportunity, Order, and Quote objects for object-based token mapping. Customers cannot generate a document from data residing in a custom object or other standard objects, such as Account or Contact.

• Documents cannot display attribute data unless you use the Custom section in the document template. This requires writing Apex code with developer support.

• The document cannot easily display related lists associated with a main object that is not a Line Item object, because a customer can only map document template Item sections to line items. The customer could use a document template Custom section, which requires Apex code and developer support.

• Vlocity cannot use conditions to filter out individual line items displayed in document template Item sections. Vlocity displays all line item data. It isn't possible for the document to display a list of line items that consist of products separated from services.

JSON-based mapping document templates do not have these limitations. You can accomplish all of the items listed above using JSON-based mapping document templates.

JSON-based mapping document templates are not bound to Salesforce objects. Instead, each of the tokens defined in the template sections are mapped to a JSON structure. At run time, the mapped elements from the input JSON replace the tokens in the template when Vlocity generates the document. A Vlocity document template can consume any data that is in input JSON. The input JSON can come from any source, including a Data Mapper extract bundle or an Omniscript.

In addition to mapping template tokens to JSON input, JSON-based mapping templates provide additional features that are not available in object-based mapping templates. JSON-based mapping templates provide the following advantages:

• You can generate Microsoft Word and PDF documents using input JSON as the data source. Document generation isn't tied to any SFDC object. Vlocity can generate documents using data extracted from any object or data that is not stored in objects, such as an Omniscript.

• You can generate documents that use advanced formatting. You can generate documents that group order line items of a particular type and you can display them in a specific format. For example, you can create a separate section for order line items that are devices and a separate section for order line items that are plans. You can display product attributes in documents, even if those attributes are not storied in the order line item fields.

• You can display repeating content in a generated document. You are not limited to line items of an object such as a Contract, Order, or Quote. For repeating items, you can display or hide individual line items based on conditions. For example, you can create a grid that displays only network products and their prices, or only active contracts associated with an account. To display repeating content, use a repeating content document template section.

• You can use formulas to specify criteria for displaying information. You can use any token from the template to build the formula, or you can define new tokens within the formula. At run time, Vlocity evaluates these formulas based on data passed to the tokens. Then, the template section may or may not be displayed based on the formula.

• You can use the item section for any type of item list, not only for line items. Display any type of grid, or table, as long as the input is available in a JSON array. For example, you can display price lists or rate tables.

• You can filter individual line items or repeatable content items to display in a document. For example, from a set of quote line items, you can display devices in one table and services in another. Use a formula to filter the type of line items to show.

Vlocity can generate documents as part of an Omniscript-based guided interaction flow. Here, the JSON input could be constructed using a Data Mapper extraction step within the Omniscript, or by collecting data from the user in the Omniscript. A remote call can pass the JSON when generating the document. You can then convert the document to PDF or Microsoft Word to access within the Omniscript. You can also attach the appropriate object record or even email it to someone.