API Server

Reference Guide

Includes:

Installation Guide
Administration Guide

Foundation 24.1
 API Server

Documentation Notice
Information in this document is subject to change without notice. The software described in this
document is furnished only under a separate license agreement and may only be used or copied
according to the terms of such agreement. It is against the law to copy the software except as
specifically allowed in the license agreement. This document or accompanying materials may
contain certain information which is confidential information of Hyland Software, Inc. and its
affiliates, and which may be subject to the confidentiality provisions agreed to by you.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the
rights under copyright law, no part of this document may be reproduced, stored in or introduced into
a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying,
recording, or otherwise), or for any purpose, without the express written permission of Hyland
Software, Inc. or one of its affiliates.
Hyland, Hyland Experience, OnBase, Alfresco, Nuxeo, and product names are registered and/or
unregistered trademarks of Hyland Software, Inc. and its affiliates in the United States and other
countries. All other trademarks, service marks, trade names and products of other companies are the
property of their respective owners.
© 2024 Hyland Software, Inc. and its affiliates.
The information in this document may contain technology as defined by the Export Administration
Regulations (EAR) and could be subject to the Export Control Laws of the U.S. Government including
for the EAR and trade and economic sanctions maintained by the Office of Foreign Assets Control as
well as the export controls laws of your entity’s local jurisdiction. Transfer of such technology by any
means to a foreign person, whether in the United States or abroad, could require export licensing or
other approval from the U.S. Government and the export authority of your entity’s jurisdiction. You are
responsible for ensuring that you have any required approvals prior to export.
DISCLAIMER: This documentation contains available instructions for a specific Hyland product
or module. This documentation is not specific to a particular customer or industry. Hyland
customers are responsible for making their own independent assessment of the information in
this documentation. This documentation: (a) is for informational purposes only, (b) is subject to
change without notice, and (c) does not create any commitments or assurances by Hyland or its
affiliates. This documentation is provided “as is” without representation or warranty of any kind.
Hyland expressly disclaims all implied, express, or statutory warranties. Hyland’s responsibilities and
liabilities to its customers are controlled by the applicable Hyland agreement. This documentation
does not modify any agreement between Hyland and its customers.
Document Name
API Server
Department/Group
Documentation
Revision Number
Foundation 24.1

© 2024 Hyland Software, Inc. and its affiliates i

 API Server
Contents

Overview
Contents
Overview....................................................................................................................................................... 1
Licensing........................................................................................................................................................ 1

Installation Guide

Installation
Requirements...............................................................................................................................................3
General Requirements....................................................................................................................... 3
Microsoft Hosting Bundle Requirements......................................................................................... 3
Hyland IdP Server...............................................................................................................................3
Licensing........................................................................................................................................................ 3
API Server Installation.............................................................................................................................. 4
Overview............................................................................................................................................. 4
Installing the API Server.................................................................................................................... 6
Verifying the Installation..................................................................................................................12
Troubleshooting........................................................................................................................................12
Internet Information Services (IIS) Considerations....................................................................... 12
Authentication Modules Besides Anonymous Authentication................................................12
WebDAV Publishing Module...................................................................................................... 13

Temp File Service Installation

Installing the Temp File Service........................................................................................................... 14
Temporary File Service Configuration Compatibility Matrix......................................................... 14
Storage Systems..............................................................................................................................14
Installation and Configuration.........................................................................................................15
Editing the Configuration File.................................................................................................... 15
Configuring Background Processing........................................................................................ 15
Configuring the Cleanup Processor.....................................................................................15
Configuring the Cache File Notification Processor............................................................ 16
Configuring the Temp File Service............................................................................................ 17
Install/Update to the Latest Temp File Service Database Schema................................... 17
Set the Tenant Encryption Scheme......................................................................................17
Set the Master Password in the Configuration File............................................................ 17
Configure a Storage System................................................................................................ 18
Configure the API Server for the Temp File Service............................................................18
Using Scriptable Configuration............................................................................................ 19
Validating the Temp File Service..........................................................................................19

Administration Guide

API Server Logging

Configuring Hyland.Logging................................................................................................................. 21
Enabling Event Viewer Logging.......................................................................................................21
Setting the Logging Level................................................................................................................ 21

© 2024 Hyland Software, Inc. and its affiliates ii

 API Server
Contents

Creating Log Files............................................................................................................................ 23

Disabling IP Address Masking........................................................................................................ 24
Configuring Log Entry Truncation................................................................................................... 24

Hyland Application Settings Utility

Hyland Application Settings Utility....................................................................................................25
Overview........................................................................................................................................... 25
Writing a Value in a JSON File.........................................................................................................26
Reading a Value in a JSON File.......................................................................................................27
Writing and Reading Array Elements.............................................................................................. 29

© 2024 Hyland Software, Inc. and its affiliates iii

 Overview

Overview
The OnBase API Server is a network server through which OnBase APIs connect to and interact
with the OnBase database. The API Server hosts various APIs which serve clients by performing
processing tasks, retrieving information from the OnBase database, and, optionally, retrieving
documents from the OnBase disk groups.

Licensing
The API Server requires no additional OnBase licensing, but OnBase modules that rely on the API
Server may require additional licensing. For licensing requirements, see the module reference guide
or help files for those modules.

© 2024 Hyland Software, Inc. and its affiliates 1

Guide
Installation
API Server

Installation Guide

Foundation 24.1
 Installation

Requirements
The following sections outline requirements information specific to API Server in OnBase Foundation
24.1.

General Requirements
For general requirements information that applies to both API Server and other modules, see the
sections on the following topics in the Installation Requirements manual:
• Databases Supported
• Operating System Requirements
• Microsoft .NET Framework Requirements
• Microsoft Visual C++ Requirements
• Server and Core Services Hardware Requirements

Microsoft Hosting Bundle Requirements

