Setting up document templates (forms)

TrakIT makes its documents, such as delivery orders, invoices, quotations and receipt vouchers, from forms. A form is a page of HTML with codes in it. When a user generates a document, TrakIT replaces each code with the details of the work order, job, invoice or other record, and saves the result as a PDF. This guide takes a form from a blank page to the documents users generate from it. It is for system administrators: only they create and change forms.

The running example is a delivery order: a work order form for your import workflow, generated for the container ABCU1234560 of the job EXBL2610045. The same steps apply to the other kinds of form, with the differences noted.

The menus you see depend on your role and on how your company has set TrakIT up. The paths on this page are those of the standard menu; see Navigating TrakIT.

1. Choose the kind of form

The kind of form decides what it can show, where users generate it and how you make it available. It cannot be changed once the form is created. Each kind has its own tab on Admin > Form Definitions:

Tab	Makes documents about	Generated from	Made available by
For Work Orders	One work order.	The work order’s Forms tab, or a workflow action.	Is Global, or the workflow’s Forms tab.
For Jobs	A whole job, with a block repeated for each work order.	The Forms tab of any work order of the job.	Is Global, or the workflow’s Forms tab.
For Reports	The rows of an advanced report.	A report subscription.	Every active report form is offered.
For Finance	An invoice, debit note or credit note, another invoice document, a quotation, a receipt or payment voucher, or a bill: the form’s Sub Type.	The finance record.	The companies ticked on the form.
For Yard Ops	A yard move.	The Device app.	The form’s Yard and Move Type.

Email forms, the layout of the emails TrakIT sends, are kept by TrakIT Support. A company uses the one chosen as its Email Template (see Company).

2. Create the form

1. Select Admin > Form Definitions, then the tab of the kind of form, here For Work Orders.
2. Select Create.
3. Enter the Form Name, for example Delivery Order, and a Form Code, such as DO.
4. Fill in the other form fields the form needs.
5. Select Create.

The new form opens. It is A4, and its content is just its name as a heading. The settings that matter most:

• Orientation, Page Numbers and Margins lay out the page. Language is the language of the form’s headings and translated words.
• File Name Syntax names the PDF, for example [CODE]-[JOB]-[GENCOUNT].
• Work order and job forms: Prevent Re-generation allows one document per work order or job until it is cancelled; WO Data Ref. writes the form’s reference number into a data field; Default External Access makes the documents visible to external users, such as the customer, by default. A job form’s Entity Filter makes it a document for one entity of the job, such as one transporter.
• Finance forms: Sub Type says what the form is for. For invoices, debit notes and credit notes, Pro-forma/Final says whether it prints pro-formas, final documents or both. Message Template gives the body of the email sent with an invoice or quotation, and Require Live Signature makes the user sign the document before it is generated.
• Yard forms: the Yard, the Move Type and Auto-Generate.

To start from a form you already have, open it and select the plus icon (Clone Form). The copy keeps the content, header, footer and roles, but is not added to any workflow, and a finance form has no company ticked.

Who: system administrators create, clone and change forms. Viewing them needs View Form Definitions in the Form Definitions section.

3. Write the content with codes

1. On the form’s Form Preview tab, select Open Editor.
2. Write the HTML under HTML Code. Form Preview on the right shows the result as you type.
3. Select Save, then Close Editor.

TrakIT refuses HTML that is not well formed, and names the line. See The form editor.

The codes follow a few patterns:

Code	Gives
%%%0,COLUMN;	A header field of the work order, by its database column, such as BOLNUM (the job reference), CONTNUM (the container) or CONTCUSNAME (the customer’s name). See Form code reference.
%%%1,CODE;, %%%2,CODE;	The date of an event, or the value of a data field, by its code in the workflow. Add a format after |, for example %%%1,DEL|dd MMM yyyy;.
[ED:CODE:NAME]	The name of an event or data field in the workflow.
##NAME##	One value, such as ##REFNO## (the document’s unique reference number), ##DATE## or ##USERNAME##. Finance forms have their own, such as ##INVNUM##, and a table of the lines, such as ##INVTABLE##.
%%%LOOP; … %%%END;	In a job form, a block repeated for each work order of the job that is not cancelled.

These are the main ones: Form code reference lists them all, the form page’s Code reference lists the patterns, and the ? button (Code Reference) in the editor lists the codes of the kind of form, and of the sub type for a finance form, with an example of each.

For the delivery order, with DEL the code of the delivery event in your workflow:

<h1>Delivery Order</h1>
<p>Reference: ##REFNO## - Date: ##DATE##</p>
<table>
  <tr><td>Job</td><td>%%%0,BOLNUM;</td></tr>
  <tr><td>Customer</td><td>%%%0,CONTCUSNAME;</td></tr>
  <tr><td>Container</td><td>%%%0,CONTNUM;</td></tr>
  <tr><td>[ED:DEL:NAME]</td><td>%%%1,DEL|dd MMM yyyy;</td></tr>
</table>
<p>Issued by ##USERNAME##</p>

Generated for the work order of ABCU1234560, it shows EXBL2610045, Example Trading Co, the container number and the delivery date. A job form puts the work orders in a repeating block, and must give one element of the block the data-id ##WOID##, or TrakIT refuses to save it:

