Use Custom Functions in Blueprints

As your Blueprints become more sophisticated, you'll often have complex calculations or business logic that needs repeating. SignStack's Custom Functions provide a clean way to encapsulate and reuse this logic.

Think of a Custom Function like creating a helper function in your own codebase – define it once, use it anywhere.

Why Use Custom Functions?

Reusability: Define complex logic (like calculating region-specific taxes or formatting an address) in one place and call it from any expression.
Readability: Keep your main Blueprint expressions (valueExpression, inclusionCondition, onCompleteMapper) clean by abstracting complex details into a named function.
Maintainability: If your business logic changes, update the Function definition once. All Blueprints using it automatically benefit from the active version.

1. Define the Function

First, create the reusable JsonataFunction asset using the /jsonata-functions API or the SignStack dashboard. Give it a unique key (e.g., calculateProratedFee), manage its version, define its params (inputs), and provide the JSONata body. (See Core Concepts: Custom Functions for creation details).

Example JsonataFunction (calculateProratedFee v1.0.0):

key: calculateProratedFee
version: "1.0.0"
status: "Active"
params: [{ "paramName": "fullAmount", "paramType": "NUMBER" }, ...]
body: (fullAmount * daysRemaining) / totalDays

2. Call the Function in Expressions (Automatic Detection)

You don't need to manually declare function dependencies in your Blueprint. SignStack automatically detects which functions you call.

Simply call the function directly within any JSONata expression in your Blueprint (like valueExpression, inclusionCondition, or onCompleteMapper) using its active key prefixed with a $.

Example: Using in a valueExpression:

// Expression for a 'proratedFeeDisplay' field in a DocTemplate
"$formatNumber($calculateProratedFee(entities.dealInfo.totalFee, entities.dealInfo.daysLeftInMonth, 30), '$,0.00')"

Example: Using in an onCompleteMapper:

// Mapper to update the dealInfo entity
"onCompleteMappers": [
  {
    "targetEntityKey": "dealInfo",
    "mapperExpression": "$merge([entities.dealInfo, { 'proratedFee': $calculateProratedFee(entities.dealInfo.totalFee, entities.dealInfo.daysLeftInMonth, 30) }])"
  }
]

How it Works: When you save your Blueprint, SignStack parses your expressions, identifies the $calculateProratedFee call, and automatically links it to the currently active version of that function in your organization. If the function doesn't exist or isn't active, you'll receive a validation error.

Custom Functions, combined with automatic detection, provide a powerful yet simple way to create sophisticated, maintainable, and reusable business logic within your SignStack Blueprints.

➡️ Next: Guides: Manage Blueprint Versions