Guide To The OnBase APIs v1.2
Guide To The OnBase APIs v1.2
Version 1.2
Prepared by:
Hyland Software, Inc.
28500 Clemens Road
Westlake, Ohio 44145
Ph: (440) 788-5000
Fax: (440) 788-5100
www.onbase.com
OnBase API Guide
DISCLAIMER
© Copyright 1992-2007 Hyland Software, Inc.
All rights reserved.
Information in this document is subject to change without notice and does not represent a commitment
on the part of Hyland Software, Inc. The software described in this document is furnished under a
license agreement or nondisclosure agreement and may be used or copied only according to the terms
of this agreement. It is against the law to copy the software except as specifically allowed in the license
or nondisclosure agreement, or without the expressed written consent of Hyland Software, Inc. Any
unauthorized duplication or use of the OnBase® Information Management System, or its corresponding
documentation is forbidden. All data, names, and formats used in this document’s examples are
fictitious unless noted otherwise. Should you have any questions pertaining to discrepancies in this
document, please contact Hyland Software, Inc.
Depending on the modules licensed, the OnBase® Information Management System may contain
portions of: Imaging technology, Copyright © Snowbound Software Corporation; CD-R technology,
Copyright © Sonic Solutions; CD-R technology, Copyright © Rimage Corporation; OCR technology ©
ScanSoft, Inc; Mail interface technology © Intuitive Data Solutions; Electronic signature technology,
Copyright © Silanis Technology, Inc.; Full text search technology, Copyright © Microsoft Corporation;
Full text search technology, Copyright © Verity, Inc.; SYBASE Adaptive Server Anywhere Desktop
Runtime, Copyright © SYBASE, Inc., Portions, Copyright © Rational Systems, Inc.; ISIS technology,
Copyright © Pixel Translations, a division of ActionPoint, Inc. Portions contained within are licensed by
U.S. Patent Nos. 6,094,505; 5,768,416; 5,369,508 and 5,258,855.
Hyland Software© and OnBase© are registered trademarks of Hyland Software, Inc. Application
Enabler™ is an unregistered trademark of Hyland Software, Inc. EMC Centera© is a registered
trademark of EMC Corporation.
All other trademarks, service marks, trade names and products of other companies are the property of
their respective companies.
Table of Contents
DECIDING ON AN API SOLUTION ............................................................................. 1
Is there an OnBase module that will meet my business needs? ...........................................1
Is there an OnBase module that “almost” meets my business needs? .................................1
Is there an OnBase module that “almost” meets my business needs that can be extended
thru the API? .........................................................................................................................1
What are the potential development costs of the solution? .................................................1
Do you wish to provide the staff to develop and then maintain the solution? .....................1
How do you engage custom development services?.............................................................2
What types of services are offered? ......................................................................................2
AVAILABLE APIS .................................................................................................. 3
Automation API .....................................................................................................................3
Available Functionality .................................................................................................................................3
Limitations ..................................................................................................................................................3
Thick Client API .....................................................................................................................4
Available Functionality .................................................................................................................................4
Limitations ..................................................................................................................................................4
Docpop ...................................................................................................................................5
Available Functionality .................................................................................................................................5
Limitations ..................................................................................................................................................5
Hyland.Services .....................................................................................................................6
Available Functionality .................................................................................................................................6
Limitations ..................................................................................................................................................6
API LICENSING ................................................................................................... 7
Concurrent Client License ......................................................................................................8
Named User Client License ....................................................................................................9
Query per Hour (Query Meter) License................................................................................10
API Querying and the Query Meter License ................................................................................................. 10
Functional API Licenses.......................................................................................................12
Archival API License .................................................................................................................................. 12
Web Services Toolkit License...................................................................................................................... 12
API TRAINING .................................................................................................. 13
Resources for Certified API Developers ..............................................................................13
Software Development Kits ........................................................................................................................ 13
API Training Downloads............................................................................................................................. 14
API Technical Support ............................................................................................................................... 14
If there is an OnBase module that almost meets the business requirement but
Is there an OnBase does not have all the necessary functionality, you should investigate the
module that “almost” possibility of enhancing the product to include the needed feature. OnBase
meets my business modules are always preferred for solutions over the API. It is also possible that
the feature(s) you require is already implemented in a more recent version of
needs? the OnBase product. In either case support personnel can assist with providing
the recommended solution to the business problem and if the best solution
isn’t readily available (due to an enhancement, etc.) they can assist with
finding a workaround to meet the business requirement in the short term.
Many of the OnBase modules have hooks that allow a trained individual the
Is there an OnBase ability to extend or alter the standard functionality that is offered. These hooks
module that “almost” provide the best of both worlds because they offer the ability to use the power
meets my business needs of the OnBase module and have the flexibility to customize the functionality
with minimal API programming.
that can be extended
thru the API?
When the above three questions do not lead to a complete solution then the following
questions should be answered in contemplating the possibility of an API Solution.
Creating an API Solution can be costly. In order to create any API Solution there
What are the potential are many costs that are often overlooked that should be considered beyond the
development costs of the actual development costs of the solution. These costs include the cost of
solution? Training, Licensing for the OnBase APIs, Cost of maintaining the solution in the
future, Cost of enhancing the solution as business requirements change, and the
cost of testing the solution.
Once again, reflecting on the cost of the solution, there is the cost of the
Do you wish to provide resources that are required to develop, test, deploy, and administer the solution.
the staff to develop and These resources will need to be utilized not just during the initial development of
then maintain the the solution but also during the life of the solution as it is maintained, and
enhanced.
solution?
There is also the option of engaging services to provide the solution for you.
If you wish to contract for a custom API solution, you can initiate the process by
How do you engage contacting your account manager. Your account manager can facilitate the initial
custom development request to the appropriate personnel.
services? The more information that you can provide up front the faster and easier it will
be to initiate the process. If you can provide a high level written description of
your business needs to your account manager this will greatly benefit the
process. Any technical details that you may have such as deployment
environment, security requirements, and application specifics will also be of
benefit.
Custom Development services can be provided in the following levels of
What types of services engagement:
are offered? 1- Full Solution Services
When you do not wish to provide the staff, to develop the solution then
full solution services can be provided. These services consist of the
initial Discovery phase in which the business and technical requirements
will be gathered, fully documented and reviewed by the business
personnel. If necessary a proof of concept may be considered during
this phase to solidify the requirements and prove the technical feasibility
of those requirements. The Implementation phase consists of design,
development, unit testing, solution testing, installation, testing support,
go live support, training (as needed), and documentation
(Administration Manual, Help Manual, Installation Manual, as needed).
In this level of engagement, all code is copyrighted and the code is not
delivered as part of the solution. Only the compiled components are
delivered.
2- Discovery and Design of the Solution
If you have an API Certified individual that will be responsible for
implementing the solution but assistance is required during the initial
phases of the project, then discovery and design services are offered to
fulfill this need. These services consist of gathering and defining the
business requirements and translating these into the design of the
solution. There may also be a need for a proof of concept to be
developed to ensure that the design is technically feasible.
The solution design will consist of recommending the appropriate API
for the solution, defining the hook points that the solution may interact
with OnBase, recommending any modules or client licensing needed to
meet the solution’s needs, and defining the high level architecture of the
API solution.
3- API Consulting
If you have an API Certified individual who has the majority of the skill
set needed to design and implement the solution, but they would
benefit from the added expertise of an OnBase API Professional then
API consulting services are offered to fulfill this need. These services
usually consist of an initial meeting to give an overview of the business
requirements and the design of the solution, and then ad hoc API
questions, design questions, or collaborative development discussions
can occur to assist the API Certified individual with the development of a
quality API Solution. When engaging in this type of services, it is
important to ensure that all of the business and technical requirements
are clearly defined and provided.
Available APIs
OnBase offers more than one API because there is no such thing as “one size fits all” in the business world
or in the development world. It is our intention to provide the necessary tools to empower a developer to
develop the best API Solution possible. With this great extensibility and flexibility comes a responsibility of
the developer to maintain a working knowledge of all the OnBase APIs and maintain a certification status in
order to receive documentation and support. With a dedicated support team for API Support, Hyland is
committed to assisting its partner and customer base when API Solutions need to be developed by providing
technical support for troubleshooting OnBase API defects. Hyland also provides contracted services for any
level of project development assistance that is desired.
In any API Solution choosing the right API is just as crucial, if not even more crucial, than the actual
implementation of the solution. OnBase offers a variety of APIs and each one is best suited for different
types of solutions. It is very important to know the differences of the APIs and the appropriate architectural
environments for each. Refer to the descriptions of the Available APIs that follow.
Automation API
The Automation API offers a quick and easy way to extend the functionality of the OnBase Thick Client. It
allows users to perform actions on one or more documents, simply by right-clicking on them and selecting
the Run Script menu option. It is also possible to add buttons to the OnBase toolbar to execute these scripts.
VB Scripts can be run from several different locations, including VB Script Hooks and the OnBase Workflow
module.
VB Scripts are defined in the OnBase Configuration module using an intuitive user interface. This interface
provides a means to create and update VB Scripts for use in OnBase.
Available Functionality
Originally designed as a document access API, the Automation API offers access to many document
properties off of the current document as well as a few other area of the OnBase Thick Client.
This API is not intended to be used in the context of the web or in any form of a custom web site. Another
API offers a much better solution for that type of environment. This API is intended to be used in desktop
applications or in integration with a desktop application or back-end processor, as it requires the presence of
a Thick Client running on the workstation during the execution of the various methods available.
Available Functionality
The thick client API is a more expansive API offering much of the functionality required for integrating other
line of business applications with OnBase.
Docpop
DocPop allows for rapid development of integrations that require retrieval of documents in a
web environment. As part of the standard Web Client, administrators can simply browse to a
URL creator page and create URLs that can then be manipulated further to return a desired
group of documents in a hit list or return a single document through a point-and-click fashion.
Available Functionality
Docpop is a very simple web enabled solution for the viewing of documents within an IE browser. The
functionality available is listed below.
Hyland.Services
Hyland.Services API is a .NET Web Service that can be used to integrate with applications across the
Internet. Given that .NET Web Services are nothing more than XML processing services, this API
supports multiple platforms. Currently, this API offers both .NET Client Libraries and a separate
library for use with the Java programming language and platform.
Available Functionality
Many OnBase system elements can be obtained through Hyland Services below is an overview of the high
level elements that can be utilized through this API. This list is not intended to be all inclusive, low level
detailed functionality will vary by OnBase version.
API Licensing
The OnBase API licensing has been designed with versatility and scalability in mind. It ensures that you
are able to purchase both a quantity and type of license that precisely suits your needs, while maintaining
the ability to increase licenses or change the licensing model altogether with little or no redevelopment of
your API-based solutions. This section briefly explains the client licensing models supported by the OnBase
APIs and other functional API licenses.
The Named User Client license is designated via the configuration module when setting up a user. A Named
User Client license will be consumed if the user credentials used to log in match those of an OnBase user who
has been configured as a Named user.
That Named user may log in and will only consume a single Named User Client license. That license will be
released immediately upon logging out. However, that user can only have two open connections at any
given time. Connecting to more than two OnBase applications or API connections with the same user, who is
configured for a Named User Client license, will cause an error to be returned.
It is not necessary to pass any additional parameters to the API method to consume a Named User Client
license; the API will automatically respect the configuration for that user.
The Query per Hour license allows the customer to have an unrestricted number of users connected to the
system. The users are restricted by the number of queries that can be executed in an hour. The number of
queries allotted in a given hour is determined by the number of blocks of 500 queries the customer has
purchased. If a customer purchases 2 blocks of 500 to be run at one workstation, they would have a total of
1000 queries per hour. The 1000 queries are shared by all users.
Example
A customer purchases 1 block of 500 to be run at one workstation, therefore they have a total of
500 queries available in one hour. Ten users connect to the system. User A executes 400 queries at
9:00AM and User B executes 100 queries at 9:30AM. The next user that attempts to execute a
query will get an error stating that the query meter was exceeded. At 10:00AM, an hour later, the
400 queries will become available for any user to use. At 10:30AM the 100 queries will become
available for any user to use.
Each type is meant for a specific business scenario, as described in further detail below. (Refer to the API
Query & Licensing Summary at the end of this section.)
This licensing option is for API solutions that allow external users to access information from an
organization’s internal OnBase system. External users are defined as users that are not employees of the
organization. In this scenario, trying to gauge the number of concurrent licenses required to service the
external users is difficult since their usage may be unknown.
This license is specific to the Core Services API. It can be utilized from the Hyland.Services API as well as
the other legacy Core Services APIs. This license is also licensed as a workstation license. When purchasing
licenses, it is necessary to purchase licenses for every web server that will be utilizing the license.
Note that you can buy query per hour blocks for more than one workstation.
The API connection code will have to be modified to utilize the Core Query API license. In most cases, there
is a simple parameter that gets passed into the connection code with the username and password. For
specific information, see the Hyland.Services SDK. If you happen to be using a legacy API and are trying to
utilize this license, please refer to the documentation provided with that legacy API or contact API Support.
This license is specific to the Thick Client API. This license is a workstation license, meaning that this license
is to be registered on the workstation that is acting as the broker for the application utilizing queries per
hour.
Note that you can buy query per hour blocks for more than one workstation, so that users may connect to
different applications on different workstations and still utilize the license from both workstations.
The API application will check your client to see if you are running with the Client Query API license
registered on that workstation. You do not have to modify your connection code.
The Archival API license is needed in order to archive new documents into the OnBase repository via any of
the OnBase APIs. This license only needs to be purchased once for a given OnBase system as it is a
database license. In the absence of this license, the APIs will return an error when trying to archive a new
document to the OnBase repository via the API. This license also includes the archival of new Electronic
Forms and Virtual Electronic Forms as the creation of one of these two types is considered a new document
just as in archiving an image document or any other file format.
The Web Services Toolkit license is needed in order to utilize the Hyland.Services API, a .NET Web Service
available for integrations. This license only needs to be purchased once for a given OnBase system as it is a
database license. With this license, a programmer is able to utilize the full functionality of the
Hyland.Services API. This license automatically includes access to the archival of new documents into
OnBase. This means that the Archival API license does not need to be purchased separately in order to
archive thru the Hyland.Services API. You will still need the Archival API license if you are using APIs other
than Hyland.Services to archive documents.
API Training
In order to effectively craft and implement solutions utilizing any of the OnBase APIs, API developers must
maintain an OnBase API certification credential. Hyland Software, Inc. offers the API Training &
Certification course for the purpose of certification.
The certification course presents an introduction to all of the different OnBase APIs available. This course
will also provide students with “hands on” experience developing custom applications that use the OnBase
APIs. At the conclusion of the course an exam will be given to test the knowledge as well as the
development and troubleshooting skills a developer learned throughout the week of the course.
Once this certification is achieved, a developer may recertify by either registering for the full API Training
& Certification course or attend a TechQuest conference offering the API recertification.
OnBase currently offers documentation and samples for the APIs in the form of Software Developer Kits.
These developer kits are only available to those individuals who have maintained the OnBase Certified API
Developer credential.
There are currently two software developer kits that can be downloaded by contacting Technical Support
and requesting the download information for that SDK. The SDKs available are:
• Thick Client API SDK – updated periodically but is not build specific. The APIs included are:
Automation API
Thick Client API
• Core Services API SDK – is build-specific. The APIs included are:
Hyland.Services API
Other legacy APIs (Core Services, Desktop, etc.)
Upon completion of the API Training course developers will be given download instructions with the
information for up to two different downloads depending on their certification status at the conclusion of the
course. These downloads are available in the private download area of either teamonbase.com or
users.onbase.com and include the following information:
• API Training Course Materials – the Power Points and labs that were given throughout the week of
the API Training course. This includes the solutions to the labs.
• API Example Applications and Scripts – a download full of various applications and scripts written
utilizing the various OnBase APIs covered during the course.
Note
The API Training Materials are available to all individuals who have attended the API Training Course. The API
Examples are only available to those individuals who have obtained the API Certification credential.
Hyland Software Technical Services offers product support for the APIs to OnBase API Certified Developers
though our API Support Group. API Support is an E-mail-based support service to resolve product or
documentation issues while crafting an API solution.
API Support can be contacted by E-mailing the API Support group via [email protected]. An OnBase
API Analyst will then be assigned to the issue and should be in contact within 48 hours of receipt of the
issue.
It is important to note that support for the APIs is limited to the resolution of defects. API Support should
not be contacted if additional assistance beyond the resolution of defects is required.
In cases where assistance with programming, software design, business system analysis, or assistance with
a Microsoft operating system or development tool is required, Hyland Software, Inc. offers such services
through their Custom Solutions Group (CSG). The CSG team is responsible for crafting and assisting in the
development and deployment of API-based solutions. They can assist you on your projects through
contracted services. To learn more about these services please contact your Hyland Account Manager.