The API Server requires Microsoft Hosting Bundle 2.x, with a minimum version requirement of
Hosting Bundle 2.1. The API Server installer installs the ASP.Net Core Hosting Bundle 2.1.30 if a
newer 2.1.x version isn't already installed.
If you are installing both 2.1 and 3.x versions of the .NET hosting bundle, they can be installed side-
by-side.

Note: Support for ASP.NET Core 2.1 on .NET Framework matches the ASP.NET Support policy for
other package-based ASP.NET frameworks. The complete list of packages covered by this policy can
be see in ASP.NET Core 2.1 Supported Packages.
The .NET Framework and Hosting Bundle is a Microsoft product. For additional installation and
configuration procedures, see the Microsoft documentation.

Hyland IdP Server

The API Server requires the Hyland IdP Server. You must have a properly installed and configured
Hyland IdP Server deployed before installing the API Server. For more information, see the Identity
and Access Management Services reference guide.

Licensing
See Licensing on page 1 for licensing requirements.

© 2024 Hyland Software, Inc. and its affiliates 3

 API Server
Installation

API Server Installation

Installing the API Server consists of the following steps:
• Installing the Hyland IdP Server

Note: For complete instructions on installing and configuring the Hyland IdP Server, see the
Identity and Access Management Services reference guide.
• Installing the API Server on page 6
• Configuring Hyland.Logging on page 21
Additionally, if your solution configuration requires the Temp File Service:
• Installing the Temp File Service on page 14

Note: If your solution requires the ability to upload documents, you will require the Temp File Service.

Overview
There are two methods for installing the API Server: Interactive and silent. An interactive installation
requires user interaction with dialog boxes during the installation process. A silent installation does
not require user interaction during the installation process.

Note: The installer automatically installs the ASP.Net Core Hosting Bundle v2.1.26 if it detects that it
is not cureently installed.
The installation executable validates that all prerequisites are met before proceeding with the
installation. If any missing prerequisites are identified, the installer alerts the user.

Note: The Microsoft .NET Framework prerequisite must always be installed separately before
running the installer.
For instructions on interactively installing the API Server, see Installing the API Server on page 6.
User Account Control (UAC)
If Windows User Account Control (UAC) is enabled, the installer must be run with elevated
administrator privileges, even if an administrator is currently logged on. If you are running a silent
installation, you must use a command prompt with elevated permissions.
Silent Installation
If you are running the installation executable silently from the command line you must include the /
silent command in addition to any required command-line parameters and flags, as in the following
example:
Hyland.ApiServer.Setup.exe /silent "WEB_SITE_ID=1" "APPNAME=ApiServer"

Note: You should check the return value of the process. A return value of 0(zero) indicates success.
Any other value returned may indicate that an error was encountered and the installation failed.
The following command-line parameters are available for use:

© 2024 Hyland Software, Inc. and its affiliates 4

 API Server
Installation

Command-Line Parameter Description

APIROOT The file path to the root folder where the API Server will be installed.
If this command-line parameter is not present, the default root folder
path is .\Program Files\Hyland\ApiServer.

APPNAME The name of the API Server application in IIS.

If this command-line parameter is not present, the default name for the
application is ApiServer.

APPPOOL The name of the application pool in IIS that you want to be created to
run the API Server.
If this command-line parameter is not present, the name of the default
application that is created is ApiServerAppPool.

WEB_SITE_ID The ID of the site in IIS that you want to host the API Server application.
Note: This is a required command-line parameter if the
WEB_SITE_NAME command-line parameter is not present.

WEB_SITE_NAME The name of the site in IIS that you want to host the API Server
application.
Note: This is a required command-line parameter if the WEB_SITE_ID
command-line parameter is not present.

USE_APPPOOL_IDENTITY Determines whether you want to specify the application pool identity.
The value is either true or false.
If this command-line parameter is not present, the default value is
false.

APPPOOL_USER The user name of the identity that will be used for the application pool.
Note: This is only required if the USE_APPPOOL_IDENTITY command-
line parameter is present and the value is true.

APPPOOL_USER_PASS The password of the identity that will be used for the application pool.
Note: This is only required if the USE_APPPOOL_IDENTITY command-
line parameter is present and the value is true.

CONFIGURATIONDIRECTO The directory containing the configuration files for the API Server.
RY This parameter preserves existing configuration files during repair and
upgrade installs.

REQUIRESSL Sets the Require SSL property in IIS to true if any value is provided.

SKIPCONFIGUREIIS Prevents the installer from modifying IIS if any value is provided.
Note: IIS must be configured manually if this parameter is included.

SKIPDOTNETBUNDLE Can be set to skip installation of the hosting bundle.

The following flags are available for use:

© 2024 Hyland Software, Inc. and its affiliates 5

 API Server
Installation

Command-Line Flag Description

-layout This flag is used to make the API Server installer download the ASP.Net
Core Hosting Bundler installer in advance. As long as the installer is
kept next to the actual API Server installer, the local copy of the hosting
bundle installer will be used instead of attempting to download it.

Installing the API Server

To install the API Server:
1. Launch the OnBase API Server Setup installer by executing Hyland.ApiServer.Setup.exe. This
executable is available from your service provider.
2. The Hyland API Server Setup dialog is displayed.

Click Install to launch the installation wizard.

© 2024 Hyland Software, Inc. and its affiliates 6

 API Server
Installation

3. The Hyland API Server Setup welcome window is displayed.

4. Click Next. The IIS Settings window is displayed.

© 2024 Hyland Software, Inc. and its affiliates 7

 API Server
Installation

5. Select a Web Site to install the API Server to from the drop-down list. The Web Site list is
populated with the web servers configured in IIS and available to the target machine.
Enter a name for the API Server in the Application Name field.
Enter a name for the application pool that will be created that you want to run the API Server in
the Application Pool field.
6. Click Next. The IIS Settings window is displayed.

