Troubleshooting guides: BarTender Print Portal Follow

Avatar
Samantha Petro

This articles applies to BarTender 2016 and later. As BarTender Print Portal is different between versions, please select your version from the dropdown above.

BarTender Print Portal is the web-based application that allows users to print anywhere by accessing the website where Print Portal is hosted. The application lives in Internet Information Services (IIS) and runs on top of a .NET core. This article will help familiarize you with some of the components and how to work with common issues. This is by no means an extensive list, but it should help to get you started. This guide is meant to help troubleshoot issues on BarTender's side as troubleshooting IIS is a bit out of scope of this article.

In order to troubleshoot any version of BarTender Print Portal, make sure you are running the latest release of your version so you do not try to troubleshoot an issue which may be already fixed. Please see How to Update to the Current Revision of BarTender for assistance on how to do this.

You will also want to have the IIS web management console installed on your system. You can find this console under Windows Features or Server Features. If you have trouble locating the features list, please contact your IT for assistance.

 

Components of BarTender Print Portal

BarTender Print Portal relies on a number of components to operate, including several services that help keep the application upright. Here are some of the key services:

  • BarTender System Service - responsible for communications with the BarTender system database
  • BarTender Print Scheduler service - handles print engines mentioned in the next section
  • .Net/Tcp Port Sharing Service - a Windows service that helps with communications between BarTender Print Portal and BarTender Print Scheduler for printing jobs

In addition to the services used for operation, here are two major components in detail: 

 

Print engine

Print engines are essentially BarTender Designer running as a service, starting and stopping dynamically as needed to handle BarTender Print Portal's demands. These print engines are maintained by the BarTender Print Scheduler service and require no user interaction to operate.

When a user creates a print job by clicking the print button, a print engine is automatically started if one is not already running. It opens the document, processes any data sent from BarTender Print Portal, then sends a print job to the Windows Print Spooler to send to your printer. In BarTender 2021 and later, print engines are also responsible for rendering the label previews.

 

System database

The system database is a SQL database that operates behind the whole of the BarTender Suite. This could be a local database installed via the Administration Console or the installation wizard or a centralized database hosted on a dedicated server.

In all versions of BarTender, the system database is required to run BarTender Print Portal. The application will not operate without it.

 

Permissions for normal operations

BarTender Print Portal requires certain permissions for normal operations. This isn't permissions for controlling access for individual users but instead permissions the components to do their job effectively. These permissions allow BarTender Print Portal to do the following:

  • Access labels, open them, and print them
  • Access printers, locally or on the network
  • Access the Active Directory users and groups list (for BarTender 2021 and later)
  • Access Librarian

This is by no means an exhaustive list but it covers some of the key functionality that BarTender Print Portal requires to operate. By default, BarTender Print Portal operates on a local administrator account that has access to locally installed printers and the Print Portal directory on your system, but sometimes that isn't enough and permission checks fail.

There are three main points of potential permissions issues: the BarTender Print Scheduler Service, the IIS App Pool Identity, and the system database login.

For the Print Scheduler Service and the App Pool Identity, you will need a Windows account with the following properties:

  • Be a local administrator, since it will need access to the Print Portal file directory
  • Have domain-level access, if you plan on using domain resources such as printers or network drives. It does not need to be a domain administrator.
  • Have permissions to read the list of users and groups in the Active Directory (for BarTender 2021 and later)
  • Not change its password. You don't want permissions errors if your password policy kicks in a few months down the road.
  • Have the local logon group policy permission. It cannot run a service or an app pool without it
  • Have permissions to access the system database. This one is only required if you use Windows Authentication.

It is recommended that you use the same account for the Print Scheduler as the App Pool identity. You can add the account to the service first to test the permissions as the App Pool Identity tends to not give error messages when a permission is lacking.

For the system database, it is recommended you use SQL authentication to avoid any permissions issues with Windows authentication. For more information, please see Configuring permissions to a System Database (Video - 5:45).

 

Setting BarTender Print Scheduler Service permissions

To change the account on the Print Scheduler service, please do the following:

  1. Open the Windows services list by searching for it in the Start Menu or locating it in the Control Panel.
  2. Scroll down to the BarTender Print Scheduler service.
  3. Right click on the service and go to Properties.
  4. Click the Log On tab.
  5. Select "this account" and enter the username and password. Remember to add the domain name else the service will attempt to start with a local account

