Printing and Paperwork

Despatch Note Keys

As part of the pack and despatch process, customer paperwork invariably needs to be generated to be included with the outgoing shipment. This paperwork is typically referred to as the 'despatch note', and sometimes as the 'customer invoice'.

OrderFlow provides a report-based mechanism for implementing this, which is discussed in a lot more detail in the Despatch Note chapter of the OrderFlow Report Writers' Guide.

Once the despatch note has been implemented and added to the appropriate instance of OrderFlow, there needs to be a mechanism by which the despatch note is associated with a shipment, so that when the packer clicks on the Print Despatch Note button, the correct paperwork comes out the printer.

The association of the shipment with the appropriate paper at this point in the process is done through another Groovy script, called the despatch note keys script. The despatch note keys script applies logic to determine which report key, or set of compound report keys, need to apply for the output of the appropriate despatch note content.

The content of the despatch note keys script, once written, is applied to application property called despatch.note.keys.

Examples

The simplest despatch note keys script simply returns a single literal value:

mydespatchnote

Technically, this is not even a script, but a single literal value. The scripted equivalent of the above is:

return 'mydespatchnote'

In both cases, the script assumes that there is a despatch note report with the identifier or key 'mydespatchnote'.

The non-trivial but still very simple implementation might involve the case where more than one brand is sold through a single sales channel, and each of these brands requires its own despatch note. An example is shown below:

def shipment = value;
def order = shipment.orderItem;
def brand = order.brand;

if (brand == 'coolshades') {
    return 'coolshades_despatchnote';
} else if (brand == 'classyeyeware') {
    return 'classyeyeware_despatchnote';
}
throw new UnsupportedOperationException('Despatch note printing not supported for unknown brand ' + brand);

Scripting Context

The key input in the scripting context is the shipment, which can be accessed in the script using the value variable. As the above example shows, the order can easily be navigated, and using other properties in the OrderFlow data model, so can the order line data.

The return value for the despatch note keys script will always be a text string, which will identify the required report key(s).

Applying the Script

The script can be applied by updating the application property despatch.note.keys. Note that this property is scoped, which means that different values can be set up for different organisations, channels and sites. The script associated with the same scope as that of the shipment will be used when selecting the correct instance of the script to apply.

Scripts with subreports

The despatch note keys script can be set up to return a compound report key, which can be used for despatch notes with compound reports which may contain separate subreports for embedded courier or return labels, return forms or other bespoke elements.

An example of a returned value in this scenario may be:

return 
'masterreport,despatch_note=despatchnote_report,courier_label=generic_label,return_form=basic_return_form_report'

In the case above, the following reports are used:

Compound Reports

Report Key	Decription
masterreport	The master report, used as a container for the contained subreports
despatchnote_report	The report key associated with the 'despatch_note' subreport parameter in the master report
generic_label	The report key associated with the 'courier_label' subreport parameter in the 'despatch_note' report
basic_return_form_report	The report key associated with the 'return_form' subreport parameter in the master report

As the above example indicates, it is possible to have subreports that container other subreports, at the cost of some extra complexity in the configuration and maintenance of these reports.

See the Despatch Note section of the OrderFlow Report Writers Guide for more details on how subreports are set up in OrderFlow despatch notes.

Dealing with Courier Label Subreports

When integratied stationery is used for courier labels, then one of the subreports described in the previous section will often be for a courier label. The problem here is that the identity of the courier label report will often depend on the courier selected, which in turn means that the despatch.note.keys script gets 'polluted' with courier-specific logic.

From OrderFlow 3.7.4 for this can be addressed by using the placeholder [courier_label] in the despatch.note.keys script, instead of the courier-specific value, as shown in the example below.

return 'masterreport,despatch_note=despatchnote_report,courier_label=[courier_label],return_form=basic_return_form_report'

Setting up the actual courier label to be used can now be done using the courier configuration, from the Setup -> Courier menu.

For this, there are two ways that the courier label subreport key can be identified, described in the next sections.

Note that if the despatch.note.keys has a [courier_label] placeholder, the system will raise an error if neither of the mechanisms described below is able to resolve the courier label report key to use.

Using a Courier Service Value

If courier service entries are present, then the 'Label Report Key' property can be used to identify the report for the courier label. This is done on a per service basis. Note that the present in this field must be a specific or 'literal' value, rather than a scripted value.

Service Label Report Key

Using a Script Value at the Courier Level

If no courier service value can be found using the mechanism just described, the system will use the scripted value set at the Courier level using the 'Label Report Key Script' property, and example of which is shown below.

Label Report Key Script

The courier level mechanism is suitable if individual service entries have not been set for the courier, or if it is easier to specify the values to be used at the courier level. An example of where this might occur is if only a single label report key needs to be used for all services.

Note that scripting context binds the shipment to the variable value. In the example script, the expression value.deliveryMethod.serviceCode returns the value of shipment's service code.

Unit Testing

A Note on Unit Testing

This section requires the that you have in place the OrderFlow integration and scripting environment. If you are interested in having this set up in your environment to enable you to write your own unit tests, please contact the Realtime Despatch support team.

An example unit test for an earlier example is shown below:

public class BrandDespatchNoteSelectionScriptTest extends BaseDespatchNoteSelectionScriptTest {

    protected String getCondition() {
        return ClasspathResourceUtils.readClassPathResource("rtd.orderflow.paperwork", "brand.despatch.note.script");
    }

    public void testBrand() {
        orderItem.setBrand("classyeyeware");
        assertEquals("classyeyeware_despatchnote", runScript());

        orderItem.setBrand("coolshades");
        assertEquals("coolshades_despatchnote", runScript());

        orderItem.setBrand("unknownspecs");
        try {
        runScript();
        fail();
        } catch (UnsupportedOperationException e) {
        assertEquals("Despatch note printing not supported for unknown brand: unknownspecs.", e.getMessage());
        }
    }
}

Note the following points on this unit test:

the script file itself is located in a file called brand.despatch.note.script in the package rtd.orderflow.paperwork.
the test class extends BaseDespatchNoteSelectionScriptTest, which defines a runScript() method, which deals with setting up the scripting context.
the test methods(s) modify the orders and shipments as required. The assertions then verify that the script returns the expected report keys value.
if an exception is thrown during script execution, this can also be tested, as shown in the example above.

Printing and Paperwork