White Paper

// Blackboard Transaction System Service Client

Version 1.2
16-Dec-2016

Version 5.1 onwards

Confidentiality: Internal + Partner (R3P)

Confidentiality: Internal + Partner (R3P)
Disclaimer
NT-WARE Systemprogrammierungs-GmbH, all its affiliates, partners and licensors disclaim all warranties,
including, but not limited to, warranties about the accuracy or completeness of statements of this
site's/document's content or the content of any site or external sites for a particular purpose. This
site/document and the materials, information, services, and products at this site/document, including,
without limitation, text, graphics, and links, are provided 'as is' and without warranties of any kind, whether
expressed or implied.
All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic,
electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval
systems - without the prior written permission of NT-WARE Systemprogrammierungs-GmbH (hereinafter
also referred to as NT-ware).
Company and product names mentioned herein are registered or unregistered trademarks of their
respective companies. Mention of third-party products is for information purposes only and constitutes
neither an endorsement nor a recommendation. NT-ware assumes no responsibility with regard to the
performance or use of these products. Also, NT-ware makes no claim to these trademarks. Any use of
trademarks, logo, service marks, trade names, and product names is prohibited without the written
permission of the respective owners.
Adlib, Express and Express Server are either registered trademarks or trademarks of Adlib Publishing
Systems Inc.; Adobe®, Adobe® Reader®, Acrobat®, Distiller®, PostScript® and products of the CREATIVE
SUITE(S) are either registered trademarks or trademarks of Adobe Systems Incorporated in the United
States and/or other countries; Android is a trademark of Google Inc.; Apple®, the Apple® logo, Mac®, Mac
OS®, Macintosh®, iPhone®, iPad® and AirPrint® are trademarks of Apple Inc. registered in the U.S. and other
countries; Box of Box Inc.; Blackboard Transact™ of Blackboard Inc.; CANON, imageRUNNER, imageRUNNER
ADVANCE, MEAP, CPCA, AMS, iW AMS, iW Desktop, iSend, iW SAM are trademarks or registered
trademarks of Canon Inc.; CardSmith® is a trademark of CardSmith LLC; CBORD CS Gold® of the CBORD
Group Inc.; Crystal Reports and other Business Objects products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business
Objects is an SAP company; Dropbox of Dropbox Inc.; eCopy™, eCopy ShareScan® and eCopy ScanStation™
are marks or trademarks of Nuance Communications, Inc.; Evernote® of Evernote Corporation; FileNet® of
IBM Corporation; Foxit®SDK and Foxit® Reader of Foxit Corporation; Google Docs of Google Inc.; Google
Cloud Print™ web printing service is a trademark of Google Inc.; Helix™ Production Workflow is a trademark
of NT-WARE Systemprogrammierungs-GmbH; HP, HEWLETT-PACKARD, PCL and LASERJET are registered
trademarks that belong to Hewlett-Packard Development Company; KONICA MINOLTA is a registered
trademark of KONICA MINOLTA Inc.; iOS® of Cisco Technology Inc.; iDRS™ SDK and IRISConnect™ are
unregistered trademarks of I.R.I.S. Group S.A.; JAWS pdf courier™ are trademarks of Global Graphics SA.;
Microsoft®, Windows®, Windows Server®, Internet Explorer®, Internet Information Services, Microsoft®
Word, Microsoft® Excel, Microsoft SharePoint®, Microsoft SharePoint® Online, OneDrive®, One Drive® for
Business, SQL Server®, Active Directory®, Hyper-V® are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries of Microsoft Corporation; Neevia
Document Converter Pro™ of Neevia Technology; NetWare®, Novell®, Novell eDirectory™ of Novell Inc. are
registered/unregistered trademarks of Novell Inc. in the United States and other countries; MobileIron® of
Mobile Iron Inc., Océ, Océ PlotWave®, Océ ColorWave® and PRISMA are trademarks or registered
trademarks of Océ-Technologies B.V. Océ is a Canon company, OpenOffice.org™ of Oracle Corporation;
PAS™ is a trademark of Equitrac Corp.; PosterJet is copyrighted and an internationally registered trademark
of Eisfeld Datentechnik GmbH & Co. KG; RedTitan EscapeE of RedTitan Limited; NETAPHOR®, SiteAudit™ are

Confidentiality: Internal + Partner (R3P)

trademarks of NETAPHOR SOFTWARE Inc.; SAMSUNG is a trademark of SAMSUNG in the United States or
other countries; Therefore™, Therefore™ Online of Therefore; UNIX® is a registered trademark of The Open
Group; uniFLOW®, uniFLOW Serverless Secure Printing®, Helix Production Workflow®, MIND®,
microMIND®, MiCard® and uniFLOW Service for AirPrint® are registered trademarks of NT-WARE
Systemprogrammierungs-GmbH; pcProx®, AIR ID® are registered trademarks of RFIdeas Inc.Readers;
CASI-RUSCO® is a registered trademark of ID Card Group; Radio Key® is a registered trademark of Secura
Key; GProx™ II is an unregistered trademark of Guardall; HID® ProxHID is a registered trademark of HID
Global Corporation; Indala® is a registered trademark of Motorola; ioProx™ is an unregistered trademark of
Kantech; VMware vSphere® and VMware vSphere® Motion® are registered trademarks of VMware; Xerox,
Xerox and Design, as well as Fuji Xerox and Design are registered trademarks or trademarks of Xerox
Corporation in Japan and/or other countries.
All other trademarks, trade names, product names, service marks are property of their respective owners
and are hereby acknowledged.
While every precaution has been taken in the preparation of this document, NT-ware assumes no
responsibility for errors or omissions, or for damages resulting from the use of information contained in this
document or from the use of programs and source code that may accompany it. NT-ware does not assume
any responsibility or liability for any malfunctions or loss of data caused by the combination of at least one
NT-ware product and the used operation system and/or third-party products. In no event shall NT-ware be
liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly
or indirectly by this document.
In addition, this manual provides links to the sites of affiliated or independent companies and certain other
businesses. NT-ware is not responsible for examining or evaluating, and NT-ware does not warrant the
offerings of, any of these businesses or individuals or the content of their websites. NT-ware does not
assume any responsibility or liability for the actions, product, and content of all these and any other third
parties. You should carefully review their privacy statements and other conditions of use.
Friday, December 16, 2016, Bad Iburg (Germany)

Important Note
Serious problems might occur if you modify the registry of your Windows operating system incorrectly.
These problems might require that you reinstall the operating system. We strongly recommend to always
back up the registry of your Windows operating system before applying changes to it, just in case you do
something wrong. NT-ware does not assume any responsibility or liability for any impact on the
operating system after changing the registry. You understand and accept that you use this information
and modify the registry of your Windows operating system at your own risk.

Copyright and Contact

NT-WARE Systemprogrammierungs-GmbH
Niedersachsenstraße 6
49186 Bad Iburg
Germany
www.nt-ware.com
Tel: +49 - 54 03 - 7243 - 0
Fax: +49 - 54 03 - 78 01 03

Confidentiality: Internal + Partner (R3P)

Email: info@nt-ware.com
Register of Companies: Amtsgericht Osnabrück
No. of entry in Register of Companies: HRB 110944
Chief Executive Officer: Karsten Huster
Responsible according to § 6 MDStV: Karsten Huster
VAT registration no. according to §27 a Umsatzsteuergesetz: DE 230932141
©1998-2016 NT-WARE Systemprogrammierungs-GmbH.

Feedback
Should you come across any relevant errors or have any suggestions please contact
documentation@nt-ware.com or use the Send feedback here button of the uniFLOW Online Help.

Technical Support
First technical support services will be provided by your dealer. Before you contact the dealer for technical
support, ensure you have read this document.

Confidentiality: Internal + Partner (R3P)

How to use this Document
Text Styles
This style is used for text that is displayed on screen.
This style is used for text the user has to type in.
This style is used for hyperlinks to web pages, internal links to other pages in this manual.
This style is used for code examples: XML code, variables or regular expressions.

Pictograms

Important Note:
Information that is crucial for the correct functioning of the uniFLOW software.

Further Information:
Pointer to additional manuals, installation manuals, white papers or the NT-ware
Knowledgebase.

Region Specific Feature:

Indicator for uniFLOW features that are not available worldwide.

External Link:
Link to an external web page.

Settings:
Detailed explanation of configuration settings or operational procedures.

Compass:
Path to the menu or configuration page in the software.

Screenshots and Diagrams

This manual contains screenshots of the software, diagrams explaining relations and pictures of products.
Even though all visuals are up-to-date at the time of writing, they are subject to change.

Language and Translations

This document has originally been written in English language. Translations of this document are based on
the English original.

Send Feedback
Should you come across any relevant errors or have any suggestions please contact
documentation@nt-ware.com or use the Send feedback here button of the uniFLOW Online Help.

Confidentiality: Internal + Partner (R3P)

About this Document
This document is delivered as part of the device / the software from NT-ware. Please read this document
before using the device / the software and keep this document or the link to an online version of this
document for future reference. Please make sure that all persons operating the device / the software are
familiar with this document. Please observe all instructions given in this document. Installation,
configuration and maintenance must only be performed by sufficiently qualified personnel. Failure to
comply with this document may void the warranty.
Every effort has been made to ensure that the contents of this manual are accurate. However, NT-ware
reserves the right to make changes without notice.

Confidentiality: Internal + Partner (R3P)

Confidentiality: Internal + Partner (R3P)
Versioning
Document Version Date Author(s) Reviewer(s)
Versioning
Claudia
1.0 February, 2012 Matthias Frye
Kleinekemper
Claudia
1.1 October, 2015 Joe Lucas, Matthias Frye, Thomas Lemmer
Kleinekemper
Thomas
1.2 16-Dec-2016 Thomas Lemmer
Lemmer

Document Name White Paper - Blackboard Transaction System Service Client.

Knowledgebase MOMKB-604 (https://web.nt-ware.net/its/browse/MOMKB-604)

File Name White Paper - Blackboard Transaction System Service Client.pdf

Technologies
uniFLOW, Blackboard
Concerned

Short Summary Described the integration of the Blackboard Transaction System Service Client plug-in for uniFLOW.

Document Version Topic(s) Changes

Changes
Complete overhaul of document after
1.0 Complete document
import to Author-it.
Configuration Parameters in uniFLOW (on
page 6) Added missing parameters and Logging
1.1 Information.
Logging (on page 9)
Renamed License.
All topics

1.2 All topics Updated terminology.

Confidentiality: Internal + Partner (R3P)

Confidentiality: Internal + Partner (R3P)
White Paper Contents

Contents
1 Blackboard Transaction System Service Client ............................................ 1
1.1 Plug-in Activation .......................................................................................................... 3
1.1.1 Automatically ................................................................................................................................. 4
1.1.2 Manually ........................................................................................................................................ 4
1.2 Configuration Parameters in uniFLOW ........................................................................... 6
1.3 Logging ......................................................................................................................... 9

I
Confidentiality: Internal + Partner (R3P)
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

1 Blackboard Transaction System Service Client

Only available in the USA and Canada.

Requirements
 Basic uniFLOW Server License V5.1 or higher.
 Blackboard Transaction System (BbTS) server running BbTS protocol version 2. The
Blackboard server has to be configured in such a way, that connections from the
NT-ware Blackboard Budget Connector plug-in are allowed!
 One Blackboard-CardSmith Budget Connector Plug-in license per Blackboard
Transaction System server.
 Blackboard Transaction System Service Client plug-in files (.bca).

The Blackboard Transaction System Service Client plug-in is a .NET-based budget

plug-in for performing budget transactions on Blackboard Transaction System (BbTS)
servers. It is designed upon the Blackboard Transaction Integration documentation and
supports servers running BbTS protocol version 2.
The BbTS protocol supports several monetary and point-based transaction types. The
following list presents a short overview:

Supported Transaction Types

 Authorization limit inquiry (Request maximum stored value account balance incl.
credit limits)
 Balance inquiry (Request stored value account balance without credit limits)
 Debit (Deduct monetary value from a stored value account for the purchase of
products/services)
 Refund (Add monetary value to a stored value account for return
products/services previously sold)

Disabled Transaction Types

 Deposit (Add monetary value to a stored value account)
 Count (Deduct a count from a non-monetary/point-based account)
 Activity (Request authorization for a non-monetary activity. Does not access an
account)
 Cash Equivalency (Monetary equivalency of points in a point-based account
applied by the 3rd-party system)

1
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

Data that is evaluated for transactions

The Blackboard transaction system uses several data fields for identifying the user, the
vendor, and the account involved in a transaction. The following list gives a short
overview of the data sent to a Blackboard transaction server:
 Vendor Number:
The vendor number uniquely identifies the provider of the B2 agent system
performing the transaction. The vendor number is assigned by Blackboard after
successful verification of the agent system. The vendor number cannot be
configured.
 Terminal Number:
A terminal number is a unique identifier for a terminal or pay station which
performs a transaction.
 Track Data/Manual ID:
Card number or manually entered ID for the user whose account should be
accessed.
 PIN:
An optional numeric secret for validation of the user.
 Tender Number:
A tender number is a value account ID inside of a user's account. The Blackboard
system supports multiple monetary and non-monetary accounts for one user with
different values and credit limits, that are identified by the tender number.

Communication between Client and Server

The communication to a BbTS server can either be configured as unencrypted or as
secured communication.
The secured communication uses a 128bit shared-key AES encryption. In productive
environments we recommend to always use an encrypted communication. The AES
key has to be provided by the Blackboard server administrator and is entered as a
hexadecimal value. The encryption is packet-based.
Please note that only transaction related data fields are encrypted, other parts remain
unencrypted.

To ensure a correct transmission of transaction requests and responses, each data

packet is signed by an error check code to verify the received data. In unencrypted
mode the LRC (Longitudinal redundancy check) algorithm is used, appending a 8-bit
error check data to the packet. In encrypted mode, a 16-bit CRC (Cyclic Redundancy
Check) value is applied.
Optionally, it is possible to enable offline transactions ensuring uniFLOW can further
execute jobs, even if the connection to the Blackboard transaction server has been
broken. In this case pending transactions are cached and will be executed after the
connection to the Blackboard server has been re-established.

2
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

Please keep in mind that it is not possible to verify the customer's current account
balance while the server connection is down.

1.1 Plug-in Activation

The Plug-in is provided with the uniFLOW installer. Prior to be able to configure the
plug-in, you first have to activate the Blackboard-CardSmith Budget Connector Plug-in
license in the Activation menu of the uniFLOW Module Config.
Activation codes are generated by the NT-ware licensing portal and are based on the
license code, the system ID of the system on which the software is installed and the
version of the uniFLOW software. In order to obtain an activation code proceed as
follows.
Please observe that you can only activate the plug-in if your uniFLOW Basic Edition has
already been activated beforehand.

1. Go to uniFLOW Server Configuration > Module Config. > Activation in order to

start the activation of the Blackboard-CardSmith Budget Connector Plug-in license.
2. In the License check section, enter your license number next to License Code
(Module) and select the Blackboard-CardSmith Budget Connector Plug-in from the
drop-down list next to Module Name.
3. Finally, click on the Activate Module button. Then, the license code will be
checked. Following this, the Activation screen is shown. Here you can choose
between a manual or an automatic activation.

3
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

1.1.1 Automatically
For an automatic activation, you need an internet connection. Note that the uniFLOW
server does not require an internet connection, only the PC with which you connect to
the uniFLOW server needs to have an internet connection. Thus, you can activate the
module from an administrator’s PC if this PC has internet access and can connect to
the uniFLOW server on the local network. You may also use proxies to connect to the
internet.
In order to start the automatic activation, please click the Activate button next to
Activate automatically.
Subsequently, the following happens.
 Your license code, system ID and name will automatically be sent to the NT-ware
activation portal.
 Your activation code will be written into the registry.
 You will return to the Activation menu again.

1.1.2 Manually
In the Activation screen, a manual activation is possible as well.
There are three different possibilities to receive an activation code:
 Online (by clicking on the here link)
 Email (by clicking on the Email link)
 Fax (by sending a fax to the given Fax number)

4
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

Online
1. If you choose the online possibility, then click on here*. Your web browser will
open and you will automatically be directed to NT-ware’s licensing website, where
all required fields will automatically be pre-filled.

2. Click on the submit button. You will then enter a screen in which you can check
your entries. If you click the Activate button here, the following screen opens.

3. You can now copy the activation code to your clipboard or print out this site.
Optionally, you can manually generate an activation code by opening your
browser and entering the address of the NT-ware licensing website:
License Portal (http://lp.nt-ware.net)

5
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

Fill out the required fields. Once you have entered all necessary information, click
the submit button. You will then enter the same screens as described above.

Email
If you want to receive your activation code by email, click on the
support@nt-ware.com link. The generated email will include the information that is
required for generating the activation code. You can add some additional information
of your choice. Upon receiving your request, we will send the activation code to you as
soon as possible.

Fax
If you want to receive your activation code by fax, please send a fax to:
+49-5403-780103.
In the fax, please include the following information:
 Serial number
 Version
 License code
 System ID
 Customer name
 Contact details, for example name/address to which the activation code should be
sent
After you have received your activation code, enter this code into the Manual Code
input field on the uniFLOW activation screen and click the Activate button to activate
your software.
After you have received the activation code, enter the received activation code into
the field next to Manual Code and finish the activation by clicking the Activate button.

1.2 Configuration Parameters in uniFLOW

After the activation of the plug-in license you can proceed with the Blackboard
configuration under Server Config. > Interface > Budget mgmt. system.
In order to connect uniFLOW to a Blackboard Budget Management System proceed as
follows:
1. Select Universal Budget Manager from the drop-down list next to Budget
Management System and click on Save.
2. In general, ensure Force Standard Budget System for uniFLOW Server is set to No
(default). If set to Yes, the uniFLOW server will make use of the internal budget
system instead of the Blackboard plug-in.
In environments where only (an) RPS(s) shall make use of the Blackboard plug-in,
set this parameter to Yes.
3. Select the Blackboard Transaction System Service Client from the drop-down list
next to Default Budget Plug-in and click on Save.

6
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

4. Now, the configuration parameters for the Blackboard Budget Management

System are displayed.

 Server address:
The host name or the IP address of the Blackboard server without port.
 Server port:
The port the Blackboard server listens on. The default port is 9003. Enter the
corresponding port number if your Blackboard server listens to a different port
than the default one.
 Terminal number:
The number of the Blackboard terminal to uniquely identify the client. Each server
requires a unique number. The terminal number has to be assigned by the
Blackboard server administrator.
 Default Tender number:
The tender number that shall be used, when accessing a customer's account.
Blackboard supports multiple tender numbers for accessing a user's account. The
number entered here is then associated with the uniFLOW server. The default
number is 0.
 Encryption key:
To use a 128bit encryption, enter the 128bit encryption key here. Observe that
the128bit encryption key has to be entered as string of hexadecimal values.
 Use encryption:
To activate encryption select Yes otherwise No. The default setting is No.
A customized user identification string can be set (see User Identification).

7
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

In production environments we strongly recommend to use encryption.

 Allow offline mode:

Set this parameter to Yes if you want to ensure that budget transactions take
place even when the Blackboard server is offline. In this case the budget
transactions will be cached and then transferred to the Blackboard server as soon
as it is available again. By default offline mode is set to No.

Observe that allowing the offline mode will bear a certain risk as it is not possible to
verify the user's current balance while the Blackboard server is down.

 User identification token:

A string defining the job value that should be passed as user identification. By
default the PAYCONID is used.
 Tender identification token:
A Blackboard-specific configuration option. The users on a Blackboard system may
have multiple transaction accounts. As opposed to the Default tender number
where one value applies to all users, the Tender identification token allows to
pass a user-related or a cost-center-related tender number to the Blackboard
Transaction System Service Client plug-in by reading the corresponding value from
a property field stored at a user-entity or a cost-center-entity. If both, a default
and a tender identification token are given, the latter one has precedence over the
default value. All %USER tokens are supported, e.g. %User.Default_CardNumber%.
Enter the token that shall be evaluated.

Configuration Examples
For each of the above parameters it is possible to configure different settings for each
host, e. g. uniFLOW and Remote Print Servers that use the Blackboard Transaction
System Service Client plug-in.
The syntax for entering multiple values is as follows: <Server
Name1>:<Option1>,<Server Name2>:<Option2>, ...
Example:
If you would like to assign different terminal numbers to each host, the configuration
line would look like:
uniFLOW:3,RPS-A:4,RPS-B:5
For setting a default value the host name can be omitted for one option.
Example:
To set a different server name for the uniFLOW server, the configuration line would be
as follows:
bbts.company.com,uniFLOW:bbts.local

8
Confidentiality: Internal + Partner (R3P)
White Paper Blackboard Transaction System Service Client

With this configuration all servers would use the dns name bbts.company.com for
connecting to the Blackboard Transaction System Service (BbTs) servers.

1.3 Logging
If logging is enabled, the following functions will be logged:
 Start/Stop of the communication thread.
 Send/Receive of data packets.
 Communication errors.
 Exceptions when reading a received packet.
 Result status of a performed transaction (successful, failed with reason).
Logging can be enabled via the Windows registry.
Platform Type Windows Registry Key

X86 HKEY_LOCAL_MACHINE\SOFTWARE\NT-ware\Mom\Blackboard
X64 HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\NT-ware\
Mom\Blackboard

Name Type Required Description

LogPath Reg_SZ Yes The absolute file path to store the logging information.
Must point to a file name, do not specify a folder only.
Example value: C:\Temp\Budget.log
LogMask Reg_SZ No An optional date/time token that is appended to the log
file name.
Example value: yyyy-MM-dd
LogLevel Reg_SZ No Allows to define which information is logged. Possible
values are: Flow, Warning, Error, Fatal.
Default value: Error

9
Confidentiality: Internal + Partner (R3P)