Document Generation is a tool that will help you generate various types of documents to support the booking process. An example of a document would be generating a Bill of Lading, or submission of Request of Transport.
Document generation consists of the following:
- HTML template
- Booking information and dynamic field values
- Running number set in basecompany settings
Prerequisites
Before you get started, it's important to set a running number for the type of document you plan to generate. If not, you might run into the following error when submitting a document:
The document being submitted above is an ROT type of document. And because a running number setting wasn't set in BaseCompany Settings, that error pops up. To fix this, set the following setting in BaseCompany Settings:
For the settings key, the third delimited value after the second colon is what determines what type of document this running number would relate to. In the example above, this running number relates to ROT documents. If you plan to generate any other kind of document, say a "RANDOM" document, then the settings key would be REF:DOCUMENT_GENERATOR:RANDOM.
The first settings "row" is where and how you define what your running number would look like. You can type in whatever text you like but the most important "text" you need to include is the running number text variable - the {{XXXX}}. Here's what all the text variables from the example mean:
| Text Variable | Description |
|---|---|
| {{YYYY}} | The current year represented in whole. If the current year is 2024, then 2024 will be substituted when generating the document's running number |
| {{MM}} | The current month represented in padded digits. If the current month is March, then 03 will be substituted |
| {{DD}} | The current day represented in padded digits. If the current day is 31, then 31 will be substituted |
| {{XXXX}} | The running number in padded digits. This increments every time documents are generated. For the very first document to be generated for a specific document type, 0001 will be substituted |
As for the second row, that needs to be there for legacy reasons.
Getting Started
To generate a document:
- Ensure you have the appropriate permissions under Manage > Permissions
- Go to Manage > Document Generator Templates
- Set a code and HTML template
- Visit any existing booking, scroll down to the Generated Documents section, click the plus icon, and choose the template you previously created
- Fill in any necessary dynamic fields present for the document
- Hit Submit
Pretty simple. But let's dive into some of the more crucial steps anyway.
Document Generator Templates
A Document Generator Template is what you use to base a document off of. The whole point of the Document Generator is to make generating documents easier. And templates is how you can achieve that.
First off, you need to give your template a code. A code is always saved in all uppercase but aside from that, it can be whatever you want. If you're planning to create a Request of Transport document, then ROT would be a good code for that - or you can just type in REQUEST OF TRANSPORT. Whichever way suits you.
Optionally, you can give your template a description. Describe your template so that someone else who wants to make use of it knows what they're using. But again, this is optional.
Next, the template itself: the core of Document Generator. A template is expected to be defined as HTML with Handlebars sprinkled in. If you don't know what those are, it's best you skip this section and ask someone else who's capable of creating a template for you.
For those familiar, a template is as described. You can utilize the full capabilities of HTML and Handlebars to create whatever kind of template that you want. There are also some special variables that you can utilize that are customized for ShipX's use case and not native to Handlebars. For example, auto-populated variables:
| Variable | Description |
|---|---|
| {{ $$documentNumber }} | A special variable that is substituted with the running number of a submitted document. |
More auto-populated variables might become available in the future but just remember that these special variables get their values not from user input but from ShipX itself. documentNumber, for example, is useful if you want to include the running number of the document in the template itself.
Finally, you need dynamic fields that map to the corresponding Handlebars variables that you set in the template. Here's an example:
In the template field, company is defined as a Handlebars variable. In order to give the variable a value, you need to define/map a field for it. The "Key" field is what's used to map a field to a variable. These must match.
Now, explaining how variables and fields play with each other is a complex topic itself, but not when you experiment around with it. Therefore, feel free to create a sample template and define and map variables and fields however you like. See how they interact.
The Helper section at the bottom contains helper components that can help make interacting with templates easier.
Preview is self-evident in how useful it is.Open up an existing template to see how it works.
TestData is useful for when you want to inject testData into the template for testing purposes, such as seeing how your template would react if an actual value is injected into it.
Generated Documents
Visit any booking and scroll down to the Generated Documents section. Here is where you generate documents.
After clicking the plus icon, you'll be greeted by a list of templates to base your document off of.
After choosing your template, you'll then be greeted by the document editor.
Starting from the top, you have the bookings section. Aside from the current booking you're creating the document for, you can associate other unrelated bookings with your document.
Down in the middle, you have the document previewer on the left and the dynamic field inputs on the right. The previewer allows you to preview your document as you make changes to it. The inputs allow you to define values for the variables that the template the document is based off of. For every change in value, the previewer refreshes with the new values you created.
At the bottom, you have the buttons:
Delete deletes your document by setting its status to VOID
Save allows you to save your changes manually in case your changes weren't automatically saved when you update the input fields.
Submit submits your document. This finalizes your document and prevents further editing. A document number will also be generated for your document.
And that's all there is to it to generate a document.
Documents Dashboard
Last but not least, there is the Documents Dashboard. You can visit the dashboard by hovering over the dashboards dropdown in ShipX's navigation bar and clicking on Documents.
The dashboard lists every document ever created for the Business Unit. You can view the document by clicking on its number in the NO column, the bookings its associated with in the booking no column, and the template it's based off of in the template column.