Overview

Web service integrations are a great way to automate printing over a web request. These requests are done over HTTP, which is insecure. Is it possible to send this over HTTPS and secure the data within the web request?

It is possible, though not directly through Integration Builder or Administration Console. Instead, you send a web request to BarTender Print Portal, BarTender's web application. BarTender Print Portal has a secure Integration Passthrough functionality which will forward web service requests to the integration listening on the same system.

This example will walk you through how to secure Internet Information Services (IIS) working underneath BarTender Print Portal, your integration, and your label file.

Applicable To

BarTender 2021 through BarTender 2022 R4

Print Portal

Prerequisites

To use BarTender Print Portal's Integration Passthrough functionality, you will need the following:

• Internet Information Services (IIS) Manager. This is a Windows Feature and can be installed using the Turn Windows Features on or off application.
• BarTender Print Portal
• An application to send the web request. This tutorial covers Postman and Insomnia, but you can choose any you like.

Additionally, here are the sample documents to follow along with this example:

• Sample documents - TempIntegration.zip 

Enabling HTTPS

In order to make the connection secure for the Integration Passthrough, you must bind HTTPS to BarTender Print Portal. This is done in the IIS Manager.

Microsoft has a step-by-step on how to configure your website for HTTPS. By default, BarTender Print Portal is listed as BarTender under the Sites list in IIS Manager. This step-by-step instructs on how to create and use a self-signed certificate. However, if you have a certificate from a Certificate Authority, you can follow the same steps (skipping the self-signed section) to use your certificate instead.

Once you have finished binding, you will see both HTTP and HTTPS listed in the Site Bindings section like in the screenshot below:

There is no need to restart the site or the system. The binding will go into effect immediately as you set it.

Turning on Integration Passthrough

Integration Passthrough is a setting in BarTender Print Portal's configuration file. By default, this setting is turned off, so if you try to send the web request now, BarTender Print Portal will ignore it.

To change the setting, you will need to open the settings file in a text-editing app as an Administrator or with an app that is capable of elevating itself. Windows will not allow you to save the file as a standard user. Please do the following

1. If you are using Notepad:
   1. Locate Notepad on your Start Menu.
   2. Right-click and run as Administrator.
2. Navigate to C:\inetpub\wwwroot\BarTender\ then open settings.xml
3. Scroll down to near the bottom and locate the IntegrationPassthrough parameter
4. Change Enabled to "true"

Once you save the file, you will need to restart several components so that all the pieces working with the Passthrough know it's enabled.

Restart the Services

1. Open the Services snap-in from the Start Menu or Control Panel.
2. Right-click on BarTender System Service and select Restart.
3. It will notify you that dependencies will restart as well. Click OK.
4. Once the dialogs disappear, all the BarTender services should say "running" next to their name

Restart the IIS App Pool

1. Open the IIS Manager
2. Click on Application Pools
3. Click on BPP_AppPool
4. Click Stop on the right-hand action list, wait a moment, then click start.

Setting up the Integration

The integration itself can be set up much like any other web service integration. Here's a brief rundown of the setup for each type of web service request:

GET

• The label must use named data sources.
• The integration must override the named data sources in the Print Document action.
• A single record is sent as part of the request URL.

POST

There are two different setups for a POST request depending on how many records you send.

If you wish to send a single record, you can set the integration and label file up the same way as a GET request. The data is sent in the body of the request instead of in the URL.

If you wish to send multiple records, the setup is as follows

• The label is connected to a text database like JSON or CSV.
• Integration overrides the database in the Print Document action to use %EventData%.
• One or more records are sent as the body of the request in the same format used in the text database connected to the label.

For this example, the sample files are a single record that can be sent by either a GET or a POST request. This is a fairly common setup and is the most straightforward.

For more information and troubleshooting, you can check out these articles:

• Can I send multiple records in a web service integration?
• Troubleshooting Guide: Integrations

Unpacking the Example

Please follow these steps to unpack the example and set it up:

1. Download the example pack: TempIntegration.zip 
2. Unpack the integration and label files to C:\TempIntegration\ 
3. Open the Integration
4. Click on the Print Document action and then the Print Options tab.
5. Change the printer to a printer you have on your system.

Setting up the Request

