BarTender Librarian
INTEGRATING SECURE WORKFLOW AND REVISIONCONTROL INTO YOUR PRODUCTION ENVIRONMENTSUPPORTS: BARTENDER ® 2021 PREVIEW 2Contents
Overview
File Storage and Management
Library Repository
Viewing Your Files and Folders
Managing Your Files
Workflows in Librarian
Creating and Configuring Workflows
Using Workflows in Librarian
Librarian API
Beginning a Visual Studio Project
Using the Librarian API
Security
Librarian Permissions in Administration Console
Workflow and Rules Permissions in Administration Console
BarTender Permissions in Administration Console that Apply to Librarian
Organizing Users and Groups According to Their Functional Roles
Advanced Security
Appendix A: Integrating Librarian with BarTender and Companion Applications
Administration Console
BarTender
Integration Builder
Print Station
Process Builder
Reprint Console and History Explorer
Appendix B: Syntax for Referencing Files in the Library
Review of Standard Windows Syntax
Referencing Files in the Library

3
5
5
5
7
10
10
11
12
12
12
15
15
16
17
17
18
19
19
19
19
20
20
20
21
21
21

Related Documentation

22

Overview
Librarian is a companion application to BarTender that groups of designers, administrators, andother users can use to cooperatively and securely manage how BarTender documents, images, andother types of files are stored and revised. Librarian can help you better manage any printing system,
but it is particularly valuable in highly regulated or secure environments, such as the medical,
pharmaceutical, military and chemical industries.
Librarian stores files in the BarTender System Database. File check-in and check-out processes
prevent users from overwriting each other's changes. Copies are retained of all previous versions ofa file so that you not only have a history of who made what changes and when, but you can also
retrieve copies of the previous versions and even revert a file to an older version. You can use
Librarian together with Administration Console to control which users can access files in Librarian
and what those users can do with the files.
In Administration Console, you can create and edit workflows to assign to files that reside in
Librarian. By doing this, you can track the progress of your files through the different steps of yourpublishing process. You can also use workflows to send email notifications to the users and groups
who need to be notified of changes in a file's workflow state or who need to review and approve files
at certain workflow steps. Librarian displays the workflow that each file is currently assigned to andthe workflow step that each file is currently in, and you can use Librarian features to advance files
through a workflow. For more information, refer to the Understanding Librarian Workflows technicaldocument at the following Seagull Scientific website:
https://www.seagullscientific.com/media/2081/understanding_librarian_workflows.pdf
Developers can use the Librarian application program interface (API), which uses any .NET language,
to check files in and out of Librarian, to revert to specific revisions of a file, and to get file informationthat is saved to the BarTender System Database.
Librarian is supported by the Enterprise edition of BarTender.

BarTender Librarian3

BarTender Librarian4

File Storage and Management
Library Repository
Librarian securely stores BarTender documents and other types of files in its Library repository,
which is a dedicated set of tables within the BarTender System Database. By using this centralized
file storage location, you can easily organize and manage multiple files that would otherwise be loose
on your hard drive. The process for bringing files into the Library repository and managing them isstraightforward and uses traditional Windows file management techniques whenever possible.

Configuring the BarTender System Database
The first time that you use Librarian, you are prompted to configure the BarTender System
Database (if it is not already configured) by following the steps in the System Database Setup
wizard. The wizard configures Microsoft SQL Server or Microsoft SQL Server Express for use by
the BarTender Suite.

Implementing a Secure Database
Any person who understands databases can use SQL Server Enterprise Manager (and otherdatabase tools) to browse and edit a SQL Server database without installing Librarian. Therefore,
when you want the highest possible level of security, your systems administrator must takeadditional steps to prevent unauthorized users from accessing your SQL Server or SQL Server
Express database by using software other than Librarian.
For more information, refer to the BarTender Security technical document at the following
Seagull Scientific website:
https://www.seagullscientific.com/resources/white-papers/

Viewing Your Files and Folders
Librarian makes it easy to view the files and folder structure that you add to the Library repository
and to view a file's revision history.