<table>
  %%%LOOP;
  <tr data-id="##WOID##"><td>##SERIAL##</td><td>%%%0,CONTNUM;</td><td>%%%0,WEIGHT|#,##0;</td></tr>
  %%%END;
</table>
<p>##NUMALL## containers, ##TOTALWEIGHT## kg</p>

Codes outside the block take the details of the job’s first work order.

4. Add the header and footer

The header and footer are printed at the top and bottom of every page. Use them for what is the same on every page, such as your letterhead and address, and keep the codes in the body of the form.

1. Open the form’s Header/Footer tab.
2. Write the HTML in Custom Header or Custom Footer, up to 1,000 characters each.
3. Enter its Height: in points, and select Update under it.

With Default Footer on and no custom footer, TrakIT prints its standard footer, which says who generated the document and when. A custom footer replaces it. Page numbers come from the form’s Page Numbers setting. See Header/Footer tab.

5. Test the form

Check the form in three steps, from layout to real data:

1. The layout. The Form Preview tab shows the content with the codes as written, and the header and footer in dashed boxes.
2. The PDF. In the editor, Test PDF saves the form and downloads it as a PDF, with its margins, header, footer and page numbers. The codes are not filled in, and the test does not count as a generation. See Test PDF.
3. Real data. Make the form available (step 6), then open the record without generating:
   • a work order or job form: on a work order of the workflow, open the Forms tab and choose the form. The preview shows it filled in with that work order’s details. No document is made until you select Generate.
   • a finance form: open the Generate popup of a record of the company, for example Approve on a draft invoice, and choose the form. The preview shows the document with the number it will get. Close the popup without selecting Generate.

While you test, you can keep a work order or job form away from users: add it only to a workflow used for tests, or tick on its User Access tab only a role your users do not hold. System administrators can always generate it.

In the result, look for:

• a code printed as it is, for example without its closing ;: it is not written correctly;
• an empty value: the record has no value yet, the code of the event or data field is not in the workflow, or a code names a database column that does not exist. A code takes a column’s name only, not a calculation.

6. Choose who uses the form

Work order and job forms. Turn on Is Global to offer the form in every workflow. Otherwise, on each workflow’s Forms tab, select Add New, choose the form and set:

• Requires: a header field, event or data field that must be filled in before the form can be generated, such as the transporter for a delivery order.
• Trigger Event Code: an event TrakIT records on the work order when the form is generated.
• Do Not Attach To Work Order, Allow Deletion From Work Order and Services.

A new form is open to every role. To limit it, tick the roles on its User Access tab. A job form can also lay out the status emails sent to the job’s customer: choose it as the workflow’s Status Email Template in Workflow settings.

Finance forms. On the form’s User Access tab, tick the companies under Select Companies and select Update. A new finance form has no company ticked, so it is offered nowhere until you do. Users choose among the active forms of the company with the right sub type each time they generate a document, so the company needs at least one form of each sub type it prints: invoice, credit note, quotation, voucher, bill.

Report forms are offered in every report subscription. Yard forms are offered for their yard and move types.

To stop using a form, turn off Active in Modify. A form that is in use, for example one that documents were generated from, cannot be deleted.

7. Generate documents

Document	Users generate it from	The PDF is kept on
Work order form	The work order’s Forms tab: Generate or Generate & Email.	The work order’s documents.
Job form	The Forms tab of any work order of the job. With an Entity Filter, the user chooses the entity under Filter.	The job’s documents.
Quotation	Generate on an approved quotation.	The quotation’s Documents tab.
Invoice, debit note, credit note	Pro-Forma, Approve, Generate Doc and Reverse Invoice on the invoice.	The invoice’s Files tab.
Receipt or payment voucher	Generate Voucher on an approved receipt or payment.	Its Documents tab.
Bill	Generate PDF on a validated bill.	The bill’s Files tab.
Yard document	On the Device app, the Forms list of a saved move, or automatically when the move is carried out, with Auto-Generate.	The move’s Files tab.
Report	A report subscription of the type Form Template PDF or Plain Text (TXT).	Sent by the subscription, by email, FTP or Web API.

A work order or job form is not attached when the workflow sets Do Not Attach To Work Order: it downloads instead. A workflow can also send work order forms on its own: an event or data field action of the type Send Email, with the content Form PDF, generates the form each time the action runs and emails it, and Attach Document to WO keeps a copy.

Each generated work order and job form is listed on Admin > Logs > Form History, with the reference number it printed with ##REFNO##. Documents already generated keep their PDF when you change the form later.

Who: generating a work order or job form needs Generate Form in the Work Orders section, and one of the form’s roles. The finance pages need their own permissions, such as Generate in the Quotations section or Approve in the Invoices section.

When a form does not appear

What you see	Why, and what to do
The form is not in Select Form on the work order	It is not active, not global and not added to the workflow, limited to services the work order does not have, or limited to roles the user does not hold. Or the user’s role lacks Generate Form.
This form requires … to be completed	The form’s Requires on the workflow’s Forms tab: fill in that field on the work order.
The finance form is not in Select Template	Its company is not ticked, it is not active, or its sub type or Pro-forma/Final setting is for another kind of document.
No ##WOID## attribute found. when saving a job form	Give an element of the repeating block the data-id ##WOID##.
Cannot delete Form in use	Turn off Active instead.