service_permissions2.png

  1. Once you have entered the credentials, click OK and proceed to click through the notifications about changing an account.
  2. Right click on the BarTender Print Scheduler service and select Restart to reboot the service under the new account.

If you receive any errors during startup, double check that the account has all the permissions listed in the previous section and repeat these steps again.

 

Setting IIS App Pool Identity permissions

To change the account on the IIS App Pool Identity, please do the following:

  1. Start the Internet Information Services (IIS) Manager.
  2. Click the arrow next to your server name to open the tree
  3. Click Application Pools
  4. Right click on the BPP_AppPool and select Advanced Settings
  5. Scroll down and locate the Identity setting. The identity will likely have a boldened value as it is set to a custom local Identity that BarTender has created for it.
  6. Click on Identity then click the button to the right of it with the elipsis [...] on it. This will open up the settings dialog.
  7. Click the Set button

appPoolIdentity.png

  1. Type the full username and password into the box. Remember to add the domain name so that the App Pool knows to use a domain user instead of a local one.
  2. Click OK and close all the dialogs, returning you back to the IIS manager.
  3. With the BPP_AppPool still selected, click Stop on the right hand menu then Start. This will restart the App Pool to run on the new account.

If any error messages show up, double check that the credentials entered are correct and that the account meets all the requirements listed in the previous selection.

 

Compatibility

To ensure that BarTender Print Portal runs smoothly, it must be run on a compatible operating system. You can see the list of compatible operating systems and versions here: BarTender supported Windows versions. When you run BarTender Print Portal on an operating system it is not compatible with, for example BarTender 2021 on Windows Server 2008, services and print engines may not run properly and you may experience crashing or irregular behavior during print time. To avoid this, check the list before installing BarTender Print Portal.

It is also recommended you match the bitrate of BarTender to the bitrate of the operating system. If you are running 64-bit Windows, install 64-bit BarTender to match it. This ensures compatibility with IIS and the BarTender services, and that print engines are running efficiently.

 

Troubleshooting BarTender 2021 and later

Click on the symptom or error message to expand the section for troubleshooting steps.

Print Scheduler could not be reached

BarTender Print Portal relies on the BarTender Print Scheduler service to create thumbnails, generate print previews, and print a job. If Print Portal is unable to contact the service to use it, you may see an error like this one:

noPSS2021.png

There are a number of reasons for this error including the service has been stopped via command line or in the services snap in, the account running the service has changed its password, or something has interfered with communications.

To get the service back up and running, please do the following:

  1. Start the Services snap in by searching for it in the Start Menu.
  2. Scroll down to the BarTender Print Scheduler service.
  3. If the service is stopped, right click it and select Start. If the service is running, right click and select Restart.

If you receive an error message about username or password being incorrect, see Setting BarTender Print Scheduler Service permissions

If you continue to have trouble, even after trying all these steps, check the compatibility between your operating system and BarTender version. If you are using an incompatible combination, the application and services may be having difficulty talking to each other. Please see the compatibility section for more information.

 

Print job aborted: file could not be opened, read, or accessed

This error message is a sort of catch-all for file errors and generally refers to two things: permissions or missing linked files. Here is an example and how to break down this error message:

file_error_2021.png

  • Next to "Print Job Aborted" is the condition that created the error. In this example, it is a record set aka a linked database. So the label file is having problems opening the database.
  • The second line says what cannot be opened. In this case, it is a csv database.
  • The third line gives some brief details about what's wrong. In this case, it couldn't find this file or locate the folder that's been defined.

So this error message is saying that the file does not exist in the location specified in the label file or the Print Scheduler service does not have permissions to reach the directory, so it appears to be missing.

When you encounter errors like this, the first step is to open the label file.

  • Do any error messages pop up?
  • Can you browse the database in the data setup dialog or does the dialog say it cannot connect to the database?
  • Do you have missing pictures with red Xs on them?
  • Can you print the label from BarTender Designer or do error messages show up?

If any of these show up, you'll need to correct them before you can print this label.

If you find that the label is printing just fine, then you may have a permissions issue. If the Print Scheduler service is unable to obtain any of the linked resources like pictures and databases to properly print the job, you'll see this error as well. To correct this, please see the permissions section on how to correct the issue.

 

Users or groups list appears empty when setting permissions

When you attempt to set permissions for folders in BarTender Print Portal, your dialog appears to be empty when you select Domain as your location such as in the screenshot below:

groupsEmpty.png

This means that BarTender Print Portal was unable to retrieve the Active Directory users and groups. It does not have permission to do so. To fix this, you will need to add an account on the IIS App Pool that has permissions to read the Active Directory list. Usually this just needs to be a domain account. Talk to your IT if you have any questions if your account can read the list.

To change the IIS App Pool account, please follow the instructions here.

 

Not all users or groups are showing up on the domain list

Despite adding a domain account to the IIS App Pool, you may find that users and groups may be randomly missing from the list.

There was an issue where BarTender Print Portal was unable to pull a full list from a very large Active Directory with tens of thousands of records or more. Please update to BarTender 2021 R5 or later to fix this issue.

 

No root folders have been configured

After configuring security for individual folders, when browsing Print Portal, you or your users are presented with an error message like this:

noRoot.png

This could be a valid error message if there are no folders that the user is allowed to see.

However, in the case where a particular user does have permissions to see a folder and you see this error message, there may be a few possible causes for this error message:

 

App pool permissions

When checking to see if the user has permissions to see a folder, BarTender Print Portal asks the Active Directory what groups the user belongs to. If this check fails, then the user is denied access by default. The check relies on the App Pool identity and could fail if the identity has changed its password, been removed, or something similar.

If this issue is due to a permissions issue, try reentering the password for the identity or changing it to an account which has permissions to talk to the Active Directory. Please see the permissions section for more details.

 

Wrong group type

An Active Directory can have several types of groups with different purposes. For authentication, you only want to select a Security-type group from the list. If a different type of group such as a Distribution-type used for email mailing lists is chosen, the check with Active Directory will fail.

If you find that the App Pool Identity is correct but groups are still failing to show valid users their folders, please update BarTender to ensure that only Security-type groups are visible on the list. Once you have updated, reconfigure the folder permissions in BarTender Print Portal.

 

Print Portal appears to hang when navigating folders

When navigating folders in Print Portal, the application appears to hang. This happens when there's a problem connecting to the system database. There are a few reasons why a system database may not be connected:

  • the database host has gone offline
  • the database no longer exists
  • the system database wasn't set up
  • the current user does not have permissions to connect

Connection issues

As much of the BarTender suite relies on the system database, the best place to start is in the Administration Console where the connection is set. To do so, please do the following:

  1. Open the Administration Console from the Start Menu
  2. Navigate to System Database on the left-hand menu
  3. Review the details in the top section on the right pane.

A healthy database connection will give a status of connected. If you see a different status, missing data, or a banner that says you don't have a system database setup, use the System Database Wizard link to configure your database connection and set one up. Here is a guide to help you through the process. It is strongly recommended you use SQL authentication to avoid the next big problem, permissions. This video will walk you through the process of setting this up in a new database. If your database is managed, please contact your database administrator.

 

Permissions issues

If the Administration Console gives you a status of connected but you're still receiving a system database error in BarTender Print Portal, you're likely encountering permissions issues. Regardless of authentication method (Windows or SQL), an account needs to have six basic permissions to properly operate. If this account is missing any of these six, normal operation is stunted and may even tell you it cannot reach the system database. 

First check which account is being used to connect to the system database by doing the following:

  1. Open the Administration Console
  2. Select System Database on the left-hand menu
  3. Click on System Database Wizard
  4. Choose to "customize connection settings". On the next screen, it will tell you the authentication method.
    1. If the method is SQL Authentication, write down the account name listed on the dialog
    2. If the method is Windows Authentication, write down the name of the account running the IIS App Pool

Once you have the account name, you can use this guide to check that your account has all of the proper permissions. If you do not know how to do this or your database is managed, please contact your database administrator and let them know you need these six basic permissions.

 

An unknown error has been encountered

When attempting to print, you may encounter an unknown error like this one:

unknown_error_2021.png

This is a generic error used to catch issues that have no other error message to display. Often this is something related to an issue with the label or something connected to the label. With a generic error like this, it's best to inspect the label itself to locate the issue.

 

Linked Resources

