One of SignStack's core strengths is its ability to make document fields dynamic. Instead of static placeholders, fields can automatically show, hide, or calculate their values based on the current EntityContext data of your workflow. This is achieved using the valueExpression and displayCondition properties on a TemplateField.

This guide explains how to use these properties with JSONata expressions to bring your documents to life.

The EntityContext: The Data Source

Remember from the Core Concepts, the EntityContext holds the authoritative data state for your running Workflow. All expressions operate on this context, typically accessed via the entities object (e.g., entities.clientInfo).

valueExpression: Calculating Field Values

The valueExpression defines the logic for determining what a field displays. It's evaluated "just-in-time" whenever the document is rendered.

• Engine: Uses the powerful, open-standard JSONata expression engine.

• Purpose: To calculate a field's value by reading from the EntityContext.

Example 1: Simple 1-to-1 MappingDisplay the client's company name directly.

• TemplateField Definition:

  {
    "key": "clientCompanyNameDisplay",
    "type": "Text",
    "valueExpression": "entities.clientInfo.companyName",
    "widgets": [ /* ... position info ... */ ]
  }

  json

Example 2: Formatting and CalculationsDisplay the total deal value formatted as currency.

• TemplateField Definition:

  {
    "key": "totalValueDisplay",
    "type": "Text",
    "valueExpression": "$formatNumber(entities.dealInfo.pricePerUnit * entities.dealInfo.quantity, '$,0.00')",
    "widgets": [ /* ... position info ... */ ]
  }

  json

Example 3: Combining Data from Multiple EntitiesCalculate a priority fee based on deal size and client status.

• TemplateField Definition:

  {
    "key": "priorityFeeDisplay",
    "type": "Text",
    "valueExpression": "$formatNumber(clientInfo.tier = 'Premium' and dealInfo.value > 50000 ? dealInfo.value * 0.02 : 0, '$,0.00')",
    "widgets": [ /* ... position info ... */ ]
  }

  json

displayCondition: Controlling Field Visibility

The displayCondition determines whether a field is shown or hidden.

• Engine: Also uses JSONata.

• Purpose: To execute logic using data from the EntityContext and return true (show the field) or false (hide the field).

Example: Conditional Discount Approval Field only show a "VP Discount Approval Signature" field if the deal value is high and the client isn't strategic.

• TemplateField Definition:

  {
    "key": "vpDiscountSignature",
    "type": "Signature",
    "assignedToRoleKey": "vpSales",
    "displayCondition": "entities.dealInfo.value > 100000 and entities.clientInfo.isStrategicPartner != true",
    "widgets": [ /* ... position info ... */ ]
  }

  json

Centralized Logic & Best Practices

• Centralization: By defining these expressions within the Template, you keep your document presentation logic encapsulated within SignStack, decoupling it from your application code.

• Read-Only: Remember, valueExpression and displayCondition only read data. Use onCompleteMappers in your Blueprint steps to update entity data.

• Use Functions: For complex or reusable logic, create a Custom Function and call it from your expressions (e.g., $calculatePriorityFee(entities.clientInfo, entities.dealInfo)).

• Handle Missing Data: Use JSONata conditionals ($exists, ternary ? :) to gracefully handle optional data.

• AI Assistance: 💡 Modern LLMs are great at generating JSONata expressions! Describe your logic in plain language and ask for the JSONata equivalent. Always review and test AI-generated code.

Using valueExpression and displayCondition transforms your static documents into dynamic interfaces that react to your business data.

➡️ Next: Guides: Manage Template Versions