7. If you want to specify the credentials of the application pool running the API Server in IIS, select
the Specify IIS Application Pool Credentials option.
Enter the user name and password of the user whose credentials you want to use for the
application pool.

Note: If your solution requires the Temp File Service and you are using a UNC storage system, the
user whose credentials you use for the application pool must have rights to the UNC shares. For
more information see Storage Systems on page 14.

© 2024 Hyland Software, Inc. and its affiliates 8

 API Server
Installation

8. Click Next. The Destination Folder window is displayed.

9. Enter the top-level installation directory in the field provided, or click Change to browse to it.
If Change is clicked, the Change destination folder window is displayed.

© 2024 Hyland Software, Inc. and its affiliates 9

 API Server
Installation

Enter a folder name in the Folder name field or select it from the Look in drop-down list, then
click OK.
If the destination folder is not changed, the default location is used.
10. Click Next. The Ready to install window is displayed.

11. Click Install to install the API Server. Click Back if you want to return to the previous window.
Click Cancel if you want to exit the wizard without installing the API Server.
12. When the installer finishes installing the API Server, click Finish. Click Close to close the dialog.
13. In Windows, launch the Internet Information Services (IIS) Manager as an administrator.

Note: IIS is a Microsoft product. For more detailed instructions on using and configuring IIS
settings, see the Microsoft documentation.
14. In the tree view, expand the site under which you installed the API Server application, locate the
API Server application itself and open the Modules configuration.

Tip: Changing any of these settings in IIS Manager on the installed application will make non-
permanent changes to the web.config file of the API Server. If the API Server is modified
or upgraded using the installer, any changes made will be removed. If it is possible, it is
recommended to make these changes at the site level so that any application of that site will
inherit the configurations.
15. Ensure the following items are present in the list of modules:
• AnonymousAuthenticationModule
• AspNetCoreModule
• HttpCacheModule

© 2024 Hyland Software, Inc. and its affiliates 10

 API Server
Installation

• UriCacheModule
If any of these modules are not present, click Configure Native Modules...
In the Configure Native Modules dialog, locate the missing module or modules, select them,
and then click OK.
16. Browse to the config directory in your API Server's installation directory. In a default installation,
this directory is located at C:\Program Files\Hyland\ApiServer\config.
17. Open the 5_scim.json file of the API Server in a plain-text editor.

Note: In Windows, the JSON file must be opened as an administrator.

18. Locate the JwtIssuerOptions block and update the values of the following settings to match
your environment.

Setting Value

Authority The URL of the Hyland IdP server. For example, https://my.server.net/
identityprovider, where my.server.net is replaced with your host
domain.
Tip: Make sure the use of HTTP or HTTPS matches the configuration
of your domain in IIS.

Audience The URL of the resources directory on the Hyland IdP server. For
example, https://my.server.net/identityprovider/resources, where
my.server.net is replaced with your host domain.
Tip: Make sure the use of HTTP or HTTPS matches the configuration
of your domain in IIS.

19. Save and close the 5_scim.json file.

20. Open the 1_server.json file in a text editor.

Note: In Windows, the JSON file must be opened as an administrator.

21. Locate the Authentication block. In the Address setting, enter the URL of your Hyland IdP server.
22. Locate the Tenant block. Uncomment the contents of the configuration block by deleting the /*
at the start of the block and the */ at the end of the block.
23. Update the values of the following settings to match your environment.

Setting Value

DataSource The name of the data source of your OnBase database.

DataProvider The database provider type. Set the value to SQL for SQL or ORACLE
for Oracle.

© 2024 Hyland Software, Inc. and its affiliates 11

 API Server
Installation

Setting Value

ConnectionString A valid connection string to the OnBase database for the database
provider type (SQL or Oracle). The connection string must include Data
Source, database, User Id, and Password information.
Tip: ADO connections strings are a method of connecting applications
to databases. Complete details on connection strings and how to
create them are available from Microsoft.
Note: Make sure you include the double-slash (\\) between the server
and the database instance to account for JSON formatting. For
example, Data Source=MyDB\\SQLInstance;

24. Save and close the file and recycle your application pool for the changes to take effect.

Verifying the Installation

You can verify if the API Server was installed correctly and is running by navigating to the following
URL in your browser:
[SERVER]/[VIRTUALROOT]/onbase/core/healthcheck
Replace [SERVER] with the name of the server that is hosting the API Server. Replace
[VIRTUALROOT] with the virtual root of the API Server. In a default installation, the virtual root of the
API Server is ApiServer.
If a blank page is displayed without any kind of error, the API Server is currently running.

Troubleshooting
Internet Information Services (IIS) Considerations
Certain modules in IIS have been identified as potentially causing issues with the API Server. The
following considerations should be carefully evaluated when configuring your environment to
prepare for installing the API Server.

Authentication Modules Besides Anonymous Authentication

Other enabled authentication modules can cause the API Server to fail to start. It is recommended
to disable all authentication modules except for AnonymousAuthenticationModule at the site or
application level.

© 2024 Hyland Software, Inc. and its affiliates 12

 API Server
Installation

WebDAV Publishing Module

