While pressing the start button or letting integrations start up automatically seems like it couldn't be troubleshooted, it is a very key first step in the integration cycle. This start step tells the integration to start looking for that trigger. If something has gone wrong, or the trigger location is no longer available, then the integration will wait indefinitely or may actually fault.

Each type of integration will have a different name for this information in your integration file and needs to be configured for this to work. For all types of integrations, the settings for your integration will be the first subsection of the Integration section and will say what it is looking for. In this screenshot, this is a file integration, so it lists File Detection as the subsection name as it is looking for files to trigger the integration.

Often times, the issues with this step involve permissions, file names, and trigger settings. If you try to start the integration in Integration Builder, an error may pop up right away to tell you the issue.

Here are some scenarios for the most common integration types which may cause issues in this step

File integrations

For file integrations, permissions and file locations are vital.

• Is the scan folder location typed correctly?
• For cloud storage locations, is the username and password correct? Is the secret key correct?
• Does the current user have permissions to access this folder? It is recommended not to use locations such as My Documents or a mapped network drive as the permissions to reach them can get complicated.
• Is the integration watching the correct folder where you're dropping the files?

If the integration cannot reach the folder, it likely will fault with a permissions error or an access error. It is recommended that scan folders are not using a virtual drive letter (aka not a physical drive) and is not in My Documents or on the desktop.

It is also recommended that a scan folder is only a Windows-based host. If you plan on using Unix, Linux, or other operating system to host your scan directory, consider using a cloud location such as FTP.

If this is a network folder, elevate the permissions of your integration so that it has proper access to this folder.

Database integrations

Access to the database is key

• Is the database online?
• Are the username and password correct?

These settings are all found in the connection settings dialog. Much like with troubleshooting a database connection on a label, opening this dialog via the [Database Connection Setup...] button will determine if the database is connecting properly. If not, the dialog will yield an error.

Socket integrations

Network connectivity is very important. If you are unable to establish a connection, you can start by looking at the connection itself

• Are the ports open?
• Is there a firewall or antivirus potentially interfering?
• Is something else using the same port?

Integrations require a quiet port. If anything else is speaking on the port, the integration will usually fault and say that the port is unavailable. Like with other integrations, an error message will often tell you what the issue is and how to fix it.

Key Takeaways

While this step may differ for each type of integration, there are some key points to troubleshooting this step for all types

• Permissions are very important
• Always ensure the integration has access to the trigger
• Failures will often cause a fault when starting the integration

Once the integration has started, it's time to wait for the trigger to arrive. It seems like a step that requires no troubleshooting, but what do you do if you're eternally stuck in a waiting state? What happens if the trigger never arrives? If you're stuck in a state of "nothing happens", then troubleshooting this step may help you track down why you're stuck here.ck

All types of integrations will wait for something to happen or show up. It could be a file, data over a network port, a record in a table, or a specific time. All the settings for trigger detection are listed in the same location as the previous step, the first subsection under the Integration header.

First subsection location

Here are a few things you can check with common integration types:

File integrations

• Is the trigger file being dropped in the scan folder listed on the integration?
• Does the trigger file match the expected File Pattern? If the integration is looking for a .csv and you drop a .css file, the file pattern does not match.
• Is there another integration which may be claiming the files first?

Database integrations

• Is the data being inserted into the correct table?
• Is the data detection method correct? If an integration is watching for an incrementing value and instead you're updating a datetime stamp, the data detection methods do not match.
• Is the watched field being incremented or the datetime stamp updated?

Socket and Web Service integrations

• Is the data being sent to the correct address?
• Is a firewall blocking the port?

Key takeaways

• Ensure that the trigger is getting to the right location
• Double check that nothing is blocking or taking the trigger before detection

Much like the previous step, this step seems like it would simply "work". While sometimes an error may show up for an issue with this step, other times the issue will only make itself apparent when the integration cycle repeats.

This action involves what the integration does once it receives the data. Only two types of integrations use post-detection actions. All other types can skip this step. Here are some things to look for with common integrations which do have post-detection actions:

File integrations

Of all the types of integrations, these are the noisiest in this step. If something goes wrong with the post detection actions, the integration will throw an error and tell you what is wrong. Common issues include permissions to make changes to the files or the folders and incorrect file paths.

The post-detection actions for a file integration are listed here:

Socket integrations

Issues with a socket integration at this step are much less obvious than with a file integration. If you have a relatively quiet socket integration, you may not actually have a problem here, but if you have a busy one, you may see this error show up on occasion: "Error: Cannot access disposed object."

What is happening here is that the socket isn't closing after receiving the data so new data is slamming right against it. The integration isn't ready for new data, so it doesn't know how to process it and simply disposes of it, assuming it's just garbage data. The socket is leaking data and prints will start dropping.

If you notice this behavior, check out this article on how to fix it: Cannot access disposed object.

Key takeaways

• This step applies to two particular integrations
• Errors in this step may not always be obvious

Integration actions are all the steps your integration takes to process and print a label. All actions are listed underneath the action header:

This example is quite simple as it only includes a printing action. However, some integrations may include multiple steps such as loops, data parsing, outputting messages or emails, or conditional statements. Here is a larger example where data is parsed out of a trigger using a series of named Search and Delete actions then the data used in a Print Document action:

This increases the complexity of this step and more points where something could go wrong. The best approach is to go simple first. Strip the actions down to a bare minimum to reduce the steps as far as possible (generally only the actions used when you create a new integration from the New menu plus the bare minimum needed to process the data) and start from there.

• Strip out extra steps. Keep to the minimum to start
• Add in each step and test to ensure the issue isn't in that particular action

The biggest challenge is testing in this step. If the issue is in a later step in the integration cycle, it will persist throughout testing all the steps. Even though this is the case, it is still vital to double check everything in this step. Here are common issue which may arise with the minimum steps in an integration:

Document location

To print a label, the integration must of course be able to open a document. If the document location or name is invalid, the integration will likely throw a document error stating there was a problem opening the document. You can find the document name in the following locations:

• Print Document action: In the Document section on the Document tab. (BarTender 2016 does not have tabs but the document information is in the same section). If the document is determined by a variable, trace where the variable originated (usually from a database field name, a Set Variable action, or one of the Search actions) and ensure the data placed in that variable is accurate.
• Print Command Script action: in the trigger data in the /AF parameter
• Print BTXML action: in the trigger data in the <Format> tag

If there is no document listed in a Print Document action, the integration will fault right away when you try to start it with an error message mentioning the missing document.

Printer name

Much like you cannot print without a document, you cannot print without a valid printer. In most cases, the integration will throw an error, usually either an invalid printer error or Windows Error code 1801 (Windows is having problems with this printer). The latter is outside the scope of this troubleshooter as it requires fixes on Windows' side, the former can be found in the following locations:

• Print Document action: In the Printer field on the Print Options tab. In BarTender 2016, this field is found in the Print Option Override section.
• Print Command Script action: in the trigger data in the /P parameter
• Print BTXML action: in the trigger data in the <Printer> tag.

If there is no printer listed, the Integration will use whatever printer is saved with the label. If your integration does not specify a printer, open the label in BarTender Designer and go to File > Print. This is the printer your integration is using.

There is a nuance with printers in BarTender 2019 and later. There are some cases where a label ends up at a different printer than expected or just seems to disappear into the aether. This is the result of the printer redirection system kicking in and sending the print job to the first available printer. If you are seeing this strange behavior, please see this document to fix this issue: Integration prints are sent to the wrong printer or seemingly random printers 

Database type or field name mismatch

If your integration uses a database and is also receiving data from an integration, you will need to ensure that the database type matches. Say for example, your label is connected to a comma separated value (CSV) database but your integration is sending one separated by tabs or something entirely different like XML data. This causes a mismatch between database types and the document isn't able to understand the data being sent to it. This may result in a variety of integration errors mentioning issues with the database, with fields, or with empty data.