Folders PaneUse the Folders pane, which is located on the left side of the
Librarian window, to view files that are currently designated in aworkflow as needing your approval, view files that are currently
checked out to you, and organize the files in the Library directoryin any structure that you want. You can add new folders, move
them, and rename them just as if they were folders in Windows
Explorer. The Library directory provides a basic storage location
for all of your Librarian files. This directory can be accessed byapplications in the BarTender Suite.

Files Pane
When you click a folder in the Library directory, the files that are in that folder are displayed in theFiles pane of the main Librarian window.

BarTender Librarian5

The Files pane displays a timestamp and file size, just as the standard Windows Explorer filesystem does, displays how many times a file has been revised and, if the file is assigned to aworkflow, displays the name of the workflow and the workflow state each file is currently in.

File History Pane
The File History pane displays a variety of revision history information that is not available in the
Windows Explorer file system. This information includes a summary of the actions that weretaken for the file for each revision (such as Add Comment and Check Out), the user who
performed those actions, the comments that were logged by the user, and which workflow state
the file is in if the file is assigned to a workflow.

Details and Preview PaneUse the Details and Preview pane to switch between a display of information about the file thatis currently selected in the Files pane and a preview of the selected file revision. When a file isassigned to a workflow, you can also use the Details pane to move the file to the next state in
the workflow.

BarTender Librarian6

To switch between views, click the Details or Preview tab at the bottom of the pane.

Managing Your Files
Adding Files to Librarian
To add files to Librarian, use one of the following methods:lll

From Windows Explorer, drag a file into the Folders orFiles pane.
On the Librarian File menu, click Add. Alternatively, rightclick the Folders or Files pane, and then click Add.
In BarTender, when you save a document, click the
Librarian icon in the Save As dialog, and then browse to
the Library folder in which you want to save the file.

BarTender Librarian7

Getting the Latest Revision
When you get the latest revision of a file, Librarian copies the last stored copy of the file in the
database to a location on your hard drive. Librarian does not check out the file or make itwritable on your drive. You can only view the latest changes that were made to the file.
To get the latest revision of a file, select the file in the Files pane, click File, and then click Get
Latest Revision. Alternatively, right-click the file in the Files pane, and then click Get Latest
Revision. When you do this, the Get File(s) dialog opens, which you can use to browse to andselect a folder on your network into which you want to copy the selected file.

Checking Files In and Out
When files are stored loose on a hard drive, users can accidentally (or deliberately) open and edit
files that other users are currently working on. This creates confusion and increases thepossibility that one user might overwrite another user’s changes. Librarian solves this problem
with its check-in and check-out functionality. When a user checks out the file, the file is writable
only for that user. All other users are prevented from editing the file until the original user checks
the file back in to the library.
When a file is checked out, a red check mark ( ) is displayed. When it is checked in, a yellow lock () is displayed.

You can see who has a file checked out by using the file's Properties dialog or by viewing the User
column in the File History pane. When users check out a file, their name appears next to theCheck Out action.

If you accidentally check out a file and want to check it back in without saving any changes, selectthe file, and then click Undo Check Out on the File menu. Alternatively, right-click the file, andthen click Undo Check Out. Any changes that you made are discarded, and the file reverts to thestate that it was in before you checked it out.

BarTender Librarian8Deleting, Restoring, and Purging Files or Folders
To delete a file or folder from Librarian means to remove it from the Library folder and the
Librarian user interface. When you delete a file, it cannot be modified, checked out, or checked
in, and when you delete a folder, all of the subfolders and files that it contains are also deleted.
However, the deleted file or folder (and its contents) does remain in the BarTender System
Database and can later be restored.
After you delete an item, you can purge it, which removes it from the BarTender System
Database altogether. When you purge a deleted file or folder, you remove all history of thedeleted item. This operation cannot be reversed. Purged items cannot be restored.
To delete an item from the Library, select the item, and then click Delete on the File menu.
Alternatively, right-click the item, and then click Delete. You can also select the item and thenpress Delete on your keyboard.
To see deleted items, click Show Deleted Items on the View menu. When you do this, allpreviously deleted folders and files are shown with faded file type icons.

To restore a previously deleted item, select the item that you want, and then click Undelete on
the File menu. Alternatively, right-click the item, and then click Undelete. After you do this, thefile or folder is restored to the Library, and you can continue to manage it as before.

BarTender Librarian

9

Workflows in Librarian
A workflow is a series of steps that define the life cycle of a BarTender document or other file. For afile that is stored in Librarian, a workflow is a series of states and transitions between the states thatthe file progresses through. These workflows can help you automate your business processes, suchas reviewing template designs or approving documents for production, and track the status of yourfiles from start to finish.

Creating and Configuring Workflows
Beginning in BarTender 2021, you use Administration Console to configure workflows (by using theWorkflow Designer) and to apply them to the files that you want (by creating workflow rules). You canthen use Librarian features to send files through the workflow progression.
Workflows consist of states that you create and customize (for example, Design, Staging, andProduction) and transitions between these states that you create and customize (for example,
Submit For Staging and Submit For Production), as illustrated in the following image, which shows theWorkflow Designer design canvas.

For each state and transition, you can specify the users or groups that you want to have access tothe file for viewing, editing, and moving to the next stage. For example, you might want to limit accessto files that are in a Design state to only members of your design team and specify further that only
certain members of that team have permissions to send a file from Design to Staging.
You can also configure email notification messages to be sent to specific recipients when you want afile to be reviewed and approved by others at various stages in its workflow life cycle. For example,
you might want an email notification to be sent to the lead designer who is responsible for the

BarTender Librarian10

decision to approve the file and then use the Submit For Staging transition to move it to the Staging
state.
For more information, refer to the Understanding Librarian Workflows technical document at thefollowing Seagull Scientific website:
https://www.seagullscientific.com/media/2081/understanding_librarian_workflows.pdf

Using Workflows in Librarian
When files are assigned to a workflow, the name of the workflow and the workflow state that the fileis currently in are displayed in the Files, File History, and Details panes. When you have permissions
to access the files at one or more stages in the workflow, you can move a file from its current
workflow state to the next state. To do this, use one of the following methods:ll

In the Files or File History pane, right-click the file, point to Transition, and then click thetransition step that you want.

In the Details pane, click the transition step that you want in the Workflow Information area.

BarTender Librarian11

Librarian API
By using the Librarian API, you can develop custom applications, in any .NET language, that use theprimary functions of Librarian to embed revision control and workflow settings in your environment.
You can use the Librarian API to check files in and out of Librarian, revert to specific revisions of a file,and get file information that is saved to the BarTender System Database.

Beginning a Visual Studio Project

We recommend that your development environment use Microsoft
Visual Studio 2019 and Microsoft .NET Framework version 4.7 orlater versions.
To begin a project in Visual Studio, follow these steps:
1. On the File menu, click New, and then click Project.
2. In the Project Types panel, under either the Visual C# or the Visual Basic node, click
Windows.
3. In the Templates pane, click Windows Application.
4. Name the project, and then click OK.
5. After you create the project, add a reference to Seagull.BarTender.Print.
6. In the Solution Explorer pane, right-click the References node, and then click Add Reference.
7. In the Add Reference window, click the .NET tab, select Seagull.BarTender.Print, and thenclick OK.
8. Verify that the project can build and compile by pressing Ctrl+Shift+B on your keyboard. If
this operation is successful, you are ready to begin your project.

Using the Librarian API
Adding Files
When you add a file to Librarian, users on the network can access the file from the BarTender
System Database. Subsequent changes to the file are also recorded to the system database,which means that users can revert to or track previous changes.
You add a BarTender file to the Library repository by calling the Library class AddFile method. The
following sample C# code shows how to add a file to Librarian.
Library library = new Library();
LibrarianFile file = library.AddFile("lib://Formats/Address.btw",@"C:\Users\Administrator\Documents\Address.btw", "Added Address.btw to thelibrary.");The first parameter that is passed in the AddFile method is the file name and the path of thefolder where you want to save your document. The second parameter specifies the path and file

BarTender Librarian12name of the file to add, and the third parameter is the comment that describes the addition of
the file into the Library.
The Library class provides an overload for the AddFile method to specify additional advanced
options for adding a file.

Checking In Files
You can check a file in to the Library repository by using the LibrarianFile CheckIn method, which
retrieves a file from a specified location on your computer and saves it to a folder in the Library.
Several overloads exist for the CheckIn method. The simplest overload requires the path and filename of the file on your computer and a comment that describes the changes that were madeto the file. The following sample C# code shows how to check in a file to the Formats directory of
the Library.
Library library = new Library();
LibrarianFile file = library.GetFile("lib://Formats/Address.btw");int revisionNumber = file.CheckIn(@"C:\Users\Administrator\Documents\Address.btw", "Modified the label design.");The first parameter in the CheckIn method specifies where to retrieve the file on your computer.
The second parameter specifies a comment that describes the changes that were made to thefile while it was checked out. Additional parameters can specify advanced check-in options.

Checking Out Files
You can check out a file from the Library repository by using the LibrarianFile CheckOut method,which saves the file to a specified location on your computer and makes the file available forediting.
Several overloads exist for the CheckOut method. The simplest overload requires only the pathand file name of the location where you want to save the file. The following sample C# codeshows how to check out a file from the Library.
Library library = new Library();
LibrarianFile file = library.GetFile("lib://Formats/Address.btw");file.CheckOut(@"C:\Users\Administrator\AppData\Local\Temp\Address.btw");

The first parameter in the CheckOut method specifies where to save the file. Additionalparameters can specify advanced check-out options.

Displaying Folder Contents
In Librarian, files and folders are stored in folders that consist of a single root directory and its
subdirectories. The root directory is the Library folder. This directory can contain subdirectories
that you create, such as "Templates" or "Images." Each subdirectory can contain any number ofsubdirectories.
You can list the contents of a directory in Librarian by using the LibrarianFile Name and/or Path
properties together with an iteration statement, such as a For loop. The following sample C#
code shows how to display a list of files in a directory that is stored in Librarian.

BarTender Librarian13

Library library = new Library();
LibrarianFolder folder = library.GetFolder("lib://Templates");// Iterate through the subfolders
StringBuilder listingBuilder = new StringBuilder();
foreach (LibrarianFolder subfolder in folder.Folders)listingBuilder.AppendFormat("Folder\t{0}\t{1}\tChildren: {2}\n",subfolder.Name, subfolder.Path, subfolder.Children.Count);// Iterate through the files in the directoryfor each (LibrarianFile file in folder.Files)
listingBuilder.AppendFormat("File\t{0}\t{1}\tRevision: {2}\n", file.Name,
file.Path, file.RevisionNumber);// Display the contents of the folder
System.Windows.Forms.MessageBox.Show(listingBuilder.ToString(), string.Format("Folder Contents ({0})", folder.Path));

In this example, a list of subdirectories and files is saved to a list of strings that is called
listingBuilder. After the list is populated with the contents of a directory, the name, path, and/or
revision number of each subdirectory or file is displayed in a message box.
For more information, refer to the Librarian API section in the Automation with the BarTender.NET SDK book of the BarTender help system.

BarTender Librarian

14

Security
To implement a secure printing system, you must make sure that the user permissions that are
specified in Administration Console allow only authorized users to access Librarian, the Workflow
Designer, and the files that are saved in Librarian folders.

Prior to BarTender 2021, permissions that allowed users to assign orchange a file's workflow state were also specified on the User
Permissions property page in Administration Console. Beginning in
BarTender 2021, file state and transition permissions are set byusing the Workflow Designer. For more information, refer to theWorkflows in Librarian chapter of this technical document.

Librarian Permissions in Administration Console
In Administration Console, you can set permissions for the actions that are associated with Librarianin the Librarian section of the User Permissions list. For each action, you can specify either Allow or
Deny for the user or group that is currently selected in the Users and Groups pane.

For Librarian, you can configure the following permissions in the Librarian permissions list:llRun: Allows users to run Librarian. Users who have only the Run permission can view files andfile history information.
Administer: Allows users to use the Librarian Administer menu to access the System Setup
dialog and the Workflow Designer and to purge deleted Librarian files.

BarTender Librarian15

This permission should be granted only to users who require
the highest level of administrative control for Librarian and theWorkflow Designer.

l

l

l

l

Edit Existing Comments: Allows users to edit comments that were logged when someone
checked a file in, renamed a file, or performed some other action on it.
Edit Files: Allows users to perform the following actions:o

Add comments to a fileo

Add files to the libraryoCheck in filesoCheck out filesoRevert files to previous revisionsoOpen files that are stored in the Library repository

Full File Control: Allows users to perform all the Edit Files actions and also move, rename,delete, and restore files in the Library repository.
Open Published Files: Allows users to open files that are in a published state.

Workflow and Rules Permissions in Administration Console
In Administration Console, you set permissions for the actions that are associated with the Workflow
Designer in the Librarian: Workflow and Rules section of the User Permissions list. For each action,
you can specify either Allow or Deny for the user or group that is currently selected in the Users andGroups pane.

BarTender Librarian16

For the Workflow Designer, you can configure the following permissions in the Librarian: Workflow
and Rules permissions list:l

Add workflows: Allows users to create new workflows.

lAdd, edit, and delete rules: Allows users to add, edit, and delete workflow rules.

lModify workflows: Allows users to edit existing workflows.

lRemove workflows: Allows users to delete existing workflows.

BarTender Permissions in Administration Console that Apply to Librarian
The BarTender permissions section of Administration Console includes the following permissions
that apply to Librarian:lPrint Published Documents: Allows BarTender users to print the latest published revision of adocument that is stored in Librarian. When you authorize a user to print documents, you also
grant permission to print published documents.

Because a file can be assigned to a workflow only if it is kept in
Librarian, files that are stored loose on a hard drive rather thanin Librarian can never be assigned a published workflow state.
Therefore, when you deny BarTender users the Print Published
Documents permission, you prevent them from even opening
documents from their individual hard drives. This can prevent
users from loading, creating, and printing unauthorized
documents.

lPrint Unpublished Documents: Allows BarTender users to print unpublished documents thatare stored in Librarian and all documents that are stored loose on a computer or the network.
The Print Unpublished Documents permission includes permission to Print Published
Documents.

Users who are denied this permission can only open
documents that are both stored in Librarian and in a publishedstate.

For more information about the Published property, refer to the Workflows in Librarian section of thistechnical document.

Organizing Users and Groups According to Their Functional Roles
When you plan the Librarian file states and Administration Console permissions that your file
management system will use, we recommend that you sort users into their functional roles and thenconfigure their permissions accordingly. For example, you might sort users into File Designers, File

BarTender Librarian17

Editors, Print Operators, and Publishers groups and then grant different types of permissions to eachgroup.
When your organization has multiple users who perform similar functional roles, it is easier toorganize them into domain user groups so that you can manage all of the group’s permissions at one
time instead of separately defining permission settings for each individual user.

Advanced Security
More advanced techniques that you can use to create and implement a secure file publishing
workflow within Librarian include the following.

Electronic Signatures
To improve the security in your publishing system, you can use the Administration Console
Electronic Signatures page to specify that users must enter an electronic signature (usercredentials) to perform actions that are listed in the Librarian section and the Librarian:Workflow and Rules section.

Logging
By using the Administration Console Logging page, you can specify that user requests to perform
actions that are listed in the Librarian section and the Librarian: Workflow and Rules section
are logged to the BarTender System Database. Then, you can review which users haverequested to perform which actions.

Document Encryption
By using the Administration Console Document Encryption page, you can encrypt individual
BarTender documents. Note that encryption is an advanced security technique that has certain
risks that you must guard against.For more information, refer to the Document Encryption Page
topic in the BarTender help system.

Controlling the Printing of Unpublished Documents
A security risk occurs any time that a user prints an unpublished (and therefore unauthorized)
BarTender document. Therefore, you should grant the Print Unpublished Documents
permission only on an as-needed basis.
Also, to guard against the possibility that unauthorized users might use someone else's
computer to print unpublished BarTender documents, you may want to require that users enterelectronic signatures before they can print. When you do this, you also create a log of theauthorized users who printed unpublished documents and when the print jobs occurred.

BarTender Librarian18

Appendix A: Integrating Librarian with BarTender and Companion
Applications
You can use files that are stored in Librarian in many of the companion applications that are includedin the BarTender Suite. This appendix describes how each application can work with Librarian in yourproduction environment.

Administration Console
Use the Administration Console Librarian and Librarian: Workflow and Rules permissions to control
whether users can do the following:l

Edit existing comments in a document that is stored in LibrarianlEdit files that are stored in LibrarianlHave full file control over files that are stored in LibrarianlOpen published files that are stored in LibrarianlChange workflow states

For more information, refer to the Security section of this technical document.

BarTender
When you work in a BarTender document, you can use BarTender Designer to access related files,
such as databases or images, that are stored in Librarian.

Integration Builder
Integrations can be saved to and opened from the Library, and Integration Builder can refer to files
that are stored in the Library.

Librarian Syntax and Integration Builder
The referencing syntax that Librarian uses can be used in Integration Builder to refer to a filefrom a command prompt. Integration Builder can use Librarian syntax with BarTender XML(BTXML) script, which is used when you run commands from within Integration Builder that startand control BarTender print jobs.
For more information about Librarian syntax, refer to Appendix B: Syntax for Referencing Files inthe Library.

BarTender Librarian19

Print Station
You can select a Librarian folder to be the root folder for Print Station. This is the folder that Print
Station uses to display the documents that are available to be printed.

Process Builder
You can save BarTender process files, which have the *.btproc file name extension, in the Libraryand edit them by using Process Builder. Additionally, process files can refer to BarTender documentsthat are stored in the Library.

Reprint Console and History Explorer
Reprint Console and History Explorer interact with Librarian indirectly via BarTender. BarTender
documents that you view and/or reprint by using these applications can reside in the Librarian
database.
For more information about the companion applications, refer to their corresponding technicaldocuments:
https://www.seagullscientific.com/resources/white-papers/

BarTender Librarian

20

Appendix B: Syntax for Referencing Files in the Library
Librarian provides a syntax for referencing files in the Library, similar to the standard syntax forreferencing files on a hard drive.

Review of Standard Windows Syntax
Because Windows users typically use their mouse to click through folders and subfolders to find files,
they may not remember that the file path syntax that Windows uses is the following.
C:\<path>\<filename>For example, to open a BarTender document, you might reference it by using the following syntax.
C:\MyTemplates\ShippingLabel.btw

Referencing Files in the Library
The syntax for referencing files in the Library more closely resembles an Internet location than a hard
drive location. The syntax is as follows.
lib://<path>/<filename>

This Internet-style URL uses forward slash marks instead of backslashes, and the “lib://” at the
beginning is always required to reference files in the Library. Therefore, when you access a file in the
Library, you use the following file reference syntax.
lib://MyTemplates/ShippingLabel.btw

Library files can be referenced by using one of the following methods:
l

l

l
l

On the BarTender or Librarian File menu, click Open, and then enter the text string for the filethat you want to reference in the File Name field.
In Process Builder, click the Administration tab, click Open, and then enter the text string forthe process file that you want to reference in the File Name field.
In Print Station, enter the text string for the file that you want to print in the Search field.
Run BarTender by using command-line parameters. The following sample command instructs
BarTender to open a document from the Library and then start a print job.

bartender.exe /F="lib://templates/shipping/overnight.btw" /Pl

Run a print job that requires BarTender to read data-sourced graphics while printing.

l

Run a BarTender XML script.

l

In Integration Builder, run commands that start and control BarTender print jobs.

For more information about how Librarian interacts with BarTender and the companion applications,
see Appendix A: Integrating Librarian with BarTender and Companion Applications.

BarTender Librarian21

Related Documentation
Seagull Scientific BarTender 2021 Preview 2 Web Pagesl

BarTender 2021 Preview 2
https://www.seagullscientific.com/support/preview-2/

lWhat's new in BarTender 2021 Preview 2
https://www.seagullscientific.com/support/preview-2/whats-new-preview-2/

Other Resources
Please visit the BarTender website at https://www.seagullscientific.com.

BarTender Librarian22