Troubleshooting Guide: Integrations Follow
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 the problem and fix it.
This troubleshooter can help you understand the moving parts as well as the integration cycle and how to troubleshoot it from a top level. There are many types of integrations, each with their own intricacies, but each type uses the same process and moving parts to function.
Components of the integration process
There are several moving parts in the integration process working together to automate your print jobs. Here is a brief description of each and how it contributes to this process
- 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 is responsible for processing the label files, preparing them, and sending them off to the printer queue.
- BarTender System Service - This service is responsible for logging and communications between services and with the system database.
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
- Are started on demand by the Print Scheduler service. More will be opened if the integration load demands it
- Work to maintain print order (so serials and records do not get out of order on your label sheet)
- Can process up to 5 documents at a time
- Will close documents if they are unused
- 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 all of it for you. You can have a maximum number of print engines equal to the number of cores in your CPU x 2.
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 sends a confirmation to the Integration Service that the job 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're not encountering 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 actually 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.
A common problem in many of the steps in the integration process is permissions, especially when using network resources. You can elevate the permissions of your integration to a domain account by clicking on the integration header then 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 in order 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
Processing integration actions
Build the Print BTXML
Still need help? Contact us!