Package Labels#

Overview#

The Label Interface – LIF functionality provides a way for you to transmit data structures that store item-related information supplied by Microsoft Dynamics 365 Business Central¹ to a label design and print program.

After the structures are imported to the third-party solution, they’re used to fill in graphical templates set up there so that you can create (and print) a variety of package labels at any time. The interface can be connected to the following programs:

• Loftware NiceLabel³ Cloud (Business edition or higher)
• Loftware NiceLabel³ On-Premises (LMS Enterprise edition or higher)
• Seagull Scientific BarTender² (Automation edition or higher)

Interface basics#

Two key components help integrate the interface with the standard app:

Label Designer

• NiceLabel³ Designer – Pro
• BarTender² Designer

Automation / Integration Builder

• NiceLabel³ Automation Builder – Pro
• NiceLabel³ Automation Builder
• BarTender² Integration Builder

The design component is used to customize label templates and layouts. The builder, on the other hand, helps those working with the functionality to create an automated printing process. This includes everything from setting a trigger (to import data) and opening a template to assigning variables and selecting a print option to feeding back values to the source system.

For a more detailed explanation of these processes, see the NiceLabel3 Cloud Setup, NiceLabel3 On-Premises Setup, and BarTender2 Setup.

Interface options#

The functionality comes with an array of tables, pages, and actions. Above all, however, it provides the configurations needed for multiple printing scenarios. You can choose between the following interface options:

• KUMAVISION Label Interface – NiceLabel³ Cloud
• KUMAVISION Label Interface – NiceLabel³ On-Premises Web Service
• KUMAVISION Label Interface – BarTender² Web Service

Another component—called KUMAVISION Label Interface File Extension—can be used to export files via on-premises solutions. As file access is restricted in SaaS environments, a separate app had to be developed for this purpose.

General setup#

You must set up the label interface before you can transmit information to an external program. You can also set up additional features during this process.

Activate the interface#

To turn on the interface:

1. Choose the Search icon, enter KUMAVISION Module Setup, and then choose the related link.
2. On the Settings FastTab, turn on the Label Interface toggle.

Label position codes#

The data structures transmitted to third-party software programs contain a list of values, each coupled with an identifier. These identifiers are the same on all labels, regardless of what the labels will be used for. To set up a value:

1. Choose the Search icon, enter Label Position Code List, and then choose the related link.
2. Fill in the fields as described in the following table.

Label Interface Setup#

To configure the label interface:

1. Choose the Search icon, enter Label Interface Setup, and then choose the related link.
2. Fill in the fields as described in the following table.

General#

File Export#

Available after installing the KUMAVISION Label Interface File Extension app.

Label Printers#

To set up a device for printing labels:

1. Choose the Search icon, enter Label Interface Setup, and then choose the related link.
2. On the ribbon, choose Label Printer.
3. Fill in the fields as described in the following table.

One printer can be stored per label code and ID. This is to ensure that external programs transmit the data stored in label structures to the correct printers. A printer can be assigned in the following ways:

1. To a certain label code and user.
2. To a certain label code and all users (that is, the User ID field is blank).
3. To all codes (that is, the Label Code field is blank) but only one user.
4. To all codes and users (Label Code and User ID fields are both empty).

Pictographs (Legacy)#

By using pictographs, you can assign symbols to labels in Microsoft Dynamics 365 Business Central¹. No longer supported by NiceLabel³ Cloud and BarTender² Web Service, the feature remains for legacy reasons.

