Actions are an essential part of automated labeling solutions. Each action performs a predefined command (or a series of commands) when a defined event happens.
Desktop Designer includes a wide range of actions. Their purpose is to eliminate the need to start the solution programming from scratch.
Manage actions using the Action Editor dialog box.
Basic Action concepts and properties are described below.
-
Available Actions: the range of actions that are included in Desktop Designer. These actions are grouped into functional sets.
-
Defining actions: an action is defined in Actions Editor by clicking the appropriate action icon in Add ribbon group. The main ribbon contains commonly used actions and – later – the actions you define as common actions. To see all available actions, click All Actions.
-
Nested Actions: actions that cannot be used on their own. Their specific characteristics require them to be nested within another action. Use buttons in Action Order ribbon group to change action placement. Each action is identified with an ID number that indicates its position in the list, including its nesting. This ID number is displayed in the potential error message so you can find the problematic action faster.
Print Label action is an example of such action. This action is nested under the Open Label action, so it references the exact label to be printed.
-
Action Execution: listed (active) actions are executed once per event. The order of actions is crucial – the execution begins at the top and moves toward bottom of the list.
-
Conditional Actions: conditional actions only run when the provided conditions allow them to be run. Condition is defined with a single line VBScript Expression or Python script.
-
Errors in Actions: if an action is not configured completely, it is marked with a red exclamation icon. Such action can be included in the event list but cannot be executed.
Note
If one of the nested actions reports an error, all parent actions are also colored red. This serves as an indication for a nested action error.
-
Disabling Actions: prevents an action from being executed. By default, each added action is enabled. Actions that are not needed, can be disabled and still kept in the configuration. The shortcut to action enabling & disabling is the checkbox in front of the action name on the list of defined actions.
-
Copying Actions: any action may be copied and pasted. Use standard Windows keyboard shortcuts, or right-click the action.
Actions Editor is a dialog for managing actions in a Desktop Designer solution.
Actions can be defined for:
-
Form: these actions are triggered with form events. They are applicable to the following events:
-
On form load: action(s) are run after a form is loaded.
-
On form close: action(s) are run after a form is closed.
-
On form timer: action(s) are run after a specified time interval.
-
On Form Inactivity: action(s) are run after the form has been inactive for a given time interval.
-
-
Form object: these actions are triggered with object-related events.
-
Variable: these actions are triggered according to the received values.
Actions Editor Dialog ribbon includes commands for adding, removing and ordering the actions. It also provides a direct access to frequently used actions.
Clipboard group icons activate the following actions:
-
Paste: pastes the clipboard data.
-
Cut: cuts the selection to the clipboard.
-
Copy: copies the selection to the clipboard.
-
Delete: deletes the selected items.
Undo & Redo group allows undoing or repeating actions.
-
Undo: Desktop Designer allows the user to undo the entire sequence of actions since opening the editor.
-
Redo: repeats the requested range of actions.
Action Order group defines the action execution order of selected actions.
-
Up and Down: arrows place the selected action in front or after any other existing action.
-
Right: arrow nests the selected action under the previous existing action.
Note
Nested action is any action that starts when the parent action is already in progress.
-
Left: arrow makes a nested action independent of the preceding action.
Note
Certain actions cannot exits independently. If such action is added to the action list, a warning appears. The warning defines which action should it be nested under.
Add assigns actions to the selected form object.
-
All actions button gives access to the entire range of Desktop Designer actions. Recently used actions are listed on the top. Use Search... field to quickly locate any action by entering its name.
-
Four buttons give direct access to the most commonly used actions:
-
Open Label: button adds the Open Label action to the event list.
-
Print Label: button adds the Print Label action to the event list.
-
Set Printer: button adds the Set Printer action to the event list.
-
Quit: button adds the Quit action to the event list.
-
Actions Explorer is a tool for adding, removing and ordering the assigned actions. Use ribbon commands to manipulate with existing actions or to add new actions.
The explorer columns provide instant overview of actions' execution options and their descriptions.
-
Enabled: enables or disables the included action.
-
Condition: display the condition for executing an action (if set).
-
Description: displays the information about an action as defined by the user.
Actions Explorer enables you to make a selection of multiple actions, and to perform copy, paste and delete operations with them. To make a selection, Use Ctrl/Shift + Click on the required actions.
Note
Multiple actions can only be selected under the same parent action, i.e. all selected actions must be on the same level. See picture below.
Editing field allows editing the advanced action properties.
-
Main properties of the selected action are available for editing on the top of the Main/editing field. Main properties differ with each action – read the dedicated action description sections for details.
-
About group allows you to describe all NiceLabel 10 actions.
-
Name: by default, action name is defined by its type and is therefore not unique. Define a custom name to make it instantly recognizable among other actions, in logs and in potential error messages.
-
Description: user notes for the selected action. Description is displayed in actions explorer.
-
Action Type: read-only field which displays the type of action.
Note
When upgrading from legacy solutions (created with NiceLabel V6 and back), update the action names based on the currently selected language. Solution version becomes updated.
-
-
Hidden properties define the less frequently defined properties. Hidden properties differ with each action – read dedicated action description sections for details.
The Desktop Designer actions are grouped into multiple functional sets. The groups with basic action descriptions are listed below.
General group contains frequently used label opening and activation related commands:
Printer group contains actions related to printing:
Form group defines actions related to form objects:
Variables group defines actions related to variables:
Data & Connectivity group defines the actions related to databases, data sending, reading or receiving, and networking.
File operations group defines the active file related actions:
Flow control group defines various sequences of actions:
Other group contains specific actions for running the commands, sending custom commands and verifying the licenses:
Open Label action specifies the label file that is going to be printed. When the action is executed, the label template opens in memory cache. The label remains in the cache for as long as the triggers or events use it.
There is no limit on the number of labels that can be opened concurrently. If the label is already loaded and is requested again, NiceLabel Automation will first determine if a newer version is available and approved for printing, then open it.
In this example, loads the label label.nlbl from folder C:\ProjectA\Labels.
C:\ProjectA\Labels\label.nlbl
If the specified label cannot be found, NiceLabel 10 tries to find it in alternative locations. For more information, see section Search Order for Requested Files in NiceLabel Desktop Designer user guide.
Using Relative Paths
NiceLabel 10 supports the use of relative paths for referencing your label file. Root folder is always the folder where the solution (or configuration in case the action is used in a NiceLabel Automation configuration) is stored.
With the following syntax, the label loads relatively from the location of the configuration file. Automation Builder searches for the label in folder ProjectA, which is two levels above the current folder, and then in folder Labels.
..\..\ProjectA\Labels\label.nlbl
Settings group selects the label file.
-
Label name: specifies the label name. It can be hard-coded, and the same label will print every time. The option Data source enables the file name to be dynamically defined. Select or add a variable that contains the path and/or file name if a trigger is executed or an event takes place.
Tip
Usually, the value to the variable is assigned by a filter.
Note
Use UNC syntax for network resources.
This action executes label printing. It must always be nested within the Open Label action. Nesting allows it to obtain the reference to the label that is going to be printed. This further allows you to keep multiple labels open at the same time, and enables you to specify which label should be printed.
After issuing this action, the label gets printed using the printer driver that is defined in the label template. If the defined printer driver is not found on the system, the label is printed using the system default printer driver. You can override the printer driver selection via Set Printer action.
To achieve high performance label printing, activates two settings by default:
-
Parallel processing. Multiple print processes are all carried out simultaneously. The number of background printing threads depends on the hardware; specifically on the processor type. Each processor core can accommodate a single printing thread. This default can be changed. For more information, see section Parallel Processing in NiceLabel Automation user guide.
-
Asynchronous mode. As soon as the trigger pre-processing completes and the instructions for the print engine are available, the printing thread takes it over in the background. The control is returned to the trigger so it can accept the next incoming data stream as soon as possible. If synchronous mode is enabled, the control is not returned to the trigger until the print process is finished. This can take a while, but the trigger benefits from providing feedback back to data-providing application. For more information, see the section Synchronous Mode in NiceLabel Automation user guide.
Note
Using Save error to variable option in Action Execution and Error Handling does not yield any result in asynchronous mode, as the trigger does not receive feedback from the print process. To capture the feedback from the print process, enable synchronous mode first.
Note
If the Print Label action is nested under a For Loop action, Automation executes it in session printing mode. This mode acts as a printing optimization mode that prints all labels in a loop using a single print job file. For details, see Session Printing section in NiceLabel Automation user guide.
Quantity group defines the number of labels to be printed using the active form.
-
Labels: sets the number of printed labels. Data source specifies or adds a variable that defines the label print quantity dynamically.
Note
Variable value is usually assigned by the Use Data Filteraction and must be integer.
All (unlimited quantity): depending on the label template design, the labels are printed in various quantities.
Unlimited Quantity Printing Details
Typically, this option is used in two scenarios.
-
Command the printer to continuously print the same label until it is switched off, or after it receives a command to clear its memory buffer.
Warning
This scenario requires Loftware printer driver to be installed and used for label printing.
If printing a fixed label, just a single print job is sent to the printer, with the quantity set to "unlimited". Label printers have a print command parameter which indicates "unlimited" printing.
If the label is not fixed, but includes objects that change during the printing, such as counters, the printed quantity is set to maximum quantity supported by the printer. Loftware printer driver is aware of the printer quantity limit and print as many labels as possible.
Example 70. Example
Maximum supported print quantity is 32,000. This is the amount of labels that are print after selecting the All (unlimited quantity) option.
-
The trigger doesn't provide any data, but only acts as a signal for "event has happened". The logic to acquire necessary data is included in the label. Usually, a connection to a database is configured on the label, and at every trigger the label must connect to the database, and acquire all records from the database. In this case, the All (unlimited quantity) option is understood as "print all records from the database".
-
Variable quantity (defined from label variable): specifies a label variable that defines the label quantity to be printed.
The trigger doesn't receive the number of labels to be print, so it passes the decision to the label template. The label might contain a connection to a database, which provide the label quantity, or there is another source of quantity information. A single label variable must be defined as "variable quantity".
Advanced group defines label printing details. Click Show advanced print options to define the Advanced print options:
This section specifies non-frequently used label quantity related settings.
-
Number of skipped labels: specifies the number of labels that are skipped on the first page of labels. The sheet of labels might have been printed once already, but not entirely. You can re-use the same sheet by offsetting the starting position. This option is applicable, if you print labels to sheets of labels, not rolls of labels, so it's effective for office printers and not for label printers.
-
Identical label copies: specifies the number of label copies to be printed for each unique label. For fixed labels, this option produces the same result as the main Number of Labels option. For variable labels, such as labels using counters, you can get the real label copies.
-
Label sets: specifies how many times the entire label printing process should repeat.
Example 71. Example
Trigger or event receive content with 3 lines of CSV-formatted data, so 3 labels are expected to be printed (1, 2, 3). If you set this option to 3, the printout is done in the following order: 1, 2, 3, 1, 2, 3, 1, 2, 3.
Tip
All Advanced group values can either be hard-coded, or dynamically provided by an existing or a newly added variable.
This action provides an interface with an external application and opens it using a command-line.
External applications can execute additional processing and provide result back to the NiceLabel 10. This action allows it to bind with any 3rd party software that can execute some additional data processing, or acquire data. External software can provide data response by saving it to file, from where you can read it into variables.
You can feed the value of variable(s) to the program by listing them in the command-line in square brackets.
C:\Applications\Processing.exe [variable1] [variable2]
Note
If you use this action in NiceLabel 10 solutions, it allows you to open web pages or create email messages directly from your forms. See section Creating hyperlinks and sending emails on form in NiceLabel 10 user guide.
File group defines the file to be opened.
-
File name: location and file name of the file or application to be opened.
The selected file name can be hard-coded, and the same file is going to be used every time. If only a file name without path is defined, the folder with NiceLabel Automation configuration file (.MISX) is used. You can use a relative reference to the file name, in which the folder with .MISX file is used as the root folder.
Data source: enables variable file name. Select a variable that contains the path and/or file name or combine several variables that create the file name. For more information see section Using Compound Values in NiceLabel Automation User Guide.
Note
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation User Guide.
Execution Options group sets program opening details.
-
Hide window: renders the window of the opened program invisible. Because NiceLabel 10 is run as a service application within its own session, it cannot interact with desktop, even if it runs with the privileges of the currently logged user. Microsoft has prevented this interaction in Windows Vista and newer operating systems for security reasons.
-
Wait for completion: specifies for action execution to wait for this action to be completed before continuing with the next scheduled action.
Tip
Enable this option if the action that follows depends on the result of the external application.
This action enhances the software functionality by using custom VBScript or Python scripts. Use this function if the built-in actions don't meet your data manipulation requirements.
Scripts can include the trigger variables – both internal variables and the variables defined or imported from labels.
Make sure that Windows account under which the service runs has the privileges to execute the commands in the script.
Note
The script type is configured per trigger in the trigger properties. All Execute Script actions within a single trigger must be of the same type.
Script editor offers the following features:
-
Insert data source: inserts an existing or newly created variable into the script.
-
Verify: validates the entered script syntax.
-
Script editor: opens the editor which makes scripting easier and more efficient.
NiceLabel 10 provides a script editor which makes your Python or VBScript scripting easier, error-free and time efficient.
The selection of scripting languages that should be used in Script editor differs between NiceLabel Designer Pro and Automation Builder :
-
In Desktop Designer , double-click on the form design surface to open Form Properties > Additional Settings > Form Scripting Language.
-
In Automation Builder , go to Configuration items > click Edit to open trigger properties > Settings > Other > Scripting.
Tip
NiceLabel 10 uses .NET variant of Python named IronPython. It works as a fully compatible implementation of Python scripting language which also supports .NET methods.
Editor Ribbon includes commonly used commands which are distributed over multiple functional groups.
-
Clipboard group offers Cut, Copy, Paste and Delete commands.
-
Undo Redo group allows undoing or repeating script editing actions.
-
File group allows loading and saving scripts in a file.
-
Load from file: loads a script from an external previously saved textual file.
-
Save to file: stores the currently edited script in a textual file.
-
-
Editing group allows finding and replacing strings in a script.
-
Find: locates the entered string in the script.
-
Replace: replaces string in the script.
-
-
Insert group: Data Source command inserts existing or newly defined data sources into the script.
-
Script group: Validate script command validates of the entered script's syntax.
Available scripting elements contain all available script items which can be used when building a script. Double-click the element or click the Insert button to insert the element at cursor position into the script.
Element description provides basic information about the inserted script element.
Error list includes the errors which are reported after the Validate script command is run.
This action specifies the name of the printer to be used for printing the active label.
Note
This action overrides the printer selected in the label properties.
This action is useful when printing an identical label on multiple printers. Always nest this action under the Open Label action to provide the label with the reference for the preferred printer.
This action reads the default settings (such as speed and darkness) from the selected printer driver and applies them to the label. If you don't use the Set Printer action, the label gets printed using the printer defined in the label template.
Warning
Pay attention when switching the printers, e.g. from Zebra to SATO, or even from one printer model to another model of the same brand. Printer settings might not be compatible and the label printouts might not appear identical. Also, label design optimizations for original printer, such as internal counters, and internal fonts, might not be available on the newly selected printer.
Printer group specifies the printer name to be used for the current print job.
-
Printer name: select it from the list of locally installed printer drivers, or manually enter a printer name. Select Data source to dynamically select the printer using a variable. If enabled, select or create a variable that contains the printer name which is used if the action is run.
This action opens printer driver properties dialog for the selected printer. The settings are saved in the label file and take effect for the current label only.
Note
The modifications the user makes using this action are temporary and affect only the current print job. The modifications are not saved in a label or form.
Settings group defines a variable for printer settings.
-
Printer settings: selects or creates a variable to store the received output printer settings. If printer settings are included in the variable, Printer Properties dialog displays them.
This action specifies the name of the print job file as it appears in the Windows Spooler. A default print job name is the name of the used label file. This action overrides it.
Note
Always nest the action under the Open Label action, so it applies to the adequate label file.
Print Job group defines the print job name.
-
Name: sets the print job name. It can be hard-coded, and the same name is used for each print action. Variable enables a variable file name. Select or create a variable that contains the path and/or file name if the event happens or a trigger fires.
Note
In Automation Builder module, the variable value is usually assigned by a filter.
This action diverts the print job to a file. Instead of sending the created print file to a printer port as defined in the printer driver, the printout is redirected to a file. You can append data to an existing file, or overwrite it.
This action enables you to capture printer commands in a separate file.
The action instructs Automation Builder module to redirect printing – as a result, the labels are not going to be printed. Make sure the action is followed by the Print Label action.
Note
NiceLabel Automation runs as service under defined Windows user account. Make sure this user account has privileges accessing the specified folder with read/write permissions. For more information, see section Access to Network Shared Resources in the NiceLabel Automation user guide.
Redirect Printing to File action is useful for printing several different labels (.NLBL files) to a network printer while retaining the correct order of labels. If multiple .NLBL files are printed from the same trigger, Automation Builder sends each label to the printer in a separate print job, even if the target printer is the same for both labels. If a network printer is used, job of another user can be inserted between two jobs the trigger must send together. Using this action, you can append print data into the same file and send its contents to the printer using the Send Data to Printer action.
File group of settings defines how the file selection for redirecting is done.
-
File name:specifies the file name. It can either be hard-coded or dynamically defined using an existing or a newly created variable.
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
Note
When using this action, make sure your user account has sufficient privileges for accessing the specified folder with read/write permissions.
File write mode group of settings selects how the file is treated in case of repeated redirects.
-
Overwrite the file: if the specified file already exists on the disk, it is going to be overwritten.
-
Append data to the file: the job file is added to the existing data in the provided file.
Persistence group controls the continuity of the redirect action. It defines the number of Print Label actions that are affected by the Redirect Printing to File action.
-
Apply to next print action: specifies for the print redirect to be applicable to the next Print Label action only (single event).
-
Apply to all subsequent print actions: specifies for the print redirect to be applicable to all Print Label action defined after the current Redirect Printing to File action.
Note
The action only redirects printing. Make sure it is followed by the Print Label action.
This action allows you to fine tune the parameters that relate to the printer driver. These include parameters such as speed and darkness for label printers, or paper tray for laser printers.
Printer settings are applied to the current printout only and are not remembered during the upcoming event.
Warning
Your parameters from Set Print Parameter action don't apply when you preview or reprint labels from your Control Center.
You can avoid this with Use printer properties saved in: Label option. Printer properties may differ from driver to driver and also from printer to printer.
Note
If you use Set Printer action to change the printer name, make sure the Set Print Parameter action is used right after. Before you can apply the DEVMODE structure to the printer driver, first load the default driver settings. This is done by the Set Printer action. The DEVMODE is only compatible with the DEVMODE of the same printer driver.
Print Parameters group allows action fine tuning before printing.
-
Paper bin: name of the paper bin that contains the label media. This option is usually used with laser and ink jet printers with multiple paper bins. The provided name of the paper bin must match the name of the bin in the printer driver. Check the printer driver properties for more details.
-
Print speed: defines printing speed. This setting overrides the setting defined with label. The provided value must be in the range of accepted values.
Example 79. Example
The first printer model accepts a range of values from 0 to 30, while the second printer model accepts values from -15 to 15. For more information, see printer driver properties.
-
Darkness: defines the darkness of the printed objects on the paper and overrides setting from the label. The provided value must be in range of accepted values.
-
Print offset X: applies horizontal offset. The label printout will be repositioned by the specified number of dots in the horizontal direction. Negative offset can be defined.
-
Print offset Y: applies vertical offset. The label printout will be repositioned by the specified number of dots in the vertical direction. Negative offset can be defined.
Tip
All print parameters can either be hard-coded or dynamically defined using an existing or a newly created variable.
Advanced group customizes the printer settings that are sent along with the print job.
Printer settings, such as printing speed, darkness, media type, offsets and similar, can be defined as follows:
-
Defined in a label
-
Recalled from a printer driver
-
Recalled from a printer at print time
The supported methods depend on the printer driver and its capabilities. Printing mode (recall settings from label or driver or printer) is configurable in the label design. You might need to apply these printer settings at print time – they can vary with each printout.
Example 80. Example
A single label should be printed using a variety of printers, but each printer requires slightly different parameters. The printers from various manufacturers don't use the same values to set the printing speed or temperature. Additionally, some printers require vertical or horizontal offset to print the label to the correct position. During the testing phase, you can determine the optimal settings for every printer you intend to use and apply them to a single label template just before printing. This action will apply the corresponding settings to each defined printer.
This action expects to receive the printer settings in a DEVMODE structure. This is a Windows standard data structure with information about the initialization and environment of a printer.
Printer settings option applies custom printer settings. The following inputs are available:
-
Fixed-data Base64-encoded DEVMODE. In this case, provide the printer's DEVMODE encoded in Base64-encoded string directly into the edit field. If executed, the action converts the Base64-encoded data back into binary form.
-
Variable-data Base64-encoded DEVMODE. In this case, the selected data source must contain the Base64-encoded DEVMODE. Enable Data source and select the appropriate variable from the list. If executed, the action converts the Base64-encoded data back into the binary form.
-
Variable-data binary DEVMODE (available in Automation Builder). In this case, the selected variable must contain the DEVMODE in its native binary form. Enable Data source and select the appropriate variable from the list. If executed, the action uses the DEVMODE as-is, without any conversion.
Note
If the variable does not provide a binary DEVMODE, make sure that the selected variable is defined as a binary variable in the configuration.
Note
Make sure the Set Printer action is defined in front of this action.
Label settings overrides label properties defined in Label Properties in Designer. Use this option when you print your labels to a printer or media with different properties as defined in Label Properties in Designer. With this option you can:
-
Change your label dimensions (width and height).
-
Add or change label margins.
-
Disable cutter.
-
Disable batch printing.
-
Apply different stocks by changing Labels Across parameter (horizontal and vertical count, gaps, processing order).
-
Redefine Portrait or Landscape orientation.
-
Rotate labels by 180° degrees.
PowerForms applies Label settings at print time. Label settings parameters are not saved in your label templates. You can provide Label settings as an XML payload.
Sample Label settings XML
The sample below presents a structural view of the label settings and their attributes.
<LabelSettings>
<Width>100</Width>
<Height>30</Height>
<Margin>
<Left>2</Left>
<Right>3</Right>
<Top>4</Top>
<Bottom>5</Bottom>
</Margin>
<LabelsAcross>
<Horizontal>
<Count>2</Count>
<Gap>4</Gap>
</Horizontal>
<Vertical>
<Count>3</Count>
<Gap>5</Gap>
</Vertical>
<ProcessingOrder>HorizontalTopRight</ProcessingOrder>
</LabelsAcross>
<Orientation>Landscape</Orientation>
<Rotated>true</Rotated>
<DisableCutter/>
<DisableBatchPrinting/>
<PaperType>Roll or Sheet</PaperType>
<PaperName>A5</PaperName>
</LabelSettings>
Label settings XML specification
This section contains a description of the XML file structure to define Label settings parameters and values.
<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="nonNegativeFloat">
<xs:restriction base="xs:float">
<xs:minInclusive value="0"/>
</xs:restriction>
</xs:simpleType>
<xs:element name="LabelSettings">
<xs:complexType>
<xs:all>
<xs:element name="DisableCutter" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence/>
</xs:complexType>
</xs:element>
<xs:element name="DisableBatchPrinting" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence/>
</xs:complexType>
</xs:element>
<xs:element name="Width" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
<xs:element name="Height" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
<xs:element name="Margin" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:all>
<xs:element name="Left" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
<xs:element name="Right" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
<xs:element name="Top" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
<xs:element name="Bottom" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="LabelsAcross" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:all>
<xs:element name="Horizontal" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:all>
<xs:element name="Count" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
<xs:element name="Gap" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="Vertical" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:all>
<xs:element name="Count" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
<xs:element name="Gap" type="nonNegativeFloat" minOccurs="0" maxOccurs="1"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="ProcessingOrder" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="HorizontalTopLeft"/>
<xs:enumeration value="HorizontalTopRight"/>
<xs:enumeration value="HorizontalBottomLeft"/>
<xs:enumeration value="HorizontalBottomRight"/>
<xs:enumeration value="VerticalTopLeft"/>
<xs:enumeration value="VerticalTopRight"/>
<xs:enumeration value="VerticalBottomLeft"/>
<xs:enumeration value="VerticalBottomRight"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="Orientation" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Portrait"/>
<xs:enumeration value="Landscape"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="Rotated" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
</xs:all>
</xs:complexType>
</xs:element>
</xs:schema>
This action diverts the print job to a PDF document. The created PDF document retains the exact label dimensions as defined during the label design process. The rendering quality of graphics in the PDF matches the resolution of the target printer and desired printout size.
Print stream data can be appended to an existing file, or it may overwrite it.
The action instructs NiceLabel 10 to redirect printing – as a result, the labels are not printed. Make sure the action is followed by the Print Label action.
Note
NiceLabel Automation module runs as service under defined Windows user account. Make sure this user account has privileges accessing the specified folder with read/write permissions. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
File group defines the redirect file.
-
File name: specifies the file name for diverting the print job to. If hard-coded, the printing is redirected to the specified file every time. To define it dynamically, use an existing or create a new variable.
-
Overwrite the file: if the specified file already exists on the disk, it is going to be overwritten (selected by default).
-
Append data to the file: the job file is appended to the existing data in the provided file (deselected by default).
-
Embed fonts in PDF: If you use some non-standard font, your solution might produce different PDF output on computers without this font. With Embed fonts in PDF option enabled, you embed your non-standard font into your solution and your solution creates the same PDF on all computers.
Embed fonts in PDF option creates PDF for Archiving (PDF/A) compliant document. The PDF/A standard ensures your documents are reproduced exactly the same way, regardless of what software you use. The information required for displaying the contents like images, fonts, and color information is embedded in your PDF file.
Note
The output PDF file consumes more space when saved with this option enabled.
Persistence group allows controlling the persistence of the redirect action. Define the number of Print Label actions that are affected by the Redirect Printing to File action.
-
Apply to next print action: specifies for the print redirect to be applicable to the next Print Label action only (single event).
-
Apply to all subsequent print actions: specifies for the print redirect to be applicable to all Print Label action defined after the current Redirect Printing to File action.
This action communicates with the printer to acquire its real-time state, and contacts the Windows Spooler for additional information about the printer and its jobs.
As a result, the information about errors, spooler status, number of jobs in the spooler is collected. This uncovers potential errors and makes them easy to identify.
Possible use case scenarios. (1) Verifying the printer status before printing. If the printer is in error state, you print the label to a backup printer. (2) Counting the number of jobs waiting in a spooler of main printer. If there are too many, you will print label to alternative printer. (3) You will verify the printer status before printing. If the printer is in error state, you will not print labels, but report the error back to the main system using any of the outbound actions, such as Send Data to TCP/IP Port, Send Data to HTTP, Execute SQL Statement, Web Service, or as the trigger response.
Live Printer Status Prerequisites
To make live printer status monitoring possible, follow these instructions:
-
Use the Loftware Printer Driver to receive detailed status information. If using any other printer driver, you can only monitor the parameters retrieved from the Windows Spooler.
-
The printer must be capable of reporting its live status. For the printer models supporting bidirectional communication see Download web page.
-
Printer must be connected to an interface with support for bidirectional communication.
-
Bidirectional support must be enabled in Control Panel > Hardware and Sound > Devices and Printers > driver > Printer Properties > Ports tab > Enable bidirectional support.
-
If using a network-connected label printer, make sure you are using Advanced TCP/IP Port, not Standard TCP/IP Port. For more information, see the Knowledge Base article.
Printer group selects the printer.
-
Printer name: specifies the printer name to be used for the current print job.
You can select a printer from the list of locally installed printer drivers, or you can enter any printer name. Data source enables variable printer name. When enabled, select or create a variable that contains the printer name when a trigger is executed or an event takes place. Usually, the variable value is assigned by a filter.
Data Mapping group sets the parameters that are returned as a result of the Printer Status action.
Warning
Most of the following parameters are only supported with Loftware printer driver. If you are using any other printer driver, you can use only the spooler-related parameters.
-
Printer status: specifies the printer live status formatted as a string.
If the printer reports multiple states, all states are merged into a single string, delimited by comma ",". If there are no reported printer issues, this field is empty. Printer status might be set to Offline, Out of labels or Ribbon near end. Since there is no standardized reporting protocol, each printer vendor uses proprietary status messages.
-
Printer error: boolean (true/false) value of the printer error status.
-
Printer offline: boolean (true/false) value of the printer offline status.
-
Driver paused: boolean (true/false) value of the driver pause status.
-
Loftware driver: specifies boolean (true/false) value of the printer driver status. Provides information if the selected driver is a Loftware driver.
-
Spooler status: specifies the spooler status in a string form – as reported by the Windows system. The spooler can simultaneously report several statuses. In this case, the statuses are merged using comma ",".
-
Spooler status ID: specifies spooler status formatted as a number – as reported by the Windows system. The spooler can simultaneously report several statuses. In this case, the returned status IDs contains all IDs as flags. For example, value 5 represents status IDs 4 and 1, which translates to "Printer is in error, Printer is paused". Refer to the table below.
Tip
The action returns a decimal value, the values in the table below are in hex format, so you will have to do the conversion before parsing the response.
-
Table of spooler status IDs and matching descriptions
Spooler status ID (in hex)
Spooler status description
0
No status.
1
Printer is paused.
2
Printer is printing.
4
Printer is in error.
8
Printer is not available.
10
Printer is out of paper.
20
Manual feed required.
40
Printer has a problem with paper.
80
Printer is offline.
100
Active Input/Output state.
200
Printer is busy.
400
Paper jam.
800
Output bin is full.
2000
Printer is waiting.
4000
Printer is processing.
10000
Printer is warming up.
20000
Toner/Ink level is low.
40000
No toner left in the printer.
80000
Current page can not be printed.
100000
User intervention is required.
200000
Printer is out of memory.
400000
Door is open.
800000
Unknown error.
1000000
Printer is in power save mode.
-
Number of jobs in the spooler: specifies the number of jobs that are in the spooler for the selected printer.
-
Loftware driver extended printer status: returns printer status and errors data in JSON format. Data includes also printer parameters like firmware version, printhead distance, and ink level.
Note
You need the latest Loftware driver to get the Loftware driver extended printer status.
Example 83. Example
NiceLabel Automation returns the following JSON content:
{ "printerName":"Production_printer_09", "version":"1", "responseType":"status3", "overallStatus":"error", "operationState":"pause", "printerType":"Thermal Transfer Label Printer", "deviceStatus": [ { "item": "fatalError", "type": "string", "internalId":"ERR_PAPER_OUT", "shortString":"Paper Out", "longString":"Printer is out of paper." }, { "item": "error", "type": "string", "internalId": "ERR_RIBBON_OUT", "shortString": "Ribbon Out", "longString": "Printer is out of Ribbon." } ], "deviceParameters": [ { "item":"state", "type":"float", "internalId":"INFO_PRINTHEAD_DISTANCE", "unit": "meter", "value": 789, "shortDescription":"Printhead distance", "longDescription":"Distance of printhead usage." }, { "item": "state", "type": "string", "internalId": "INFO_FW", "unit": "", "value": "FW27.3.13", "shortDescription": "Firmware version", "longDescription": "The version of the Firmware loaded on the printer." }, { "item": "property", "type": "integer", "internalId": "INFO_PRINT_DISTANCE", "unit": "seconds", "value": 16004, "shortDescription": "Print Distance", "longDescription": "Print Distance that the printer printed since odometer reset." } ] }
This action saves label template in the printer memory. The action is a vital part of Store/Recall printing mode, using which you first store a label template into the printer's memory and later recall it. The non-changeable parts of label design are already stored in the printer, so you only have to provide the data for variable label objects at print time. For more information, see section Using Store/Recall Printing Mode in NiceLabel Automation user guide.
Note
The required label data transfer time is greatly minimized as there is less information to be sent. This action is commonly used for stand-alone printing scenarios, where the label is stored to the printer or applicator in the production line and later recalled by some software or hardware trigger, such as barcode scanner or photocell.
Advanced options for storing label to printer group allows you select a label and the preferred storing variant.
-
Label name to be used on the printer: specifies the name to be used for storing the label template in printer memory. Enter the name manually or enable Data source to define the name dynamically using an existing or newly created variable.
Warning
When storing the label to a printer, it is recommended to leave the label name under the advanced options empty. This prevents label name conflicts during the recall label process.
-
Store variant: defines printer memory location for stored label templates. Enter the location manually or enable Data source to define the name dynamically using an existing or newly created variable.
The Print PDF Document action prints static PDF documents that are not linked to the labels in your PowerForms solutions. Use this action to print any PDF document directly from your solutions. The PDF documents can be stored on:
-
Your computer
-
NiceLabel Control Center
-
Web server
-
Shared network drives
Tip
The action is useful if you plan to equip your packages with printed PDF reports on included items, or if you want to print the packaging documentation without opening the file browser.
Printer group specifies the printer name to be used for the current print job.
-
Printer name: select it from the list of locally installed printer drivers, or manually enter a printer name. Select Data source to dynamically select the printer using a variable. If enabled, select or create a variable that contains the printer name which is used if the action is run.
File group defines the redirect file.
-
File name: specifies which PDF to print.
Note
Use the UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation User Guide.
This action opens another form from the same solution or a form from your disk.
Settings group includes the following options:
-
Navigate back to previously opened form: reopens the preceding form when the Open Another Form action is run.
-
Open form: defines a form to be opened when the Open Another Form action is run.
There are four ways to open a form:
-
Enter the absolute file path.
-
Select an existing form from the solution.
-
Click Open to locate the file on the disk.
-
Use a data source to define the file path dynamically
Form data sources group helps you manage variable values when switching between forms.
-
Reset variable values: By default, if a form object's content is a variable value, switching to another form retains its current value. If you enable the Reset variable values option, the value of the variable resets to its initial value after you open another form.
-
Note
The Open another form action only keeps the values of variables that are in use as object data sources. If the variables are only listed in the Dynamic Data Manager, their values are not transferred.
Note
If the variable has no initial value, the object appears empty.
Example 87. Example
This option can be useful for data management solutions. When editing the data, you want to keep the existing values. When adding new data, you need to reset the values. If you use the first form for data editing and the second form for adding new data, you keep the Reset variable values option disabled for the data editing form, and enable this option for the data adding form.
This action moves the focus to a specified object on a form.
Settings group defines focus movement:
-
Move focus to first object in tab order: sets focus on the first object in the defined order after running the form.
-
Move focus to selected object places focus after running the form on the selected object.
This action enables you to retrieve the numbers of selected rows, or selected field values in the Database Table form object. The values are stored in an existing or newly created variable. Get Selected Table Row action works as a counterpart of the Select Table Row action.
Form Table group allows you to choose the Database Table object on the form, and to select which values should be stored in a variable.
-
Table: defines which Database Table object on the form is used with this action.
-
Selected row numbers: stores numbers of selected table rows in the Selected rows variable.
-
Table field content for selected rows: stores the field-related value of selected table rows.
-
Table field: defines the table field from which the values are taken and stored in the Selected rows variable.
-
Note
If multiple rows are selected, the stored values (row numbers or field values) are separated by commas. To enable multiple row selection, open Database Table object properties > Settings an enable multiple row selection.
Note
If the stored values (row numbers or field values) contain comma, they are surrounded with quotation marks.
-
-
Selected rows variable: selects or creates a variable that stores the Table field or Selected row numbers value.
Tip
Use this variable as a data source to display the selected values in a form object.
Tip
To display the selection of record immediately after the form is run, use the On Form Load event. Go to Form Properties > Events > On Form Load and click Actions.... Add Select Table Row action and define the rows as explained in this section.
This action allows you to define which row in a Database Table form object is selected. It works as a counterpart of the Get Selected Table Row action.
Form Table group allows you to choose the Database Table object on the form, and select the mode under which the row in the chosen table is selected.
-
Table: defines which Database Table object on the form is used with this action.
-
Selection mode: defines database record selection mode.
-
First row: selects the first row in the Database Table object.
-
Last row: selects the last row in the Database Table object.
-
Row number: enables custom selection of a database table rows. Enter the row numbers or define them dynamically using a data source. To select multiple rows, enter their row numbers separated by commas.
-
Field value: selects all records in the database table with matching data value.
-
Table field: database field with value(s) that are selected in case of a match.
-
Field value: value which selects the row (record) in case of a match.
-
Note
Row number and Field value options select the table row without regard to the current sorting of table rows. For example, "row number 3" remains selected even if table sorting repositions the "row number 3" to any other row.
-
Select all rows: selects all rows in the table.
-
Deselect all rows: deselects all rows in the table.
Note
Multiple rows are selected if the table supports it. If not, only the first row is selected.
-
When selecting a table row, the row number can be stored in a variable. To enable this option, use the Store selected row number to variable option in Database Table properties.
Note
The Select Table Row action defines its selection range on the dataset. This means that the records are directly selected from the connected database, and not from the table. If there is filtering enabled the Database Table object, it does not affect the Select table row action.
This action sets properties of form object, like width, height and color.
Settings group defines the properties to be set:
-
Object name: form object to be edited. Drop-down list contains objects on the form.
-
Property: defines the form object property to be set. The availability of properties depends on the currently selected object.
Tip
The settings take effect after the form is run and the assigned event takes place.
Property
Role
Applicability
X
Sets distance from left/right form border.
All form objects.
Y
Sets distance from top/bottom form border.
All form objects.
Width
Sets object width.
All form objects.
Height
Sets object height.
All form objects.
Enabled
Makes the object enabled or disabled.
All form objects.
Visible
Makes the object visible or invisible.
All form objects.
Font name
Changes font name to the selected one.
All form objects with textual content.
Font size
Changes font size to the selected value.
All form objects with textual content.
Font style
Changes font style to the selected one.
All form objects with textual content.
Font color
Changes font color to the selected one.
All form objects with textual content.
Color
Changes the object color to the selected one.
All form objects, except Database Navigator, Picture.
Visible columns
Makes a selection of table columns visible.
Columns are visible in the same order as entered in the Value field.
Database Table.
-
Value: comma-separated values. Use the “ character if value name includes a comma.
Tip
An example for object property defining is described in Database Table form object section of User Guide for Designers.
This action translates all strings on a form to the selected language. Translation file that contains strings in source language and translated strings is mandatory for this action. If you have to create a new translation file, follow the formatting rules below.
Translate form settings group selects language and selects or creates a new translation file.
-
Language: language to be used on the translated form. The language name is defined in the first row of the translation file.
Tip
The language name in the translation file is user-configurable. Use the same ID (name) in the action as you have defined in the translation file. The language name can be fixed or variable. Its usage depends on the language selection type you that is used on the form.
Fixed name: hard-coded language name which must match the name in the first row of the translation file.
Variable name: Example is a drop-down box with language names. When the user changes the language in the list, the onChange event executes the Translate Form action. The drop-down box saves the user selection in a variable, which is used for the action.
-
Translation file: file that contains source strings and translations into various languages. This is a structured text file, similar to a CSV file.
-
Create translation file: click this button to create the translation file containing the source and translated strings.
Translation File Structure: a text file with UTF-8 encoded data. It is similar to comma-separated-values (CSV).
Formatting Rules are mandatory. Always follow the below listed rules.
-
The first line contains language ID.
-
The first field is always named as Source. Do not change it.
-
The names of other fields in the first row are user-configurable. Use the suggested names, such as "Language 2" and "Language 3", or replace them with whatever describes the language better, such as "German", "French", "Chinese", etc.
-
All lines that follow the first line are lines with the translations from the original language. The first field contains the original string, the next fields in the same line contain translation to other languages. The first line specifies in which order the translation should follow the source string.
-
All values are enclosed with double-quote characters (").
-
All values are delimited by a semicolon character (;).
-
If you have multiline text objects in the form, the newline (<CR><LF>) will be encoded as special string $NEWLINE$.
-
If you leave the translation empty, the Source string is used.
Example of Translation File:
Source";"DE" "&Print";"&Druck" "Customize$NEWLINE$your$NEWLINE$printing$NEWLINE$forms";" Anpassen$NEWLINE$Sie$NEWLINE$Ihre$NEWLINE$Druckformen" "Printer:";"Drucker" "Quantity";"Menge" "SAMPLE";"PROBE" "Se&ttings";"Einstellungen" "Translate";"Übersetzen" "www.loftware.com/solutions";""
Translating Strings
When using the Translate Form action anywhere in your form, all strings of the form are automatically saved to the translation file whenever you save the form. This ensures that the translation file is always up to date with your form.
The translation file is Unicode-aware text file. You can edit it in any text editor, but you might have troubles recognizing the fields, because their values are semicolon-separated and not aligned one below another.
You can also open the file in a spreadsheet application, such as Microsoft Excel. In this case, the fields belonging to particular language are displayed in the same column of data, and much easier to edit.
Note
Spreadsheet applications might change the input file structure of the translation file. In this case, reformat the data by yourself after you save the translation file.
Example 94. Example
Microsoft Excel will save the translation file as CSV. The fields lose the double quotes around the values and will be delimited by comma (,) instead of semicolon (;). You will have to convert commas into semicolons and put double quotes around fields. This can be done with a few search & replace actions.
Translating Label Values in a Solution
Forms sometimes display values that come from labels in the same solution document. The Translate Form action does not translate these label values automatically because you have to manually add them to the translation file.
Add label values to the translation file using the same formatting rules as described above.
Example 95. Example
Your solution contains one form and one label. The form includes Data Initialization object for assigning values to the label variables. You want to display the originally English form in German language using the Translate Form action (i.e. by clicking a button on the form).
Original prompt text for variables is "Define variable value". To display German translation, add this line to the translation file: "Define variable value";"Definieren Sie den Variablenwert"; After you click the button with assigned Translate Form action, the prompt text appears in German.
The Message action creates pop-up windows with custom messages in your Solutions so you can provide your operators with:
-
Specific warnings
-
Error messages
-
Information
-
Questions
You can assign fixed values to Caption and Message actions or connect to dynamic data sources. You can save responses to your messages ("OK", "Cancel", "Yes", or "No") as variables. You can also use Messages as debugging tools when you design and test forms by showing the results of functions in messages.
Creating custom messages for your forms in the Actions Editor.
Messages contain graphic symbols corresponding to different messages:
-
Information
-
Errors
-
Warnings
-
Questions
Add messages with the Messages action to prevent confusion and inform operators of data processing errors when your solutions run.
This action assigns a new value to the selected variable.
Variables usually obtain their values using Use Data Filter action (available in Automation Builder) which extracts fields from the received data and maps them to variables. You might also need to set the variable values by yourself, usually for troubleshooting purposes. In Automation Builder, the variable values are not remembered between multiple triggers, but are kept while the same trigger is being processed.
Variable group defines the variable name and its value.
-
Name: name of variable that should store the value changed.
-
Value: value to be set to a variable. It can either be manually or dynamically defined using an existing or a newly created variable.
This action saves values of a single or multiple variables in an associated data file.
In NiceLabel Automation module, this action allows data exchange between triggers. To read the data back into the trigger, use action Load Variable Data.
Tip
The values are saved in a CSV file with the first line containing variable names. If the variables contain multi-line values, the newline characters (CR/LF) are encoded as \n\r.
Settings group defines the file name.
-
File name: data file to save the variable data to. If the name is hard-coded, values are saved into the same data file each time.
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
If file exists group offers additional options to save the values.
-
Overwrite the file: overwrites the existing data with new variable data. The old content is lost.
-
Append data to the file: appends the variable values to the existing data files.
File Structure group defines the CSV variable data file parameters:
-
Delimiter: specifies the delimiter type (tab, semicolon, comma or custom character). Delimiter is a character that separates the stored variable values.
-
Text qualifier: specifies the character that qualifies the stored content as text.
-
File encoding: specifies character encoding type to be used in the data file. Auto defines the encoding automatically. If required, the preferred encoding type can be selected from the drop-down list.
Tip
UTF-8 makes a good default selection.
-
Add names of variable in the first row: places the variable name in the first row of the file.
Variables group defines the variables whose value should be read from the data file. Values of the existing variables are overwritten with values from the file.
-
All variables: variable data of all variables from the data file is read.
-
Selected variables: variable data of listed variables is red from the data file.
This action loads values of a single or multiple variables from the associated data file as saved by the action Save Variable Data . Use this action to exchange the data between triggers. You can load a particular variable or all variables that are stored in the data file.
Settings group defines the file name.
-
File name: specifies the file for the variable data to be loaded from. If the name is hard-coded, the values are loaded from the same file each time.
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
File Structure group settings must reflect the structure of the saved file from the Save Variable Data action.
-
Delimiter: specifies delimiter type (tab, semicolon, comma or custom character). Delimiter is a character that separates the values.
-
Text qualifier: specifies the character that qualifies content as text.
-
File encoding: specifies the character encoding type used in the data file. Auto defines the encoding automatically. If needed, select the preferred encoding type from the drop-down list.
Tip
UTF-8 makes a good default selection.
Variables group defines the variables whose values should be loaded from the data file.
-
All variables: specifies all defined variables in the data file to be read.
-
Selected variables: specifies selection of individual variables to be read from the data file.
This action defines how the values of selected variables should be formatted.
The most popular string manipulation actions are: delete leading and trailing spaces, search and replace characters, and delete opening and closing quotes.
This feature is often required is a trigger receives an unstructured data file or legacy data. in such cases, the data needs to be parsed using the Unstructured Data filter. String Manipulation action allows you to fine-tune the data value.
Note
If this action doesn't provide enough string manipulation power for a particular case, use Execute Script action instead to manipulate your data using Visual Basic Script or Python scripts.
Variables group defines the variables whose values need to be formatted.
-
All variables: specifies all the defined variables in a data file to be formatted.
-
Selected variables: specifies a selection of variables to be formatted from the data file.
Format Text group defines string manipulation functions that apply to the selected variables or fields. Multiple functions can be used. The functions apply in the same order as seen in the editor – from top to bottom.
-
Delete spaces at the beginning: deletes all space characters (decimal ASCII code 32) from the beginning of the string.
-
Delete spaces at the end: deletes all space characters (decimal ASCII value 32) from the end of a string.
-
Delete opening closing characters: deletes the first occurrence of the selected opening and closing characters that is found in the string.
Example 100. Example
If using "{" as opening character and "}" as closing character, the input string
{{selection}}is converted to{selection}.
-
Search and replace: executes standard search and replace function upon the provided values for find what and replace with. Regular expressions are supported.
Note
Several implementations of regular expressions are present. NiceLabel 10 uses .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.
-
Replace non printable characters with space: replaces all control characters in the string with "space" character (decimal ASCII code 32). Non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
-
Delete non printable characters: deletes all control characters in the string. Non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
-
Decode special characters: decodes the characters (or control codes) that are not available on the keyboard, such as Carriage Return or Line Feed. NiceLabel 10 uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. This option converts special characters from NiceLabel syntax into actual binary characters.
Example 101. Example
When you receive the data "<CR><LF>", Desktop Designer uses it as plain string of 8 characters. You will have to enable this option to interpret and use the received data as two binary characters
CR(Carriage Return – ASCII code 13) andLF(Line Feed – ASCII code 10).
-
Search and delete everything before: finds the provided string and deletes all characters in front of the defined string. The string can also be deleted.
-
Search and delete everything after: finds the provided string and deletes all characters behind the defined string. The string can also be deleted.
This action sends SQL commands to your SQL server and collects results. Use commands SELECT, INSERT, UPDATE, and DELETE.
Use Execute SQL Statement action to achieve these two goals:
-
Obtain additional data from a database: You want to print labels with data from your database, but not all of the required values. For example, only values for
Product IDandDescription, but not forPrice. Create an SQL statement to look up the values forPricein the SQL database.SELECT Price FROM Products WHERE ID = :(Product ID)
The
IDis field in the database,Product IDis a variable defined in the trigger.
-
Update or delete records in a database: After your labels are printed, update the database records and inform the system that the particular records have already been processed. SQL code example: Set the table field
AlreadyPrintedvalue toTruefor the currently processed record.UPDATE Products SET AlreadyPrinted = True WHERE ID = :(Product ID)
Or delete the current record from a database, because it's not needed anymore.
DELETE FROM Products WHERE ID = :(Product ID)
The
IDis field in the database,Product IDis a variable defined in the trigger.
Note
To use values of variables inside SQL statements, insert colon (:) in front of variable names. This signals that a variable name follows.
Important
When you create your solution with a database connection, use prompt variables on your labels instead of database fields.
Use the same names for prompt variables as are defined for database fields, for example:
Database field: food_products_1c.ProdCode
Prompt variable on your label: ProdCode
NiceLabel then automatically maps corresponding variables with database fields.
Database Connection group defines the database connection that is used for the statement.
Tip
Before you can send an SQL sentence to a database, set up the database connection. Click the Define button and follow the on-screen instructions. You can connect to a data source that can be controlled using SQL commands, so you cannot use text (CSV) or Excel files.
SQL Statement group defines an SQL statement or query to be executed.
Tip
Statements from Data Manipulation Language (DML) are allowed to execute queries upon existing database tables.
Use standard SQL statements, such as SELECT, INSERT, DELETE and UPDATE, including joins, function, and keywords. The statements in DDL language that are used to create databases and tables (CREATE DATABASE, CREATE TABLE), or to delete them (DROP TABLE) are not permitted.
-
Test: opens Data Preview section. Simulate execution (selected by default) tests the execution of SQL statements. Click Execute to run the simulation.
Tip
Data Preview section allows you to test the execution of your SQL statement upon a live set of data. To protect the data from accidental updates, make sure the option Simulate execution is enabled. The statements INSERT, DELETE and UPDATE will execute. This enables you to gain feedback on how many records will be affected, then all of the transactions will be reversed.
If you use variables in the SQL statement, you will be able to enter their values for the test execution.
-
Insert data source: inserts predefined or newly created variables into an SQL statement.
-
Export/Import: enables exporting and importing SQL statements to/from an external file.
-
Execution mode: specifies the explicit mode of SQL statement execution.
Tip
In cases of complex SQL queries, it becomes increasingly difficult to automatically determine what is the supposed action. If the built-in logic has troubles identifying your intent, manually select the main action.
-
Automatic: determines the action automatically.
-
Returns set of records (SELECT): receives the data set with records.
-
Does not return set of records (INSERT, DELETE, UPDATE): use this option if executing a query that does not return the records. Either insert new records, delete or update the existing records. The result is a status response reporting the number of rows that were affected by your query.
-
-
Execution timeout: allows you to define the time delay for sending your commands to the SQL server. Use the execution timeout if you are sending multiple consecutive SQL commands that require a longer processing time.
Type the requested timeout duration in seconds. By default, the execution timeout duration is 60 s. If you want your database provider to define the timeout, type in 0 s.
Result group allows you to set how the SQL statement result should be stored, and to define action iteration.
-
Save Data to Variable: selects or creates a variable to store the SQL statement result. This option depends on the selected Execution mode.
-
Result of SELECT statement. After you execute a SELECT statement, it results in a data set of records. You receive a CSV-formatted text content. The first line contains field names returned in a result. The next lines contain records.
To extract the values from the returned data set and to use them in other actions, define and execute the action Use Data Filter upon the contents of this variable (this action is available in Automation Builder).
-
Result of INSERT, DELETE and UPDATE statements. If you use INSERT, DELETE and UPDATE statements, the result is a number indicating the number of records affected in the table.
-
-
Iterate for Every Record. If enabled, NiceLabel automatically adds a new action For Every Record. See more about this action in a dedicated topic.
All nested actions are repeated for each record that has been returned using the SQL statement.
Note
Automatic database field mapping is enabled. Prompt variables on your label automatically connect to your database fields with the same names. For example:
Database field:
food_products_1c.ProdCodePrompt variable on your label:
ProdCode
Retry on failure group allows you to configure the action to continually retry establishing the connection to a database server in case the first attempt is unsuccessful. If the action fails to connect within the defined number of attempts, an error is raised.
-
Retry attempts: specifies the number of tries to connect to the database server.
-
Retry interval: specifies the duration of time between individual retry attempts.
Warning
Don't put the Database Table object on your printing form if you use Execute SQL Statement action. Results might be wrong.
Example 103. Example
You want to print labels with data from your food_products_1c database but only records with predefined field value UseBy.
You define UseBy value with variable ProdUser. In this case, ProdUser value is "3".
After each label is printed, NiceLabel writes database values in a text file on your disc. Use the following actions:
Only labels where UseBy value equals "3" are printed and values are written in a text file:
This action rereads the specified database table.
Table group selects the database table to be reread.
-
Table: defines an existing table to be reread or creates a new one using the Step-by-Step Database Wizard.
This action reads data from a formatted CSV text file and imports it into an SQL database.
Note
Before using this action, a connection to the SQL database must already be set. The action does not work with file-based databases, such as Microsoft Access, or data files like Microsoft Excel, or plain text files. Use a server-based SQL database, such as Microsoft SQL Server.
The following rules apply to this action:
-
The table must already exist within the SQL database.
-
The table must contain PRIMARY KEY.
-
The first line in a text file must define field names.
-
The field names in the text file must match field names in the database table.
-
If the text file does not provide a value for some field, NULL is written to the database. If the field does not accept NULL values, an empty string ("") is written.
-
Setting values for auto-incremental fields are ignored. The database provides value for such field.
-
If the value from text file does not match the structure of the field, the action is canceled and an error message is displayed. For example, when trying to enter alphanumerical value into numerical field.
-
If you filter records on the form and display only records matching certain condition, you can only import records that either do not provide value for the filter field, or provide the same value for the filter as defined with the form.
-
Only filters with condition "equal" , not "greater than", "less than", "contains" or similar are permitted.
-
If the text file contains fields not defined in the SQL database, the import will ignore them. Only known fields will be imported.
Settings group selects the table.
-
Table defines a predefined table from the drop-down menu or creates a new one using the Step-by-Step Database Wizard.
File Text Structure group specifies the text database parameters:
-
Delimiter: specifies the delimiter type in the data file. Select a predefined delimiter, or create a custom one.
-
Text qualifier: specifies the text qualifier. Select a predefined delimiter or insert a custom one.
-
File encoding: specifies the character encoding type used in the data file. Auto defines the encoding automatically. If needed, select the preferred encoding type from the drop-down list.
This action sends data to any external device which accepts TCP/IP connection on a predefined port number.
Send Data to TCP/IP Port establishes connection with a device, sends the data and terminates the connection. The connection and communication is governed by the client – server handshake that occurs when initiating or terminating the TCP connection.
Connection Settings group sets connection details.
-
Reply to sender: Enables direct reply to the socket from which the trigger data originates. Use this option to provide feedback about the printing process.
Note
This option is available in NiceLabel Automation.
Prerequisites for Reply to sender setting are:
-
Remote party does not close the communication channel, once the message gets delivered.
-
Send Data to TCP/IP Port action is used within the TCP/IP Server trigger.
-
Do not configure the Execution Event in the TCP/IP Server trigger as On client disconnect.
-
-
Destination (IP address:port): destination address and port of the TCP/IP server. Hard-code the connection parameters and use fixed host name or IP address or use variable connection parameters by clicking the right arrow and selecting a predefined variable. For more information, see section Combining Values in an Object in NiceLabel Automation user guide.
Example 107. Example
If the variable
hostnameprovides the TCP/IP server name and the variableportprovides the port number, enter the following parameter for the destination:[hostname]:[port]
-
Disconnect delay: prolongs the connection with the target socket for the defined time intervals after the data has been delivered. Certain devices require more time to process the data. Insert the delay value manually or click the arrows to increase or decrease it.
-
Save data reply in a variable: selects or creates a variable that stores the server reply. Any data received from the TCP/IP server after passing the "disconnect delay" is stored in this variable.
Note
Send Data to TCP/IP Port action is executed on Web Printing Server and not on the Web Printing Client.
If you use Send Data to TCP/IP Port action in NiceLabel Web Client and you want to execute locally (bypassing the Web Printing Server), add the prefix "LOCAL_" to your action name.
Content group defines the content to be sent to a TCP/IP server.
Tip
Use fixed content, mix of fixed and variable content, or variable content alone. To enter variable content, click the button with arrow to the right of data area and insert a variable from the list. For more information, see section Combining Values in an Object in NiceLabel Automation user guide.
-
Data: content to be sent outbound.
-
Encoding: encoding type for the sent data. Auto defines the encoding automatically. If needed, select the preferred encoding type from the drop-down list.
This action sends data to a serial port. Use it to communicate with external serial-port devices.
Tip
Make sure the port settings match on both ends – in the configured action and on the serial-port device. Serial port can be used by a single application in the machine. To successfully use the port from this action, no other application may use the port at the same time, not even any printer driver.
Port group defines the serial port.
-
Port name: name of the port to which the external device connects to. This can either be a hardware COM port or a virtual COM port.
Port Settings group defines additional port connection settings.
-
Bits per second: speed rate used by the external device to communicate with the PC. The usual alias used with the setting is "baud rate". Select the value from the drop-down menu.
-
Data bits: number of data bits in each character. 8 data bits are almost universally used in newer devices. Select the value from the drop-down menu.
-
Parity: method of detecting errors in a transmission. The most common parity setting, is "none", with error detection handled by a communication protocol (flow control). Select the value from the drop-down menu.
-
Stop bits: halts the bits sent at the end of every character allowing the receiving signal hardware to detect the end of a character and to resynchronize with the character stream. Electronic devices usually use a single stop bit. Select the value from the drop-down menu.
-
Flow control: serial port may use interface signals to pause and resume the data transmission.
Content group defines the content to be sent to serial port.
Tip
Fixed content, mix of fixed and variable content, or variable content alone are permitted. To enter variable content, click the button with arrow to the right of data area and insert a variable from the list. For more information, see section Combining Values in an Object in NiceLabel Automation user guide.
-
Data: content to be sent outbound.
This action collects data received via serial port (RS-232) and saves it in a selected variable. Use this action to communicate with external serial port devices.
Port group defines the serial port.
-
Port name: name of the port to which an external device connects to. This can either be a hardware COM port or a virtual COM port.
Port Settings group defines additional port connection settings.
-
Bits per second: speed rate used by the an external device to communicate with the PC. The usual alias used with the setting is "baud rate".
-
Data bits: specifies the number of data bits in each character. 8 data bits are almost universally used in newer devices.
-
Parity: specifies the method of detecting errors in a transmission. The most common parity setting, is "none", with error detection handled by a communication protocol (flow control).
-
Stop bits: halts the bits sent at the end of every character allowing the receiving signal hardware to detect the end of a character and to resynchronize with the character stream. Electronic devices usually use a single stop bit.
-
Flow control: serial port may use interface signals to pause and resume the data transmission.
Example 110. Example
A slow device might need to handshake with the serial port to indicate that data should be paused while the device processes received data.
Options group includes the following settings:
-
Read delay: optional delay when reading data from serial port. After the delay, the entire content of the serial port buffer is read. Enter the delay manually or click the arrows to increase or decrease the value.
-
Send initialization data: specifies the string that is sent to the selected serial port before the data is read. This option enables the action to initialize the device to be able to provide the data. The option can also be used for sending a specific question to the device, and to receive a specific answer. Click the arrow button to enter special characters.
Data Extraction group defines how the defined parts of received data are extracted.
-
Start position: starting position for data extraction.
-
End position: ending position for data extraction.
Result group defines a variable for data storing.
-
Save data to variable: select or create a variable to store the received data.
This action sends data to a selected printer. Use it to send pre-generated printer streams to any available printer.
NiceLabel Automation module uses the installed printer driver in pass-through mode just to be able to send data to the target port, such as LPT, COM, TCP/IP or USB port, to which the printer is connected.
Note
Possible scenario. Data received by the trigger must be printed out on the same network printer, but on different label templates (.NLBL label files). The printer can accept data from various workstations and will usually print the jobs in the received order. Automation Builder module will send each label template in a separate print job, making it possible for another workstation to insert its job between the jobs created in our own Automation Builder module. Instead of sending each job separately to the printer, merge all label jobs (using the action Redirect Printing to File) and send a single "big" print job to the printer.
Printer group selects the printer.
-
Printer name: name of the printer to send the data to. Select the printer from the drop-down list of locally installed printer drivers, enter a custom printer name, or define it dynamically using an existing or newly created variable.
Data Source group defines the content to be sent to printer.
-
Use data received by the trigger: trigger-received data it used. In this case, you want the received printer stream to be used as an input to the filter. Your goal is to redirect it to a printer without any modification. The same result can be achieved by enabling the internal variable
DataFileNameand using the contents of the file it refers to. For more information, see section Using Compound Values in NiceLabel Automation user guide. -
File name: path and file name of the file containing a printer stream. Content of the specified file is sent to a printer. Select Data source to define the file name dynamically using a variable value.
-
Variable: variable (existing or new) that contains the printer stream.
-
Custom: defines custom content to be sent to a printer. Fixed content, mix of fixed and variable content, or variable content alone are permitted. To enter variable content, click the button with arrow to the right of data area and insert a variable from the list. For more information, see section Combining Values in an Object in NiceLabel 10 user guide.
This action sends data to the destination Web server using the selected HTTP method. HTTP and HTTPS URI schemes are allowed.
HTTP works as a request-response protocol in client-server computing model. In this action, acts as a client that communicates with a remote server. This action submits a selected HTTP request message to a server. The server returns a response message, which can contain completion status information about the request and may also contain requested content in its body.
Connection Settings group sets connection parameters.
Note
This action supports Internet Protocol version 6 (IPv6).
-
Destination: address, port and destination (path) of the Web server.
Note
If a Web server runs on default port 80, skip the port number. Hard-code the connection parameters and use a fixed host name or IP address. Use a variable value to define this option dynamically. For more information, see section Using Compound Values in NiceLabel Automation user guide.
Example 113. Example
If the variable
hostnameprovides the Web server name and the variableportprovides the port number, you can enter the following for the destination:[hostname]:[port]
-
Request method: available request methods.
-
Timeout: timeout duration (in ms) during which the server connection should be established and response received.
-
Save status reply in a variable: variable to store the status code received from the server.
Tip
Status code in range 2XX is a success code. Common "OK" response is code 200. Codes 5XX are server errors.
-
Save data reply in a variable: variable to store the data received from the server.
Authentication group enables you to secure the Web server connection.
-
Enable basic authentication: allows you to enter the required credentials to connect to the Web server. User name and password can either be fixed or provided using a variable.
HTTP Basic authentication (BA) uses static standard HTTP headers. The BA mechanism provides no confidentiality protection for the transmitted credentials. They are merely encoded with Base64 in transit, but are not encrypted or hashed in any way. Basic Authentication should be used over HTTPS.
-
Show password: unmasks the password characters.
Note
HTTP Request action is executed on Web Printing Server and not on the Web Printing Client.
If you use HTTP Request action in NiceLabel Web Client and you want to execute locally (bypassing the Web Printing Server), add the prefix "LOCAL_" to your action name.
Content group defines the contents to be sent to a Web server.
-
Data: content to be sent outbound. Fixed content, mix of fixed and variable content, or variable content alone are permitted. To enter variable content, click the button with arrow to the right of data area and insert variable from the list. For more information, see section Combining Values in an Object in NiceLabel 10 user guide.
-
Encoding: encoding type for the sent data.
Tip
Auto defines the encoding automatically. If needed, select the preferred encoding type from the drop-down list.
-
Type: Content-Type property of the HTTP message. If no type is selected, the default
application/x-www-form-urlencodedis used. If an appropriate type is not listed, define a custom one or set a variable that would define it dynamically.
Additional HTTP Headers are requested by certain HTTP servers (especially for REST services).
Note
HTTP Request action already uses a built-in subscription key, so you don't need to enter Ocp-Apim-Subscription-Key value in Additional HTTP Headers.
You must provide Ocp-Apim-Subscription-Key value if you make a call to Cloud API from non-NiceLabel application.
-
Additional headers: hard coded headers or headers obtained from variable values. To access the variables, click the small arrow button to the right hand side of the text area. For more information, see section Combining Values in an Object in NiceLabel 10 user guide.
Certain HTTP servers (especially for REST services) require custom HTTP headers to be included in the message. This section allows you to provide the required HTTP header.
HTTP headers must be entered using the following syntax:
header field name: header field value
For example, to use the header field names
Accept,User-AgentandContent-Type, you could use the following syntax:Accept: application/json; charset=utf-8 User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36 Content-Type: application/json; charset=UTF-8
You can hard code the header field names, or you can obtain their values from trigger variables. Use as many custom header fields as you want, just make sure that each header field is placed in a new line.
Note
The entered HTTP headers override the already defined headers elsewhere in the action properties, such as Content-Type.
Web Service is a method of communication between two electronic devices or software instances. Web Service is defined as a data exchange standard. It uses XML format to tag the data, SOAP protocol is used to transfer the data, and WSDL language is used to describe the available services.
This action connects to a remote Web service and executes the methods on it. Methods can be described as actions that are published on the Web Service. The action sends inbound values to the selected method in the remote Web service, collects the result and saves it in selected variables.
After importing the WSDL and adding a reference to the Web Service, its methods are listed in the Method combo box.
Note
You can transfer simple types over the Web Service, such as string, integer, boolean, but not the complex types. The WSDL must contain single binding only.
You plan to print product labels. Your trigger would receive only a segment of the required data. E.g. the trigger receives the value for Product ID and Description variables, but not the Price. The price information is available in a separate database, which is accessible over Web service call. Web service defines the function using a WSDL definition. For example, function input is Product ID and its output is Price. The Web Service action sends Product ID to the Web service. It executes and makes an internal look up in its database and provide the matching Price as the result. The action saves the result in a variable, which can be used on the label.
Web Service Definition group includes the following settings:
Note
This action supports Internet Protocol version 6 (IPv6).
-
WSDL: location of WSDL definition.
WSDL is usually provided by the Web service. Typically, you would enter the link to WSDL and click Import to read the definition. If facing troubles while retrieving the WSDL from online resource, save the WSDL to a file and enter the path with file name to load the methods from it. automatically detects if the remote Web Service uses a document or RPC syntax, and whether it communicates appropriately or not.
-
Address: address at which the Web Service is published.
Initially, this information is retrieved from the WSDL, but can be updated before the action is executed. This is helpful for split development / test / production environments, where the same list of actions is used, but with different names of servers on which the Web Services run.
Fixed content, mix of fixed and variable content, or variable content alone are permitted. To enter variable content, click the button with arrow to the right hand side of data area and insert variable from the list. For more information, see section Combining Values in an Object in NiceLabel 10 user guide.
-
Method: methods (functions) that are available for the selected Web service. The list is automatically populated by the WSDL definition.
-
Parameters: input and output variables for the selected method (function).
Inbound parameters expect an input. For testing and troubleshooting reasons, you can enter a fixed value and see the preview result on-screen. Typically, you would select a variable for inbound parameter. Value of that variable will be used as input parameter. The outbound parameter provides the result from the function. You must select the variable that will store the result.
-
Timeout: timeout after which the connection to a server is established.
Note
Web Service action is executed on Web Printing Server and not on the Web Printing Client.
If you use Web Service action in NiceLabel Web Client and you want to execute locally (bypassing the Web Printing Server), add the prefix "LOCAL_" to your action name.
Authentication enables basic user authentication. This option defines user credentials that are necessary to establish an outbound call to a remote web service.
-
Enable basic authentication: enables defining the Username and Password that can be entered manually or defined by variable values. Select Data sources to select or create the variables.
-
Show password: uncovers the masked Username and Password characters.
Details about security concerns, are available in section Securing Access to your Triggers in NiceLabel Automation user guide.
Data Preview field allows you to perform a test Web service execution.
-
Execute button executes a Web service call.
It sends values of inbound parameters to the Web service and provides the result in the outbound parameter. Use this functionality to test the execution of a Web service. You can enter values for inbound parameters and see the result on-screen. When satisfied with execution, replace the entered fixed value for inbound parameter with a variable from the list.
This action saves variable value or other data streams (such as binary data) in a selected file. The NiceLabel Automation service must have write access to the defined folder.
File group defines the file to be opened.
-
File name: location of the file to be opened within this action.
Path and file name can be hard-coded, and the same file is going to be used every time. If only a file name without path is defined, the folder with NiceLabel Automation configuration file (.MISX) is used. You can use a relative reference to the file name, in which the folder with .MISX file is used as the root folder.
Data source: enables variable file name. Select a variable that contains the path and/or file name or combine several variables that create the file name. For more information, see section Using Compound Values in NiceLabel Automation User Guide.
If file exists group handles options in case of an already existing file.
-
Overwrite the file: overwrites existing data with new data. The old content is lost.
-
Append data to the file: appends variable values to the existing data files.
Content group defines which data is going to be written in the specified file.
-
Use data received by the trigger: original data as received by the trigger is going to be saved in the file. Effectively, this option makes a copy of the incoming data.
-
Custom: saves content as provided in the text area. Fixed values, variable values and special characters are permitted. To enter variables and special characters, click the arrow button to the right of the text area. For more information, see section Combining Values in an Object in NiceLabel Automation User Guide.
-
Encoding: encoding type for the sent data. Auto defines the encoding automatically. If needed, select the preferred encoding type from the drop-down list.
This action reads content of the provided file name and saves it in a variable. Content of any file type, including binary data can be read.
Usually, Automation Builder module receives data for label printing using a trigger. E.g. if a file trigger is used, the content of trigger file is automatically read and can be parsed by filters. However, you might want to bypass filters to obtain some external data. Once you execute this action and have the data stored in a variable, you can use any of the available actions to use the data.
This action is useful:
-
If you must combine data received by the trigger with data stored in a file.
Warning
If you load data from binary files (such as bitmap image or print file), make sure the variable to store the read content is defined as a binary variable.
-
When you want to exchange data between triggers. One triggers prepares data and saves it to file (using the Save Data to File action), the other trigger reads the data.
File group defines the file to read the content from.
-
File name: location of the file to be read within this action.
Path and file name can be hard-coded, and the same file is going to be used every time. If only a file name without path is defined, the folder with NiceLabel Automation configuration file (.MISX) is used. You can use a relative reference to the file name, in which the folder with .MISX file is used as the root folder.
Data source: enables variable file name. Select a variable that contains the path and/or file name or combine several variables that create the file name. For more information see section Using Compound Values in NiceLabel Automation User Guide.
Note
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation User Guide.
Content group sets file content related details.
-
Variable: variable that stores the file content. At least one variable (existing or newly created) should be defined.
-
Encoding: encoding type for the sent data. Auto defines the encoding automatically. If needed, select the preferred encoding type from the drop-down list.
Note
Encoding cannot be selected if the data is read from a binary variable. In this case, the variable contains the data as-is.
Retry on Failure group defines how the action execution should continue if the specified file becomes inaccessible.
Tip
Automation Builder module might become unable to access the file, because it is locked by another application. If an application still writes data to the selected file and keeps it locked in exclusive mode, no other application can open it at the same time, not even for reading. Other possible causes for action retries are: file doesn't exist (yet), folder does not exist (yet), or the service user doesn't have the privileges to access the file.
-
Retry attempts: defines the number of retry attempts for accessing the file. If the value is set to 0, no retries are made.
-
Retry interval: time interval between individual retries in milliseconds.
This action deletes a selected file from a drive.
NiceLabel Automation module runs as service under a defined Windows user account. Make sure that account has the permissions to delete the file in a specified folder.
File group sets the file related details.
-
File name: the name of the file to be deleted. File name can be hard-coded. Data source dynamically defines the File name using an existing or newly created variable.
Path and file name can be hard-coded, and the same file is going to be used every time. If only a file name without path is defined, the folder with NiceLabel Automation configuration file (.MISX) is used. You can use a relative reference to the file name, in which the folder with .MISX file is used as the root folder.
Data source option enables variable file name. Select or create a variable that contains the path and/or file name or combine several variables that create the file name. For more information see section Using Compound Values in NiceLabel Automation User Guide.
Note
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation User Guide.
This action opens the system browse for file or folder dialog.
Dialog group sets the browsing preferences.
-
Browse for: selects between browsing for file or folder.
-
Filter: sets the file type to be located. Enter the file type manually, define the filters using a Define File Filters dialog or select Data source to determine the filter dynamically using a variable value. The Define File Filters dialog allows the user to:
-
List the filters. Each filter is identified with a Filter Name and Filter type.
-
Manage the existing filters using Add, Delete, Move up and Move down buttons.
Note
If you remove all filters, file type selection drop-down list will not be shown when the dialog opens.
-
-
Initial folder: sets the initial folder to be opened with action.
-
Dialog title: title of the file browser window that opens with action.
-
Allow non-existing file: enables browsing for a file that does not exist in the specified folder. This option allows you to store the path to a non-existent file in a variable and use it in a series of actions. The file can be created later using other actions, such as Save Data to File.
Output data source group selects a variable for file/folder path storing.
-
Save path to: existing or new variable for the file/folder path to be saved to.
This action executes all of the subordinate (nested) actions multiple times. All nested actions are executed in a loop for as many times as defined by the difference between start value and end value.
Note
For Loop action starts session printing mode – a printing optimization mode that prints all labels in a loop using a single print job file. For details, see Session Printing section in NiceLabel Automation user guide.
Loop Settings group includes the following options:
-
Start value: loop starting point reference. Select Data source to define the start value dynamically using a variable value. Select or create a variable containing a numeric value for start.
-
End value: ending point reference. Select Data source to define the start value dynamically using a variable value. Select or create a variable containing a numeric value for start.
Tip
Negative values are permitted for Start value and End value.
-
Save loop value to a variable: saves the current loop step value in an existing or a newly created variable. The loop step value is allowed to contain any value between start and end value. Save the value in order to reuse it in another action to identify the current iteration.
This action executes subordinate nested actions multiple times. All of the nested actions are executed in a loop as many times as there are records in the form table with a connected database.
You can use all records or selected records to execute subordinate nested actions.
The Settings group selects the records.
-
Form table: form table that contains records for which action should repeat.
-
Use all records: repeats an action for all records in a defined table.
-
Use selected record: repeats an action for the selected records only.
If you use the action Execute SQL Statement with enabled option Iterate for Every Record, NiceLabel automatically inserts For every Record action. A note appears about the automatic mapping of your variables.
|
|
|
Prompt variables on your label automatically connect to your database fields with the same names. See the instructions on how to create your solutions:
Important
When you create your solution with a database connection, use prompt variables on your labels instead of database fields.
Use the same names for prompt variables as are defined for database fields, for example:
Database field: food_products_1c.ProdCode
Prompt variable on your label: ProdCode
NiceLabel then automatically maps corresponding variables with database fields.
Example 121. Example
Your solution is connected to your database. You want to print selected records on your labels.
Use action For Every Record and nest actions to print your labels. Select the Use selected records option.
Select the records in your database table on your printing form, then print your labels.
This action allows you to:
-
monitor errors while the actions are being executed
-
run an alternative set of actions, if an error occurs
Try action creates Do and On error placeholders for actions. All actions that should execute if a trigger fires, must be placed inside the Do placeholder. If no error is detected when executing actions from Do placeholder, these are the only actions that ever execute. However, if an error does happen, the execution of actions from Do placeholder stops and the execution switches over to actions from On error placeholder.
Example 123. Example
If any action in the Do placeholder fails, the action execution stops and resumes with the actions in the On Error placeholder. If Try would be placed on its own, that would terminate the trigger execution. In our case, Try is nested under the For loop action. Normally, any error in Do placeholder would also stop executing the For loop action, even if there are still further steps until the For loop is complete. In this case, the Save Data to File action does not execute as well. By default, each error breaks the entire trigger processing. However, you can also continue with the execution of the next iteration in the For loop action. To make this happen, enable the Ignore failure option in the Try action. If the data from the current step in For Loop causes an error in the Do placeholder, the actions from On Error execute. After that, the Save Data to File in level 2 execute and then the For loop action continues to execute in the next iteration.
This action provides for an easy error detection and execution of "feedback" or "reporting" actions. For example, if an error happens during trigger processing, you can send out a warning. For more information, see section Print Job Status Feedback in NiceLabel Automation user guide.
Note
Important! The Try action gives expected results with asynchronous actions. If your Try loop includes the Print Label action that fails, the action execution still completes the Try loop, and does not switch to the On error actions as expected. The result for not switching to the On error actions is the Print Label action that runs in synchronous mode by default. To avoid this, make sure supervised printing is on. Go to trigger settings > Other > Feedback from the Print Engine and enable Supervised printing.
Note
Read more about supervised printing in section https://help.nicelabel.com/hc/articles/360021148458.
This action configures multiple actions within the same container. All actions placed below the Group action belong to the same group and are going to be executed together.
This action provides the following benefits:
-
Better organization and displaying of action workflow. You can expand or collapse the Group action and display the nested actions only when needed. This helps keep the configuration area cleaner.
-
Defining conditional execution. You can define a condition in the Group action just once, not individually for each action. If the condition is met, all actions inside the Group are executed. This can save a lot of configuration time and can reduce the number of configuration errors. Group action provides a good method to define IF..THEN execution rules for multiple actions.
This action returns structural information about the associated label file. It provides information about the label dimensions, printer driver and lists all label variables, and their main properties.
The Get Label Information action returns the original information as saved in the label file. Additionally, it also provides information after the print process has been simulated. The simulation ensures that all labels variables get the value as they would have during a normal print. Also, the label height information provides correct dimensions in case you define the label as a variable-height label (in this case, the label size depends on the amount of data to be printed). The action returns the dimensions for a label size, not for a page size.
The action saves label structure information in a selected variable. You can then send the data back to the system using the HTTP Request action (or a similar outbound data connectivity action), or send it back in trigger response, if you use a bidirectional trigger.
Note
This action must be nested under the Open Label action.
Variable group selects or creates a variable that stores the structural information about a label.
-
Name: specifies the variable name. Select or create a variable which stores the XML-formatted label information.
-
If you want to use the information from the XML inside this trigger, you can define the and execute it with Use Data Filter action (Automation Builder only).
-
If you want to return the XML data as a response in your HTTP or Web Service trigger, use this variable directly in the Response data field of the trigger configuration page.
-
If you want to save the XML data to a file, use the Save Data to File action.
-
Additional settings group allows you to enable the use of provisional values.
-
Use provisional values: replaces missing data source values with provisional values.
Tip
See section Variable in NiceLabel 10 user guide for detailed description of provisional values.
Sample Label Information XML
The sample below presents a structural view of the label elements and their attributes as they are returned.
<?xml version="1.0" encoding="UTF-8"?>
<Label>
<Original>
<Width>25000</Width>
<Height>179670</Height>
<PrinterName>QLS 3001 Xe</Printer>
</Original>
<Current>
<Width>25000</Width>
<Height>15120</Height>
<PrinterName>QLS 3001 Xe</Printer>
</Current>
<Variables>
<Variable>
<Name>barcode</Name>
<Description></Description>
<DefaultValue></DefaultValue>
<Format>All</Format>
<CurrentValue></CurrentValue>
<IncrementType>None</IncrementType>
<IncrementStep>0</IncrementStep>
<IncrementCount>0</IncrementCount>
<Length>100</Length>
</Variable>
</Variables>
</Format>
Label Information XML Specification
This section contains a description of the XML file structure as returned by the Get Label Information action.
Note
All measurement values are expressed in the 1/1000 mm units. For example width of 25000 is 25 mm.
-
<Label>: this is a root element.
-
<Original>: specifies label dimensions and printer name as stored in the label file.
-
Width: this element contains the original label width.
-
Height: this element contains the original label height.
-
PrinterName: this element contains the printer name for which the label has been created for.
-
-
Current: specifies label dimensions and printer name after the simulated print has been completed.
-
Width: this element contains the actual label width.
-
Height: this element contains the actual label height. If a label is defined as a variable-height label, it can increase along with label objects. For example, Text Box and RTF object sizes may increase in vertical direction and cause the label to expand as well.
-
PrinterName: this element contains printer name that will be used for printing.
Example 126. Example
A printer different from the original one is going to be used if the original printer driver is not installed on this computer, or if the printer has been changed using the Set Printer action.
-
-
<Variables> and <Variable>: the element
Variablescontains a list of all prompt label variables, each defined in a separateVariableelement. The prompt variables are the ones listed in the print dialog box when you print label from NiceLabel 10 . If there are no prompt variables defined in the label, the elementVariablesis empty.-
Name: contains variable name.
-
Description: contains variable description.
-
DefaultValue: contains default value as defined for the variable during the label design process.
-
Format: contains the acceptable type of variable content (characters).
-
IsPrompted: contains information whether or not the variable is prompted at print time or not.
-
PromptText: contains text that prompts the user for value input.
-
CurrentValue: contains the actual value that is used for printing.
-
IncrementType: contains information, if the variable is defined as a counter or not. If identified as a counter, it tells what kind of counter it is.
-
IncrementStep: contains information about the counter step. Counter value increments/decrements for this value on the next label.
-
IncrementCount: contains information about the point of counter value incrementing/decrementing. Usually, the counter changes value on every label, but that can be changed.
-
Length: contains maximum number of stored characters in a variable.
-
IsPickListEnabled: contains information whether or not the user selects variable values from a pick list.
-
PickListValues: contains the actual (selectable) pick list values.
-
XML Schema Definition (XSD) for Label Specification XML
<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="Format" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Label">
<xs:complexType>
<xs:all>
<xs:element name="Original">
<xs:complexType>
<xs:sequence>
<xs:element name="Width" type="xs:decimal" minOccurs="1" />
<xs:element name="Height" type="xs:decimal" minOccurs="1" />
<xs:element name="PrinterName" type="xs:string" minOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Current">
<xs:complexType>
<xs:sequence>
<xs:element name="Width" type="xs:decimal" minOccurs="1" />
<xs:element name="Height" type="xs:decimal" minOccurs="1" />
<xs:element name="PrinterName" type="xs:string" minOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Variables">
<xs:complexType>
<xs:sequence>
<xs:element name="Variable" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Name" type="xs:string" minOccurs="1" />
<xs:element name="Description" type="xs:string" minOccurs="1" />
<xs:element name="DefaultValue" type="xs:string" minOccurs="1" />
<xs:element name="Format" type="xs:string" minOccurs="1" />
<xs:element name="CurrentValue" type="xs:string" minOccurs="1" />
<xs:element name="IncrementType" type="xs:string" minOccurs="1" />
<xs:element name="IncrementStep" type="xs:integer" minOccurs="1" />
<xs:element name="IncrementCount" type="xs:integer" minOccurs="1" />
<xs:element name="Length" type="xs:string" minOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
</xs:schema>
This action executes commands that are included in a selected command file. All File type options provide commands that NiceLabel 10 executes in top-to-bottom order.
Command files usually provide data for a single label, but you can define files of any level of complexity. For more information, see section Command File Types.
File group defines the type and name of the command file that is going to be executed (JOB, XML or CSV).
-
File type. Specifies the type of the command file to be executed.
-
File name. Specifies the command file name.
File name can be hard-coded, and the same command file will execute every time. The option Variable enables a variable file name. Select or create a variable that contains the path and/or file name if a trigger is executed or an event takes place. Usually, the value to the variable is assigned by a filter.
Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
This action executes the entered custom NiceLabel commands.
Always nest this action under the Open Label action. This enables referencing the label to which the commands apply. For more information, see section Using Custom Commands in NiceLabel Automation user guide.
Note
Majority of custom commands is available with individual actions, so in most cases, custom commands are not required.
Note
Send Custom Commands action can be used to end the Session printing mode. This mode acts as a printing optimization mode that prints all labels in a loop using a single print job file. To end session printing, nest the Send Custom Commands action under the For Loop action and use the SESSIONEND command. For details, see sections Session Printing and Using Custom Commands in NiceLabel Automation user guide.
Script editor offers the following features:
-
Insert data source: inserts an existing or newly created variable into the script.
-
Script editor: opens the editor which makes scripting easier and more efficient.
This action reads the activated license and executes the actions nested below this action only if a certain license type is used.
Tip
Verify License action provides protection of your trigger configuration from being run on unauthorized machines.
Note
License key that activates software can also encode the Solution ID. This is the unique number that identifies the solution provider that sold the NiceLabel 10 license.
If the configured Solution ID matches the Solution ID encoded in the license, the target machine is permitted to run nested actions, effectively limiting execution to licenses sold by the solution provider.
The triggers can be further encrypted and locked so only authorized users are allowed to open the configuration. For more information, see section Protecting Trigger Configuration in NiceLabel Automation user guide.
License Information group allows you to select the license ID.
-
License ID: defines the ID number of the licenses that are allowed to run the nested actions.
-
If the entered value is not the License ID that is encoded in the license, the nested actions is not executed.
-
If the entered value is set to 0, the actions execute if a valid license is found.
-
Note
Digital Partner UID can also be used as License ID. This option is available for members of NiceLabel Digital Partner Program.
This action logs an event to NiceLabel Control Center for history and troubleshooting purposes.
Note
To make Log event action active, make sure that print job logging to NiceLabel Control Center is enabled.
Event Data group provides information about the logged event.
-
Information: basic description of the event that will be included in the NiceLabel Control Center event log. Up to 255 characters are allowed in this area.
-
Details: detailed description of the event to be logged in the NiceLabel Control Center. Up to 2000 characters are allowed in this area.
Tip
The descriptions entered in Information and Details fields allows you to filter out the events in Control Center All Activities History. When working with Control Center, go to History > All Activities > Define filter. For more details, read the Control Center User Guide.
This action executes the print process and provides label image preview. By default, the preview is saved to disk as JPEG image, but you can choose other image format. You can also control the size of the created preview image. The action generates preview for a single label.
Once you have the label preview created in a file, you can send the file to a third party application using one of the outbound actions, such as Send Data to HTTP, Send Data to Serial Port, Send Data to TCP/IP Port, or use it as response message from bidirectional triggers, such as and Web Service Trigger. The third party application can take the image and show is as label preview to the user.
Preview group defines the file to be previewed and its details.
-
File name: specifies the path and file name. If hard-coded, the same file is used every time. If you only use the file name without path, the folder with configuration file (.MISX) is used. You can use a relative reference to the file name, where folder with .MISX file is used as root folder. Data source option enables variable file name. Select or create a variable that contains the path and/or file name after a trigger is executed. Usually, the value to the variable is assigned by a filter.
-
Image type: specifies the image type which is used for saving the label preview.
-
Preview label back side (2-sided labels): enables preview of the back label. This is useful, if you use double-sided labels and want to preview the label's back side.
Example 132. Example
For example, if your label template defines dimension as 4" × 3" and the label printer resolution is set to 200 DPI, the resulting preview image has dimensions of 800 × 600 pixels. Width equals 4 inches times 200 DPI, which results in 800 pixels. Height equals 3 inches times 200 DPI, which results in 600 pixels.
Additional settings group allows you to enable the use of provisional values.
-
Use provisional values: replaces missing data source values with provisional values and displays them in the label preview.
Tip
Provisional value defines a custom placeholder variable value in an object while designing labels or forms. In a label object, the provisional value is replaced by the real variable value at print time.
This action allows you to create a review-ready variant of an existing label. Label objects in such variants have locked data source values. Their content is defined by the current value of the applicable data source.
The purpose of creating a review-ready variant of a label with “locked” data sources is to make the label suitable for approval process in which data and template need to be approved together. Instead of viewing a label without defined content for its objects, the approver reviews a variant with defined values. This allows him to quickly see and approve the final label layout with actual values that are going to be used for printing.
Tip
Label approval process is applicable to labels that are stored in Control Center Document Storage. You can apply various approval workflow types for the stored labels and label variants. Approval workflow selection depends on the requirements of your business environment. See NiceLabel 10 Control Center User Guide for more details.
Settings group defines the label file to be converted and the output file (label variant).
-
Label name: the name of the label file to be converted into a review-ready variant with locked data source values. Data source dynamically defines the Label name using an existing or newly created variable.
-
Print time data sources: this option allows you to define the data sources whose values are going to be provided at the actual print time. If a data source is listed in this field, its value is not locked and can be provided at print time. Typical examples are data sources for production values like LOT number, expiry date, etc.
Tip
Insert only data source names without square brackets, separated by commas or listed in a column using Enter key.
-
Output file name: the name of the label variant file that is going to be ready for review. Data source dynamically defines the Label name using an existing or newly created variable.
There are several rules that apply to the review-ready label variant:
-
Data source values are locked by default. To exclude the data sources from being locked, list them in Print time data sources field to keep them active on the review-ready label. You can define their values at print time.
-
Counter variables, functions, database fields and global variables are converted to non-prompted variables.
-
Graphics are embedded.
-
The destination label variant stored in NiceLabel Control Center Document Storage is automatically checked in. Original Label name and Print time data sources are used as check-in comment.
-
Label variants can be opened in NiceLabel 10 Designer in locked state.
-
Label files generated with this action cannot be imported.
-
If label variants are stored in printer memory, the recall command can only provide values for print time data sources.
-
If using NiceLabel Control Center, label preview in Document Storage allows editing of print time data sources.
-
Current time and current date variables cannot be set as Print time data sources on the review-ready label variant.
Certain objects accept multiple values as their content. Such content can be a combination of fixed values, variables and special characters (control codes). The objects that accept combined values are identified by a small right arrow button on the right side of the object. Click the arrow button to enter either a variable or a special character.
-
Using fixed values. Enter a fixed value for the variable.
-
Using fixed values and data from variables. Combined values may contain variables and fixed values. The variable names must be enclosed in square brackets
[]. Enter the variables manually or insert them by clicking the arrow button to the right. During the processing time, the values of variables are merged together with fixed data and used as the object content.In the example below, the content is merged from three variables and fixed data items.
-
Using special characters. Special characters are supported with combined values. You can enter the special characters manually, or insert them using a dropdown list. In this case, the value of
variable1is merged with fixed data and form-feed binary character. The list of available special characters is available here.
This topic describes best practice steps to use shared network resources.
The execution component of Desktop Designer runs in service mode under specified user account inheriting access privileges of that account.
To be able to open label files and to user printer drivers in Desktop Designer, the associated user account must be granted sufficient privileges.
When accessing the file on a network drive, use the UNC syntax and not the mapped drive letters. UNC is a naming convention to specify and map network drives. Desktop Designer will try to replace the drive-letter syntax with the UNC syntax automatically.
Example 137. Example
If the file is accessible as G:\Labels\label.lbl, refer to it in UNC notation as \\server\share\Labels\label.lbl (where G: drive is mapped to \\server\share).
When opening a file in Document Storage inside Control Center, use the HTTP notation such as http://servername:8080/label.lbl, or WebDAV notation as \\servername@8080\DavWWWRoot\label.lbl.
Note
You must first add and configure the users that work with files stored in Document Storage in your Control Center. Read more about user management in the https://help.nicelabel.com/hc/categories/360003767257.
To print labels using a network shared printer, make the printer driver available on the server where Desktop Designer is installed on.
Make sure the user account that Desktop Designer runs under has access to the printer driver. If the network printer was just installed on the machine, Desktop Designer might not see it until you restart the Service.
Tip
To allow automatic notification of new network printer drivers, you have to enable the appropriate inbound rule in Windows firewall. For more information, see the Knowledge Base article.
If Desktop Designer attempts to load a label or image file, and this file is not immediately found, it neither cancels the processing nor does it report an error. It tries to locate the requested file at alternative locations.
Desktop Designerchecks file locations in the below listed order:
-
Check if the file exists at the location as defined in the action.
-
Check if the file exists in the same folder as solution or label file.
-
Check if the label file exists in
.\Labelsfolder (for graphic files, check.\Graphicsfolder). -
Check if the label file exists in
..\Labelsfolder (for graphic files, check..\Graphicsfolder). -
Check if the file exists in the global Labels folder (Graphics folder for graphics files).
If the file cannot be found at any of above listed locations, the action fails. An error is raised.
|
Spooler status ID (in hex) |
Spooler status description |
|
0 |
No status. |
|
1 |
Printer is paused. |
|
2 |
Printer is printing. |
|
4 |
Printer is in error. |
|
8 |
Printer is not available. |
|
10 |
Printer is out of paper. |
|
20 |
Manual feed required. |
|
40 |
Printer has a problem with paper. |
|
80 |
Printer is offline. |
|
100 |
Active Input/Output state. |
|
200 |
Printer is busy. |
|
400 |
Paper jam. |
|
800 |
Output bin is full. |
|
2000 |
Printer is waiting. |
|
4000 |
Printer is processing. |
|
10000 |
Printer is warming up. |
|
20000 |
Toner/Ink level is low. |
|
40000 |
No toner left in the printer. |
|
80000 |
Current page can not be printed. |
|
100000 |
User intervention is required. |
|
200000 |
Printer is out of memory. |
|
400000 |
Door is open. |
|
800000 |
Unknown error. |
|
1000000 |
Printer is in power save mode. |