The biggest culprit is missing resources. Open the label and inspect it.

  • Do any error messages pop up?
  • Can you browse the database in the data setup dialog or does the dialog say it cannot connect to the database?
  • Do you have missing pictures with red Xs on them?
  • Can you print the label from BarTender Designer or do error messages show up?

If any of these show up, you'll need to correct them before you can print this label.

If you find that the label is printing just fine, then you may have a permissions issue. If the Print Scheduler service is unable to obtain any of the linked resources like pictures and databases to properly print the job, you'll see this error as well. To correct this, please see the permissions section on how to correct the issue.

 

Linked databases

Databases linked on a label can be a bit more tricky as there are a number of elements in play. When connecting to a database in Print Portal, the connection uses the account on the IIS App Pool (for Windows Authentication) or the credentials stored in the label (for database authentication). Text databases tend to throw file errors when something goes wrong connecting to them, so this section is more geared towards relational databases.

Here are some possible issues that could cause a database error:

  • The database has been moved or renamed
  • The database is offline
  • The ODBC connection is configured with a User DSN instead of a System DSN
  • The credentials needed to connect to the database are not stored in the label.
  • The database is using Windows Authentication and the current user running BarTender Print Portal is not authorized to access the database.

As there are many database types and connections, this is not a comprehensive list nor is every option going to fit every database connection. It is best to open the label and observe the connection type and troubleshoot from there. Start by opening the database dialog by going to File > Database Connection Setup

  • If you receive a connection error when opening the dialog or when trying to browse the records, the database has likely been moved, renamed, is offline, or is otherwise unavailable. You will need to locate the database and check if it is available and online. If your database is managed, talk to your database administrator.
  • In the Database Setup dialog, click the Database Setup Wizard dialog and check the connection details
    • Is the connection using Windows Authentication or database authentication?
    • Are the credentials stored in the document (for database authentication)?
    • Are the credentials here correct?
  • If using an ODBC connection, check the DSN configurations

Once you've corrected any errors, ensured authentication is correct, and stored credentials in the document (except for Windows Authentication), make sure to save the document and return it to the Print Portal folder.

 

Troubleshooting BarTender 2016 & 2019

Click on a error message to expand the section for troubleshooting steps

Unable to access the BarTender System Database

BarTender Print Portal relies on the system database for a number of operations. If there are any connection problems, you'll see a message like this:

nosysdb2016.png

There are a few reasons why a system database may not be connected:

  • the database host has gone offline
  • the database no longer exists
  • the system database wasn't set up
  • the current user does not have permissions to connect

Connection issues

As much of the BarTender suite relies on the system database, the best place to start is in the Administration Console where the connection is set. To do so, please do the following:

  1. Open the Administration Console from the Start Menu
  2. Navigate to System Database on the left-hand menu
  3. Review the details in the top section on the right pane.

A healthy database connection will give a status of connected. If you see a different status, missing data, or a banner that says you don't have a system database setup, use the System Database Wizard link to configure your database connection and set one up. Here is a guide to help you through the process. It is strongly recommended you use SQL authentication to avoid the next big problem, permissions. This video will walk you through the process of setting this up in a new database. If your database is managed, please contact your database administrator.

 

Permissions issues

If the Administration Console gives you a status of connected but you're still receiving a system database error in BarTender Print Portal, you're likely encountering permissions issues. Regardless of authentication method (Windows or SQL), an account needs to have six basic permissions to properly operate. If this account is missing any of these six, normal operation is stunted and may even tell you it cannot reach the system database. 

First check which account is being used to connect to the system database by doing the following:

  1. Open the Administration Console
  2. Select System Database on the left-hand menu
  3. Click on System Database Wizard
  4. Choose to "customize connection settings". On the next screen, it will tell you the authentication method.
    1. If the method is SQL Authentication, write down the account name listed on the dialog
    2. If the method is Windows Authentication, write down the name of the account running the IIS App Pool

Once you have the account name, you can use this guide to check that your account has all of the proper permissions. If you do not know how to do this or your database is managed, please contact your database administrator and let them know you need these six basic permissions.

 

Failed to connect to the BarTender Print Scheduler Service

BarTender Print Portal relies on the BarTender Print Scheduler service to generate print previews and print a job. If Print Portal is unable to contact the service to use it, you may see an error like this one:

noPSS2016.png

There are a number of reasons for this error including the service has been stopped via command line or in the services snap in, the account running the service has changed its password, or something has interfered with communications.