The WebDAV functionality intercepts requests to the API Server that use certain HTTP verbs. The
WebDAV module should be removed or disabled for any instance of the API Server. There are
multiple options available for disabling the WebDAV functionality.
If the WebDAV functionality can be disabled for the entire machine, you can disable the WebDAV
Publishing feature in Windows Features.
To disable WebDAV Publishing:
1. Navigate to the Control Panel and select Turn Windows features on or off.
2. In the Windows Features dialog, navigate to I nternet Information Services | World Wide Web
Services | Common HTTP Features and ensure the WebDAV Publishing feature is disabled.
If the WebDAV functionality cannot be disabled for the entire machine, you must disable the
functionality for the site or application.
To disable the WebDAV module for the site or application:
3. In Windows, launch the Internet Information Services (IIS) Manager with elevated
administrator privileges.
4. Locate either the site under which the application is installed or the application itself and open
the Modules configuration.
5. In the list of modules, find WebDAVModule and click Remove to remove it from the list.
6. Navigate back to the site or application and open the Handler Mappings configuration.
7. In the list of handler mappings, find WebDAV and click Remove to remove it from the list.
8. Recycle the application pool for the changes to take effect.
You can also manually modify the application's web.config file, but by default the sections that
must be modified are locked by IIS, and must first be unlocked.
To manually configure the web.config file:
9. In Windows, launch the Internet Information Services (IIS) Manager with elevated
administrator privileges.
10. Select the server and open the Feature Delegation configuration.
11. Change the Feature Delegation level to Read/Write.
12. In the application's web.config file, navigate to the system.webServer section.
13. In the <system.webServer> node, add the <modules> node. If the <modules> node is already
present and commented out, uncomment it.
14. In the <modules> node, add the <remove name="WebDAVModule" /> element. If the <remove
name="WebDAVModule" /> is already present and commented out, uncomment it.
15. Save and close the web.config file.
16. Recycle the application pool for the changes to take effect.

© 2024 Hyland Software, Inc. and its affiliates 13

 Temp File Service Installation

Installing the Temp File Service

If your solution requires the ability to upload documents, then you must also install and configure the
Temp File Service.

Temporary File Service Configuration Compatibility

Matrix
The following table displays the compatibility matrix for the Temporary File Service Configuration
Utility (TempFSConfiguration) for different OnBase versions. These versions can be downloaded
from the Software Downloads page in your Customer Portal on Hyland Community.

OnBase Version Temporary File Service Configuration Utility Version

EP2 1.0.x

EP3 1.2.x

EP4 1.5.x

EP5 1.6.x

22.1 1.7.4

23.1 1.7.4

24.1 1.7.5

Storage Systems
The Temp File Service supports both S3 and UNC storage systems, but S3 is the recommended
storage system. S3 storage systems are more secure by limiting access to only those with
credentials, which can be limited to only the Temp File Service. However, if S3 storage systems are
not available for use, UNC can be used.
If you are using an S3 storage system, before deploying the Temp File Service you must have access
to an S3 server (server URL, access key and secret key) and a bucket therein that is not shared with
any other system.
If you are using a UNC storage system, you must have access to a UNC share that is similarly not
shared with any other system. Additionally, the user running the application pool for the API Server
must have rights to the UNC shares.
The Temp File Service can be used in a load balanced environment. To configure the Temp File
Service for such an environment, contact your first line of support.

© 2024 Hyland Software, Inc. and its affiliates 14

 API Server
Temp File Service Installation

Installation and Configuration

The Temp File Service is installed as part of the API Server installation. To finish installation of the
Temp File Service, two further steps must be completed, including:
• Editing the Configuration File on page 15
• Configuring Background Processing on page 15
• Configuring the Temp File Service on page 17

Editing the Configuration File

As part of the API Server installation, 5_tempfs.json is created in the config folder of the API Server's
installation location. To edit the 5_tempfs.json file:
1. Open the file using a plain text editor such as Notepad.
2. After "Idp":"Scope":"Name":, enter "evolution".
3. Under TempFileService":"Tenant":, replace [TenantName1] in
"Tenant_[TenantName1]_DDL" with the name of the tenant.
4. After "ConnectionString", replace [Server1] with the server address, replace [Database1]
with the name of the database, replace [User] with the user ID, and replace [Password] with
the password for that connection.
5. Under TempFileService":"Tenant":, replace [TenantName1] in
"Tenant_[TenantName1]_SQL" with the name of the tenant.
6. After "ConnectionString", replace [Server1] with the server address, replace [Database1]
with the name of the database, replace [User] with the user ID, and replace [Password] with
the password for that connection.
7. Save the configuration file.
DDL is the tenant used for all DDL requests, such as table creation. SQL is the tenant used for all SQL
requests. The entries for the DDL and SQL tenants must match each other. Additional tenants can be
added as needed.

Configuring Background Processing

The behavior of the background processors for the Temp File Service can be customized in the
5_tempfs.json file, located in the config folder of the API Server's installation location. Two separate
processors can be configured: the Cleanup Processor and the Cache Field Notification Processor.

Configuring the Cleanup Processor

The Cleanup Processor controls the background deletion of expired temp files. To configure the
Cleanup Processor:
1. Open the 5_tempfs.json file in a plain text editor such as Notepad.
The file is located in the config folder of the API Server's installation location.
2. Locate the "CleanupProcessor" section of the 5_tempfs.json file.
3. After "Enabled" :, enter true to enable the Cleanup Processor, or false to disable it.
By default, this option is set to true.

© 2024 Hyland Software, Inc. and its affiliates 15

 API Server
Temp File Service Installation

4. After "StartupDelaySeconds" :, enter the number of seconds you want the Cleanup
Processor to wait before processing after the Temp File Service restarts.
By default, this option is set to 0 seconds.
5. After "RunDelaySeconds" :, enter the number of seconds you want the Cleanup Processor to
wait between each time it runs.
By default, this option is set to 300 seconds.
6. After "ErrorBehavior" :, enter one of the following options for how the processor should
behave when an error occurs:
• Enter LogAndContinue to have the processor log the error and wait the amount of time
configured in the RunDelaySeconds option before continuing.
• Enter HaltProcessor to have the processor stop running entirely when it encounters an error.
By default, this option is set to LogAndContinue.
7. Save the configuration file.

Configuring the Cache File Notification Processor

