Aug 082016

Working with DYMO Label Web Service

Download Word Version of this post

Download PDF Version of this post

What is the DYMO Label Web Service?


In the past, developers had to provide a browser-specific plug-in for each major web browser.  Nowadays, most browsers have phased out native plug-in support.  Google, for example, stopped supporting Chrome their NPAPI browser extension in September 2015.  In response, we released the DYMO Web Service as a new cross-browser solution allowing third-party developer applications the ability to interface with the DLS SDK in a seamless, browser-agnostic fashion.  It handles all printer-related requests from the JavaScript Library that the DYMO Label Framework browser plug-ins used to perform.

(For more information on the framework, please visit


How do I install the DYMO Label Web Service?


First, download the appropriate installer for your OS.  You can find them at the following URL:



Double-click on the installer and follow the directions provided by the install wizard.


Double-click on the DMG file to mount it.  Select the newly mounted volume and double-click on the PKG file found within it.  Then follow the directions provided by the install wizard.

How can I tell if I have DYMO Label Web Service installed?


The DYMO Label Web Service is installed as long as you have installed DYMO Label Software 8.5.3 or newer using the express “Express” mode.

If you choose to install DYMO Label Software in “Custom” mode, be sure to select the DYMO Label Web Service component as follows:


Custom select components to install







If installed, there will be an executable file named DYMO.DLS.Printing.Host.exe within the DLS working folder (normally found within the C:\Program Files (x86)\DYMO\DYMO Label Software folder on Windows and the /Library/Frameworks/DYMO/SDK folder on Mac).



Executable location (Windows)

Executable location (Windows)


How can I tell if the DYMO Label Web Service is running?

You should see the DLS application icon within the system tray.  Right-click this icon to display a context menu.  The menu displays the web service’s status (i.e., “Started on port 41951” or “Stopped”).

The following shows what it looks like on Windows.

DLS icon and context menu (Windows)

DLS icon and context menu (Windows)


On Mac, the DLS application icon and context menu will appear within the system tray like this:

DLS icon and context menu (Mac)

DLS icon and context menu (Mac)

I do not see it in the system tray.  How can I start it?



You can start the web service again by navigating to the DLS working folder and running the executable named DYMO.DLS.Printing.Host.exe.


Open a Finder window, navigate to the /Library/Frameworks/DYMO/SDK/ folder, and click on the icon.

Open a terminal prompt and enter the following command:

launchctl start com.dymo.dls.webservice


How can I start or stop the DYMO Label Web Service?

You can start or stop the web service at any time by open right clicking on the service’s icon in the system tray and choosing the Start service and Stop service menu items, respectively.  Although API functions will not execute after stopping the service, the service icon will remain in the system tray after stopping it.


How can I configure the DYMO Label Web Service?


Clicking the Configure menu item will cause a configuration window to appear.  This allows you to change the language and listening port.  The web service will normally try to use the first available port within the 41951-41960 range.  You can override this behavior by checking the Use single port checkbox, which makes the service only try using the specified port only. You cannot specify a port number that does not fall within the specified range.  The service will not try using any other port if an error occurs while using this option.

Web Service configuration dialog (Windows)

Web Service configuration dialog (Windows)



Web Service configuration dialog (Mac)

Web Service configuration dialog (Mac)



How can I tell if the DYMO Label Web Service is functioning properly?

Click the Diagnose menu item within the context menu while the service is running.  If the self-test succeeds, a dialog box will appear asking you to open a test page in your browser to see if SSL certificate is working.


Diagnose successful (Windows)

Diagnose successful (Windows)

Diagnose successful (Mac)

Diagnose successful (Mac)


Click the Yes button to open your default web browser.  The browser should display a page indicating the web service is running correctly.  The page address should be something to the following effect:


The port number may vary from machine to machine.


Web Service is up and running configuration

Web Service is up and running configuration


How do I use the DYMO Label JavaScript Library?


Getting Started

You need to link to the DYMO Label Framework’s JavaScript library in order to use the DYMO Label Web Service via web pages.  You accomplish this by using the following code snippet:

 <script src="dymo.label.framework.js" type="text/javascript" charset="UTF-8"></script>

Your code then needs to call the following initialization method while providing it a callback to be invoked by the library when initialization completes:


The library invokes this callback whether or not initialization completes successfully.


Do I need to change my code to work with the new DYMO Label JavaScript Library?

Although it may work with old unmodified code in some cases, it is highly recommended to make a few changes to avoid future problems.

The biggest change to the JavaScript Library is the move from a synchronous architecture to an asynchronous one.  This move has several advantages, improved UI responsiveness and shorter discovery time while scanning the available port range.  Synchronous AJAX calls are already marked deprecated in most major web browsers, so we recommend switching to asynchronous JavaScript Library initialization as soon as possible.


What will happen if I leave my old code unchanged?

If you do not update your code to make use of asynchronous calls, the JavaScript Library will fall back to the synchronous behavior upon accessing the library for the first time when a page is loaded.  It will synchronously try to scan the first port.  This is either the default port or the last known working one (i.e., the cached port number).  The library will use web service-based functionality if it successfully connects to the port.  Otherwise, it will fall back to using native plug-ins.  All subsequent calls to the library will continue to reuse whatever method succeeded until you reload the page.


What do I need to change in my code to make it properly work with new the JavaScript library?


The library now makes use of a new initialization method to perform asynchronous initialization through use of a callback method.  Since the library performs initialization in the background, calling an SDK function prior to initialization results in an error.  Your code should be updated to call the new dymo.label.framework.init() method while providing it a callback to be invoked by the library when initialization completes.  Please note the library invokes this callback whether or not initialization completes successfully.

Any code initialization involving calls to the JavaScript Library is typically located inside an event handler (i.e., window.onload).  Below is typical JavaScript code demonstrating how to do this with the old synchronous architecture:

function startupCode() {
/* access DLS SDK */

window.onload = startupCode;

This code will not work correctly under the new asynchronous architecture.  It should be changed to call an intermediate “helper” method that firsts calls new init() method accepting your callback as a parameter.  The library invokes the callback containing your original startup code after library initialization completes.  Below is the updated JavaScript code that uses asynchronous initialization:

function startupCode() {
/* access DLS SDK */
function frameworkInitHelper() {
// init, then invoke a callback


window.onload = frameworkInitHelper;

If initialization is asynchronous, are other methods asynchronous as well?

The short answer is, “Yes!”  As stated previously, synchronous AJAX requests are deprecated, so our new JavaScript library contains new asynchronous equivalents for every method that calls the web service.  These methods have the same names as their counterparts in the former architecture along with the Async suffix appended to them.  They take the same number of parameters with corresponding types as well.  The only major difference is that the new methods return a Promise object instead of the actual return value.  You make use of this object by providing its then() method your callback function and one argument which receives the actual return value when the asynchronous method completes.

 dymo.label.framework.getPrintersAsync().then(function(printers) {
// printers list (same list the getPrinters() returns)


How do I make use of Promise objects in asynchronous programming?

Asynchronous JavaScript programming is not covered here. Please refer Google’s documentation on Promise object usage and errors handling:

How can I tell if the JavaScript library is currently using the web service?

The dymo.label.framework.checkEnvironment() method returns a CheckEnvironmentResult object along with multiple parameters (please refer to existing documentation on checkEnvironment() method).  The new JavaScript library contains an additional property within this object called isWebServicePresent.  You can use this property to determine if the web service is actually used.

As with all other SDK-related methods, do not call checkEnvironment() until init() finishes initializing. Synchronous library initialization and web service discovery will occur if it is called before init() completes.

Basic Service API Functions


The following is a list of basic API functions provided by the DYMO Label JavaScript Library.


Purpose:  Returns a list of installed DYMO printers
Parameters:  None.

printers = dymo.label.framework.getPrinters();
for(var i = 0; i < printers.length; i++)
var printer = printers[i];


Purpose:  Returns a document object model (DOM) for label file.

labelUri – label file Uri


 var labelUri = "file:///Volumes/DATA/DieCut.label";
var label = dymo.label.framework.openLabelFile(labelUri);


It is necessary to use the label.getLabelXml() or label.toString() functions to obtain XML representations of a label.


dymo.label.framework.renderLabel(labelXml, paramXml, printerName)


Purpose:  Returns a graphic representation of the label (PNG) encoded in base64 format.

labelXml – DOM or XML representation of the label

paramXml – render parameters

printerName – printer name


 var image = document.createElement('img');
var labelXml = dymo.label.framework.openLabelFile(labelUri).getLabelXml();
var pngData = dymo.label.framework.renderLabel(labelXml, "", printerName);
image.src = "data:image/png;base64," + pngData;

dymo.label.framework.printLabel(printerName, paramXml, labelXml, labelSetXml)


Purpose:  Prints a label on the specified printer.

printerName – printer name

paramXml – printing parameters

labelXml – DOM or XML representation of the label

labelSetXml – data set for label objects


 var paramsXml = dymo.label.framework. createLabelWriterPrintParamsXml ({ copies: 2 });
var labelSetXml = new dymo.label.framework.LabelSetBuilder();
var record = labelSet.addRecord();
record.setText("Address", "Test Address String");
dymo.label.framework.printLabel(printerName, paramsXml, labelXml, labelSetXml);




What is Trace functionality?

Our JavaScript Library now includes trace functionality that may help you debug your code.  You can enable it by adding the following code vline before calling the init() method:

dymo.label.framework.trace = 1;

When using this code, you will see which steps the library takes every time it attempts to initialize (i.e., synchronous vs asynchronous initialization, port number if web service is discovered, fallback implementation selection, etc.).

Below is sample trace output when init() is called and the web service is present:

checkEnvironment > cachedWebPort : 41951
checkEnvironment > trying async service discovery
_createFramework > return _framework : undefined (async)
onEnvironmentChecked > checkResult isBrowserSupported : true, isFrameworkInstalled: true, isWebServicePresent: true
chooseEnvironment > WebServicePresent

The following is an example for case when init() is not called but the web service is running (fallback mode for legacy user code):

checkEnvironment > cachedWebPort : 41951
checkEnvironment > trying sync service discovery
Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user’s experience.
checkEnvironment > web service found at port :41951
onEnvironmentChecked > checkResult isBrowserSupported : true, isFrameworkInstalled: true, isWebServicePresent: true
chooseEnvironment > WebServicePresent

This sample output demonstrates the case when the web service is not running (fallback mode for legacy plug-ins).  Here the init() method was called; not calling the init() method will eventually lead to same fallback behavior but will additionally result in a hung UI during the initialization phase):

checkEnvironment > cachedWebPort : undefined
checkEnvironment > trying async service discovery
_createFramework > return _framework : undefined (async)
checkLegacyPlugins > WIN platform
checkLegacyPlugins > non-IE
checkLegacyPlugins > ‘application/x-dymolabel’
onEnvironmentChecked > checkResult isBrowserSupported : true, isFrameworkInstalled: true, isWebServicePresent: false
chooseEnvironment > WIN


How do I perform error logging?

Improper DYMO Label SDK usage or multiple unexpected external factors may result in errors.  You may need to retrieve logging data in these cases to help resolve problems.

Network and web service errors

To see communication errors and service fault messages, you will need to open Developer Tools (invoked by F12 key in most browsers) and open “Network” tab. If you see erroneous response in the list, you can click it and look for details in adjacent window (look and position is browser-specific). Response body would normally contain error description.

Web service log

The log file is located at %LocalAppData%\DYMO\DLS8\DLSWebService.log

If you are performing some specific tests, we recommend you delete the existing log before making a test run to eliminate any unnecessary log messages.

Aug 032016

There has been a lot of confusion out there among our developers as to whether they should use the DLS installer or the SDK installer within apps that make use of our DYMO printers.

Let’s try to clear this up as it isn’t immediately obvious what each installer is used for.

Our DLS installer contains everything needed to integrate printing functionality within your app.  This is what needs to be installed in order for your apps to work.

The SDK installer, on the other hand, contains documentation and samples that describe how to make use of the functionality found within the DLS SDK.  The “SDK installer” isn’t really named appropriately and will probably be renamed in future releases for the sake of clarity.

The DLS installers for both Windows and Mac can be found at the following URL:

The SDK installers for both Windows and Mac can be found here:


Hopefully, that clears things up a bit.

Jan 052016

I hope everyone enjoyed their holidays!  We have had a number of issues reported, several of them were big enough that we decided to release an 8.5.3 patch version that fixes the issues that were found.

Issues Fixed:

  • Win: There were instances that caused Barcode corruption when the Barcode was rotated on a label
  • Mac: There were issues with with the Web Service refreshing the list of DYMO printers
  • Mac: Web Service method timeout is increased due to too many timeouts
  • JS: Fixed issues with Async calls
  • JS: Fixed Issue that isBroswerSupported return the wrong value
  • JS: Fix Issue with a Crash when running in IE8

Reference the following posts for additional set up information.  Keep in mind that the Web Service is built into this version of DYMO Label so the standalone install is no longer required.


Thanks for all the great feedback!  Let us know of any issues found, we’ll continue to give the best support we can.

Update: Fixed a typo that was referencing the wrong revision number for the Windows build

Dec 142015

We are proud to announce the release of DYMO Label software version 8.5.3 for Mac.

UPDATE: The newest version is available in the following post: DLS 8.5.3 Patch Release

This release includes:

  • Support for OS X El Capitan
  • Support for Microsoft Office 2016
  • DYMO Label Web Service is installed for use by the DYMO Label Framework.

You can now download: DYMO Label software 8.5.3
You can also download the JavaScript Library : DYMO Label Framework 2.0

The JavaScript library is the same as the one posted in the DLS Windows release so the information in the following posts apply to the Mac version of the SDK. Keep in mind that the Web Service is built into this version.

Thanks again for everyone’s patience.  We were not able to do a Beta on the Mac version but it contains all the feedback that we got from the Windows Beta.  If there are any issues, please either post on the blog or send an email to sdkreply at newellco dot com.  We’ll be monitoring both looking for issues and will try to respond to issues as quickly as possible.  Keep in mind the more information that you include in your post/email, the better we will be able to help you.

It should be noted that the JavaScript Samples that are in older posts on the blog have not been updated to incorporate the web service correctly.


We’ve had some reports from our users that a reboot may be required for the DYMO Web Service to get properly configured.  We are looking into this further.  The way you know you are in a state that requires a reboot is as follows:

  1. Click on the DYMO icon in the upper right on the top menu bar
  2. Select Diagnose
  3. If a dialog pops up and it complains about no ssl assigned to the port, you should reboot.
  4. If you see a dialog that says “DYMO Label Web Service is running on port XXX”, then there could be a different issue.



Dec 082015

We are proud to announce the release of DYMO Label software version 8.5.3 for Windows.

UPDATE: The newest version is available in the following post: DLS 8.5.3 Patch Release

This release includes:

  • Support for Microsoft Windows 10
  • Support for Microsoft Office 2016
  • DYMO Label Web Service is installed for use by the DYMO Label Framework.

You can now download: DYMO Label software 8.5.3
You can also download the Javascript Library : DYMO Label Framework 2.0

Reference the following posts for additional set up information.  Keep in mind that the Web Service is build into this version of DYMO Label so the standalone install is no longer required.

We also know that you are interested in the Mac version.  We have had a lot of issues getting the design to work on Mac OSX, we have hit a major milestone this week and we now have a release candidate for DLS 8.5.3 for the Mac.  If everything passes, we should be able to release it within a work week.

As a note to all our patient customers, we really appreciate you and your patience.  This has been a more difficult release than we had thought but it is finally happening.  All we have now is the imminent MacOSX release.   Thank you!

Update: Added link to new Javascript library version and added links to older posts for references

Sep 302015

Hello everyone,

A lot of our SDK users are running into a particular issue printing barcodes where they will be clipped or not printed at all. The issue is actually being caused by a bug in the .NET Framework (v4.0 and newer), specifically in XPS printing. The trigger for the issue is when our printers go into “Barcode and graphics” mode. Unless manually overridden, the DYMO SDK will switch the printer to “Barcode and graphics” mode whenever a barcode or image object is present on the label. When in this special mode, the resolution of the printer changes from 300 x 300 DPI to 300 x 600 DPI. This “non-square” resolution is not handled correctly by XPS and causes the clipping issues.

Below is an example of this issue. The label on top is OK while the label on the bottom is printed with the issue.


What you may notice is the label with the issue stops printing at a distance across the label that is equal to the width of the label. This is the crux of the XPS bug and as you can see, also affects other label object types as well.


Now that we understand the issue a little better, what can we do about it? Let me start by saying that we have made Microsoft aware of this issue. Since there are no guarantees they will fix the problem, we are currently working on a solution that will be pushed out in a future update of DYMO Label Software. In the meantime, you have a few choices for working around the issue:

  • Design your label in portrait orientation. For most label types, the issue will not arise if the label is printed in portrait orientation. By using the object rotation feature in DLS, you can easily design a label in portrait orientation that will look identical to one designed in landscape orientation.
  • Compile your SDK applications against .NET 3.5. As mentioned earlier, the issue is with .NET Framework versions 4.0 and newer. Current versions of DLS are compiled against .NET 3.5 so you will not see this issue when printing from DLS. However, if you are compiling your SDK application against newer versions of .NET, when your application runs, the newer version of the framework will be loaded. Even though the DYMO SDK binaries are compiled against 3.5, .NET backwards compatibility will kick in and the newer version will be used instead. So, to take this approach, you will need to compile your SDK application against .NET 3.5.
  • Force the print job into “Text” mode. In the DYMO Framework, you can override the print quality setting using the ILabel.Print(IPrinter, IPrintParams) API. An example of how to override this setting can be seen below (the parameter used to change the print quality is marked in bold):

    LabelWriterPrintParams prms = new LabelWriterPrintParams(1, "print job 1", FlowDirection.LeftToRight, RollSelection.Auto, LabelWriterPrintQuality.Text);
    _label.Print(printer, prms);

Thanks for bearing with us on this issue. Rest assured we are working hard to get the fix out. In the meantime, we hope this blog post will help you get your labels printing correctly.

Sep 242015

We apologize for the length of the delay in this release but we ran into a number of unforeseen issues trying to fix a couple of the bigger issues that were brought to our attention. The two issues that we are addressing in this release are problems with HTTPS and Network Printer discovery.


Network Printers

This was a big issue. A service running on windows will not see Network/shared printers for a user and there are Microsoft bugs that prevent seeing these printers when the service is run as the current user. With that in mind, we had to re-implement the way the service is run. It is now a service that starts when the user logs in. This Service will appear in a user’s application tray and can be configured from there. This will allow the SDK to see any Network/Shared Printers that the user has installed.


Our JavaScript library now connects to the web service via HTTPS. We have to install a self-signed certificate to allow this to happen. After installation finishes, we will ask the user if they want to open up the default browser to accept the certificate. Once the certificate is accepted then all HTTPS traffic should work as normal. You can install the certificate on other browsers by going to “https://localhost:/DYMO/DLS/Printing/Check”. This is important for the Firefox browser.

New Tray application

The new tray tool has several options:

  • Start/Stop the Service
  • Configure: Which will let you specifically configure a port within the approved range.
  • Diagnose: This will confirm that the service is running and identify the port.


  • The KB2954953 patch no longers needs to be applied for the service to work
  • We’ve seen some issues where the service needs to run with elevated permissions to see the printers. We are working on this issue.
  • We’ve seen some crashes when the service starts or at the end of the install. We are investigating but you should be able to start the service from the C:\Program Files (x86)\DYMO\DLS Web Service\DYMO.DLS.Printing.Host.exe
  • The Mac version is being tested right now and we hope to have a version released soon.

We appreciate your patience! We are working on this as hard as we can and understand your frustrations with delays. We want to insure that we release a quality product that can meet your demands. Your feedback is valuable to us!

Aug 202015

We are proud to announce the Open Beta of the new DYMO Label Framework JavaScript Library 2.0. This solution uses a new communication mechanism that will work on all browsers. This means that we have removed the dependency of browser specific plugins like NPAPI and Active-X. The current DYMO Label Framework API is fully supported.


The new init method

Since the new communication protocol needs to discover the port that the DYMO service is listening on, a new method was introduced, dymo.label.framework.init(callback). This method performs a scan of a range of ports to look for the DYMO service. This method needs to finish before any other DYMO Framework API calls are made. To accomplish this, the method takes a callback method that will be called as soon as the dymo.label.framework.init method finishes.

Backward Compatibility Mode

If the dymo.label.framework.init method is not called (i.e. no user code has been changed) then the Framework goes into backward compatibility mode. It will try to scan the first port in the defined range and if it finds the service, the new communication protocol will be used. If it fails, it will fall back to the previous implementation that uses native plugins (NPAPI/Active-X).

Init Example

Typical startup code where a method is subscribed to an onload event:

function startupCode() {
    /* access DYMO Label Framework Library */
window.onload = startupCode;

The code should be changed to call a shim that will initialize the DYMO Framework before calling the rest of the startup code.

function startupCode() {
    /* access DYMO Label Framework Library */
function frameworkInitShim() {
    dymo.label.framework.init(startupCode); //init, then invoke a callback
window.onload = frameworkInitShim;


We have added a new tracing feature. This can be used to help debug issues with the new service. The property is called dymo.label.framework.trace. When set to true, it will put tracing messages in the browser developer console. You should set the trace property before calling the dymo.label.framework.init method:

Tracing Example

dymo.label.framework.trace = 1; //true

Known Limitations

  • The port number that the service binds to is not user definable. We tried to use a range of ports that are not typically used but there could be port conflicts.
  • HTTPS: Because the service currently uses insecure (http) requests, some browsers may have some issues. For example, Firefox will block insecure XHR requests when a page is loaded through HTTPS. So in order to enable it, the user has to click icon in the address bar and enable insecure requests within a secure connection.
  • As stated in the requirements, a Microsoft patch is typically required on Windows 8 and greater.
  • MacOSX support is not included in this Beta, we are working on it now and we will post more news about this version soon.
  • As with DLS, we do not support Windows Server configurations.

To Do

  • A new version of the DYMO Label Software 8.5.2 will become available. This version will include the new Framework implementation and will be considered the Release version of the new Framework. This is expected to be released near the end of September.
  • Service Configuration (Port Number): Currently, the service will bind to the first available port within a given range. We will add a parameter that will allow a user to assign a particular port within the given range.
  • Investigate the best way to work over HTTPS without issues
  • We are implementing asynchronous versions of existing API methods
  • Take constructive feedback and bug reports from our Beta Customers. We will be releasing new versions of the Beta as we respond to issues found in the field.

Update 08/28/2015

If the Web Service fails to install, try and turn off your Anti-virus software before installing.


Update 09/09/2015

We apologize for the delay of the next version of the Beta.  We’ve have been working on full HTTPS support, for which testing is ongoing, we found some issues and want to fix them before releasing.  We’ve also reproduced the service not recognizing networked printers.  We are investigating the possible solutions since it appears to be a limitation of what the service has access to.  We’ll keep you informed of any developments.

Aug 102015

As many of you know, Google is removing support for NPAPI in the Chrome browser. Our existing JavaScript SDK utilizes this API. We have been diligently working on a new communication mechanism that will work on all browsers and will avoid such things as NPAPI and Active-X and will decouple the SDK from browser specific implementations.

The good news is that we are currently testing our new communication protocol and it will be ready for a Beta release soon.

We have worked hard to make sure that the new SDK will be backwards compatible. There will be the addition of an initialization method, but the existing API works the same.

Our new SDK will utilize TCP/IP to communicate between the browser and a Windows service running on the client machine. The new service will be installed with DLS when upgrading to the new version. A range of ports will be available for our windows service, if the browser cannot bind to one of the ports, it will fall back to our legacy plug-in architecture. For additional security, the service will accept connections only from localhost.
Stay tuned to this blog for more information.