To get the service back up and running, please do the following:

  1. Start the Services snap-in by searching for it in the Start Menu or locating it in the control panel.
  2. Scroll down to the BarTender Print Scheduler service.
  3. If the service is stopped, right click it and select Start. If the service is running, right click and select Restart.

If you receive an error message about username or password being incorrect, see Setting BarTender Print Scheduler Service permissions

If you continue to have trouble, even after trying all these steps, check the compatibility between your operating system and BarTender version. If you are using an incompatible combination, the application and services may be having difficulty talking to each other. Please see the compatibility section for more information.

 

This request operation sent to PrintScheduler/Service did not receive a reply within the configured timeout

BarTenter Print Portal relies on the BarTender Print Scheduler service to generate print previews and print a job. In some cases, communication between the two has suddenly stopped and you receive this long error message:

noPSS2016-response.png

There are a few potential fixes for this error message but the easiest and most common fix is to simply restart the BarTender Print Scheduler service:

  1. Start the Services snap in by searching for it in the Start Menu or locating it in the control panel.
  2. Scroll down to the BarTender Print Scheduler service.
  3. If the service is stopped, right click it and select Start. If the service is running, right click and select Restart.

If you receive an error message about username or password being incorrect, see Setting BarTender Print Scheduler Service permissions. This could be a result of the account on the service having its password changed. It is recommended to use an account which does not change its password.

 

Print job aborted: file could not be opened, read, or accessed

This error message is a sort of catch-all for file errors and generally refers to two things: permissions or missing linked files. Here is an example and how to break down this error message:

file_error_2016.png

  • Next to "Print Job Aborted" is the condition that created the error. In this example, it is a record set aka a linked database. So the label file is having problems opening the database.
  • Next says what cannot be opened. In this case, it is a csv database.
  • Next gives some brief details about what's wrong. In this case, it couldn't find this file or locate the folder that's been defined.

So this error message is saying that the file does not exist in the location specified in the label file or the Print Scheduler service does not have permissions to reach the directory, so it appears to be missing.

When you encounter errors like this, the first step is to open the label file.

  • Do any error messages pop up?
  • Can you browse the database in the data setup dialog or does the dialog say it cannot connect to the database?
  • Do you have missing pictures with red Xs on them?
  • Can you print the label from BarTender Designer or do error messages show up?

If any of these show up, you'll need to correct them before you can print this label.

If you find that the label is printing just fine, then you may have a permissions issue. If the Print Scheduler service is unable to obtain any of the linked resources like pictures and databases to properly print the job, you'll see this error as well. To correct this, please see the permissions section on how to correct the issue.

 

The record set could not be created

When printing or previewing a label, error message similar to this appears at the bottom of the screen:

nodbconnection2016.png

This message is a database error, indicating something is wrong with the database connection stored in the label. When connecting to a database in Print Portal, the connection uses the account on the IIS App Pool (for Windows Authentication) or the credentials stored in the label (for database authentication). Text databases tend to throw file errors when something goes wrong connecting to them, so this section is more geared towards relational databases.

A few causes for this error message:

  • The database has been moved or renamed
  • The database is offline
  • The ODBC connection is configured with a User DSN instead of a System DSN
  • The credentials needed to connect to the database are not stored in the label.
  • The database is using Windows Authentication and the current user running BarTender Print Portal is not authorized to access the database.

As there are many database types and connections, this is not a comprehensive list nor is every option going to fit every database connection. It is best to open the label and observe the connection type and troubleshoot from there. Start by opening the database dialog by going to File > Database Connection Setup

  • If you receive a connection error when opening the dialog or when trying to browse the records, the database has likely been moved, renamed, is offline, or is otherwise unavailable. You will need to locate the database and check if it is available and online. If your database is managed, talk to your database administrator.
  • In the Database Setup dialog, click the Database Setup Wizard dialog and check the connection details
    • Is the connection using Windows Authentication or database authentication?
    • Are the credentials stored in the document (for database authentication)?
    • Are the credentials here correct?
  • If using an ODBC connection, check the DSN configurations

Once you've corrected any errors, ensured authentication is correct, and stored credentials in the document (except for Windows Authentication), make sure to save the document and return it to the Print Portal folder.

 

 

Still need help? Contact us!

 

Please sign in to leave a comment.