The Cache File Notification Processor is used to coordinate temporary cahce file creation. To
configure the Cache File Notification Processor:
1. Open the 5_tempfs.json in a plain text editor such as Notepad.
The file is located in the config folder of the API Server's installation location.
2. Locate the "CacheFileNotificationProcessor" section of the 5_tempfs.json file.
3. After "Enabled" :, enter true to enable the Cache File Notification Processor, or false to disable
it.
By default, this option is set to true.
4. After "StartupDelaySeconds" :, enter the number of seconds you want the Cache File
Notification Processor to wait before processing after the Temp File Service restarts.
By default, this option is set to 0 seconds.
5. After "RunDelaySeconds" :, enter the number of seconds you want the Cache File Notification
Processor to wait between each time it runs.
By default, this option is set to 300 seconds.
6. After "ErrorBehavior" :, enter one of the following options for how the processor should
behave when an error occurs:
• Enter LogAndContinue to have the processor log the error and wait the amount of time
configured in the RunDelaySeconds option before continuing.
• Enter HaltProcessor to have the processor stop running entirely when it encounters an error.
By default, this option is set to LogAndContinue.
7. Save the configuration file.

© 2024 Hyland Software, Inc. and its affiliates 16

 API Server
Temp File Service Installation

Configuring the Temp File Service

Prerequisite: After the service has been installed in IIS and the JSON configuration file is in place,
follow the steps below to configure the Temp File Service.
1. Download the TempFileService.Configuration utility from the Software Downloads page in your
Customer Portal on Hyland Community.
2. Extract the files from the .zip file downloaded to any location on your computer.
3. Run the TempFileService.Configuration utility from a command line.
What to do next: Once you run the utility, you will be able to finish the configuration by completing
the following steps:
• Install/Update to the Latest Temp File Service Database Schema on page 17
• Set the Tenant Encryption Scheme on page 17
• Set the Master Password in the Configuration File on page 17
• Configure a Storage System on page 18
• Configure the API Server for the Temp File Service on page 18

Install/Update to the Latest Temp File Service Database Schema

The Temp File Service database, the tenant previously specified in the 5_tempfs.json file, must be
updated to the most recent database schema. To do this, execute the following command, with [path
to 5_tempfs.json] replaced with the full path to the 5_tempfs.json file:

TempFileService.Configuration.exe database update --json-config "[path

to5_tempfs.json]"

If the API Server was installed in the default directory, the following command can be used:

TempFileService.Configuration.exe database update --json-config "C:\Program

Files\Hyland\ApiServer\config"

If you use Oracle database, the use of quoted identifiers will cause all identifiers to be case sensitive.
This means that the hsitempfile user must be created as "hsitempfile", including the double
quotation marks, or the migration will not recognize it.

Set the Tenant Encryption Scheme

The tenant encryption scheme must be set in the 5_tempfs.json configuration file. To configure the
encryption, execute the following command, with [path to 5_tempfs.json] replaced with the
path to the 5_tempfs.json file and MyTenantNameHere replaced with the name of the tenant:

TempFileService.Configuration.exe security set-tenant-scheme --json-config

"[path to 5_tempfs.json]" --tenant MyTenantNameHere

Set the Master Password in the Configuration File

The master password must be set in the 5_tempfs.json configuration file. This password is used to
encrypt S3 access and secret keys in the database and should be the same for every instance of the
Temp File Service that uses this database.

© 2024 Hyland Software, Inc. and its affiliates 17

 API Server
Temp File Service Installation

To configure this password, execute the following command, with [path to 5_tempfs.json]
replaced with the path to the 5_tempfs.json file and [my_password_here] replaced with the
password:

.\TempFileService.Configuration.exe security set-global-scheme --use-

master-password-v2 --password "[my_password_here]" --json-config "[path to
5_tempfs.json]"

Note: Once this command is run, the password is encrypted using the Windows DPAPI.

Configure a Storage System

The storage system for the Temp File Service must be configured using the 5_tempfs.json file. To
configure this storage system:
1. Run the following storage command:
TempFileService.Configuration.exe storage
2. Run the following subcommand with [path] replaced with the path to the 5_tempfs.json file and
[tenant name] replaced with the tenant name in the Datasource string in 5_tempfs.json:
select-database --json-config [path] --tenant [tenant name]
3. Run the following command with [type] replaced with either S3 or UNC depending on the type
of storage system in use:
add --type [type]
You are prompted to add in all relevant information for the storage system being configured.

Note: The Set Active Storage System options for TempFS are part of the storage system that
needs to be set as the active storage system. TempFS offers various types of storage classes
which consumes software. Currently, OnBase software only supports short-term storage. The --
mid-term and –cache options exist for developers if they know they need to set them and any
additional requirements or configurations. The proper choices for OnBase would be Short-Term
Storage = TRUE, and Mid-Term and Cache Storage Systems = FALSE.

Configure the API Server for the Temp File Service

You must make changes to the API Server's 1_server.json file in order to complete installation and
configuration of the Temp File Service (TempFS).
To configure the API Server for TempFS:
1. Browse to the config directory in your API Server's installation directory.
In a default installation, this directory is located at C:\Program Files\Hyland\ApiServer\config.
2. Open the 1_server.json file in a plain text editor, such as Notepad.
3. Locate the TempFileStorage tag.
4. In the Address tag, enter the URL of the Temp File Service. The URL should be of the format
http://[SERVER]/[APIServerName]/tempfs/, where [SERVER] is replaced with the server where
your API Server is installed and [APIServerName] is replaced with the name of your API Server.
5. Save and close the file.

© 2024 Hyland Software, Inc. and its affiliates 18

 API Server
Temp File Service Installation

6. Recycle your application pool for the changes to take effect.

Using Scriptable Configuration

Configuration of the Temp File Service can also be completed using scripted commands. For most
users, the previously discussed configuration method is recommend. Scriptable configuration does
allow for automation of the process by more advanced users. The command for using scriptable
configuration is storage-scriptable, so the very basic scripted command is:
\TempFileService.Configuration.exe storage-scriptable
Scriptable configuration recognizes the following commands:
• Add: This command is used to create a storage system. For example:
TempFileService.Configuration.exe storage-scriptable add --type S3 --url
http://localhost:9000 --bucket user-bucket --access-key manager --secret-
key password --force-http --force-path --tenant MyTenantNameHere --json-
config M:\TEMPFS\5_tempfs.json

