Overview

BarTender 2022 introduces a RESTful API which allows you to automate print jobs using REST calls. REST APIs are the modern method for applications and systems to exchange data with each other over the network or internet. Requests execute functions of the server based resource that can change its state/form/status, but also perform related server side actions. If you've used the Print Portal REST API or any other REST API, you may find this style of API calls quite familiar. Though unlike the aforemntioned APIs, the functioning of these API calls is more similar to Integration or Process Builder Actions.

Applicable to

BarTender 2022 and later

Automation Edition or higher

Information

REST API Requirements

• Version: BarTender 2022 R1 and later
• Edition: Automation or Enterprise Editions
• Sending application: Custom, Swagger, Insomnia, Postman
  • Supports IWA, NTLM, and basic authentication
  • Supports CORS
  • Curl, C#, and .NET languages are supported for custom applications
• BarTender install to receive the commands

The API operates using port 5159 so this port will need to be open so that the API can receive the REST commands.

Security

The REST API supports several types of authentication

• Basic Authentication
• Integrated Windows Authentication (IWA)
• Windows Challenge/Response (NTLM)

By default, Basic Authentication is disabled.

When using Insomnia or Postman to send requests, set the authentication to NLTM.

When using IWA, the account sending the REST requests will need to have the following properties:

• User sending the request must have permission to log into the server
• User must have permissions to administer integrations as set in the Administration Console

Using Basic Authentication

Basic Authentication is disabled by default. To enable it, please do the following:

1. Navigate to C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0 if using the latest version).
2. Locate appsettings.json.
3. Scroll down to AuthenticationSchemes near the bottom and change Basic from False to True
4. Save the file.
5. Open Administration Console.
6. Navigate to Windows Services on the left hand side menu and restart the BarTender Integration Service.

Sending over HTTPS

The REST API is built on Window's HTTP server (Http.sys). However, you can configure the REST API to use HTTPS instead to secure your connections. 

Much like setting up HTTPS with integrations, you'll be bouncing the REST requests off Print Portal. You will need an SSL certificate, either from a Certificate Authority or a self-signed certificate for this process.

1. First, Secure Print Portal with HTTPS using your SSL certificate
2. Direct all RESTful calls to https://localhost/Bartender/api/actions. Replace localhost with the server name or IP as needed.

REST API commands

The BarTender REST API uses only three REST commands: POST, GET, and PATCH. Here is an overview of how each one interacts with the API.

IDs are used to work with any currently deployed action. When you POST a script, the ID is contained within the response if the script was accepted by the API. The ID will last only as long as the script is active on the API server. By default, this is 60 minutes, but it can be changed in the POST message.

The variables you can retrieve using a GET are like variables in an integration. You can retrieve integration and global variables as well as any local variables you create through POST actions. The values you retrieve will be relative to the script ID you submit.

POST scripts

When using a POST command, you can tell BarTender to perform various actions and leave these actions running after submitting. By default, an action will persist by default for 60 minutes but the time is changeable.

POST allows for various actions to tell BarTender what you'd like it to do. If you've used Integration Builder or Process Builder, these categories should look relatively familiar as they're the same type of commands that both of these applications use. Here is a list of categories:

• Print Actions - Print Document, Command Script, BTXML script
• Input Actions - Read a file, listen to serial port etc.
• Output Actions – Write Message to Log, Send Web Service Request etc.
• Execute Actions – Set Variable, Run a shell command etc.
• File Actions - Create a folder, Copy a file, Delete a file etc.
• Transform Actions – Search and Replace Action, Search and Delete etc
• Database Actions - Execute SQL, Transform Text to Record Set, For Each Database Record, etc. (see Database section below)

When sending a POST, these actions can be written in BTXML script, YAML, or JSON. If you have a working BTXML integration, using BTXML may be the quickest transition for you. Here is an example print BTXML script:

If you've worked with REST APIs before, are creating a new API interface, or are just more familiar with JSON or YAML, the API can also accept these calls. They're a bit simpler and easier to read than BTXML. Here are some examples in both formats:

After submitting the POST, the API will send a response back. This response will contain a status code that tells you if the script was accepted or not. You'll want to look for code 201, which indicates that the script has been accepted and is scheduled to run. If you receive a successful response, the script's ID will also be included in the response.

However, if you receive another response, the help documentation has a full list of each response code to help you diagnose the issue. The location of the documentation is listed in the API Reference section below.

Database Actions

When working with database actions, you'll need to specify the database connection. Unlike with integrations, you cannot specify this through the dialog on the action. Instead this is done in one of the action's properties.

To configure the connection, you'll need a connection file to tell the API what you want. This connection file defines the database connection as well as any settings you've specified like custom SQL or aliases. 

To make a database connection file, first set the connection up in BarTender designer by connecting to a database. Once you have made the connection, if the database dialog isn't open, go to File > Database Connection Setup to open it up. At the bottom of the dialog, click the Export button.

This will save the connection information in XML format. Your username, password, and other identifying information are obfuscated and are not saved in plain text.

Once you have the file, you can use it in the ConnectionSetup property for any action that uses a database connection. The connections only work for that specific action, so set one up for each action you use.

API Reference

There are several places in the help documentation to help you get started. The help documentation is located in BarTender Designer or online. Once you open designer, close the popups and go to Help > BarTender Help. Here are key places to find REST API documentation:

BTXML reference

If you are using BTXML to submit your scripts, you can find a full BTXML script reference here in BarTender's help file:

Here you can find an introduction to BTXML and a full reference with a complete list of tags.

YAML and JSON reference

YAML and JSON use the same types of variables and setup, though the formatting may be slightly different between the two. BarTender's YAML reference has an extensive list of all the variables, scripts, and calls you can make in the help file. You can find this here.

When you open up the YAML reference, you'll find a list of all available actions within the API, grouped by action type, as well as a short description of each. Clicking on the action takes you to a page which lists all the available properties for each action as well as an example of what one might look like in practice.

The main page of the YAML reference also lists how to combine actions into groups and create arrays of actions to be sent as one single script to the API.

ReDoc

ReDoc is one of two tools you can use with the API. It contains examples, brief information on each of the command types, and a list of response patterns that you may receive plus what each of them means.

You can find ReDoc located at hostname:5159/api/actions/reference/index.html where hostname is the name of the computer hosting BarTender. When you navigate to this URL in your browser, you'll be greeted by the API.

Each of the API commands can be found either by scrolling down the page or using the menu on the left side to reach the command of choice. When you navigate to each command, the right-hand bar will scroll with you and has interactive sections you can use to see example API calls and responses.

For POST, you are presented with sample BTXML. The content type can be changed to swap the format between BTXML, YAML, and JSON. Some examples have a second drop down menu with additional examples. Here is a screenshot of the POST command with a JSON example selected

Below the example and the description of how the example works is a list of possible responses sent back from the API. The API uses common HTTP response codes, though each one is tailored to mean something specific for the API, such as the script is in the wrong format or the client is not an authenticated user.

Each type of command has a different set of response codes and they're color coded to indicate if the command was successful or not. The green ones can be expanded to see what is in a successful response code. Here is an example of responses from POST:

Swagger

Swagger is an API reference and tool that comes packaged with the BarTender suite installation. It contains a full script and REST command reference with the added benefit of being able to use it for testing scripts.

You can find swagger at hostname:5159/swagger where hostname is the name of the computer hosting BarTender. When you enter this address into your web browser, it brings up the front page of the documentation.

Each command is clickable and expands to show a brief description as well as a testing tool. When you click the Try it Out button on the right-hand side, you can edit the values you wish to send to the server. For Swagger, you can either use a text file containing a custom script, or build off the examples in the request body at the bottom.

Once you've edited the values and are satisfied, scroll, down and click the big blue Execute button. This will send the script to the server, which will send a response back. For example, this is a successful response returned from a POST command:

Much like with ReDoc, there is a list of responses below the REST tool. It lists all the potential response codes plus a brief description. The successful response codes will also have an example of what might be returned.

You can use Swagger as a tool to test your scripts and make sure they work correctly before placing them into production. It's a good tool for troubleshooting and checking the response patterns in real time using a visual representation of the system.