Troubleshooting Guide: Integrations
Overview
The Integration system consists of moving, automated parts. Troubleshooting something that isn't immediately visible may seem daunting, but working through the process step by step can help locate and fix the problem.
This troubleshooter can help you understand the moving parts and integration cycle and how to troubleshoot them from a top-level perspective. There are many types of integrations, each with its own intricacies, but each uses the same process and moving parts to function.
Applicable to
BarTender 2019 and later
Components of the Integration Process
Several moving parts in the integration process work together to automate your print jobs. Here is a brief description of each and how it contributes to this process.
Services
- BarTender Integration Service: This service runs the integrations themselves, starts and stops them, as well as handles trigger detection and processing.
- BarTender Print Scheduler Service: This service processes the label files, prepares them, and sends them to the printer queue.
- BarTender System Service: This service logs and communicates between services and the system database.
Print Engines
A Print Engine is a fancy term for BarTender Designer running as a service. It will appear as bartend.exe on the list of running processes. Print Engines are automatically started and stopped by the Print Scheduler service and are used to print the actual label. Print engines have the following properties by default:
- The Print Scheduler service starts them on demand. If the integration load demands it, more will be opened.
- It works to maintain print order (so serials and records do not get out of order on your label sheet).
- It can process up to 5 documents at a time and close them if unused.
- They are automatically closed by the Print Scheduler service if not used after 60 minutes.
Print Engines are automatic. You do not need to open or close them yourself, as the Print Scheduler service handles everything. You can have a maximum number of Print Engines equal to the number of cores in your CPU x2.
The Integration Cycle
Integrations are cyclical by nature. They start and wait for something to trigger them to work. This could be a file, a record in a database, an email, something over a network, a time-based trigger, or the like. Once the trigger is detected, the integration gets to work, processing the data and sending it off to print. Everything outside the purple Print Scheduler box is handled by the Integration Service.
In general, once the job is sent to the queue and the Print Scheduler confirms to the Integration Service that it is done, the integration will return to a waiting state.
The integration may reach the stop state for a few reasons:
- This is a timed integration that does not repeat.
- The integration is stopped in Integration Builder, in the Administration Console, or by the service shutting down.
- The integration system has faulted and cannot recover.
With the number of moving parts of the integration system, it is important to remember a few things when troubleshooting:
- Always update to the latest service release. This ensures you don't encounter a bug that has already been fixed.
- Work through each step of the integration cycle in order. This ensures that you're not trying to fix something that was broken in the previous step.
- If you need help or encounter something this guide hasn't covered, please contact support!
For this process, you will need access to the integration file (.btin), label file(s) (.btw), any database files, trigger data (if not a timed integration), and Integration Builder.
Troubleshooting
Permissions are a common problem in many of the integration steps, especially when using network resources. You can elevate the permissions of your integration to a domain account by clicking on the integration header and entering the information in the User Account section.
Set permissions here and do not set an account on the Integration Service unless instructed to do so by Technical Support. Equally you can set an account on the BarTender System Service and the Integration Service will inherit those permissions.
The account must have the following properties to run the integration properly:
- be a member of the local administrator's group (required for messaging, accessing temp files, and accessing the file structure unhindered to retrieve labels, etc)
- have domain-level access (to access any networked printers or drives)
- have the group policy allow logon locally (you can't run a service or a task without this)
- does not change its password (you don't want your integration to go down when the password policy kicks in)
To troubleshoot the integration process, click on a step to expand each section. Work through them one at a time to help track down the problem:
Starting the Integration
Waiting for the Trigger
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.
Post-Detection Actions
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.
Processing Integration Actions
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
Build the Print BTXML
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.
Automated Printing
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.
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 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.
Still need help? Contact us!
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.
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:
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.
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: