While pressing the start button or letting integrations start up automatically seems like it couldn't be troubleshot, it is a key first step in the integration cycle. This 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, are the username and password correct? Is the secret key correct?
• Does the current user have permission 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 be hosted only on a Windows-based system. If you plan on using Unix, Linux, or another operating system to host your scan directory, consider using a cloud location such as FTP.

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

Database Integrations

Access to the database is key. Determine the following:

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

These settings are all found in the connection settings dialog. Like 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 cannot 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 the issue 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. This 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," troubleshooting this step may help you track down why you're stuck here.

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.

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 that 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 date-time stamp, the data detection methods do not match.
• Is the watched field being incremented, or is 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 become 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 that 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 change the files or the folders and incorrect file paths.

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

Socket Integrations

At this step, issues with a socket integration 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: Integration Error When Running Socket Integration.

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, double-checking everything in this step is still vital. Here are common issues that 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. 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 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 no document is listed in a Print Document action, the integration will fault immediately 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 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
• Print Command Script action: in the trigger data in the /P parameter
• Print BTXML action: in the trigger data in the <Printer> tag

If no printer is 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.

Sometimes, a label ends up at a different printer than expected or just disappears 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 see this strange behavior, please see this article to fix this issue: Integration Prints Are Sent to Wrong or Random Printers.

Database Type or Field Name Mismatch

If your integration uses a database and receives data from an integration, you must 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 cannot understand the data sent to it. This may result in various integration errors, mentioning issues with the database, fields, or empty data.

Additionally, even if your database types match, if the field names differ in name or 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. In this dialog, you can check the field names and the type of database 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 must 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 must be told to override the information. This is found in the Database Overrides section of the Print Document action on the Print Options tab. You must override the database with Integration data or EventData to pass the trigger data to the label.
• Not defining named data sources: Integrations must be told how to pair variables with named data sources on the label. If you find that you are missing named data sources under the same name on the Named Data Sources tab, click the Import Document Settings button on the Documents tab 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 create your own BTXML and send it through an integration using the Print BTXML action, you don't need to! The integration automatically converts your data and settings in the print action to BTXML.

If 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.

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 and 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, 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 easier than it seems.

As mentioned in the introduction to this guide, the Print Engines 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

At 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, and 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 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 can bypass most dialog boxes, some 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 not be bypassed, so turning off this dialog is recommended.

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

• Error in the page size dialog: This message may appear while the integration can automatically resize a document if the template is set to a static size or the size exceeds the manufacturer's specifications for your printer. If this happens, open 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: These can occur 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.

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 not listed in the article above.

General

The Integration Suddenly Stops

Integrations can stop for many reasons, several of which 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 Slowly

Many factors can contribute to a file integration running slowly, but this type of integration is unique to these factors. 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 as 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 slowly, 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 slowly for many 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 will slow down as 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 your integration skips labels, you may find a 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 When Running Socket Integration.