Note: The returned and displayed ID is needed for the other commands.
• Update: This command is used to update the settings of an existing storage system. For
example: TempFileService.Configuration.exe storage-scriptable update --id
7 --type S3 --url http://localhost:9000 --bucket user-bucket --access-
key manager --secret-key password --force-http --force-path --tenant
MyTenantNameHere --json-config M:\TEMPFS\5_tempfs.json
• Delete: This command is used to delete an existing storage system. For example:
TempFileService.Configuration.exe storage-scriptable delete --id 6 --tenant
MyTenantNameHere --json-config M:\TEMPFS\5_tempfs.json
• Set Active: This command sets the specified storage system as the active system. For example:
TempFileService.Configuration.exe storage-scriptable set-active --id 7 --
short-term --mid-term --cache --tenant MyTenantNameHere --json-config M:
\TEMPFS\5_tempfs.json
During configuration, scriptable configuration should be used to configure tenant storage methods
using the Add command and set the active storage system using the Set Active command. For most
other uses, scriptable configuration should only be used by advanced users. For additional guidance,
contact your first line of support.

Validating the Temp File Service

The configuration of the Temp File Service can be validated using the validation command.
To validate the Temp File Service:
1. Run the following command:
TempFileService.Configuration.exe validation upload-file --help
2. Follow the on-screen prompts to validate the configuration of the Temp File Service.

© 2024 Hyland Software, Inc. and its affiliates 19

Guide
Administration
API Server

Administration Guide

Foundation 24.1
 API Server Logging

Configuring Hyland.Logging
A Hyland.Logging section is available in the 0_logging.json file. This section controls diagnostics
logging for the API Server.

Enabling Event Viewer Logging

Events can be logged to the Hyland log in the Windows Event Viewer. The following steps describe
how to ensure that Event Viewer logging is enabled.
1. Ensure the WindowsEventLogging element exists in the 0_logging.json file.
2. If necessary, modify the HylandLog attribute. When events are logged to the Hyland log, they
display this value as their source.
The default source name for the API Server is ApiServer.

Setting the Logging Level

To set the logging level:
1. Open the .json file in a plain-text editor.
2. Within the Hyland.Logging element, locate the Routes element
3. Locate the element for the logging route that you want to configure. Logging route elements can
include the following:

Logging Route Elements Description

DiagnosticsConsole Information logged in the Diagnostics Console.

ErrorEventLog Information logged in the Windows Event Viewer.

4. In the section for the route you are configuring, ensure that a Minimum-Level attribute is
included. Add the attribute if it does not already exist. For example:

© 2024 Hyland Software, Inc. and its affiliates 21

 API Server
API Server Logging

This enables detailed messaging to the diagnostics route.

Note: Depending on the application, this attribute might be included by default but commented
out. Remove the /* and */ from the line to uncomment the line.
5. To refine the severity of messages being received by the diagnostics route, you can edit the
attribute for minimum and maximum logging levels:
• The Minimum-Level attribute limits the lowest-severity log level that is received.
• You can add a Maximum-Level attribute, which limits the highest-severity log level that is
received.
• The values for these attributes can be set to any of the following log level severities, listed
from most severe to least severe.

Note: Log level names are case sensitive.

Log Level Description

Critical Logs that describe an unrecoverable application, system crash, or

catastrophic failure that requires immediate attention.

Error Logs that highlight when the current flow of execution is stopped due to
a failure. These logs indicate a failure in the current activity, but not an
application-wide failure.

Warning Logs that highlight an abnormal or unexpected event in the application

flow but do not otherwise cause the application to stop.

Information Logs that track the general flow of the application.

Debug Logs that are used for interactive investigation during development.

Trace Logs that contain the most detailed messages and may include sensitive
data. These logs should never be enabled in a production environment.

None A logging category that does not write any logging messages.

For example, a route in the .json file could be edited to include the following attributes:
"Minimum-Level": "Debug",
"Maximum-Level": "Error"
This example specifies that the logging route only receives logging messages with a severity
level of Debug or above, and it receives no messages with a higher severity level than Error.

Note: The default severity level of a route is a minimum of Information and a maximum
of Critical. The route uses these severity levels if it does not include a Minimum-Level or
Maximum-Level line specified in the .json file.
6. Save the file and restart the application.

© 2024 Hyland Software, Inc. and its affiliates 22

 API Server
API Server Logging

Creating Log Files

Logging routes can be configured to write logs to separate external .log files. These files can later be
opened for viewing in the Diagnostics Console or in a text editor such as Notepad.
To configure Hyland.Logging to write log files:
1. Open the .json file for the application that contains the Hyland.Logging element.
2. Locate the Hyland.Logging element.
3. Add the following logging route to the element:
"File": "FILEPATH",
"Maximum-Level": "Critical",
"Minimum-Level": "Information",
"FileRollInterval": "Day",
"FileRollOnSize": true,
"FileCountLimit": 30,
"FileByteLimit": 10485760
}
4. Replace "FILEPATH" with the file path for the log file, including the name of the file you want
the log to be saved as. This file must be a .log file. For example, "./logs/ApiServer.log" would
write the logs to a file called ApiServer.log in the /logs directory within the directory where the
application is installed.
5. Set the "Maximum-Level" attribute to the maximum level of severity you want to be reported in
the log.
6. Set the "Minimum-Level" attribute to the minimum level of severity you want to be reported in
the log.
7. Set the " "FileRollInterval" attribute to the interval that you want a new log created. The following
intervals are available for use:

Interval Description

Minute A new log file is created every minute.

Hour A new log file is created every hour.