Additionally, even if your database types match, if the field names differ in name or in order, this can also cause similar integration errors.

To double check that the databases match correctly, you can do the following

• Open the label file in BarTender Designer. Go to File > Database Connection Setup. Here on this dialog you can check the field names as well as the type of database that is connected to your label.
• Additionally you can find the name of the connected database in this setup dialog and open it on your computer to double check the format (for example CSV vs tab-delimited) and double check the field names.
• Compare the connected database to the data included in the trigger.

If your label's database is anything but a text file (or an Excel file in BarTender 2019 R5 and later), the integration will always fail with a database mismatch. If your label is connected to an unsupported database, you will need to change the connection to a supported one and reconfigure your objects on the label to look at the new field.

Label has only default data

This happens because the integration is not handing data off to the label during print time. The culprit is likely that the integration wasn't told to do so (default behavior) and only occurs in a Print Document action. Here are the two scenarios with this issue and how to fix them

• Handing off database information: the integration needs to be told to override the database information. This is found in the Database Overrides section of the Print Document action. In BarTender 2019 and later, this is on the Print Options tab. You will need to override the database with "Integration data" or "EventData" to pass the trigger data to the label.
• Not defining named data sources: Integrations need to be told how to pair up variables with named data sources on the label. If you find that you are missing named data sources under the section of the same name on the Named Data Sources tab (in BarTender 2016, the section name is the same), click the Import Document Settings button on the Documents tab (at the top of the pane in BarTender 2016) and then pair the imported named data sources with the integration variables.

Key takeaways

• To best troubleshoot this step, reduce the number of actions to the smallest amount then add them in to see where the problem might be.
• Data is a common problem in this step. Correcting it here prevents problems in the next steps

The printing part of the integration cycle relies on a formatted version of XML called BTXML. It contains document and printer information plus any data from the trigger file you've set to pass on to the label.

While you can certainly create your own BTXML and send it through an integration using the Print BTXML action, you don't need to! The integration converts your data and settings in the print action to BTXML automatically for you.

As long as you've gone through all the troubleshooting in the previous steps, the BTXML will be converted just fine and you can move to the next step in the process.

The final step in the integration cycle before it repeats is the actual printing. This is all handled by the Print Scheduler service automatically and follows a simple flow. Here is a clip from the flowchart at the top of this article:

Once the BTXML script is sent to the Print Scheduler from the previous step in the cycle, this one begins right away. The service handles opening the print engine then interpreting what label file must be opened (if it's not already open in an engine). Once the document is open, data is placed into the correct places on the label, if sent from the Integration, either via a database override or named data sources. After the data is processed, the label is sent to the printer listed in the BTXML or linked on the label if one is not listed.

With all this done automatically in a service, that leaves the question of what happens when something goes wrong? How do you troubleshoot it? As you've done most of the work in the previous steps, troubleshooting this step is actually easier than it seems.

As mentioned in the introduction to this guide, the print engines here used by the Print Scheduler service are actually BarTender Designer running as a service. This means that you can troubleshoot this step using Designer itself. 

Basic troubleshooting

During print time, a Print Engine automatically prints a label file according to the BTXML script's instructions. If you were to mimic this script, you open a label and go to File > Print, change the printer name, then print the document. There are a few extra steps a BTXML script can do, but this simple action can tell us quite a bit about what is happening in an invisible Print Engine.

Opening and printing the document

The most basic behavior of a Print Engine is opening and printing the documents. While previous steps checked to ensure the document was in the right place, opening it will check to make sure that the Print Engine can properly use the document during print time.

• Try opening the document. Does it open or do you see errors or messages pop up?
• If you try to print the document, does it print or do errors or warnings pop up?

If either of these resulted in a dialog box popping up presenting warnings or errors, these could be interfering with the automatic printing process. The next section can help you with these dialogs.

Errors and warning dialogs

While a Print Engine is capable of bypassing most dialog boxes, some will cause the print to be skipped or error out. Sometimes a Print Engine does not properly communicate this information to integration logging, so checking and watching for any boxes here can help find the issue.

Here are some examples of dialogs that may be bypassed but could still be responsible for integration issues:

• Page adjustment dialog - when a printer has slightly different media, BarTender will automatically adjust the label. If the label looks strange, it may be a difference in media. Adjust the label and save it with the integration printer to prevent this dialog from popping up.
• Clipping warning - in early revisions of BarTender 2019, this warning was an error that stopped printing. If printing is stopping here, please update your software.
• TrueType font substitution message - this message can be turned off in the print dialog. This could potentially not be bypassed, so turning off this dialog is recommended.

Here are a few dialogs which could cause the print to stop and error out. These may also appear in the integration messages:

• Error in the page size dialog - while the integration can automatically resize a document, if the template is set to a static size or the size exceeds manufacturer's specifications for your printer, this message may appear. If this happens, open up the page dialog by going to File > Page Setup and reviewing the details and settings on the Page tab. Double check that there are not too many columns or rows on the Layout tab as well.
• Database connection errors - this can happen if a database file is moved or otherwise becomes unavailable. Reestablish the link using File > Database Connection Setup then save the document.
• Template does not reference database fields - Please see Error 3600: Template does not reference any database fields 
• Missing pictures or linked objects - this error can appear if linked pictures or objects have been moved or are on a network location that is no longer available. BarTender will not print until the objects or pictures have been relinked.
• An error mentioning TMP - the label or a linked resource has likely become corrupted. It is recommended to restore a backup of the label or remake it.

This is hardly an exhaustive list, but it addresses the more common issues you might encounter during troubleshooting.

Key Takeaways

• This automated step can be checked using BarTender Designer
• Dialogs can often tell you the issue

Additional troubleshooting

Sometimes the problem can't be found directly in the integration cycle. Here are some additional resources that might help you out with miscellaneous situations that are not listed in the article above.

The integration suddenly stops

Integrations can stop for a number of reasons, but many are covered in the article above. The most common reason not listed above is that the resource suddenly becomes unavailable. This is most prevalent in database integrations and file integrations using cloud storage locations. BarTender 2021 will attempt to restart the integration when the resource becomes available, but earlier versions would simply stop the integration.

If your integration suddenly stops, check the logs for the most recent error to determine the cause.

File Integrations

Integration is running slow

There are a number of factors that can contribute to a file integration running slow that is unique to this type of integration. The size of the scan folder is important. As a file integration relies on scanning the scan folder for new files, if the number of files grows very large, the scan takes longer and longer the more files are dropped into this folder.

If your integration is not set to delete or move a trigger file once it's done processing, these trigger files will build up over time. If you notice your integration running slow, remove processed trigger files from the scan folder to see if that improves speeds.

Database integrations

Duplicate records or multiple prints

If a database integration is scanning a table and the label is also connected to this same table, you'll likely end up with duplicate labels. Please see these articles for how to fix this situation and how to properly set up your database integration and labels:

• Multiples of the Selected Records Quantity Printing from a Database Integration 
• Print Document Using Database Triggers (Video - 7:27) 

Integration is slow to pick up records

Integrations can run slow for a number of reasons, but there is a unique situation specifically for database integrations. A database integration scans an entire table to check for new records that match what is specified in the trigger section. If a database table grows very large, this process is going to slow down as more and more records are added to the table, causing strain on the database server with every query.

It is recommended to clean out unused records in the database with regular maintenance or set the integration to delete records after processing to help relieve strain on the database and integration.

Socket integrations

Cannot access disposed object error

If you notice that labels seem to be skipped in your integration, you may find an "Cannot access disposed object" error in the logs. This means that the socket is not properly closing between jobs. To fix this issue, please see Integration error: Cannot access disposed object