Sales Contract Applet

Sets up a repeating customer commitment — a maintenance agreement, a subscription, a rental — as a contract folder initialised from a template, carrying the duration, the dates, the signable agreement and the recurring sales invoices that bill it. A folder posts nothing; each occurrence becomes a real sales invoice through the same backend job as Recurring Sales Invoice. Most contracts are created without opening this applet: finalising a sales document with a contract item line creates one folder per unit sold, which fails unless the item carries a sales contract template. Nothing expires a contract — its status is Active or Inactive, changed by hand.

Overview

The Sales Contract Applet is where a repeating customer commitment is set up and then billed: a maintenance agreement, a subscription, a rental. You build a sales contract template once, attach an agreement template (the document the customer signs, held as a mail-merge file), and then initialise a sales contract folder from that template for a particular customer. The folder carries the duration, the dates and the recurring sales invoices that bill it.

The applet is administrative in shape — the registry lists it as a TNT-ADMIN applet — and a lot of what happens around it happens in the backend rather than here. In particular, a finalised sales document whose line is a contract item creates folders and their recurring invoices automatically; see Lifecycle and effects.

Where it fits

Screens and menus

Open the applet from the Applet Store or its menu link, which lands on the folder listing. The bare applet address does not resolve — typed without the rest of the path, it shows a not-found page.

Three menu entries:

Settings has three entries: Application Settings, Default Selection, Printable Format Settings. The Settings area opens on the client-side permission listing, not on any of those three. Personalization lists Default Selection.

Sales Contract Folder

The folder container is a stack of nineteen view columns: listing, Initialize, folder edit, customer and member pickers, add agreement template, create recurring sales invoice, item and line-item screens, bin and batch listings, attachments, sales-invoice edit, and the address pickers.

The folder edit screen has seven tabs: Main Details, EKYC, Agreement, Attachmment (spelled that way on screen — the misspelling is the product’s), Recurring Sales Invoice, Gen Doc and Fixed Asset.

Sales Contract Template

Listing, create and edit, plus two sub-tabs on the edit screen — Sales Invoice Template and Agreement Template — and an item picker. The listing shows active templates only.

Agreement Template

Listing, create and edit. An agreement template is stored as a mail-merge header: a document number, a name, a URL key pointing at the file, and a type of either Google Docs or MS Docs. The applet holds the pointer; it does not hold the document.

Configuration

Before you can use it

• A sales contract template, or Initialize has nothing to offer.
• An agreement template, if the contract needs a signable document. It needs the document’s URL key and its type.
• Contract items linked to a template. For the automatic path (see Lifecycle and effects) the item record must carry a sales contract template, and that template must be linked to a generic-document template. Both are hard backend requirements; without them the background job fails — see Troubleshooting.
• A printable format filed under transaction type SALES_CONTRACT if the contract is to be printed.
• A customer — the folder’s Entity ID is required.

Applet settings

Where they live. Application Settings is the shared settings screen. Default Selection and Printable Format Settings are this applet’s own; Personalization’s Default Selection is per-login and says so on screen (“This will override Applet Default Settings”).

The settings model declares about fifty further INCLUDE_*, ENABLE_*, ENABLE_CUSTOM_STATUS_* and HIDE_* keys. Twenty of the HIDE_* keys do something: each hides one column on the recurring-invoice line editor — the unit-price, discount, quantity, UOM, tax and withholding-tax columns — and they are the Field Settings toggles that matter for this applet. The rest are read by nothing here.

Document behaviour settings

There is no status-flow, posting, workflow or approval setting, because there is no posting and no workflow. The applet has no e-Invoice control of any kind.

Feature visibility / permissions

The applet contains one client-side permission check in total: INTERNAL_SALES_INVOICE_DISPLAY_PRICING, which hides prices on the recurring-invoice line listing. Note that it is a sales-invoice key, not a contract key.

Backend permissions:

Creating or initialising a folder needs …_FOLDER_HDR_CREATE; saving one needs …_FOLDER_HDR_UPDATE.

Fields

Sales Contract Folder — Main Details

Sales Contract Template

Create requires Sales Contract Template Number and Sales Contract Template Name. Status defaults to ACTIVE and ACTIVE is the only option offered, on both create and edit — there is no way to deactivate a template from this applet. Optional: EKYC required, EKYC validity period in months, subscription duration with a Months/Days unit, fixed asset, remarks.

On the edit screen the template number and name are editable, so nothing on a template is immutable after save.

Agreement Template

Lifecycle and effects

What the applet writes

• Contract folders. Initialize creates the folder directly from a template, with no sales order and no sales invoice created.
• Sales contract templates, agreement (mail-merge) templates, fixed-asset links and attachments.
• Recurring sales invoices — the Create Recurring Sales Invoice screen creates a recurring sales invoice tied to the folder. These are the same records the Recurring Sales Invoice Applet manages, and the same backend job materialises them.