Day A new log file is created every day.

Month A new log file is created every month.

Year A new log file is created every year.

Infinite A new log is never created.

8. Set the "FileRollOnSize" attribute to "true" or "false" to limit log files based on size. If set to
"true", a new log file to be created when the current log file reaches the configured size limit.

© 2024 Hyland Software, Inc. and its affiliates 23

 API Server
API Server Logging

9. Set the "FileCountLimit" attribute to the number of log files to be kept before older files are
deleted. If you do not want to delete older files, you can set the value to "null".
10. Set the "FileByteLimit" attribute to the maximum size in bytes a log file can be before creating a
new file. This attribute is only active if "FileRollOnSize" is set to "true".
11. Save the file and close the text editor.
12. Reset the application.

Disabling IP Address Masking

In the Diagnostics Console, the IP address of the workstation is displayed in certain tabs. By default,
the source IP address is obfuscated so that it cannot be identified. To display the full source IP
address of the workstation, a key must be entered into the diagnostics route in the Hyland.Logging
section of the 0_logging.json file being used by the workstation.
To enter the key into the 0_logging.json file:
1. Open the 0_logging.json file.
2. Locate the Hyland.Logging section of the file.
3. In section for the diagnostics route you want to configure, enter the following key:
a. "DisableIPAddressMasking": true
4. Save the file and restart the application.

Configuring Log Entry Truncation

Logging entries can be configured to truncate in length to avoid the creation of overly long individual
entries.
To configure Hyland.Logging to truncate individual log entries:
1. Open the .json file for the API Server that contains the Hyland.Logging element.
2. Locate the Hyland.Logging element.
3. Add the following line toe the element before any specified logging routes:

"TruncateLogValues": "NUMBER"

4. Replace "NUMBER" with the desired length for log entries in characters in quotation marks. For
example, replacing "NUMBER" with "20" will truncate all messages at 20 characters in length.
5. Save the file and close the text editor.
6. Reset the API Server.

© 2024 Hyland Software, Inc. and its affiliates 24

 Hyland Application Settings Utility

Hyland Application Settings Utility

Current H1 topic should be reviewed.
The Hyland Application Settings Utility is a command-line utility for writing and encrypting specified
sections of JSON configuration files.

Note: Decryption of configuration values encrypted by the Hyland Application Settings Utility is
not supported for all modules or applications. If you encrypt values in a configuration file for an
unsupported application, that application will not be able to decrypt the values at runtime.

Overview
This section explains how use the Hyland Application Settings Utility. For more information on how
to acquire the utility, contact your first line of support.
To deploy the Hyland Application Settings Utility, unpackage the files in the release package by
extracting them to a location in your environment. You can then use the command line from that
location to execute the commands for the utility.
The following commands are available:

Command Description

write Writes a specified property value to a JSON configuration file. You can also
encrypt the property value with this command.
See Writing a Value in a JSON File on page 26.

read Reads a specified property value in a JSON configuration file and returns it in the
command-line console output. You can also decrypt an encrypted property value
with this command.
See Reading a Value in a JSON File on page 27.

help Returns a list of available commands and a short description of each command.
You can add a command after the help command to return a list of the
parameters used by that command.
For example, the following command returns a list of the parameters for the write
command:
Hyland.Application.Settings.Utility.exe help write

version Returns the full name and version number of the Hyland Application Settings
Utility.

© 2024 Hyland Software, Inc. and its affiliates 25

 API Server
Hyland Application Settings Utility

Writing a Value in a JSON File

The write command allows you to write a specified property value to a JSON configuration file. By
default, the write command writes values to the file in plain text, but you can encrypt a value by using
the --encrypt parameter.

CAUTION: Be very careful when updating the JSON configuration files. If a copy exists with a similar
naming scheme (for example, appsettings.backup.json), and that copy is not deleted, the incorrect
JSON configuration file may be used. Configuration files are read in lexicographic order, or the order
in which they are loaded. This means that the last file saved is the first file loaded. The order of
precedence for the loading of the configuration sources is: 1) appsettings.json file, 2) appsettings.
{AltName}.json file, 3) Key-per-file directories, 4) Environment variables, and 5) Command Line
arguments. As a result, if a JSON configuration file is configured with an alternate name, and is the
most recently saved version of the JSON configuration file, the file with the alternate name will take
precedence, which causes major errors during login.
Note the following considerations:
• If a value already exists for the specified property, the write command overwrites the existing
value. This is true regardless of whether the original value is plain text or encrypted.
• If you are encrypting a value, the configuration file must remain in the location specified in the
parameters for the write command. If the file is moved after the value is encrypted, the value
cannot be decrypted by the utility or the supported application.
The write command is executed by appending parameters to the
Hyland.Application.Settings.Utility.exe write command. The following parameters are available:

Parameter Short Description Required

Name

--applicationRoot -a The path to the directory that contains the application Yes
using the configuration file.
For example:
-a C:\repo\application

--file The file name of the JSON configuration file. If the file is Yes
located in a subdirectory of the location specified in the --
applicationRoot parameter, also include the relative path
to the file.
For example:
--file config\appsettings.json

--property -p The name of the property to write. For nested properties, Yes
use a colon (:) delimiter.
For example, where a property called masterDB contains
a sub-property called ConnectionString, to which you
want to write a value:
-p masterDB:ConnectionString

--value -v The value to write. Yes

© 2024 Hyland Software, Inc. and its affiliates 26

 API Server
Hyland Application Settings Utility

Parameter Short Description Required

Name

--verbose Sets the diagnostics logging level for the information No

returned by the command.
If this parameter is included in a command, detailed
logging information is returned.
If this parameter is not included in a command, logging
information is returned only if an error occurs.

--force -f Forces the creation of the property if it is not already No

present in the configuration file.

--encrypt Encrypts the property value written to the configuration No