Instead, pictographs should now be added through external sources. By using parameters (such as "PAR_*“ codes specified on the Label Position Code List page) and a certain function, however, you can still choose whether to show a symbol on a certain label.

Label structures#

Label structures are representations of the core information used for labeling. Within a structure, you can assign position codes to Microsoft Dynamics 365 Business Central¹ records and fields. The lines of the structure specify the data that you want to show on a label and where this information comes from. The structures can be used for multiple items (none are related to a specific item).

To set up a structure:

1. Choose the Search icon, enter Label Structure List, and then choose the related link.
2. On the ribbon, choose New.
3. Fill in the fields as described in the following table.

Label structure lines#

The structure lines represent the individual positions that should be printed on the label.

Source type-subtype combinations#

The following table shows the subtypes that you can add to a source type and what will happen if you do (=source value).

Copy structure (action)#

Copies an existing label structure. To use this function:

1. On the Label Structure List page, choose New.
2. On the ribbon, choose Copy Structure.
3. In the Copy from Label Code field, specify the code of the structure that you want to copy lines from.
4. Turn on the Copy Incl. Values toggle if also want to copy manual source values (source type Text or source type Pictograph in combination with subtype Path). If you leave the toggle turned off, their source values will be blank, and you need to fill them in again.
5. Choose OK to copy the lines from the selected structure to the new one.

Label structure versions#

You can create versions of a label structure if you want to use some version of the structure to start being valid on a specified date. To set up this feature:

1. Choose the Search icon, enter Label Structure List, and then choose the related link.
2. Open a label structure.
3. In the Version Nos. field, enter a number series that will be used for the versions of this structure.

You can then see the current structure version in the Active Version field. Data copied from previous, expired versions remains available as well.

The system identifies the active structure version by looking for one where the work date is within the period specified in the Starting Date and Ending Date fields. If this results in more than one search hit, the version with the highest number will be used as the active version.

Create a new version#

To create a new version of a label structure:

1. Choose the Search icon, enter Label Structure List, and then choose the related link.
2. Open a label structure.
3. On the ribbon, choose Versions and then choose New.
4. With the Version Nos. field filled in, you can exit the No. field to have a number assigned automatically. If the Version Nos. field hasn’t been filled in on the structure card, you need to enter a number manually.
5. The work date is then automatically suggested in the Starting Date field. However, you can specify another date if needed.

You can now enter data on the lines manually or choose Copy Structure on the ribbon to copy lines from an existing structure or version.

Version Matrix (action)#

Compares structure versions on a matrix. You can specify filters here before you choose Show Matrix on the ribbon.

Change Log (action)#

Shows changes to a label structure if structures and versions are tracked. This action extends the standard change log functionality. To include label structures on logs, you must add the following tables in Change Log Setup:

• Table 5488108 - KVSKBALabelStructureHeader
• Table 5488109 - KVSKBALabelStructureLine
• Table 5488116 - KVSKBALabelStructureVersion

For more information about tracking changes, see Auditing changes.

Item-Label Relations#

Label structures essentially tell another program where to print lines (position codes) on a label and how to calculate values for them.

All structures are universally valid so that they can be used for multiple items. To assign a structure to an item, choose Item-Label Relations on the ribbon of the relevant structure, item, or item variant.

The Item-Label Relations page stores the links between items and structures, as well as their units of measure, language codes, and customers or vendors. These values are then used to find a label structure or create a new label.

For example, by specifying a unit of measure and a customer number, you can create an OEM label for a certain customer as described in the following table.

Overpack quantities#

The Overpack Quantity field is used when the Print at Receipt toggle is turned on and the No. of Copies Position Code field in Label Interface Setup is blank. When both conditions are met, the number of copies is calculated as follows:

Non-tracked and tracked items

Label contents and preview#

For the most part, labels are created automatically in Microsoft Dynamics 365 Business Central¹ before they’re copied to a third-party solution.

After the labels have been imported, the external program creates the relevant information and sends it to the selected printer. Manual intervention shouldn’t be necessary in this context.

However, to track the generation of label contents in Microsoft Dynamics 365 Business Central¹ and preview labels for revisions, you can choose Show Label Contents on the ribbon of a label structure or the Item-Label Relations page.

When you run this function from the Item-Label Relations page, data is filtered for the selected relations. If you run it from a structure, you can only filter for a label code.

On the Label Contents page, you can fill in values on the header, for example, a serial number or an expiration date. You can also enter other information to see how specific label positions are calculated.

The fields in the following table must be filled in as described:

You can also enter something in other fields if necessary:

Calculate Contents (Action)#

Starts in Microsoft Dynamics 365 Business Central¹ the process of calculating line values based on the specified label structure.

Preview Label (Action)#

Provides an online preview of labels created in NiceLabel³ Cloud or BarTender² Web Service.

For this purpose, the label design and print program will simulate the standard printing process, store the results as a PDF file, and send the PDF to Microsoft Dynamics 365 Business Central¹.

After you run the Preview Label action, the label is shown on the Preview Label FastTab.

Create Structure File (Action)#

Creates a file that contains all codes and sample values assigned to positions on a label, as a basis for designing new data structures.

After the structure is created, it is stored in the standard Download folder. The file name shows the label code, the ID of the user who created the file, and the date and time of creation.

If you’re using KUMAVISION Label Interface – NiceLabel³ Cloud or BarTender² Web Service, the file extension will be JSON. If you’re using the KUMAVISION Label Interface – NiceLabel³ On-Premises Web Service, the structure will be in the XML format. File contents are arranged in the same way as in the file sent to the label design and print program.

Create a Label (Manually)#

After the label information has been determined for a specific item, label data can be created and transmitted by choosing Create Label File. This will create a file manually.

Create a label (automatically)#

Warehouse receipt#

If the Print at Receipt checkbox is selected on the Item-Label Relations page, labels will automatically be created for items when you post their receipt at a warehouse.

As an example, you created and ordered in advance multiple items, which are now being received.

You then post their receipt so that a label is created and copied automatically to the relevant label design and print program. The PDF file generated for the label will be three pages long, with each page showing one of the three items listed in the Qty. Received field on the receipt.

NiceLabel³ On-Premises#

Required version or edition#

The NiceLabel³ Web Service requires the Loftware NiceLabel³ On-Premises LMS Enterprise edition or higher.

NiceLabel³ On-Premises Setup#

Label Interface Setup#

On this page, you need to select KUMAVISION Label Interface – NiceLabel³ On-Premises Web Service in the Output Interface field.

Everything else can be configured in the same way as for the default interface.

Label structure#

To transmit data to NiceLabel³ On-Premises through a web service call, you need to fill in the NiceLabel³ On-Premises Web Service URL field in the label structure.

Using NiceLabel³ On-Premise#

You can take the following steps to integrate Loftware NiceLabel³ On-Premises with your Microsoft Dynamics 365 Business Central¹ environment.

NiceLabel³ Automation Builder#

With the help of filters and triggers provided by NiceLabel³ Automation Builder, you can set up print scenarios based on data provided by Microsoft Dynamics 365 Business Central¹.

XML Data Filter#

Because data is transferred to NiceLabel³ On-Premises in the XML format, you need an XML filter. Add this filter, and a name, to a new data structure. On the ribbon, choose Import Data Structure to import a structure file from Microsoft Dynamics 365 Business Central¹. For more information on how to generate the file, see Create Structure File.

To use XML nodes as variables, you can then set the Usage property of every element in the structure to Variable Value.

Create a trigger#

Afterward, create a unique trigger that contains the processes that you want to run. Go to the Configuration Items tab, choose Add, and then choose Web Service.

Give the trigger a unique name and assign a port for communication with the web service. The port will be part of the web service URL and will be linked to the label structure in Microsoft Dynamics 365 Business Central¹.

Typically, the label design program is set up in a way so that variables will be read off the labels. Since label integration in this scenario occurs throughout the system and the labels used are transmitted as parameters of a structure, you need to set up integration variables manually by choosing Add > Variable on the Variables tab.

To respond to preview or printout requests sent from Microsoft Dynamics 365 Business Central¹, you must also add the ResponseData variable. This variable will later be used to return values to the app.

Use Data Filter#

Now, assign the NiceLabel³ parameters to the specified variables by adding the Use Data Filter function to the Actions tab.

Afterward, enter the XML structure as a name on the Filter tab. If the names of the XML variables match the position codes set up in Microsoft Dynamics 365 Business Central¹, choose Auto Map on the Data Mapping tab.

The information stored in the data structure is then assigned to each variable by the system. If names are different, you must create mappings manually.

Open Label#

Open the relevant label. As the label name is stored on a data structure line in Microsoft Dynamics 365 Business Central¹, you can again use a variable to get the name. Add the Open Label action, select the Data Source checkbox on the Settings tab, and fill in the Label Name field.

Preview: Print to PDF#

To save print information as a PDF file so that you can preview the label, add the Redirect Printing to PDF action, enter a file name, and select the Overwrite File checkbox.

Because this action should only be performed for previewing a label, go to the Show Execution and Error Handling Options tab and add the condition that for this function to work, the PreviewFormat variable must be set to True.

Print Label#

Afterward, add the Print Label action and specify that the number of labels to print (=No. of Copies) will be sourced from a variable.

Preview: Read data from file#

For previews, the contents of the PDF file must then be read and copied to the ResponseData variable. Add the Read Data from File action. In the properties, set the File Name as explained under Preview: Print to PDF and enter 20 as the Number of Retries.

Because, again, this action should only be performed for label previews, add on the Show Execution and Error Handling Options tab the condition that for this function to work, the PreviewFormat variable must be set to True.

Preview: Set ResponseType PDF#

Because the return value for a preview consists of a PDF document, you also need to convert the ResponseType. For this purpose, add another action that sets the variable to application/pdf in the case of previews.

NiceLabel³ Cloud#

Required version or edition#

The NiceLabel³ Cloud interface requires NiceLabel³ Cloud Business edition or higher.

NiceLabel³ Cloud setup#

NiceLabel³ Cloud APIs Using NiceLabel³ Cloud APIs#

Before you can use NiceLabel³ APIs, you need to log on to the API Developer Portal, create a subscription, and link the subscription to your Control Center. For more information, see Cloud Integrations – NiceLabel3 Help Center page.

Label Interface Setup#

On this page, you must select KUMAVISION Label Interface – NiceLabel³ Cloud Web Service in the Output Interface field and enter an API subscription key.

Everything else can be set up in the same way as for the default interface.

Label printers#

With NiceLabel³ Cloud, you can store what is known as cloud printers. As they aren’t connected to Microsoft Dynamics 365 Business Central¹, they cannot be selected in the app.

To add them, you need to retrieve printer information through the API from the NiceLabel³ Cloud by choosing NiceLabel³ Printer on the ribbon.

You can then choose Update Printer List to connect to the API and get the list of cloud printers stored online.

Label structure#

With NiceLabel³ Cloud, you can set up automated workflows to specify labeling actions and processes. You can also create a single workflow for use in every print scenario by assigning a variety of variables to the parameters available in the NiceLabel³ Automation Builder.

Automated workflows can be identified by their trigger IDs. To send label data structures from Microsoft Dynamics 365 Business Central¹ to the right triggers, you need to store a NiceLabel³ Cloud API identifier for each of them.

The content of this field must match the name of the trigger specified in the NiceLabel³ Control Center.

Use NiceLabel³ Cloud#

You can take the following steps to integrate Loftware NiceLabel³ Cloud with your Microsoft Dynamics 365 Business Central¹ environment.

NiceLabel³ Automation Builder#

With the help of filters and triggers provided by NiceLabel³ Automation Builder, you can set up print scenarios based on data provided by Microsoft Dynamics 365 Business Central¹.

Json data filter#

Because data is transferred to NiceLabel³ Cloud in the JSON format, you need a JSON filter. Add this filter, and a name, to a new data structure. On the ribbon, choose Import Data Structure to import a structure file from Microsoft Dynamics 365 Business Central¹. For more information on how to generate the file, see Create Structure File.

To use JSON parameters as variables, you can then set the Usage property of every element in the structure to Variable Value.

Create a trigger#

Afterward, create a unique trigger that contains the processes that you want to run. On the Configuration Items tab, choose Add, and then choose Cloud.

Give the trigger a unique name and a unique ID. This ID will be used to trigger cloud services and will be linked to the label structure in Microsoft Dynamics 365 Business Central¹.

Typically, the label design program is set up in a way so that variables will be read off the labels. Since label integration in this scenario occurs throughout the system and the labels used are transmitted as parameters of a structure, you need to set up integration variables manually by choosing Add > Variable on the Variables tab.

To respond to preview or printout requests sent from Microsoft Dynamics 365 Business Central¹, you must also add the ResponseData and ResponseType variables. These will later be used to return values to the app.

Use Data Filter#

Now, assign the NiceLabel³ parameters to the specified variables by adding the Use Data Filter function to the Actions tab.

Afterward, enter the JSON structure as a name on the Filter tab. If the names of the JSON variables match the position codes set up in Microsoft Dynamics 365 Business Central¹, choose Auto Map on the Data Mapping tab.

The information stored in the data structure is then assigned to each variable by the system. If names are different, you must create mappings manually.

Open Label#

Open the relevant label. As the label name is stored on a data structure line in Microsoft Dynamics 365 Business Central¹, you can again use a variable to get the name. Add the Open Label action, select the Data Source checkbox on the Settings tab, and fill in the Label Name field.

Initialize ResponseType variable#

Set the ResponseType to application/json. Add the Set Variable action, enter ResponseType in the Name field, and select the application/json value.

Initialize ResponseData variable#

The ResponseData variable, on the other hand, must be “{}.” For this purpose, add the Set Variable action, enter ResponseData in the Name field, and enter {}.

Preview: Print to PDF#

To save print information as a PDF file so that you can preview the label, add the Redirect Printing to PDF action, enter a file name, and select the Overwrite File checkbox.

Because this action should only be performed for previewing a label, go to the Show Execution and Error Handling Options tab and add the condition that for this function to work, the PreviewFormat variable must be set to True.

Print label#

Afterward, add the Print Label action and specify that the number of labels to print (=No. of Copies) will be sourced from a variable.

Preview: Read data from file#

For previews, the contents of the PDF file must then be read and copied to the ResponseData variable. Add the Read Data from File action. In the properties, set the File Name as explained under Preview: Print to PDF and enter 20 as the Number of Retries.

Because, again, this action should only be performed for label previews, add on the Show Execution and Error Handling Options tab the condition that for this function to work, the PreviewFormat variable must be set to True.

Preview: Set ResponseType PDF#

Because the return value for a preview consists of a PDF document, you also need to convert the ResponseType. For this purpose, add another action that sets the variable to application/pdf in the case of previews.

Set ResponseType and ResponseData#

As a last step, open the trigger settings. On the Communications tab, enter ResponseType in the Response Type and [ResponseData] in the Response Data field for use by the cloud trigger.

Seagull Scientific BarTender²#

Required version or edition#

BarTender² Web Service requires the Seagull Scientific BarTender² Automation edition or higher.

BarTender² setup{ #additional-bartender-setup }#

Label Interface Setup#

On this page, you must select KUMAVISION Label Interface – BarTender² Web Service in the Output Interface field.

Everything else can be set up in the same way as for the default interface.

Label structure#

To transmit data to BarTender² through web service requests, you also need to fill in the following fields on label structure headers:

Use BarTender²#

You can take the following steps to integrate Seagull Scientific BarTender² with your Microsoft Dynamics 365 Business Central¹ environment.

BarTender² Integration Builder#

With the Integration Builder, you can create and manage print scenarios.

When you set up a new scenario, you can also select the trigger that you want to use for interfacing with Microsoft Dynamics 365 Business Central¹. Choose Web Service.

Service#

The name of the scenario will match the name of the web service. However, if necessary, you can change the name on the Integration tab.

Input data#

On the Input Data tab, set the input format to JSON Variables and choose New Sample to select the structure file that you created in Microsoft Dynamics 365 Business Central¹. For more information on how to generate the file, see Create Structure File.

This will transfer the values of the variables set up in Microsoft Dynamics 365 Business Central¹ to BarTender² as sample data.

Response#

On the Response tab, select the format and the content that you want returned to Microsoft Dynamics 365 Business Central¹.

As an encoded PDF stream is required to preview labels, the response by the app should be copied to a new variable to ensure that this value is filled in by an independent action.

Variables#

On the Variables tab, you can change default variables used in print scenarios or add new variables. As neither action is required in this case, you don’t need to change anything here for now.

Actions#

On the Actions tab, you can store various steps that make up something of a workflow. The program will follow each step as data is received. The actions have been classified as follows:

• Print
• Transform
• Input
• Output
• Execute
• File
• Database

Each action also comes with a subset of steps that can be linked together as needed. For more information, see the BarTender²documentation.

Sample task#

Have the label design and print program save label data received for preview as a PDF file before transmitting the information to Microsoft Dynamics 365 Business Central¹ in a response stream.

If the data isn’t meant for preview, however, have the program print the label information by using the printer specified in the associated data structure.

Solution#

1. Print or preview
   First, add a Select Case action to perform a check if the action that triggered the printing process is used when previewing labels (that is, if the PreviewFormat variable linked to the action has been set to True). Specify that the next steps in the process will be different for previews and printouts.

2. Preview
   Assuming the ETI_DOCUMENT variable will be used to transfer data from Microsoft Dynamics 365 Business Central¹ label structures, the document that you want to open must now be linked to the variable.
   
   The use of this method will reduce the number of printing scenarios needed, as the data structures already designate the relevant labels.
   
   Regarding print options, specify that print data should be saved to a PDF and enter the path to the directory where you want to store the file. Afterward, choose Named Data Sources to assign the variables that you want to add to data sources in the Label Designer.
   
   As a next step, you need to store the PDF file in Base64 format in a variable (to allow a response by the label interface). Add the PowerShell Command action, select Embedded Commands for the Source property, and enter the following:
   
   [convert]::ToBase64String((Get-Content -path < file name from extended print options > -Encoding byte))
   
   Afterward, enter the variable that you set up under Response in the Send Command Output and Errors to Variable field.

3. No preview = print
   For a label to be printed instead, add the Print Document action. The look of the label remains because the layout is specified by the label structure stored in Microsoft Dynamics 365 Business Central¹.
   
   As for print options, you can use variables to specify the printer you want to use and the number of labels you want printed based on the label structure created in Microsoft Dynamics 365 Business Central¹. Variables are specified in BarTender² via %< name of variable >% (for example, %TYPE_NO% or %ETI_PRINTER%).
   
   As a last step, choose Named Data Sources to assign the variables you want transmitted from the relevant print scenario to the named data sources used in the Label Designer.