For this section, you will need Insomnia, Postman, or a similar application to send a web request. For both POST and GET, the URL for the request requires an integration URL. You can find this URL in Integration Builder in the Service section. This screenshot is from the example integration file. The section highlighted in yellow will be the integration URL:

If you've used web service integrations before, this URL should be rather familiar. When sending a regular web service request, you send the request to this full URL path to trigger the integration to print. However when using a passthrough, we're sending the request to BarTender Print Portal instead, but it needs to know which integration to send it to. We tell it this by giving it the integration URL.

For both GET and POST, the web request URL will be in this format:

https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=[IntegrationURL]

Notice that this URL is different than the one listed in the integration file. It is sending the request through the Integration Passthrough which then forwards it off to the targetURL

For our example files, filling in the integration URL, the full request URL will be:

https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute

The following examples use the URL from above. If you're using your own files, replace the example integration URL with the one matching the URL found in your own integration.

http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute

Creating a GET request

A GET request sends all the information in the URL. This is often done by filling out the Header information. However, since the Integration Passthrough requires the targetURL parameter, the label data needs to be placed in a different location.

For Insomnia (in the screenshot below), the proper location is Query. For Postman, the location is Params.

If you are building your own URL, add each parameter onto the URL as a key-value pair with an & in between each pair like the URL preview in the screenshot above.

Here is the data used in this example:

• URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
• Key-value pairs:
  • Company: company
  • IDNumber: 3

Creating a POST request

A POST request sends the data in the body of the request instead of in the URL. Much like the GET request, the POST request has a targetURL parameter to tell the Integration Passthrough where to send the information.

If you peeked at all the settings in the integration file, you might've noticed that the Input Data is set to JSON. The integration is capable of parsing the JSON key-value pairs into usable variables automatically without you needing to do any extra work or add any actions. If you're planning on sending only one record, this may be a good option for you.

Here is the data used in this example:

• URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
• Body data: {"Company": "The Company", "IDNumber": "3"}

Sending the request

With everything set up, you're ready to send your request.

1. Start the integration. Click on the Test tab then click the big green Start button
2. In Insomnia or Postman app, click the Send button. If you are using a custom app, initiate the request normally.
3. Return to the integration. You should see messages begin to appear in the message section.
4. Once you see the message saying the job has been sent to the spooler, congratulations. You've sent the request through the Integration Passthrough system and printed a label.

Troubleshooting

Didn't go the way you expected? Here are some common issues you may encounter.

SSL peer certificate or SSH remote key was not OK

When sending the request for the first time, this error shows up (screenshot is from Insomnia):

This error appears when you're using a self-signed certificate. Simply disable SSL validation and resend the request.

404 Not Found

When sending the request, you encounter the following error message in a response from the Integration Passthrough service (screenshot is from Insomnia):

Here are the common causes for this error:

This error can indicate that the integration itself is not running. When the Passthrough attempts to forward the information, there's no integration to receive it. The Passthrough service assumes that the URL is incorrect and replies to you with a 404 Not Found. Make sure to start your integration first before sending data to it.

This error can also indicate that the targetURL parameter is missing or incorrect. Review the Setting up the Request section to ensure your URL is correct and how to find the integration URL.

Additionally, this error can indicate that the Integration Passthrough is not turned on. Review the Integration Passthrough section on how to set this up.

Data prints as %VariableName% instead of an actual value

On your label, you may see values with % instead of actual information on your label. The % notation indicates a variable in integration speak. When the integration doesn't have any values to put into these variables, it simply sends the variable name for printing instead.

When this happens, the value (left side) is not typed correctly in your web request app or is missing. The value must match the variables listed in the integration. These variables are in the Print Document action on the Named Data Sources tab. Notice in the screenshot below how the values from Insomnia (in black) match the variable names in the integration (in white):

The same is true with the JSON data from the POST example.

For GET requests only, if you find that the Named Data Sources are set up and match correctly to the data you're sending but still only see variable names, check where you're putting the data to send. If you place the data in the Header section (for both Insomnia and Postman), this data doesn't carry through the Integration Passthrough service. Return to the Setting Up the Request section to ensure that you're putting the data in the correct location.

Integration errors

Receiving an integration error? Check out this in-depth guide: Troubleshooting Guide: Integrations