file.
If this parameter is included in a command, the specified
value is encrypted, and the encrypted value is written to
the file.
If this parameter is not included in a command, the
specified value is written to the file in plain text.

Required and optional parameters are added to the write command line, as shown in this example:

Hyland.Application.Settings.Utility.exe write -a C:\repo\application

--file config\appsettings.json -p masterDB:ConnectionString -v
Server=myServer;Database=myDB; --verbose --force --encrypt

Note: If a parameter value includes spaces, you must enclose the entire value in quotation marks.
For example, if using the -a parameter to point to the path C:\Program Files\App, the full parameter
and value would be: -a "C:\Program Files\App"
If the --force parameter is not used, the property passed in must already exist in the file. If the --
force parameter is used, then the property passed in does not need to already exist.
If the property exists, --force will write the property value to the configuration file. If the property
does not exist, --force will create the configuration sections for the property value and write the
value to the configuration file.
If you are using the write command to write a property value in an array, you must use the proper
index to refer to an element in the array. See Writing and Reading Array Elements on page 29 for
more information.

Reading a Value in a JSON File

The read command allows you to read a specified property value in a JSON configuration file and
return it in the command-line console output. By default, the read command returns values exactly
as they appear in the file, but if the value is encrypted, you can decrypt it by using the --decrypt
parameter.

© 2024 Hyland Software, Inc. and its affiliates 27

 API Server
Hyland Application Settings Utility

Note the following considerations:

• Decrypting an encrypted value with the read --decrypt command does not write the decrypted
value to the configuration file. The value remains encrypted in the configuration file.
• If you are decrypting a value, the configuration file must be in the same location as it was when
the value was encrypted. If the file is moved after the value is encrypted, the value cannot be
decrypted by the utility or the supported application.
The read command is executed by appending parameters to the
Hyland.Application.Settings.Utility.exe read command. The following parameters are available:
This table has more than two columns. Please review for column width and row height. Make
adjustments as necessary.

Parameter Short Description Required

Name

--applicationRoot -a The path to the directory that contains the application Yes
using the configuration file.
For example:
-a C:\repo\application

--file The file name of the JSON configuration file. If the file is Yes
located in a subdirectory of the location specified in the --
applicationRoot parameter, also include the relative path
to the file.
For example:
--file config\appsettings.json

--property -p The name of the property to return. For nested properties, Yes
use a colon (:) delimiter.
For example, where a property called masterDB contains
a sub-property called ConnectionString, from which you
want to read a value:
-p masterDB:ConnectionString

--verbose Sets the diagnostics logging level for the information No

returned by the command.
If this parameter is included in a command, detailed
logging information is returned.
If this parameter is not included in a command, logging
information is returned only if an error occurs.

--decrypt Decrypts the property value returned in output.

Required and optional parameters are added to the read command line, as shown in this example:

© 2024 Hyland Software, Inc. and its affiliates 28

 API Server
Hyland Application Settings Utility

Hyland.Application.Settings.Utility.exe read -a C:\repo\application --file

config\appsettings.json -p masterDB:ConnectionString --verbose --decrypt

Note: If a parameter value includes spaces, you must enclose the entire value in quotation marks.
For example, if using the -a parameter to point to the path C:\Program Files\App, the full parameter
and value would be: -a "C:\Program Files\App"
If you are using the read command to return a property value in an array, you must use the proper
index to refer to an element in the array. See Writing and Reading Array Elements on page 29 for
more information.

Writing and Reading Array Elements

The Hyland Application Settings Utility can write and read array elements, as well as encrypt and
decrypt values within array elements.
Array indexing begins at zero, so an element at the n position in an array has an index of n-1. The
following table lists common array scenarios and the appropriate index to use.

Scenario Index

Creating a new array When creating a new array, the element is added to the first position of
the array.
The first element is in the n=1 position, and it has an index of 0.

Accessing an element in An element in the n position has an index of n-1.

an existing array For example, the third element in an array (the n=3 position) has an
index of 2.

Adding to an array When adding an element to an array, the new element is added to the
last position in the array.
For example, if an array has five elements and a new element is added,
it is added to the sixth position (n=6), and it has an index of 5.

In the following example JSON configuration, the Certs array contains two elements, representing
multiple Thumbprint properties. The first element in the array has an index of 0, and the second
element has an index of 1.

© 2024 Hyland Software, Inc. and its affiliates 29

 API Server
Hyland Application Settings Utility

In this example, the following write command can be used to encrypt and write the value
myCertThumbprint to the first Thumbprint element:

Hyland.Application.Settings.Utility.exe write -a C:\repo\application --file

config\appsettings.json -p config:Certs[0]:Thumbprint -v myCertThumbprint --
encrypt

Similarly, the following read command can be used to decrypt and return the value in the first
Thumbprint element:

Hyland.Application.Settings.Utility.exe read -a C:\repo\application --file

config\appsettings.json -p config:Certs[0]:Thumbprint --decrypt

In either command, you could use either Certs[0] or Certs:0 in the -p parameter to reference the
first element in the Certs array and the Thumbprint property in that element. To write or read the
values of any other array elements, update the array index number to point to the element you want
to reference.
To create a new element in an array, you must use the --force parameter. In the previous JSON
example, only indexes 0 and 1 exist, so the new element will be created with an index of 2. The
following command demonstrates how to force-create and encrypt the value of myCertThumbprint
in a new element in the array:

Hyland.Application.Settings.Utility.exe write -a C:\repo\application --file

config\appsettings.json -p config:Certs[2]:Thumbprint -v myCertThumbprint --
force --encrypt

In all of the example commands above, Thumbprint is appended after the index reference to
designate which parameter in the element is being set or retrieved, as an element can be a single
field or a collection of fields. If a specific parameter within the referenced element is not designated
while using the --force parameter, the entire element will be overwritten.

© 2024 Hyland Software, Inc. and its affiliates 30