The automatic path — where most contracts actually come from

When a sales invoice is finalised — from Sales Invoice (Internal) or through the API’s update-posting-status route — a background job looks at each of its lines. It is queued only when the finalised document is a sales invoice: a contract item sold on a cash bill, a sales order or any other document creates nothing here. The job acts on an item line whose item’s transaction type is SALES_CONTRACT, on a FINAL document, that it has not already handled. For each such line it:

1. Looks up the sales contract template on the item record — and fails with “Item not Connected to any Sales Contract Template…” if the item has none.
2. Looks up the template’s link to a generic-document template — failing with “SALES_CONTRACT_TEMPLATE NOT LINKED TO ANY GENERIC_DOC_TEMPLATE…” if absent.
3. Adjusts the start date by the link’s offset.
4. Creates one folder per unit of quantity sold.
5. Populates and creates the recurring sales invoice for each folder.
6. Marks the line handled so it cannot recur.

So selling a contract item on an invoice is what normally creates the contract. Initialize is the manual alternative, and the controller says so.

The agreement PDF: what gets filled in, and what comes out blank

An agreement template is a Google document. The contract turns it into a PDF for the customer to sign. None of this shows on screen until the PDF appears on the folder’s Agreement tab, or fails to.

What happens behind the scene. After the automatic path creates the folders, BigLedger queues one merge for each folder. The merge covers every agreement template linked on the sales contract template’s Agreement Template tab. For each one it:

1. Opens the document in Google Docs, using BigLedger’s own Google account.
2. If the agreement template has fill-in fields, makes a copy named after the original plus the contract number. In the copy, every marker (the field’s code in double curly braces) is replaced with a value.
3. Exports the result as a PDF and stores it on the folder. On the Agreement tab, Download saves it as "<contract number> - Agreement".

Sell three units of a maintenance-plan item and you get three folders, each with its own PDF.

What a fill-in field can take. The customer’s name, phone and e-mail from the customer record, the member’s card number, the company code and the branch code. The list also offers document numbers and billing and shipping address lines. Those always come out blank: the merge never loads the invoice they would come from.

Things to know before you rely on it:

• No screen sets up the fill-in fields. They exist only through the API. An agreement template without them is exported exactly as written, so the customer receives your template with its markers still in it.
• Only the automatic path makes a PDF. A folder created with Initialize gets no agreement. The folder’s own add-agreement-template screen saves nothing.
• The document must be one BigLedger’s Google account can open. Choosing MS DOCS as the type changes nothing: the merge always goes through Google Docs, and the stored PDF is marked as Google Docs.
• A failed merge tells nobody. It is written to the server log only, and the Agreement tab stays empty.
• An inactive agreement template is still merged while it is linked. To stop it, remove the link on the sales contract template’s Agreement Template tab.
• Values are taken once, when the folder is created. Correct the customer’s phone number afterwards and the PDF keeps the old one.
• Signature required is a note, not a process. It is stored with the PDF, and nothing in BigLedger collects a signature against it.

The job that stays with a person. Whoever sold the contract opens the new folder the same day and reads the PDF against the customer record: markers left in, blank address lines, the wrong name. If the tab is empty, or the PDF is not fit to send, prepare the agreement outside BigLedger from the same template and upload the signed copy on the folder’s attachments tab, which the screen spells Attachmment. Doing this every time is what makes it a check. Nothing else will notice.

Posting proof block

A contract folder posts nothing: no journal, no stock movement, no GL code to resolve, and no VOID.

What the applet cannot do

• No Final, Void, Discard, Close or Expire. None of those controls exists for a contract folder, and nothing enforces any status transition — only that a status is set.
• No Final on a recurring invoice from here either. There is no Final button. Posting is done by the backend job, which sets the recurring row’s posting status to POSTED.
• Nothing expires a contract. No job, no scheduler and no validator reads the end date to change a status.

Related applets

• Recurring Sales Invoice Applet — the same recurring records, with the recurrence rule, the scope dialog and the series semantics documented in full.
• Sales Invoice (Internal) — both the trigger (a finalised contract-item line creates folders) and the destination (each recurring occurrence becomes an invoice there).
• Item Maintenance — where a contract item is linked to its sales contract template. Miss this and the backend processor throws.
• Customer Maintenance — the party to the contract.
• Fixed Asset — a folder can carry a fixed-asset link.

Troubleshooting

Related documentation

• POS and Sales module
• Identity Verification and E-Signature — what the EKYC tab does, and what the product does not do about signing or credit checks
• Recurring Sales Invoice Applet