Avocet High Frequency Infrastructure

Contents
Avocet 2017.2..................................................................................................................5
Avocet Production Data Management System Installation Guide.............................7
Avocet installation preliminaries and references...........................................................................................7
Supported operating systems, servers, and databases for Avocet desktop ................................................8
Avocet 2017.2 components........................................................................................................................11
Avocet 2017.2 installation packages...........................................................................................................12
Avocet 2017.2 licensing..............................................................................................................................13
Common prerequisites for Avocet desktop.................................................................................................13
Avocet Installer utility..................................................................................................................................15
Upgrade prerequisites.................................................................................................................................16
Files to download........................................................................................................................................16
Before launching the Avocet Installer..........................................................................................................17
Launch the Avocet Installer.........................................................................................................................18
Install the licensing software.......................................................................................................................21
Install Avocet...............................................................................................................................................24
Microsoft ClickOnce....................................................................................................................................36
Install the AppServer..................................................................................................................................49
Install Petrel Studio Plug-in 2015................................................................................................................49
Install OFM Plug-in 2014.1, 2016.1, or both...............................................................................................50
Troubleshooting installation issues.............................................................................................................50
Post-installation considerations..................................................................................................................51
Production day start....................................................................................................................................51
Specify a timeout interval for the Avocet client...........................................................................................52
Define links to custom screen-level help files.............................................................................................53
Enable custom screen-level help on an existing database implementation................................................54
High frequency infrastructure: installation and configuration.................................56
HFI manager and the AvocetHFSync service.............................................................................................56
HFI manager prerequisites.........................................................................................................................57
HFI manager and high frequency data flow................................................................................................57
Introduction to Apis interfaces and configuration properties.......................................................................62
Suggested workflow for installing Avocet HF store and HFI Manager .......................................................63
How to implement a corporate historian in a high frequency setting..........................................................75
How to set up your OPC UA data sources for high frequency implementations ........................................88
Run script to grant non-administrative or standard user rights to Avocet HF store and HFI manager........93
Multiple HFI manager and Avocet HF store instances................................................................................94
Multiple Avocet HF store and corporate historian instances.......................................................................96
Apis backup and restore command line options.......................................................................................101
Appendix 1: Manual steps to apply security settings to your corporate historian.....................................105
Appendix 2: Manual steps to grant non-administrative or standard user rights to Avocet HF store and HFI manager
..................................................................................................................................................................106
Appendix 3: Install and uninstall Apis components (manual procedure)...................................................114
Appendix 4: Security guidelines and technologies....................................................................................116
Appendix 5: Install and launch the HF Player...........................................................................................135
Appendix 6: Troubleshooting.....................................................................................................................139
Working with data flow configuration and alarms...................................................143
How to work with the Data Flow screen ...................................................................................................143
Real-time and historical data in the Avocet context..................................................................................144
Configuration of data flow.........................................................................................................................144
Before you begin ......................................................................................................................................144
Access the Data Flow screen...................................................................................................................145
Data Flow screen compared with Tag Mapping screen............................................................................145
Map historian tags to Avocet items ..........................................................................................................146
Check connectivity to the Avocet HF Store and corporate historian.........................................................147
Set up the Avocet item for data flow configuration....................................................................................147
How to map tags manually........................................................................................................................150
Specify transaction and property in the Avocet database and populate HF Store tags............................150
Map corporate historian tags with Avocet item and transaction properties..............................................151
Display additional data fields....................................................................................................................153

ii Avocet High Frequency Infrastructure

 Contents

How to add previously defined tag mappings ..........................................................................................155

Use templates to populate tag mapping entries.......................................................................................155
Save tag mapping entries as a template...................................................................................................155
Apply a tag mapping template to another item.........................................................................................156
Mail settings, recipients, and groups.........................................................................................................156
Define your SMTP mail settings (include HFIManager.exe.config)...........................................................157
Define a mail recipient..............................................................................................................................159
Define a mail group ..................................................................................................................................159
Link mail group with recipients..................................................................................................................160
Link mail recipients to mail groups............................................................................................................160
Manage the Mail Queue Viewer................................................................................................................160
Alarms.......................................................................................................................................................161
Alarm events and alarm thresholds..........................................................................................................162
Before you begin.......................................................................................................................................163
Access an alarm screen ..........................................................................................................................164
Configure the alarm limits for the Limit screen..........................................................................................165
Configure watchdog alarms......................................................................................................................167
Configure off normal alarms.....................................................................................................................167
Browse alarm and event history with an OPC UA client...........................................................................167
Use templates to apply alarm settings......................................................................................................168
Save alarm settings as a template............................................................................................................168
Apply alarm settings to another item........................................................................................................169
How to load high-frequency alarm transactions and global tag maps......................................................169
High-frequency alarm transactions...........................................................................................................169
Global tag maps........................................................................................................................................171
Appendix: Troubleshooting data flow configuration...................................................................................173
General guideline......................................................................................................................................173
Impact of synchronization on data source tags........................................................................................174
Other.........................................................................................................................................................175
About calculations .....................................................................................................178
About your HF configuration file................................................................................................................178
Extensibility...............................................................................................................................................178
HistorianConfigurations............................................................................................................................179
Validations.................................................................................................................................................180
ItemLinkChains.........................................................................................................................................181
Calculations..............................................................................................................................................183
TransactionTemplateDefinition..................................................................................................................183
Working with calculations..........................................................................................................................184
Background...............................................................................................................................................184
Distinguishing features..............................................................................................................................185
Data source and real-time or historical data.............................................................................................185
When calculations are run........................................................................................................................185
Out-of-the-box versus custom calculations...............................................................................................186
Real-time data..........................................................................................................................................187
Historical data...........................................................................................................................................188
Inputs and outputs....................................................................................................................................190
Calculation reference................................................................................................................................190
Calculation definition attributes.................................................................................................................191
Filtering criteria.........................................................................................................................................191
OPC HDA data types................................................................................................................................191
Aggregation methods................................................................................................................................192
Calculation examples................................................................................................................................193
Generic calculation example.....................................................................................................................193
Custom clamping calculation: walkthrough...............................................................................................196
Historical value calculation........................................................................................................................203
Custom percent change calculation..........................................................................................................204
Custom calculation validations..................................................................................................................206
PI Historian configuration..........................................................................................208
HFConfig_PIHistorian.xml........................................................................................................................208
Edit the HFConfig_PIHistorian.xml file......................................................................................................209
Define data tags........................................................................................................................................209
Load data tags..........................................................................................................................................210
Autocreate PI historian tags......................................................................................................................210
Avocet web services API............................................................................................211

iii
Share configuration files between AvocetVM and AvocetWebService projects........................................211
Edit the Web.config file and verify the license file path.............................................................................212
Enable pass-through authentication ........................................................................................................213
Encrypt database connection strings........................................................................................................214
Encrypt passwords in regular connection strings.....................................................................................216
Set up IIS 8.0 or 8.5 on Windows Server 2012 R2 (manual steps)..........................................................217
Internet Information Services roles and features......................................................................................218
Install IIS 8.0 or 8.5 on Windows Server 2012 R2....................................................................................218
Test the IIS HTTP connection on Windows 2012 R2 Server....................................................................223
Configure HTTP response headers..........................................................................................................224
Enable HTTPS..........................................................................................................................................225
Enable the .NET 4.5 application pool........................................................................................................229
Add the web services application under the default website ...................................................................231
Browse the web service node to launch the Swagger UI..........................................................................232
Add the WebApiServer tag to your AppConfig_ProjectLayer file..............................................................234
Restart IIS after a configuration change in the Avocet web service configuration....................................235
Apply security constraints to user roles and HTTP request methods.......................................................235
Notifications..............................................................................................................................................237
Edit the HFIManager.exe.config file and verify plug-in..............................................................................237
Mail settings, recipients, and groups.........................................................................................................238
SignalR scale out configurations...............................................................................................................242
Avocet web services controllers and operations.......................................................................................244
HTTP request methods and status codes................................................................................................245
Log into the application ID........................................................................................................................245

iv Avocet High Frequency Infrastructure

Avocet 2017.2

Copyright © 2018 Schlumberger. All rights reserved.

This work contains the confidential and proprietary trade secrets of Schlumberger and may not be
copied or stored in an information retrieval system, transferred, used, distributed, translated or
retransmitted in any form or by any means, electronic or mechanical, in whole or in part, without the
express written permission of the copyright owner.
Trademarks & Service Marks

5
 Schlumberger, the Schlumberger logotype, and other words or symbols used to identify the products
and services described herein are either trademarks, trade names or service marks of Schlumberger
and its licensors, or are the property of their respective owners. These marks may not be copied,
imitated or used, in whole or in part, without the express prior written permission of Schlumberger. In
addition, covers, page headers, custom graphics, icons, and other design elements may be service
marks, trademarks, and/or trade dress of Schlumberger, and may not be copied, imitated, or used, in
whole or in part, without the express prior written permission of Schlumberger. Other company, product,
and service names are the properties of their respective owners.
® ® ® ®
Avocet , Studio , PIPESIM , and OFM are marks of Schlumberger.
An asterisk (*) is used throughout this online help to designate other marks of Schlumberger.
Security Notice
The software described herein is configured to operate with at least the minimum specifications set
out by Schlumberger.You are advised that such minimum specifications are merely recommendations
and not intended to be limiting to configurations that may be used to operate the software. Similarly,
you are advised that the software should be operated in a secure environment whether such software
is operated across a network, on a single system and/or on a plurality of systems. It is up to you to
configure and maintain your networks and/or system(s) in a secure manner. If you have further questions
as to recommendations regarding recommended specifications or security, please feel free to contact
your local Schlumberger representative.
Product Information
Country of Origin: United States of America

6 Avocet High Frequency Infrastructure

Avocet Production Data Management
System Installation Guide
This section discusses how to install the Avocet Production Data Management System (PDMS)
components through the Avocet Installer utility.
The Avocet PDMS components include the following:
• Avocet
• ClickOnce for Avocet client
• Avocet application server
In addition, the Avocet Installer offers the following options:
• Schlumberger Licensing software 2017.1
• Petrel Studio Plug-in 2015
• OFM Plug-in 2014.1 and OFM Plug-in 2016.1
The Avocet platform also offers a high frequency data implementation options. Its components are
the
• Avocet HF store
• Avocet HFI manager
For the installation and setup instructions of the Avocet HF store and Avocet HFI manager, refer to
the Help topic High Frequency Infrastructure Manager Installation and Configuration.

Avocet installation preliminaries and references

This section introduces the Avocet prerequisites and lists supplemental information that is helpful to
the configuration and deployment of certain Avocet components.

Note: To start installing Avocet components immediately, without reviewing preliminaries and
prerequisites, skip to the Avocet Installer utility section.

To complete the setup and configuration of some of the components, refer to the following Help topics
and documents:

Help topic Description

Installation Reference Provides guidelines for MS SQL server and Oracle database setup

Supplies a deployment overview

Summarizes upgrade scenarios

Application Servers and Process Groups Contains configuration steps for setting up Internet Information Services server
to support the Avocet web services API and the application server

Avocet Integration: Studio Contains installation and configuration information for the Petrel Studio Plug-in
2015

7
 Help topic Description

Avocet Integration: Oilfield Manager Projects Contains installation and configuration information for the OFM Plug-in 2014.1
and 2016.1

High Frequency Infrastructure Manager Describes how to configure and deploy the Avocet HF Store and HFI manager
Installation and Configuration in an OPC UA high frequency implementation

The Avocet Installer does not deploy the Avocet web services independently
Avocet Web Services
as its own package because the web services package is designed mainly for
developers. Refer to the Avocet Web Services documentation for configuration
details.

Supported operating systems, servers, and databases for Avocet desktop

This topic summarizes the client and server operating systems and the databases that Avocet 2017.2
supports for the Avocet desktop.

Supported Client OS

Windows 7 SP1 64-bit, Professional and Enterprise editions

Windows 10 64-bit, Professional and Enterprise editions

Supported Server OS

Windows Server 2012 R2 64-bit

Supported database server

Oracle 12.1.0.2 (Oracle 12c) Enterprise

MS SQL Server 2012 SP2 Standard

The Enterprise editions of the database servers support features such as database partitioning and
compression. The Standard editions do not support these features though they do support all Avocet
functionality. When sizing your database, if the Enterprise features are not required, you can use the
Standard edition.

Note: While the Enterprise edition of MS SQL Server 2012 SP2 has not been formally certified,
it is used in test and production deployments.

As a rule of thumb, you should also use the most recent release of the database server.
The following SQL database engine has been tested for disconnected desktops:
• SQLite v.3.7.17
SQLite is specifically aimed at local installations on disconnected field laptops having single users. Its
requirements are minimal.
The following IIS versions are supported for the web services API:
• IIS 8.0 or 8.5 on Windows server 2012 R2

8 Avocet High Frequency Infrastructure

Client workstation requirements
This topic contains a table that shows the recommendations for the client workstations that connect
Avocet to its database. The recommendations cover the operating system, processor, physical memory,
and so on.

Requirement Minimum Size Recommended Size

Operating System Microsoft Windows 7 SP1 64-bit Microsoft Windows 7 SP1 64-bit

Processor Intel i3 or equivalent Intel i7 or later

Physical Memory 2 GB 8 GB or greater

Hard Disk Space 2 GB 20 GB or greater

Display 17-in monitor (1280 x 1024) 21-in monitor (1920 x 1080)

Client software Microsoft .NET 4.6.1 Runtime, Microsoft Internet Explorer 8 or later

Microsoft Office 2003 or higher required for integration for Office applications

Database connectivity Required for client machines connecting directly to the database (client/server mode).

SQL Server client software is included with Microsoft Vista or later. SQL Server client software
matching the database server version is recommended.

Oracle Instant Client software is included with the application. Oracle client software deployed
on machines is also supported.

Database server guidelines

This topic contains a table that shows the recommended guidelines for database servers, such as
operating system, processor, and so on.

Note: The requirements and recommendations described herein are guidelines. They may vary
depending on your specific deployment requirements.

Database server specifications will change based on anticipated data requirements and user load.
Specifications here indicate typical configurations. At a minimum, data and indexes should be separated
on two physical disks with their own disk controllers.
The database server can be deployed using vendor-specific high availability solutions for redundancy
and disaster recovery. Proper back-up procedures should be used to provide protection against failures
based on standard IT procedures.

Note: Beginning with Windows Server version 2008 R2, all Windows Server versions are
released in 64-bit only.

Requirement Recommended Size Recommended Size

(Smaller asset) (Larger asset)

Operating System Microsoft Windows Server Microsoft Windows Server 2012 R2

2012 R2

Processor 2 Intel Dual x64 Server class 4 Intel Dual x64 Server class CPUs or better
CPUs or better

Physical Memory 8-16 GB 32-128 GB

9
 Requirement Recommended Size Recommended Size

(Smaller asset) (Larger asset)

Hard Disk Space 2 x 500 GB or greater The database sizing varies by client.

Display 17” monitor (1024 X 768)

Database software Recommended: Microsoft SQL Server 2012 SP2 Standard Edition or Oracle 12.1.0.2
(Oracle 12c) Enterprise Edition

Following your Oracle or MS SQL Server guidelines, you can install and run the database on any
compatible database server.

Application server requirements

This topic contains a table that shows the recommended application server requirements such as
operating system, processor, physical memory, and so on.
Application server requirements change based on anticipated user load.
For example, the hard disk space values in the following table assume that a single machine contains
the application, replication, and web servers and that the client intends to store months of replication
data.
The sizing values always vary with the client's business requirements. As always, try to determine the
scale before deploying Avocet.

Requirement Minimum Size Recommended Size

Operating System Microsoft Windows Server Microsoft Windows Server 2012 R2 x64
2012 R2 x64

Processor Intel Core, AMD Opteron, or 2 Intel Dual x64 Server class CPUs or better
equivalent

Physical Memory 16 GB 32-64 GB

Hard Disk Space 1 TB 2 x 1 TB or greater

Display 17” monitor (1024 X 768)

Server software Microsoft .NET 4.6.1 Runtime, Microsoft Internet Explorer 8 or later

Microsoft Office 2003 or higher required for integration for Office applications

Database connectivity Required for client machines connecting directly to the database (client/server mode).

SQL Server client software is included with Microsoft Vista or later. SQL Server client software
matching the database server version is recommended.

Oracle Instant Client software is included with the application. Oracle client software deployed
on machines is also supported.

Avocet as a published application through Citrix or Microsoft technologies

Avocet can be deployed on Citrix Presentation Server, Citrix XenApp, or Windows Terminal Server
through an xcopy deployment on a published endpoint.

10 Avocet High Frequency Infrastructure

 Server requirements for delivering Avocet as a published application
This topic contains a table that lists the requirements for delivering Avocet as a published application.
The information includes operating system, processor, physical memory, hard disk space, and so on.

Requirement Minimum Size Recommended Size

Operating System Microsoft Windows Server 2012 R2 64-bit Microsoft Windows Server 2012 R2 64-bit

Processor Intel Dual, Quad, or 8-Way Server class Intel Dual, Quad, or 8-Way Server class CPU’s
CPUs or better or better

Physical Memory 16-32 GB 32-128 GB

Hard Disk Space 50 GB or greater 50 GB or greater

Display 17” monitor (1280 x 1024) 21-in monitor (1920 x 1080)

Server software Microsoft .NET 4.6.1 Runtime, Microsoft Internet Explorer 8 or later

Microsoft Office 2003 or higher required for integration for Office applications

Database connectivity Required for client machines connecting directly to the database (client/server mode).

SQL Server client software is included with Microsoft Windows Vista or later. SQL Server
client software matching the database server version is recommended.

Oracle Instant Client software is included with the application. Oracle client software deployed
on machines is also supported.

Client requirements for consuming Avocet as a published application

This topic discusses the client requirements for consuming Avocet as a published application.
Hardware requirements vary based on the operating system selected for Citrix Presentation Server
or Windows Terminal Services clients.
Citrix supports a variety of operating systems including UNIX, Macintosh, Linux, Microsoft DOS,
Windows, and Windows CE. Contact Citrix for more information.
Microsoft supports a variety of operating systems including Mac and various Windows versions. Contact
Microsoft for more information.

Microsoft Visual Studio

Because Microsoft .NET 4.6.1 Runtime is a prerequisite that the Installer provides, you should use a
compatible version of Microsoft Visual Studio as your preferred editor: for example, Microsoft Visual
Studio 2015.

Avocet 2017.2 components

This topic contains a table that describes the main software components in the Avocet 2017.2 installation
package.

Component Description

Avocet desktop client The main client GUI where you perform your production management tasks

Configuration Tool Utility that allows administrators to initialize databases, modify the type system, set up units
of measure, and perform a range of administrative tasks

11
 Component Description

Database Configuration Tool Utility that allows administrators to create and initialize fresh database instances and upgrade
existing database with the latest data type definitions

APIS Foundation The Advanced Plant Information System (APIS) is a data collection system consisting of a
database (HoneyStore) and data historian server (ApisHive). The ApisHive structure is the
basis of the Avocet HF Store, a local historian in the Avocet high-frequency implementation.
You must install and configure APIS Foundation to enable the OPC UA high-frequency
implementation. See the Help topic High Frequency Infrastructure Manager Installation and
Configuration.

HFI Manager The high frequency infrastructure (HFI) manager supports the automatic synchronization of
high frequency data. It actively monitors updates to the Avocet database and then automatically
updates the related tags in the Avocet HF store. See the Help topic High Frequency
Infrastructure Manager Installation and Configuration.

AvocetWebService The web services API is addressed to developers to customize and extend their own web
services applications. It does not have its own installation routine. See the Avocet Web
Services documentation in the AvocetVM\Documentation folder.

Note: The Avocet web services API is required for the Avocet application server
deployment and is installed with the application server.

ClickOnce Deployment package that enables an Avocet server to publish files to multiple Avocet clients,
providing for the installation and updating of Avocet clients through a web connection

Application server A server that is especially designed to handle the execution of Avocet processes, such as
allocations and data loading. It requires the Avocet web services API and an Internet
Information Services (IIS) server.

Redistributables Avocet includes several redistributables, such as Microsoft Visual C++ Redistributable for
Visual Studio 2015, .NET Framework 4.5.2, Visual C++ Runtime, Report Viewer, and others.

Plugins Studio and OFM plugins are available for connecting Avocet with Studio and OFM

Avocet 2017.2 installation packages

Avocet 2017.2 components are contained in three zipped files that you can download from the SIS
Software Download Center. This topic lists the three files (installation packages) and explains what is
in each.
The installation package is available at SIS Software Download Center.

Installation package Description

Avocet_2017.2_Full_Release.zip Contains the Avocet implementation folders AvocetVM,

AvocetWebService, and AppServer

Avocet_2017.2_InstallationUtility.zip A Windows PowerShell utility from which you can install Avocet
prerequisites and components, including the ClickOnce
deployment package and Studio and OFM plug-ins

Avocet_2017.2_Prerequisites.zip A convenience zipped package that contains the Avocet

prerequisite components

12 Avocet High Frequency Infrastructure

Avocet 2017.2 licensing
Avocet 2017.2 requires an Avocet date-based version (DBV) license file that is current at the time of
its commercial release.
The client maintenance expiration date is included in the feature line of your license. For example,
2017.09 indicates that your license expires in September, 2017. If you are under a current maintenance
contract and intend to use existing features, you can run Avocet 2017.2 using your existing license.
However, if you intend to use new features, such as the web services API, you need to renew your
license.
You can view your license features in your Avocet installation by selecting File > About and clicking
the Licensed Modules tab in the About Avocet dialog. Internal users can view the following license
grid on the Hub:
• licensing grids
For additional licensing requirements, contact your Avocet business development manager.
Avocet 2017.2 uses FlexLM version 11.14 or later from MacroVision for concurrent licensing. Daemons
are available for both Microsoft Windows and UNIX operating systems.
If your Avocet 2017.2 installation uses a license server (portNumber@serverName), then you must
use Schlumberger Licensing Tool 2017.1, which includes the FLexLM 11.14 license.You can download
the Schlumberger Licensing Tool 2017.1 from the SIS Software Download Center. You can enter the
search criteria “Schlumberger licensing.”

Common prerequisites for Avocet desktop

The Avocet desktop version requires several runtime and redistributable files.
Windows Powershell 3.0 or later is required by the Avocet Installer utility and for executing certain
post-install scripts. You must already have Windows Powershell 3.0 or later already deployed before
you can successfully launch the Avocet Installer utility.
Aside from Windows Powershell, the Avocet Installer utility checks for other prerequisites and installs
missing prerequisites after you acknowledge a prompt.
The Avocet desktop requires the following prerequisite runtime and redistributable files:
• Microsoft Visual C++ Redistributable for Visual Studio 2015
• Microsoft .NET Framework 4.6.1 or later
• Microsoft ReportViewer 2010 Redistributable
• Microsoft ReportViewer 2012 Redistributable
• Microsoft Visual C++ 2008 Runtime Libraries (x64)
• Microsoft Visual C++ 2008 Runtime Libraries (x86)
• Microsoft Visual C++ 2010 Runtime Libraries (x64)
• Microsoft Visual C++ 2010 Runtime Libraries (x86)
• Microsoft Visual C++ 2012 Runtime Libraries (x64)
• Microsoft Visual C++ 2012 Runtime Libraries (x86)
• Microsoft Access Database Engine Redistributable 2010
• Windows Powershell 3.0 or later
Depending on your OS, you may already have at least some of the prerequisites installed. To check
which prerequisites you have, you can view the listing of installed programs in the Control Panel’s
Program and Features window, as seen in this excerpt:

13
 To execute some of the configuration and verification commands, you should have the administrator
privilege or be able to run tasks as the administrator.

Check file versions through Windows registry

If you have administrative privilege, you can check the Windows registry for updates by running the
regedit command.
This example shows how to check the .NET framework version through Registry Editor.

1. Launch the regedit.exe command.

2. In the Registry Editor, open the following subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Update
You can view .NET Framework and redistributable entries, as shown in this example:

You can either refer to the corresponding Microsoft websites for downloading and verifying the
installation of the components or run the Avocet Installer utility.

Run PowerShell with administrator privileges for Windows 8

This task shows how to modify the Windows PowerShell so it always runs with administrator privileges.
Thereby you do not have to select Run as Administrator even if you are already an administrator on
the system.
On a Windows 8 system, when launching the PowerShell window you may get an error when running
the script. To run the script successfully, you have to select Run as Administrator even if you are
the administrator on the system. To avoid this extra step, you can modify the Windows PowerShell
shortcut so that it always runs with the administrator privilege.

1. Right-click the Windows PowerShell shortcut to display the flyout menu, and choose Properties.

2. In the Shortcut tab of the Windows PowerShell Properties dialog, choose Advanced… .

14 Avocet High Frequency Infrastructure

 3. In the Advanced Properties pop-up, select the Run as administrator check box.

4. Click OK to close the Advanced Properties pop-up.

5. Click Apply in the Windows PowerShell Properties dialog, and then click OK.

Avocet Installer utility

This section lists the tested and supported Avocet Installer utility platforms. It also shows how to install
the various Avocet components and third-party utilities using the Avocet Installer utility.
You can use the Avocet Installer utility for both single and multiple system installations. The utility
includes the prerequisites.
The Avocet Installer utility is supported on
• Window server 2008 R2
• Windows server 2012 R2
The Avocet Installer utility also runs on supported Windows client versions, but not all installation
routines are supported on the Windows clients. For example, you cannot install the application server
on Windows clients.

15
 Note: The Avocet web services API is installed as part of the application server installation. It
does not have its own installation routine. You must manually deploy the web services API if
you want to use it to extend or customize web applications other than the application server.

Upgrade prerequisites
This procedure provides guidelines for what you must do if you have an existing implementation that
you are upgrading.
If you have an OPC UA implementation that uses the ApisHive instance of an Avocet HF store, you
can use the Avocet Installer to upgrade to the latest Apis Foundation version. The upgrade script
leaves intact all settings, modules, and items of your Avocet HF store configuration.
Before upgrading any aspect of Avocet, do the following:

1. Save ALL customized files.

These files include all your Avocet project implementation files:
• AppConfig_ ImplementationName .xml
• ImplementationName .xml layer file
• vmConfig_ ImplementationName .xml
• CustomNavigators_ ImplementationName .xml
• GridReports_ ImplementationName .xml
• TransactionDataGridConfig_ ImplementationName .xml
• TransactionRollupConfig_ ImplementationName .xml
Your customizations may extend to other Avocet files, so be sure to copy them as well.
2. If you have customized scripts, DLLs, or configuration files, be sure to copy and save them.

Files to download
This task lists which files to download and then shows how to download them from the Schlumberger
Integrated Solutions (SIS) Software Download Center.
From the Schlumberger Integrated Solutions (SIS) Software Download Center (SIS Software Download
Center), download the following zipped files:

• Avocet_2017.2_Full_Release.zip
This contains the Avocet content folders AvocetVM, AvocetWebService, and AppServer.
• Avocet_2017.2_InstallationUtility.zip
This contains the Avocet Installer components, including prerequisites and utilities.
• Avocet_2017.2_Prerequisites.zip
A convenience package, this zipped file contains the Avocet prerequisites, also contained in the
Avocet_2017.2_InstallationUtility.zip file. You can copy this package to multiple machines to lay
down the Avocet prerequisites.

Downloading the Files

1. Log into the SIS Software Download Center by selecting

https://www.sdc.oilfield.slb.com/SIS/Login.aspx.
2. Review and accept the terms of usage agreement if you have not done so already.
3. Review any updates at the Welcome Message page, and click Continue to display the Software
Download Center main page.

16 Avocet High Frequency Infrastructure

 4. Under Product Group Name, select Production. Then under the Product List\ Product Name
category, select Avocet Operations Technologies to display the available downloads.
5. Select the zipped file or files to download, and click Download.
The File Download Manager window opens. The download may start automatically. Otherwise,
follow the prompts, and set your download folder to a temporary location.

Before launching the Avocet Installer

This task shows the steps that you need to complete before you can launch the utility.
Be sure to save all custom configuration files to a separate folder so that they are not overwritten.
Download or obtain the Avocet_2017.2_Full_Release.zip file, and extract the Avocet content folders
to a temporary location.
Download or obtain the zipped Installer package from a secure location and copy it to your local drive
and temporary folder.

1. Extract the contents of the zipped Installer package to the temporary folder.
The file contents, which are contained in a single Installer folder, are displayed below:.

2. Copy the Avocet content folders you extracted from the Avocet_2017.2_Full_Release.zip file to
the Avocet subfolder that resides within the Installer folder.
The Installer\Avocet subfolder should display the contents as shown in the following screenshot:

17
 3. Paste your customized Avocet files to their respective subfolders in the Installer folder.
4. Optional. After you copy the Avocet content folders to the Avocet subfolder, you can copy and
move the Installer folder to different supported systems to install different components.
The following diagram outlines how the Avocet Installer deploys the Avocet content folders to a
specified deployment folder:

Launch the Avocet Installer

This task shows how to launch the installer.
To run the installation scripts, you will need PowerShell 3.0 or later.

1. Double-click InstallerUI.bat to launch the Avocet Installer utility.

By default, all standard options are selected.

18 Avocet High Frequency Infrastructure

2. Review the description of the installation options before launching any install routine.
3. Before clicking Install to launch an install routine, consider the following:
• The routine prompts you before installing any missing prerequisites. If you choose not to install
the prerequisite, the installation routine exits.
• The Avocet HF store and Schlumberger Licensing Software selections are installed in predefined
folders, ignoring the browse path specified under Deployment location.
• The Schlumberger Licensing Software selection is installed in a predefined folder, ignoring the
browse path specified under Deployment location.
• You must select the Terms & Conditions acceptance and the safety acknowledgment before the
Install option is enabled.
• If the installation routine encounters any error, the install stops at that point.

About the installation options

This topic summarizes the different installation options presented by the Installer and indicates which
ones require additional configuration after the installation is complete.
The Avocet Installer selections are shown below:

19
 Option Description Additional configuration

Avocet the AvocetVM folder and contents The Installer checks for and prompts you to install
any missing prerequisites, including
• Microsoft .NET Framework 4.6.1 or later
• Microsoft Visual C++ Redistributable for Visual
Studio 2015
• Microsoft ReportViewer 2010 Redistributable
• Microsoft ReportViewer 2012 Redistributable
• Microsoft Visual C++ 2008 Runtime Libraries (x64)
• Microsoft Visual C++ 2008 Runtime Libraries (x86)
• Microsoft Visual C++ 2010 Runtime Libraries (x64)
• Microsoft Visual C++ 2010 Runtime Libraries (x86)
• Microsoft Visual C++ 2012 Runtime Libraries (x64)
• Microsoft Visual C++ 2012 Runtime Libraries (x86)
• Microsoft Access Database Engine Redistributable
2010

ClickOnce for the ClickOnce deployment package Setup instructions are described herein.
AvocetClient

Avocet the Avocet application server, including the The Avocet application server requires Windows
AppServer scheduler process.The application server manages server 2012 R2. After installing the application server,
resource-intensive processes such as data loading, refer to the Help topic Application servers and process
allocations, and so forth. These processes can be groups for setup and configuration instructions.
served on separate systems, apart from the system
where the Avocet client resides.

Avocet HF Store The Avocet HF store is a proxy for the ApisHive, an If you have an existing Apis installation, the Avocet
OPC UA server that reads tag data from an OPC Installer upgrades your existing instance while
UA corporate historian. The Avocet HF store is maintaining your settings, modules, and items. It is
required for high frequency data collection. By recommended that you set the license path for the
default, the Avocet Installer creates an APIS install Avocet HF Store at the prompt, before you install it.
directory with its subfolders in the C:\Program Files The Avocet HF store instance or instances must be
path. It ignores the value specified in the paired with the Avocet HFI manager on the same
Deployment location field. system. Refer to the Help topic High Frequency
Infrastructure Manager Installation and Configuration.

Avocet HFI The High Frequency Infrastructure (HFI) manager The Avocet HF store instance requires the Avocet
manager is a new feature that supports the high frequency HFI Manager to be installed on the same system.
implementation. It polls the Avocet database for Refer to the Help topic High Frequency Infrastructure
changes related to high frequency data and Manager Installation and Configuration.
automatically synchronizes the update with the
Avocet HF store.

Schlumberger This is the 2017.1 version of the Schlumberger You manually configure the license utility after it is
Licensing Licensing utility. The Installer deploys it in its default installed.
Software location, ignoring the value in the Deployment
location field.

Studio and OFM The Studio plug-in is an integration component that If necessary, you can copy the extracted folder to the
plug-ins lets you load Avocet well bore and completion items target systems. Each plugin utility folder contains an
into Petrel for analysis.The two OFM plug-ins enable MSI installer file. You manually launch the MSI file
the export of forecast data from OFM to Avocet.You to install the plugin. Refer to the Help topics Avocet
can install both OFM plug-ins on the same system Integration: Studio and Avocet Integration: OFM.
if you have the corresponding OFM versions
installed. Each plugin folder is extracted to the path
specified in the Deployment location field.

Deployment the file path for installing the selected options. The
location Installer does not read the Deployment location
value for the Avocet HF Store, Schlumberger
Licensing, and plug-in selections

Terms and You must acknowledge both statements by selecting

Conditions and their check boxes.

20 Avocet High Frequency Infrastructure

 Option Description Additional configuration

Safety Critical
statements

Install the licensing software

This section discusses how to install the local license file and how to set up licensing on the server.
This particular topic provides an overview of the steps and some tips on configuring the server.
Subsequent topics provide step-by-step instructions.
The licensing software option launches a separate InstallShield wizard for Schlumberger Licensing
2017.1. Follow the on-screen instructions. You can accept the default selections.
As a result of a successful installation, a Schlumberger Licensing menu option is created in the Start
menu tree under the Schlumberger folder: Schlumberger Licensing 2017.1.
The install script generates an output message denoting the status of the license installation:

You can launch the Schlumberger Licensing window:

21
 Installing and configuring your license
To install and configure your license, review the Schlumberger Licensing User Guide that you can
access from the Help menu in the Schlumberger Licensing window.
As an example, to set a remote license server, enter the port number and fully qualified domain name
under Remote License Servers text box. Then click Add license server.

Be sure that your user and system variables are entered correctly. This will depend on the type of
license that you have selected.
As an example, the port number and domain name are entered as both user and system variables in
the Environment Variables dialog under the Advanced tab of your computer’s System Properties
definition.

Schlumberger Licensing can run on your local machine or on a license server. Therefore, use one of
the following workflows:
• To use a local license file, install and set up Schlumberger Licensing on your local machine.
• To use a server license file, install and set up Schlumberger Licensing on your licensing server
machine and on your local machine.

22 Avocet High Frequency Infrastructure

Set up a local license file
This task shows how to set up licensing with a local license file.

1. Save the license file to any folder on your local machine.

2. Choose Start > Programs > Schlumberger > Schlumberger Licensing nnnn.n >
Schlumberger Licensing.
The Schlumberger Licensing window opens.
3. Click Stop in the Local License Server section.
The license server stops.
4. Click Add License File.
The Open dialog opens.
5. Browse to the folder where you saved the license file.
6. Select the file and click Open.
7. Click Start.
A confirmation dialog box opens.
8. Click Apply.
9. Click OK to close the Schlumberger Licensing window.

Set up a licensing server

This task shows how to install setup the licensing server and then connect that server to your local
machine.
License server machine tasks
Perform these steps on the license server machine.

1. Save the license file to any folder.

2. Select Start > Programs > Schlumberger > Schlumberger Licensing 2017.1 > Schlumberger
Licensing from your Start menu.
The Schlumberger Licensing window opens.
3. Click Stop in the Local License Server section.
The license server stops.
4. Click Add License File.
The Open dialog opens.
5. Browse to the folder where you saved the license file.
6. Select the file and click Open.
7. Click Start.
A confirmation dialog opens.
8. Click Apply.
9. Click OK to close the Schlumberger Licensing window.

Local machine tasks

Perform the following steps on your local machine:

23
 1. Choose Start > Programs > Schlumberger > Schlumberger Licensing 2017.1 > Schlumberger
Licensing from your Start menu.
The Schlumberger Licensing window opens.
2. Enter your license server name in the All License Servers section, and then click Add License
Server.
3. Click Apply.
4. Click OK to close the Schlumberger Licensing window.

Install Avocet
This set of tasks shows how to install Avocet from the Installer, launch Avocet for the first time, and
prepare your new or existing database.

1. To deploy the AvocetVM folder to the target directory specified under Deployment location, do the
following:
a) Select Avocet.
b) Verify the deployment location.
c) Select the Terms & Conditions and safety acknowledgement check boxes.
d) Click Install.
Windows Powershell is displayed. You are prompted to install any prerequisites. If the deployment
is successful, you receive a message saying that the setup is finished and specifying the location
of the log file. You are returned to the directory path of the Installer folder.
The Avocet Installer should copy your customized files to their respective folders.
2. Verify that your customized files were successfully deployed to their respective folders.
3. Exit Windows Powershell by typing Exit at the directory prompt.

Initialize a fresh database

This task shows how to initialize a fresh database instance for your Avocet implementation.
Define your fresh database schema in Microsoft SQL Server or Oracle.
Refer to the Help topic Installation Reference for database setup guidelines.
You typically create and initialize a fresh database if this a first-time installation. If you are upgrading
from an earlier version of Avocet, you typically upgrade and initialize an existing database. Refer to
the Help topic Initialize an existing database.

1. Launch the Database Configuration Tools utility (DatabaseConfigTools.exe) from your

installationDirectory\AvocetVM\config folder.
2. In the Navigation Tree, click Application Initializer to open the Application Initializer screen.
3. Select the data source, and specify the connection string, as in the MS SQL Server example shown
below that uses SQL Server authentication:

24 Avocet High Frequency Infrastructure

 Note: You can choose to use Windows authentication in your connection string, provided
you have enabled it on your database server.

4. Click Next to go to the application options.

5. Specify the Implementation Name and Application ID values.
Although you can enter different values for each, to make a first-time implementation easier, enter
the same value for both the Implementation Name and Application ID fields.
6. Click the Add Layer drop-down list, make your layer selections, and click Add to add them to the
Layers list.
7. Verify the other selections.
8. Click Finish to initialize the fresh database.
The corresponding configuration files are generated under the installationDirectory\AvocetVM\config
file path:
• AppConfig_ ImplementationName .xml
• vmConfig_ ImplementationName .xml
• CustomNavigators_ ImplementationName .xml
• GridReports_ ImplementationName .xml
• TransactionDataGridConfig_ ImplementationName .xml
• TransactionRollupConfig_ ImplementationName .xml
The ImplementationName .xml layer file is stored under installationDirectory\AvocetVM\config\layer.
9. Verify that the layer hierarchy is maintained in your AppConfig_ ImplementationName .xml file,
as in this example:

25
 • <layers>
<layer>AVM</layer>
<layer>UnitSystem_Imperial</layer>
<layer>OG_STD</layer>
<layer>HF</layer>
<layer>YourImplementationLayer</layer>
</layers>

• Check that the corresponding vmConfig_layerName.xml extensions are listed, as in this

example:
<vmConfig id="YourImplementationLayer">
<base>vmConfigBase.xml</base>
<extension>vmConfig_OG_STD.xml</extension>
<extension>vmConfig_HF.xml</extension>
<extension>vmConfig_YourImplementationLayer.xml</extension>
</vmConfig>

If implementing publisher-subscriber replication or high frequency data collection, proceed to generate

replication triggers for your database instance.
Windows authentication and connection string syntax
Microsoft recommends using Windows authentication to connect to your database server.
If you choose Windows authentication as your connection method, you must first ensure that the
Windows authentication user account is defined on your database server. For example, in MS SQL
Server you can launch Microsoft SQL Server Management Studio, connect to your database server,
and verify the Windows user account under the Security > Logins subfolder:

You must include an Integrated Security attribute (or Trusted_Connection depending on your data
provider) in your connection string. You can refer to the following table, which is described in this
MSDN web page.

Data provider Connection string syntax attribute

SqlClient Integrated Security=true;

or
Integrated Security=SSPI;

Note: Integrated Security=SSPI; is recommended because Integrated Security=true;

generates an exception error when used with an OleDB provider.

OracleClient Integrated Security=yes;

OleDb
Integrated Security=SSPI;

Odbc Trusted_Connection=yes;

When constructing your connection string using Windows authentication, you can omit the user name
and password.

26 Avocet High Frequency Infrastructure

The following example shows an MS SQL server database connection string for Windows authentication:
<connectString>Network Library=DBMSSOCN;Data Source=DatabaseServer,1433;
Initial Catalog=DatabaseName;Integrated Security=SSPI;Application Name=AVM</connectString>
The next example shows an Oracle database connection string for Windows authentication:
<connectString>Data Source=MyOracleDB:1521;Integrated Security=yes;</connectString>

How to upgrade from Avocet 2014.1.n to Avocet 2017.1

This upgrade section assumes that you have an existing database that you wish to upgrade.
If you want to create a fresh database, see the topic Initialize a fresh database.

Note: If upgrading from an earlier Avocet version, refer to the Help topic Avocet upgrade
scenarios in the Installation Reference section.

Initialize an existing database

For an existing database, this section discusses how to execute the Upgrade Manager, upgrade to
the latest data types, and remove references to deprecated features.
To ensure that your existing database is up to date and compatible with the latest 2017.2 Avocet
implementation, you
• run Upgrade Manager to upgrade the database schema
• initialize the upgraded database with the latest type information
• remove references to deprecated features
• generate replication triggers if you have not already done so
Execute the Upgrade Manager
This topic discusses running the Avocet Upgrade Manager when you update an existing database so
that you can verify that you have the latest database scripts.
The Database Configuration Tools utility (DatabaseConfigTools.exe) offers the Upgrade Manager
feature. It scans your current database for existing scripts. It then lists the scripts that are
• not installed on your database
• available to be applied in the current upgrade session
Using the Upgrade Manager, you can
• select which scripts to initialize
• deselect scripts so that they do not run during the upgrade session
• display which script updates have been applied to the database
• mark scripts that you do not want to run
The Upgrade Manager lists scripts in chronological order, beginning with the earliest one that is not
installed on the database. You can run the scripts multiple times across upgrade sessions without
them failing the initialization process.

27
 Note: If you are upgrading from Avocet 2012.1 or Avocet 2012.1 SP 1, you have to first execute
specified preliminary upgrade scripts before continuing to the formal database upgrade. Refer
to the Help topic "Database upgrade from Avocet 2012.1 or Avocet 2012.1 SP 1" in the Installation
Reference section for more information.

Perform script upgrades

This task shows how to perform a script upgrade and how to tell if the script ran successfully, failed,
or was not run.

1. In the implementationFolder\AvocetVM folder, launch DatabaseConfigTools.exe.

2. From the Tree, select Upgrade Manager to display the Upgrade Manager pane.
By default, the Upgrade Manager displays the available upgrade scripts.

28 Avocet High Frequency Infrastructure

3. From the App Id drop-down list, select the application Id to connect to.
The application Id references the database you want to upgrade.
The Upgrade Manager displays the corresponding scripts having the updates that you can apply
to the target database. All scripts are selected by default.

Note: This list may differ from the default list depending how long it has been since your last
upgrade.

4. Review the selected scripts and de-select the ones you do not want to submit for upgrading in the
current session.

29
 5. In the ribbon toolbar, click Home > Upgrade to apply the scripts to your database and initialize the
selected ones.
The upgrade status of each script is displayed in the right-hand side panel. For example, a successful
upgrade is noted with a green checkmark as in the following example:

When a selected script fails the upgrade, it is noted with an X mark against a red background, as
shown in this example taken from a different upgrade session:

You can click on the X to view the accompanying error message. An example error message is
shown below:

You can export these errors to an Excel spreadsheet by clicking the Export Errors to Excel button
at the bottom of the panel.

30 Avocet High Frequency Infrastructure

 Any unselected scripts that are part of the upgrade session are marked with an X against a black
background. The flyout message Not Run is displayed when the mouse pointer hovers over the X.

To summarize, scripts that are included in an upgrade session can have a status of
• success
• failed
• not run

Show applied updates

This task shows how you can view the scripts that have run successfully against a database or that
have been designated Never Run and have been excluded from the upgraded list.

1. In the Upgrade Manager, select an application Id (database) from the database drop-down list.
2. Click Home > Show Applied Updates in the ribbon toolbar.
The scripts that have been executed against the database or that have been designated Never
Run are listed in the left-hand panel, as shown in this example:

31
 Any upgrade or other action does not affect the scripts that have already been applied to the
database.
3. Deselect Show Applied Updates to return to the list of available upgrade scripts.

Never Run

32 Avocet High Frequency Infrastructure

 This task shows how to designate scripts that you do not want to run during the upgrade session. For
example, you may not want to run a script that overrides or interferes with a custom script which you
have created.

Note: Be careful which script or scripts you designate as Never Run because they are removed
from the list of available upgrade scripts for the application ID.

To mark a script as Never Run, do the following:

1. In the list of scripts to upgrade, select the script you do not want to execute against the application
ID.
2. In the ribbon toolbar, choose Home > Never Run.
The script designated Never Run is removed from the list of scripts to upgrade for the specific
application ID and database. When you select Home > Show Applied Updates, the Never Run
script is displayed at the bottom of the list of scripts that have been applied to the database.
3. For future reference, note the script or scripts that you have designated as Never Run.
4. If in a later upgrade session you decide to run the upgrade script, do the following:
a) Choose Home > Show Applied Updates, and scroll to the upgrade script you designated as
Never Run.
b) Select the script, and click Home > Upgrade.
The script is executed against the database. In the status list on the right-hand panel, scroll to the
bottom of the list to verify that the script upgrade was successful.

Troubleshooting: query for upgrade scripts

You can use a SQL query to search your database for upgrade scripts. For the upgrade to succeed,
be mindful that column names in each table must be unique.
Each upgrade script is identified in the database VERSION table by the type DB_UPG_VER (database
upgrade version), with each script having its unique version string identifier. You can use the following
SQL database query to search for the upgrade scripts in the database: SELECT * FROM VERSION
WHERE VER_TYPE = 'DB_UPG_VER'. The query result looks similar to the following example:

Some script upgrades can fail because of errors similar to the following:
• Column names in each table must be unique. Column name 'CHAR11' in table 'ITEM_EVENT_EXT'
is specified more than once.
• Column names in each table must be unique. Column name 'VAL61' in table 'ITEM_EVENT_EXT'
is specified more than once.
If the types of errors listed above appear during the upgrade process, it means that the columns already
exist in the specified table.You can contact the Schlumberger deployment team to address any issues.
Initialize the existing database with the latest definitions from the type system
This task shows how to initialize your existing database with the latest definitions from the type system.

1. Launch the Avocet Configuration Tools utility (configTools.exe).

33
 2. Log into your application ID.
3. Access the Database Initializer screen (Database Tools > Database Initializer).
4. Verify that the layers you want to initialize are marked for import.

5. Select Home > Tools > Initialize.

The corresponding configuration files are generated.

After initializing your database with the latest type definitions, you should
• remove references to deprecated features
• generate replication triggers if you haven't done so
Remove references to deprecated features
Upgrade users must delete certain configuration files and remove tags that point to deprecated features.
Effective Avocet 2017.1 onwards, the Avocet UA Server and Visualization Designer have been
deprecated. Consequently, as an upgrade user, you should remove configuration files and settings
that point to these features.

1. In the installationDirectory\AvocetVM\Config subfolder, remove the following files:

• DbInfo_OPCUAServer.xml
• vmConfig_OPCUAServer.xml

2. In the installationDirectory\AvocetVM\Config\Layer subfolder, remove the OPCUAServer.xml layer

file.
3. In the installationDirectory\AvocetVM implementation folder, remove the
Slb.Avocet.OPCUAServerObjects.dll file.
4. Open your AppConfig_ProjectLayer.xml file, remove the following entries, and save the file:
• Dbinfo_OPCUAServer.xml extension from the <dbInfo> node
• vmConfig_OPCUAServer.xml extension from the <vmConfig> node
• OPCUAServer.xml layer file from the <layer> node

5. Open your vmConfig_ProjectLayer.xml file, remove the following entries, and save the file:
• node type definition for TreeNode.Visualization
• corresponding screen configuration ID
Slb.Avocet.OPCUA.Client.Screens.VisualizationWellOverview

34 Avocet High Frequency Infrastructure

Generate replication triggers
This task shows how to generate replication triggers so that the Avocet database can process high
frequency data or receive updates from field databases in Avocet replication scenarios.
To generate replication triggers, follow these steps:

1. Open the Avocet Configuration Tools utility (ConfigTools.exe), and in the Navigation Tree, access
Replication > Trigger Manager to open the Trigger Manager screen.
2. Check whether the Home > Replication Triggers > Create Publisher Database option is enabled.
If it is greyed out, go to step 3. Otherwise, click Create Publisher Database.
The publisher database is created.
3. Click Create Replication Triggers to generate the SQL Server replication triggers, as shown in
this screen excerpt:

Launch the Avocet executable for the first time

For each Avocet version, when you first launch an Avocet executable that requires you to log into a
database, you must accept the Terms and Conditions statement before you can proceed to log in.
Accepting the statement is a one-time action for each Avocet version.
When first launching AvocetVM.exe or ConfigTools.exe , you must accept the Terms and Conditions
statement that displays before you can log into the database.

1. Double-click AvocetVM.exe or ConfigTools.exe.

The Terms and Conditions statement is displayed in the foreground of the Login dialog.
2. Review the statement, and click Accept.
You are able to log into the database. You do not have to repeat this task for the current Avocet
version.

35
Microsoft ClickOnce
Avocet is a Microsoft Windows Presentation Foundation & Windows Forms application, which you can
publish using ClickOnce technology.
ClickOnce is a deployment technology that allows you to create a self-updating Avocet deployment
that can be installed and run with minimal user interaction.
You can publish a ClickOnce application in two different ways: from a web page or from a network file
share. A ClickOnce application can be installed on an end-user's computer and be run locally even
when the computer is offline, or it can be run in an online-only mode without permanently installing
anything on the end user's computer.
An Avocet ClickOnce deployment is self-updating. It can check for newer versions as they become
available and automatically replace any updated files. The deployment can specify the update behavior.
A network administrator can also control update strategies, for example, marking an update as
mandatory. Updates can also be rolled back to a previous version by the end user or by an administrator.
An Avocet ClickOnce deployment is inherently isolated; therefore, installing or running an Avocet
ClickOnce deployment cannot break existing applications. Avocet is completely self-contained; each
application is installed to and run from a secure per-user, per-application cache.
The ClickOnce deployment package consists of files that support the deployment of a current Avocet
implementation from a shared folder on a server system to multiple client workstations.

1 Using the Avocet Installer utility, install the ClickOnce deployment package, including the AvocetVM content, in a test
folder on a server system.

2 To publish the ClickOnce content from a production environment, create a shared folder either through a network file
share or through an IIS web server with an application folder. Client workstations can access the Avocet content from
the shared folder.

3 Copy the contents of the ClickOnce deployment folder from the test folder to the shared folder in the production
environment.

4 Maintain product and configuration updates in the ClickOnce deployment. Launch the Installer to update the ClickOnce
content in the test folder, and copy the updated content to the shared folder in the production environment.

Install ClickOnce (new install)

This task tells how to install the ClickOnce package on a system where the ClickOnce package has
not been deployed previously.
All systems where ClickOnce is extracted and deployed must have the .NET 4.5.2 runtime already
installed on them.
As a precaution, copy any custom Avocet configuration files and save them to a temporary location.
Before launching the Avocet Installer, make the requisite changes to the <GenerateBootstrapper>
stanza of the COgenV4_x64.xml or COgenV4_x86.xml file under the Installer\BuildProjects file path
of your Avocet Installer directory. Refer to Edit the COgenV4_xNN project file.
If you have removed the Oracle Instant Client, be sure that have deleted certain executables and
assembly files (dlls) before building your ClickOnce deployment. See the Help topic "Removing the
Oracle Instant Client" in the Installation Reference section.

1. Copy the AvocetVM folder of the Avocet installation package and paste it to the Avocet subfolder
of your Installer directory, as indicated in the following screenshot:

36 Avocet High Frequency Infrastructure

2. Copy your custom Avocet configuration files to their corresponding AvocetVM subfolders under
Installer > Avocet > AvocetVM.
3. Double-click InstallerUI.bat to launch the Avocet Installer utility.
4. Under Standard options, de-select all options except for ClickOnce for AvocetClient.
The ClickOnce installation includes the AvocetVM folder and its contents.
5. Under Deployment location, click Browse to locate and select your deployment folder.
6. Select the check boxes to accept the terms and conditions and the safety acknowledgment.
7. Click Install.
Windows Powershell is displayed. You are prompted to install any prerequisites. If the deployment
is successful, you receive a message saying that the Avocet ClickOnce deployment (x64) and (x86)
setup is finished and specifying the location of the log file. You are returned to the directory path
of the Installer folder.
8. Exit Windows Powershell by typing Exit at the directory prompt.
A ClickOnce container folder is created under the specified deployment folder. It contains two
subfolders: Publish_x64 and Publish_x86. The Publish subfolders contain the content that is
made available to Avocet client systems. The contents of each folder are the same, but designed
for 64-bit and 32-bit client systems respectively.

Edit the COgenV4_xNN project file

The COgenV4_x64.proj or COgenV4_x86.proj file builds and deploys the ClickOnce deployment
package. You should modify it to prevent certain errors from occurring when client workstations try to
download the package.

37
 You will need to have the URL by which the client workstation connects with the ClickOnce deployment
server.

Note: If you are updating the project file after the initial ClickOnce installation, go to step 8.

1. Go to the Installer folder of your Avocet Installer installation path.

2. Access the BuildProjects subfolder (Installer > BuildProjects).
3. Open the appropriate project file (COgenV4_x64.proj or COgenV4_x86.proj) in a text editor, such
as Notepad++.
4. Locate the two <GenerateBootstrapper> stanzas just below the <!--Generate the setup bootstrapper
--> comment.
5. In each stanza, change the ComponentsLocation tag to "Absolute": ComponentsLocation="Absolute".
6. Below the ComponentsLocation tag, add the ComponentsUrl tag to each stanza, and set it equal
to the address by which client workstation connects with ClickOnce deployment server.
For example, you could enter "http://localhost/ClickOnce" :
ComponentsLocation="Absolute"
ComponentsUrl="http://localhost/ClickOnce"

Note: Specify the http protocol for the ComponentsUrl tag. Do not enter https here. At the
file share site or IIS web server, you can add the https binding.

7. Save the updated project file.

8. If you update the project file--for example, change the URL--after the initial ClickOnce installation
and deployment, then do the following:
a) Save the project file.
b) Delete the Publish_xNN subfolders from the ClickOnce installation directory.
c) Using the Avocet Installer, reinstall the ClickOnce for Avocet client package.
d) Update your file share or web server settings as needed, and restart the corresponding process
to initialize the changes.

ClickOnce publication site

To enable clients to access the published files, you first create a location in the production environment
where they can be shared.
You can create a
• network share
• web server with an application folder
Network share
If your network security allows you to do so in your work environment, you can set up a network file
sharing site to deploy the ClickOnce files to clients.
You can create a network shared folder using the Create a Shared Folder Wizard or the command
line. When creating your shared folder, make sure that you include the Publish_x nn subfolder in the
share.
Create a network share using the Wizard
This task shows how to create a network file sharing site using the Shared Folder Wizard.

1. On your Windows system, access the Start > Administrative Tools > Computer Management
> System Tools node, and double-click the Shared Folders entry.
2. Right-click the Shares folder to display the fly-out menu, and select New Share… .

38 Avocet High Frequency Infrastructure

 The Create A Shared Folder Wizard is displayed.
3. Click Next, and follow the prompts.

Note: Administrator privilege is required to install prerequisites on client workstations.

4. Specify the permissions on the Shared Folder Permissions pane, and click Finish.
The shared folder is created.
5. Right click the newly created share, and choose Properties from the flyout menu.
The Properties tab is displayed.
6. Access the Share Permissions and Security tabs to verify or update permissions, and click OK
when done.
7. Verify your Windows Firewall settings to ensure that they enable the correct levels of access.
8. Copy the contents of the Publish_x nn folder to the specified network share.
Depending on network and security settings, your file share link will be similar to
\\serverName\DisplayName. Remote clients can access the Avocet content to deploy and update
it on their systems.

Create a network share (command line)

This task shows how to create a network file sharing site using the command line.

1. Create the folder to be shared on the appropriate drive. Note its physical path.
2. Go to Start > All Programs > Accessories, and right-click Command Prompt to display the fly-out
menu.
3. Click Run as Administrator to display the Command Prompt window.
4. At the prompt, enter
net share <sharename=drive:path>
where sharename is the network name of the shared folder and drive:path is the absolute physical
path of the shared folder: for example, ClickOnce=C:\AvocetDeployment\ClickOnce\Publish_xNN.

Note: You can type net share ? to display help for the net share syntax.

5. Copy the contents of the Publish_x nn folder to the specified network share.
Depending on network and security settings, your file share link will be similar to
\\serverName\DisplayName. Remote clients can access the Avocet content to deploy and update
it on their systems.

Web server application

This topic provides guidelines for setting up an Internet Information Services (IIS) web server application
for ClickOnce deployment.
You can refer to the IIS setup instructions in the Help topics Application servers and process groups
or Web Services API. You can choose to install the appropriate version of IIS (8.0 or 8.5) on Windows
2008 server or Windows 2012 server.
The referenced topics depict one approach for setting up a web server application. They are intended
as examples only. Your approach may differ depending on your network structure, security
considerations, firewall rules, and so forth.
When setting up your connection tree in IIS, you do not have to copy or extract folder contents. The
ClickOnce installation routine sets the directory structure.

39
 Note: For the ClickOnce web server application, you will need to edit the IIS > Request Filtering
rules to ensure all filtering options are enabled.

Set up an IIS web server application for ClickOnce deployment

This task shows how to add an IIS web server application for ClickOnce deployment.
You have already defined your IIS web server.
See the Help topics Application servers and process groups or Web Services API for setup instructions.
Your IIS settings, especially your custom IIS settings, are saved to a web.config file that is created
in the physical path of the IIS web server application of your ClickOnce deployment, as shown in the
following screenshots:

Note: Do NOT delete or manually modify the web.config file outside the IIS environment.
Otherwise, you have to recreate your settings and customizations within IIS.

1. Launch IIS, and in the connection tree, right-click on the Sites > Default Web Site node of your
server to display the flyout menu.
2. Choose Add Application... .
The Add Application dialog is displayed.
3. In the Add Application dialog, complete the following fields:

40 Avocet High Frequency Infrastructure

 Field Description

Alias Enter the display name of the deployment: for example, ClickOnce.

Application pool To select an application pool other than the default value, click the Select… button to choose
from the Application Pool drop-down list.

Physical path Specify the physical path to include the Publish_x nn subfolder: for example,
C:\rootDirectory\Publish_x nn.

Refer to the following example screenshot:

This connection uses pass-through authentication.

4. Click OK.
In the connection tree, your application node definition will look similar to the following example:

The content view of the ClickOnce application will look similar to the following:

41
 5. Enable Windows authentication (IIS > Authentication) and directory browsing (IIS > Directory
Browsing).
6. Double-click IIS > Request Filtering to display the Request Fitlering pane.
7. Under the Actions column, choose Edit Feature Settings... .
The Edit Request Filtering Settings dialog is displayed.
8. Under the General heading, verify that all filtering options are selected, as in the following screenshot:

9. Click OK.

42 Avocet High Frequency Infrastructure

 Configuration settings are saved to the web.config file residing in the physical path of your application
folder:
configuration>
<system.webServer>
<defaultDocument>
<files>
<add value="avocet.htm" />
</files>
</defaultDocument>
<security>
<requestFiltering allowDoubleEscaping=
"true" />
</security>
</system.webServer>
</configuration>

10. Continue next to set the default launch document, avocet.htm.

Set the default launch document

This task shows how to set the Avocet.htm file as the default launch document for ClickOnce clients.
You must set Avocet.htm file as the default launch document for ClickOnce.

1. Choose IIS > Default Document to display the Default Document panel, and choose Add… from
the Actions column to add avocet.htm as the default launch document.

2. Click OK, and ensure that Avocet.htm is first in the list.

3. Restart the web server (Actions > Manage Server > Restart) to initialize the changes.
4. Verify that the Avocet.htm launch page displays on the local system:
a) In the connection tree, select your ClickOnce application node.
b) Under the Actions, select Manage Application and choose your browse option (http or https),
depending on your security settings and bindings.
The Avocet.htm launch page is displayed, as in this example:

43
Set the security bindings
For your ClickOnce web server application, you can enable the HTTPS binding.
The ComponentsUrl tag in the COgenV4_x NN.proj project file must be specified with the http protocol.

1. In the IIS connection tree, select the Default Web Site node.
2. Under the Actions column, select Edit Site > Bindings... to open the Site Bindings dialog.
3. Choose Add... to open the Edit Site Binding dialog, and complete the following:
a) Choose https in the Type drop-down list.
b) Leave the IP address as All Unassigned.
c) Specify a port number. You can use the default 443 if it is not is use.
d) Choose the machine certificate as the SSL certificate selection.
e) Click OK to return to the Site Bindings dialog.
f) Click Close.
4. In the connection tree, choose your ClickOnce application folder, and then select IIS > SSL
Settings.
5. In the SSL Settings pane, make sure that the Require SSL check box is deselected.
6. Under the Actions column, choose Manage Application > Advanced Settings... to open the
Advanced Settings dialog.
7. Next to Enabled Protocols, enter http, and click OK.

Client workstations can access the ClickOnce deployment site using either http or https protocol. If
using https protocol, then in the URL string the client must specify the server name as listed in the
machine certificate.
Install the ClickOnce deployment on client workstations
In the production environment of a ClickOnce deployment, client workstations connect to an Avocet
production database through a network share or web server application folder.
The Avocet.htm launch document gives clients the option to install the Avocet runtime prerequisites.

44 Avocet High Frequency Infrastructure

Clients should install the runtime prerequisites that are supplied with the Avocet deployment package
in the network share or web server application folder. These prerequisites are customized for Avocet.
Clients should not install the runtime redistributable packages from Microsoft.
The customized Avocet prerequisites include, but are not limited to, the following:
• Microsoft Visual C++ Redistributable for Visual Studio 2015
• Microsoft .NET Framework 4.5.2
• Microsoft ReportViewer 2010 Redistributable
• Microsoft ReportViewer 2012 Redistributable
• Microsoft Visual C++ 2008 Runtime Libraries (x64)
• Microsoft Visual C++ 2008 Runtime Libraries (x86)
• Microsoft Visual C++ 2010 Runtime Libraries (x64)
• Microsoft Visual C++ 2010 Runtime Libraries (x86)
• Microsoft Visual C++ 2012 Runtime Libraries (x64)
• Microsoft Visual C++ 2012 Runtime Libraries (x86)
You must have administrative privileges on the client workstation to install the prerequisites.
Use Internet Explorer as your browser for accessing the Avocet ClickOnce deployment.
Have your login credentials ready to log into the network share or web server.
Determine whether you, as the client, access the Avocet ClickOnce deployment from a network share
folder or from an IIS web server application folder.
To install Avocet on end-user workstations:

1. Browse to the network share or web server application folder:

• If accessing a network share, then launch Remote Desktop Connection, enter the name of the
computer and your login credentials to connect to the share, and then double-click the Avocet.htm
file.
• If accessing the web server application folder, enter the URL in Internet Explorer (http:// or
https://serverHostName:portNumber/applicationName) and then enter your login credentials at
the prompt.
The Avocet launch page is displayed:

45
 2. If this is a first-time installation on the workstation, select the 32-bit or 64-bit installation prerequisite
option, and follow the prompts.

Note: The Install Prerequisites (64-bit) option installs all components, including the 32-bit
runtime files.
During the installation of the runtime libraries, you may be asked to close certain Microsoft
applications. Otherwise a reboot is required. To avoid a reboot, close any open Microsoft
Word, Visual Basic, or Internet Explorer instances.

a) Execute the Run command to start the Avocet Setup for the selected option.
b) For each prerequisite, accept the license agreement, and click Install and follow any prompts.
3. Click the

button to start the Avocet implementation process.

4. Click Install to install Avocet on the client.
The application is installed in C:\Documents and Settings\<User_Name>\Local
Settings\Apps\2.0\<HexKey>\<HexKey>\AvocetVM.
You can also find the path of the installation in the About box of the application.
5. Once the installation is complete, the application is launched, and the Login dialog displays.
You can proceed to configure your Avocet implementation.
An Avocet icon is installed on the Desktop or an Avocet entry is added to the Start menu.

Launch the application on client workstations

The client can launch Avocet from either a desktop icon or the Start menu.

1. From the Start menu choose the Avocet entry, or from the Desktop choose the Avocet icon.
The application will launch and display the Login dialog.
2. Enter the login credentials and choose other options as required.

46 Avocet High Frequency Infrastructure

3. Click Login.
The application verifies the credentials and displays the interface.

Remove the application from client workstations

This task shows how to remove Avocet that has been installed on client workstations using the
ClickOnce deployment.

1. From the Start menu, select Control Panel > Add/Remove Programs.
2. Right-click Avocet from the list of installed programs, and choose Uninstall.
A prompt dialog is displayed.
3. Select Remove the application from this computer.
4. Click OK to continue uninstalling the program.

Update the ClickOnce deployment

If you make global configuration changes to your Avocet ClickOnce implementation or if you have
received new files from Schlumberger because of product updates, you will need to redeploy your
Avocet ClickOnce implementation. You can do so by relaunching the Avocet Installer utility.
As a safeguard, always back up your custom configuration files and save them to a temporary location.
When you recreate a published file set, save the existing Publish_xNN folder(s) to a temporary location
and let the Avocet Installer utility generate the new folders.
You update your published ClickOnce client files whenever you
• make changes to your Avocet configuration on the ClickOnce server
• receive new files from Schlumberger because of product updates
You perform these updates by rerunning the Avocet Installer utility and re-creating your ClickOnce
published output by repeating the ClickOnce for AvocetClient installation option. The ClickOnce
client then downloads the updated files.
To update your ClickOnce package on the ClickOnce server, follow these steps:

1. Move your current DeploymentFolder\ClickOnce\Publish_xNN folder and save it to a temporary

location.

By repeating the ClickOnce for AvocetClient installation option, you are creating an updated
Publish_xNN folder. Moving the existing Publish_xNN folder ensures that any outdated files are
removed.
2. Copy the updated content and any custom configuration files to their appropriate locations in the
Avocet folder under the Installer directory, as suggested by this screenshot:

3. Rerun the Avocet Installer utility by double-clicking InstallerUI.bat.

4. In the Avocet Installer wizard, select only ClickOnce for AvocetClient under the Standard options.

47
 5. Under Deployment location, click Browse to locate the deployment folder where your ClickOnce
files reside.
6. Select the check boxes to accept the terms and conditions and the safety acknowledgment.
7. Click Install.
The Windows PowerShell window is launched, and updated Publish_xNN subfolders are created
in the deployment folder.
8. Compare the new Publish_xNN subfolders against the previous ones to note any changes.
9. Review the updated content and custom configuration files under the AvocetVM subfolder to ensure
that no errors exist.
10. After checking for errors, point the network file share or IIS web server application in the production
environment to the updated Avocet ClickOnce deployment package.
The latest updates are available to the ClickOnce clients for download.

Note: ClickOnce clients should also back up custom configuration files before downloading
the latest content.

ClickOnce troubleshooting guidelines

This topic provides troubleshooting suggestions for different issues you might encounter.
Issue Suggestion

Client unable to install Avocet from IIS web server application If the Application Install dialog does not launch, then check
folder your web browser's security settings.

Client unable to install Avocet from network share Browse to the sharedFolder \Publish_xnn\AvocetVM folder,
and click the AvocetVM.application manifest file.

The Application Install dialog is displayed.

Click Install.

Client unable to install prerequisites Verify that the COgenV4_xNN.proj file's ComponentsUrl
and ComponentsLocation attributes are updated.

Other troubleshooting considerations include the following:

48 Avocet High Frequency Infrastructure

 • When copying the ClickOnce content between directories, be careful not to duplicate .dll files in the
Publish_xNN folder. Duplicate .dll files, even a single one, can create issues with Avocet.
• Do not modify the files in the Publish_xNN folder unless you are updating to a newer release or
adding custom files.

Install the AppServer

You install the application server on a Windows server 2012 R2 system.
You should have already installed Avocet. Before installing the application server, it is recommended
that you define in Avocet an LDAP user with pass-through authentication. The Avocet web services
interface that supports the application server requires pass-through authentication.
Refer to the Help topic Application servers and process groups for configuration details.
The application server requires a secure (https) Avocet web services interface, which the Avocet
Installer deploys along with a supporting Internet Information Services (IIS) 8.0 or 8.5 server that
connects with the application server via the web services interface. Upon completion of the install
routine, you are prompted whether you want to assign the domain computer certificate to the IIS https
binding. If you have custom or third-party certificates, you must configure the https binding manually
in the IIS console.

1. To install the application server to the target directory specified under Deployment location, do the
following:
a) Select AppServer
b) Verify the deployment location.
c) Select the Terms & Conditions and safety acknowledgement check boxes.
d) Click Install.
A prompt is displayed, asking for the port and path to the Schlumberger License server.
2. Specify the port number, host, and file path to the Schlumberger License server.
The default port number is 27000.
Windows Powershell is displayed. You are prompted to install any prerequisites.
3. At the Avocet AppServer Setup prompt, click Yes to attach your domain computer certificate to the
IIS https binding.
If you have third-party or custom certificates, click No. You must manually configure the IIS https
binding with the certificate.
4. Exit Windows Powershell by typing Exit at the directory prompt.

If you have not already done so, define an LDAP user with pass-through authentication.
You must edit the DeploymentFolder\AppServer\Web.config file.
Refer to the Application servers and process groups Help topic for configuration information.

Install Petrel Studio Plug-in 2015

The Petrel Studio Plug-in 2015 is compatible with Studio 2015.4 or Studio 2015.5.
Refer to the Help topic Avocet Integration: Studio for prerequisites.

1. To deploy the Petrel Studio Plug-in 2015 to the target directory specified under Deployment location,
do the following:
a) Under Extended options, select Petrel Studio Plug-in 2015.
b) Verify the deployment location.
c) Select the Terms & Conditions and safety acknowledgement check boxes.

49
 d) Click Install.
Windows Powershell is displayed. You are prompted to install any prerequisites. If the deployment
is successful, you receive a message saying that the setup is finished and specifying the location
of the log file. You are returned to the directory path of the Installer folder.
2. Refer to the Help topic Avocet Integration: Studio to complete the installation and configuration.

Install OFM Plug-in 2014.1, 2016.1, or both

The OFM Plug-in 2014.1 or OFM Plug-in 2016.1 enables the export of the flow rate forecast of a
completion that is defined in an OilField Manager (OFM) project to an Avocet database. The OFM
Plug-in 2014.1 has been tested against OFM versions 2014.1 and 2014.1.3. The OFM Plug-in 2016.1
has been tested against OFM version 2016.1.
OFM Plug-in 2014.1 and OFM Plug-in 2016.1 require Avocet 2017.2 and the corresponding OFM
version (2014.1, 2014.1.3, and/or 2016.1).
The Avocet and OFM instances do not have to be installed on the same system. If they exist on
separate systems, then you can first deploy the OFM Plug-in to the system where Avocet is installed
and generate the installer package.You can then copy the installer package to the system where OFM
resides and launch the installation routine.

Note: You can install both OFM Plug-in 2014.1 and OFM Plug-in 2016.1 on the same system
running Avocet 2017.2.Your configuration must also have the compatible OFM versions (2014.n
and 2016.1) installed on the same or different systems. As a best practice, both OFM integrations
should connect with the identical Avocet database.

Refer to the Help topic Avocet Integration: Oilfield Manager Projects for a complete list of prerequisites.

1. To deploy the OFM Plug-in 2014.1 or OFM Plug-in 2016.1 to the target directory specified under
Deployment location, do the following:
a) Under Extended options, select OFM Plug-in 2014.1 or OFM Plug-in 2016.1. If installing both
plug-ins, select OFM Plug-in 2014.1 and OFM Plug-in 2016.1.
b) Verify the deployment location.
c) Select the Terms & Conditions and safety acknowledgement check boxes.
d) Click Install.
Windows Powershell is displayed. You are prompted to install any prerequisites. If the deployment
is successful, you receive a message saying that the setup is finished and specifying the location
of the log file. You are returned to the directory path of the Installer folder.
2. Refer to the Help topic Avocet Integration: Oilfield Manager Projects to complete the installation
and configuration.

Troubleshooting installation issues

This section provides guidelines for troubleshooting general installation issues.

Installation script does not run

This task shows how to resolve an issue that might occur when the PowerShell script is not signed.

1. Launch the Windows PowerShell in administrator mode.

2. Change directory (cd) to the directory path of the Installer folder.
If any folder names in the path contain spaces, enclose the entire file path in quotation marks.
3. Enter Get-ExecutionPolicy at the directory prompt:

50 Avocet High Frequency Infrastructure

 If the message RemoteSigned is not returned, then you need to change the execution policy.
4. To change the execution policy, in the Windows Powershell enter the Set-ExecutionPolicy
RemoteSigned command at the directory prompt:
PS C:\AvocetInstaller2016\Installer>
Set-ExecutionPolicy RemoteSigned

Execution Policy Change

The execution policy helps protect you from scripts that you do not trust.
Changing the execution policy might expose you to the security risks
described in the about_Execution_Policies help topic at
http://go.microsoft.com/fwlink/?LinkID=135170.
Do you want to change the execution policy?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
PS C:\AvocetInstaller2016\Installer>
A message displays that explains the consequences of the execution policy change.
5. Type Y at the prompt to accept the policy change.
You are returned to the directory prompt.

Post-installation considerations
After you install your Avocet components and define your project layer files, you can specify the
production day for collecting and aggregating data and a timeout interval for the Avocet client.
You define these parameters in the AppConfig_ProjectLayer .xml file of your implementation.

Production day start

At the initial implementation or deployment of a project, you (as administrator) can specify a start and
an end time for an actual production day in which to collect and aggregate data.
By default, daily allocation calculations begin at an inclusive start time of 12:00 PM (00:00:00) and
conclude at an exclusive end time of 12:00 PM (00:00:00).

Note: Because the end time is exclusive, the actual end time is 11:59:59 PM (23:59:59).

The calculations return the values for the specific day, not for individual hours. Monthly allocation
calculations use similar inclusive start times and exclusive end times. They start at 12:00 PM (00:00:00)
of the first day of the month and end at 12:00 PM (00:00:00) of the last day of the month. The
calculations return the values for the specific month.
The production day itself extends for 24 hours. When you specify a start time for the production day,
the system assumes the end time of the production day is 24 hours later. For example, if the production
day's inclusive start time is 6:00 AM (06:00:00), then the production day's exclusive end time is 6:00
AM (06:00:00) of the following day.

Note: The actual start and end times in this example are 6:00 AM (06:00:00) and 5:59 AM
(05:59:59).

In allocation processing, the default daily calculations are distinguished from the production day
calculations. The production day calculation values are aggregated for the specified production day
period, which excludes part of the current day and extends to the following day.

51
 In the example outlined above, the production day calculations ignore values collected before 06:00:00
of the current day, as they belong to the previous production day.
You enable a production day data collection period by specifying the start time in the AppConfig_
ProjectLayer .xml.

Specify production day start

As an administrator, you can define a production day by adding a <prodDayStart> tag to your
AppConfig_ ProjectLayer .xml file.
You should specify the production day at the beginning of your project implementation. As a rule of
thumb, do not define or change the production day after you have implemented your project.

1. In your AppConfig_ ProjectLayer .xml file, locate the section containing the application ID of the
database to which you are connecting.
2. At an appropriate level in the XML hierarchy, add the <prodDayStart> tag, and specify a numerical
value between 00:00:00 and 23:59:59.
<prodDayStart>06:00:00</prodDayStart>
<firstDayOfWeek>Monday</firstDayOfWeek>
<fileLoaderConfig>LoaderConfig.xml</fileLoaderConfig>
<downtimeLevels>3</downtimeLevels>
<orgUnitLevels>4</orgUnitLevels>
The system automatically defaults to an exclusive end time that is set 24 hours after the
<prodDayStart> time.
3. Save theAppConfig_ ProjectLayer .xml file.
4. Start or restart the Avocet application to initialize the change.
The allocation process uses the production day start value to calculate and aggregate data for the
defined production day.

Specify a timeout interval for the Avocet client

You can specify a timeout interval that determines when your Avocet desktop or web client will shut
down after a period of inactivity. Actions such as mouse clicks and behind-the-scenes Avocet processes
are considered activity.
By specifying timeout intervals so that Avocet clients shut down after a period of inactivity, you can
free up licenses from inactive users. Thus you make them available to other users.

1. Open your project's AppConfig_projectLayer.xml file.

52 Avocet High Frequency Infrastructure

 2. Locate the stanza where your application ID is defined.
3. Enter the following node <inactivityLogout>.
4. Just below the <inactivityLogout>, enter the following elements:
• <timeoutInMinutes> </timeoutInMinutes>
• <warningInMinutes> </warningInMinutes>
Your code block should display as shown in the following example having sample values:
<inactivityLogout>
<timeoutInMinutes> 10 </timeoutInMinutes>
<warningInMinutes> 1 </warningInMinutes>
</inactivityLogout>
The element <timeoutInMinutes> denotes the timeout interval after which the client shuts down.
The element <warningInMinutes> indicates the time that you are alerted before the shutdown. In
the above example, the system will shut down after 10 minutes of inactivity. You receive a warning
prompt one minute before the shutdown occurs.
When Avocet shuts down, the accompanying license is released and becomes available to another
user.
5. Save your project's AppConfig_projectLayer.xml file.
6. Restart the Avocet client.
A modal window displays a warning message at the designated interval before the shutdown occurs.
When the timeout interval is reached, you are prompted to log in again or to exit the application.

Define links to custom screen-level help files

You can link your custom help files to Avocet screens. This task shows how to define the links to the
custom screen-level help files and override the existing help link.

Note: See the Release Notes for instructions on linking to the standard Avocet Help that is
packaged with the installation.

You can link your custom help files to Avocet screens through the Home > Navigation > Add Context
Help Link ribbon toolbar option. Your custom help file overrides the existing help link. You can store
the help files locally, or you can link to external sites, such as Sharepoint. You can modify the
AppConfig_xxx.xml of an existing database to enable the context help feature. You invoke the help
content from the Help icon on the screen.
You should be familiar with the structure of the vmConfig.xml file before linking the help to a screen
type. Place your help file or help files in the desired location.
To define links to custom screen-level help files, follow these steps:

1. To be able to see the Add Context Help Link option, select the Diagnostic node in the Login
dialog when logging into the Avocet client.
2. On the screen or screen type that you wish to link the help file, click Home > Navigation > Add
Context Help Link to open the Custom Dialog Window.

53
 3. Click the Type drop-down list to display the selection of screen types to which you can assign the
screen-level help. You can assign the help to a specific screen or to a group of related screens.

Screen Type Description

Node Assigns the help file to a specific tree node. Note that a custom deployment with different tree
node IDs would break any assigned help links.

Screen Assigns the help file to designated <screen> node for the currently displayed screen. This help
might be available to multiple screens defined under the <screen> node.

Screen_Config Assigns the help file to a <screenConfig> node that references the <screen> node of the currently
displayed screen.This assignment is more specific than the <screen> node assignment.Typically
you would use this assignment for a specific Item Editor screen type because Item Editor screens
reference the same <screen> node

Class Assigns the help file to the class name to which the currently displayed screen belongs. If
assigned to the class, the screen-level help will work in all configurations as long as the class
is not reused for multiple screen types: for example, Item Editor, Data Entry, Transaction, and
so forth

Select your screen type assignment.

4. Accept the corresponding ID value in the ID field.
It is tied to the screen type selection.
5. In the Link field, specify the location of the help file.
It can a relative path on your local system—for example, ..\\AvocetVM\Help. It can be an internal
URL, such as to a company’s Sharepoint site. Or, if your security permits, it can be an external
link.
6. Click OK.
7. Restart the Avocet client to initialize the change.
8. To display the linked help file, click the Help icon in the upper right-hand corner of the screen.

Enable custom screen-level help on an existing database implementation

This task shows how to edit the AppConfig_ProjectLayer.xml file to enable custom screen-level help
on an existing database implementation.

1. Open your project layer AppConfig_ProjectLayer.xml file under ..\AvocetVM\Config, and locate the
application ID definition that contains the database to which you connect.
2. At the same level as the <database> node, enter the following XML markup, highlighted in yellow
in the following example: <contextHelp>contextHelp.xml</contextHelp>.
<application id="ProjectLayerAppID">
<description>ProjectLayerAppID</description>
<database>

54 Avocet High Frequency Infrastructure

 <driver>SQLSERVER</driver>
<sqlsyntax>SQLSERVER</sqlsyntax>
<connectString>Network Library=DBMSSOCN;Data Source=localhost,
1433;Initial Catalog=DatabaseName;User ID=sa;Password=MyPassword;
Application Name=AVM</connectString>
</database>
<contextHelp>contextHelp.xml</contextHelp>

3. Save the file.

4. When initializing your database through the Avocet Configuration Tools utility (configTools.exe),
be sure to choose the Load Context Help selection in the Database Initializer screen (Database
Tools > Database Initializer).

55
High frequency infrastructure: installation
and configuration
The Avocet high frequency implementation is based on two components that you install from the
Avocet Installer utility: Avocet HF store and Avocet HFI Manager.
This section describes the installation steps for the Avocet HF store and Avocet HFI manager. It also
describes the configuration guidelines for setting up the Avocet high frequency implementation.

HFI manager and the AvocetHFSync service

The high frequency infrastructure (HFI) manager monitors the Avocet database for updates to high
frequency data.
High frequency data is generally considered to be in the range of one sample per one second to one
sample per 15 minutes. Low frequency is considered to be any sampling that is less than the lower
boundary of the high frequency data range.
The HFI manager monitors the Avocet database for these changes:
• add, delete, and update actions on tag maps
• add, delete, and update actions on Limit, Watchdog, and Discrete alarms
• updates to item and transaction properties resulting from calculations
The HFI manager contains a Windows service component called AvocetHFSync. As these changes
occur in real time, the HFI manager triggers the AvocetHFSync service, which automatically
synchronizes the data and the tag maps in the Avocet HF store. The HFI manager eliminates the need
for on-demand, manual synchronization, as it actively monitors database changes and automatically
updates the related tags in the Avocet HF store.
You can view messages about the status and actions of the AvocetHFSync service through the
Windows Event Viewer, as shown in this example screenshot:

This section addresses the following topics:

56 Avocet High Frequency Infrastructure

 • the high frequency data flow and prerequisites
• configuration guidelines for connecting the HFI manager to the application ID that points to the high
frequency implementation
• corporate historian creation
• security settings for corporate historians
• connection manager instances for your OPC UA data sources
• access for standard users to Apis and AvocetHFSync services
• multiple HF store and multiple corporate historian configurations
• APIS backup and restore command line options
To complete your high frequency implementation, refer to the following Help topics:

Help topic Description

Data Flow Configuration and Alarms Tells how to set up tag mapping and alarms for high frequency data

Calculations Describes how calculations are defined in a high frequency workflow

Connection Manager, Data Loading, and Tag Provides descriptions of how to set up connection manager instances to obtain
Mapping historical and real-time data. The subtopic How to set up your OPC UA data
sources for high frequency implementations is included in this section.

HFI manager prerequisites

To enable the HFI manager, you must ensure that certain preconditions are met.
The HFI manager and the Avocet HF store instance or instances must be paired on the same system.
One instance of the HFI manager can support multiple Avocet HF store instances on the same system.
Replication triggers must be enabled on the target database of the high frequency implementation.
You can do so through the Replication > Trigger Manager feature of the Avocet Configuration Tools
utility (ConfigTools.exe).
You should have already defined an application ID that points to the database supporting the high
frequency implementation. (Refer to the Help topic Avocet Production Data Management System
Installation Guide.) You should already have defined a secure Connection Manager instance with at
least an Avocet HF store instance.
The HFI manager and concomitant AvocetHFSync service run under an administrator account. You
can, however, configure a standard user account with administrator permissions for the HFI manager,
AvocetHFSync service, and APIS-related features.

HFI manager and high frequency data flow

The following diagram illustrates the main components and data flows in a high frequency
implementation governed by the HFI manager.
This diagram shows a logical representation of the high frequency components and data flows. The
components can coexist on one system, but in most production environments, they are deployed
across multiple systems.

57
 The following table describes the main relationships in the high frequency data flow:

HFI Manager and Avocet The HFI manager through its AvocetHFSync service listens for changes to the Avocet
Database database. It polls the LOG_ROWS table for events related to the synchronization process,
such as updates to tag maps, alarms, item properties, and transactions.
Replication triggers must be defined in the Avocet database.

HFI Manager and Avocet HF Store The HFI manager through its AvocetHFSync service automatically synchronizes the
database updates with the Avocet HF Store. It also passes calculation inputs from the
database to the Avocet HF Store.

Avocet HF Store and Desktop The Avocet desktop client defines the alarms, tag maps, and calculations; connects with
Client the Avocet HF store through a connection manager instance; and sends the data to the
Avocet HF store through an OPC UA data feed.
The Avocet desktop client does not display real-time data updates.

Avocet HF Store and Corporate Through tag mapping definitions, the Avocet HF store and corporate historian exchange
Historian OPC UA data updates.

Avocet HF Store|Corporate Through the Avocet SCADA load process, high frequency data from the Avocet HF store
Historian|SCADA Load|Avocet and the corporate historian is converted to low frequency and sent to the Avocet database.
Database
Note: The Avocet database does not store high frequency data. High frequency
data must be aggregated at low frequency intervals for it to be stored in the Avocet
database.

Avocet HF Store|Corporate The OPC UA client can be a custom or third-party client that is OPC UA compliant. Both
Historian|OPC UA Client the Avocet HF store and corporate historian send high frequency data to the OPC UA
client connection through an OPC UA data feed. An OPC UA client, such as a visualization
tool, can display real-time updates. For secure connections, you must manually copy the
client certificate to the trusted folders of the Avocet HF store and the corporate historian
instance.

58 Avocet High Frequency Infrastructure

Avocet HF Store
The Avocet High Frequency (HF) store is an implementation of the APIS Foundation components.
The Avocet HF store is required by Avocet when you implement high-frequency data collection, data
cleansing (clamping), calculations, or alarms. The Avocet HF store is the local data historian server
that processes and stores the high-frequency data sent by the corporate historian through the OPC
UA protocol. The Avocet HF store can support any corporate historian that uses the OPC UA protocol.

Note: The HFILicensing service is installed along with the Avocet HF store instance and applies
the requisite license to all Apis components.

If your OPC UA historian is not OPC UA compliant, you can use a software wrapper to complete the
connection to the Avocet HF store: for example, the Matrikon wrapper for the PI data historian.
The Avocet HF store manages the data through tag mapping between the corporate historian's tag
definitions and the matching Avocet item or transaction and its related property in the Avocet database.
The tag mapping is maintained through a synchronization process.
The synchronization process is performed automatically by the HFI manager's AvocetHFSync service.
The Avocet HF store can set alarm ranges and clamping values on the data received from the corporate
historian. It can perform calculations on high- and low-frequency data. Using OPC UA protocol, the
Avocet HF store passes the high-frequency data, including units of measure, alarm ranges, and
calculation outputs, to the corporate historian and SCADA load process.
To set up the Avocet HF store, you must install and configure the APIS Foundation package. The
Avocet HF store must coexist on the same system as the HFI manager. In a fresh install of the Avocet
HF store, security settings are automatically applied and security certificates are installed.
Item link chain
The Avocet HF store requires that the item links which make up its organizational hierarchy be populated
with data so that the calculations are applied to specific item types.
A default item link template is found in the installationDirectory\AvocetVM\Config\HFConfig_base.xml
file.
<ItemLinkChain Id="HFConfig_ILC_base">
<LinkType SourceIdLocation="FROM" Id="BATTERY_ITEM" />
<!--ITEM -> BATTERY-->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!--BATTERY -> ORG_UNIT4-->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!--ORG_UNIT4 -> ORG_UNIT3-->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!--ORG_UNIT3 -> ORG_UNIT2-->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!--ORG_UNIT2 -> ORG_UNIT1-->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!--ORG_UNIT1 -> COMPANY-->
<LinkType SourceIdLocation="FROM" Id="SCADA_ORG" />
<!--COMPANY -> SCADA-->
</ItemLinkChain>
The default item link chain definition maps the Avocet item types under the BATTERY_ITEM link down
to the SCADA item, which is the data historian instance. By default, the data historian instance is the
Avocet HF store.
The item link chain uses the ORG_ITEM link to traverse the Avocet organizational hierarchy down to
the COMPANY item. The From and To connections are shown in this excerpt from the Type Editor:

59
 The SCADA_ORG link then links the COMPANY item with the SCADA item.

In this way, a SCADA item is linked with specific Avocet item types. The SCADA item data properties
are applied to specific Avocet item types in the Avocet database. A representative item hierarchy is
shown below:

You can customize your item types based on your business needs. For example, you can substitute
or add other item links, such as WELL_ITEM, BORE_ITEM, and so forth. Your organization units can
reflect your business structure by using different labels, such as country, region, and other geographic
or organization labels.
The default item link chain supports one or more Avocet HF store instances that are assigned to the
COMPANY item level in the specified Avocet organization hierarchy. If your Avocet HF store is assigned
to the COMPANY level in the same organization structure, you do not need to modify this stanza.

Note: For most deployments, it is recommended that you use Schlumberger as the client
company instance.

You would need to modify or create a new item link chain if

• your organization structure is different from the one specified in the default chain
• you want to assign the Avocet HF store to a different item level in the default chain

60 Avocet High Frequency Infrastructure

When creating your own links between Avocet item types and the Avocet HF store, it is recommended
that you follow this linking structure to the COMPANY item, and then use the SCADA_ORG link type
to point to the Avocet HF store.
To enable the item link chain in your high frequency implementation, you must either manually enter
specific data instances or use a data loader to supply them.

Corporate historian
The corporate historian is a data historian software component that records the process data of an
external mechanism: for example, a meter. For high frequency data collection, the interval is in the
range of one sample per one second to one sample per 15 minutes.
This data is communicated in the form of tags. The tags are data elements that consist of time-stamps,
values, and sample quality information. These tags are passed to the Avocet HF store using the OPC
UA protocol. In the Avocet HF store these tags and their values are mapped to and synchronized with
matching Avocet transactions or items and their properties. The corporate historian passes raw data
directly to the OPC UA client.
You can use any data historian that uses the OPC UA protocol. If using a protocol other than OPC
UA when connecting with a data historian, you will have to create a software wrapper to adapt the
other protocol to OPC UA.
In Avocet, you can select the corporate historian as a data source and use the SCADA load process
(Interfaces > Measurement > SCADA Load) to load the historian's tags directly into the Avocet
database. During the load process, the specified aggregation method and interval are applied to the
high-frequency data, resulting in low-frequency sample values that are stored in the Avocet database.

SCADA load process

The SCADA load process lets you load high frequency data from either your data historian or the
Avocet HF store.
The high frequency data is converted to low frequency data that is passed directly to the Avocet
database.
The main difference between the two data sources is that the data historian supplies real-time data
and possibly its associated data. The Avocet HF store contains
• copies of the real-time data
• cleansed data resulting from clamping, unit of measure definitions, and other calculations
• and possibly the historical data associated with real-time and cleansed data
During the load process, the specified aggregation method is applied to the high frequency data stream.
The aggregation method determines the sampling intervals that convert the high frequency data to a
low frequency data stream.
You define the tag mapping and aggregation methods through the Data Flow Configuration screen
for high frequency implementations or through the Tag Mapping screen for low frequency or historical
data. Refer to Working with Data Flow Configuration and Alarms for more information.

Avocet database
The Avocet database stores low frequency or historical data.
The low frequency data can be the result of aggregation sampling intervals applied to high frequency
data from the corporate historian during the SCADA load process.
The Avocet database provides low frequency or historical production management data to the Avocet
native client in the desktop implementation.
All client connections to the Avocet database are defined by connection strings.

61
 The HFI manager uses the OLE DB interface to process log rows to communicate with the Avocet
database.
In most implementation scenarios, you create and maintain the Avocet database on its own database
server.

Introduction to Apis interfaces and configuration properties

As a deployment engineer or administrator, when managing your high frequency implementation, you
may work with the Apis interfaces Apis Buddy Utility Tool and Apis Management Studio and with certain
configuration settings.
This section provides summary guidelines. For detailed information, please refer to the Apis Help,
which you can access through the Help menu of the Apis Management Studio.
The Apis Buddy Utility Tool allows you to perform initial setup and configuration tasks and to view the
status of different operations. Through its Tools menu, you can
• register new ApisHive instances to function as HF Stores or corporate historians
• launch in context the Windows Event Viewer, the Services window, and so forth
• configure OPC UA security settings

The Tools > Configure OPC UA menu option allows you to manually set security options, such as
security policies and message security modes, and copy certificates to the respective trusted folders
of the OPC UA servers.
The Apis Management Studio allows you to customize module properties, verify connectivity, observe
tag values, adjust cache settings, and so forth.

62 Avocet High Frequency Infrastructure

 For the most part, you should let the HFI Manager manage the configuration settings of your high
frequency implementation. In Apis Management Studio, the only manual task that you are required to
do is to enter the name of the corporate historian's security certificate in the ServerCertificatePath
property of the corresponding TF_CorporateHistorian module instance.

Suggested workflow for installing Avocet HF store and HFI Manager

This workflow summaries the chief tasks you should perform to prepare the installation of the 2016.1
Avocet HF store and HFI Manager and to ensure a successful initial synchronization.
To gain an overview of the installation process, you should review this summary before proceeding
to the installation steps. Guidelines are provided as if you are installing on top of an existing 2014.1.n
high frequency (HF) implementation. Refer to the Help topic Avocet Production Data Management
System Installation Guide for how to set up and use the Avocet Installer utility.
Preliminaries
• Save ALL custom Avocet configuration files.
These files include all your Avocet project implementation files:
• AppConfig_ ImplementationName .xml
• ImplementationName .xml layer file
• vmConfig_ ImplementationName .xml
• CustomNavigators_ ImplementationName .xml
• GridReports_ ImplementationName .xml
• TransactionDataGridConfig_ ImplementationName .xml
• TransactionRollupConfig_ ImplementationName .xml
• If you have customized scripts, DLLs, or other configuration files, be sure to copy and save them.

63
 • If you are installing on top of an existing high frequency implementation with the Avocet HF store,
the installation routine automatically detects it and upgrades it to the latest version of Apis Foundation.
During the upgrade, your existing settings, modules, and items are preserved and carried forward.
However, to be on the safe side, save all your Apis instances, custom configuration files, and data.
• Uninstall the AvocetUAServer service because it is deprecated. (Use the sc delete command.)
• If you were running an HF store on a separate system, uninstall the application server/IIS setup. The
application server/IIS setup is no longer required for the HF store.
• Save your non-Apis historian configuration and data.
Install Schlumberger Licensing Server 2015.1
Follow the instructions for setting up and configuring the server. Note the system name, domain, and
port number for the server. The license path is stored under the system variable
SLBSLS_LICENSE_FILE. You will enter the license path when installing the other components.
Install Avocet
After a successful installation, do the following:
• Verify that all custom Avocet configuration files are deployed to their respective folders. The Avocet
Installer should have copied the custom files to the correct locations.
• Make sure replication triggers are created.
• Restore an existing application ID or define a new application ID that references the database which
contains the high frequency implementation.
• Remove references to deprecated features.
Install Avocet HF Store
After installing the Avocet HF store and rebooting the system, do the following:
• Verify that all Apis-related services are installed and running.These include ApisHive, ApisHoneyStore,
and ApisOPCHDA.
• Verify that the security settings and certificates are correctly applied and installed. In the Certificate
Manager of the Apis Buddy Utility Tool, you should see two certificates:
ApisHive@fullyQualilfiedDomainName and Avocet.

Note: If this is an upgrade, you will need to manually set the security and message encryption
settings for your ApisHive instance.

• Verify through the Apis Buddy Utility Tool that the Apis components have obtained their license.
Add a corporate historian instance
Adding a corporate historian instance at this stage is optional. You can either add
• an Apis-based corporate historian
• a non-Apis OPC UA corporate historian
Define a Connection Manager instance
Log into the application ID that references the database that hosts the high frequency implementation
and define a secure Connection Manager with the Avocet HF store instance and, optionally, an OPC
UA corporate historian instance. Refer to the Help topic How to set up your OPC UA data sources for
high frequency implementation.
Install HFI Manager
Install the HFI manager on the target system where Avocet HF store is installed along with a defined
secure Connection Manager instance that includes an Avocet HF store instance.

64 Avocet High Frequency Infrastructure

The results of the HFI manager installation routine are as follows:
• The contents of the AvocetVM\Config folder are copied to the HFIManager\Config folder. This includes
the AvocetVM\Config\AppConfig_ProjectLayer.xml file that contains the application ID pointing to
the high frequency implementation database. It also includes the AppConfig.xml file where the
license file path is defined. Note that custom configuration files contained in the AvocetVM\Config
folder are also copied to the HFIManager\Config folder.
• The AvocetHFSync service is installed.
• The specified application ID that points to the high frequency database is copied to the
HFIManager.exe.config file and to the HFILicensing.exe.config file.
• In the HFIManager.exe.config file, the relative path value of the ConfigDir key is modified to point
to the HFIManager\Config\AppConfig.xml file.
• The specified license server path is copied to the <licenseFilePath> tag in the
HFIManager\Config\AppConfig.xml file.
• The AvocetHFSync service is started. If you have configured an OPC UA corporate historian and
added it to a Connection Manager instance, it populates the following properties in the TF_Corporate
Historian module of the Apis Management Studio: CertificatePath, CertificateStorePath,
MessageSecurity, and PkiType.

Install or upgrade Avocet HF Store

This task describes how to install or upgrade the Avocet HF store, an ApisHive instance of the OPC
UA server that is required for the Avocet high frequency implementation.
In Avocet, define the application ID that references the database you will use for the high frequency
implementation. Note the application ID because you will need to specify it during the installation
routine.
If you have an existing instance of the Avocet HF store, the installation routine automatically detects
it and upgrades it to the latest version. During the upgrade, your existing settings, modules, and items
are preserved and carried forward.

Note: However, unlike a fresh install, where security settings are automatically applied, you
have to manually configure your security settings after an upgrade.

The Avocet HF store files are installed in a predefined path and folder. The installation routine ignores
the deployment location specified in the Installer GUI.
The HFILicensing service, which is installed with the HF store, applies the requisite license to the Apis
components.

1. To install the Avocet HF store, do the following:

a) Select Avocet HF Store.
b) Select the Terms & Conditions and safety acknowledgement check boxes.
c) Click Install.
A prompt is displayed, asking for the port and path to the Schlumberger License server.
2. Specify the port number, host, and file path to the Schlumberger License server.
If the License server is co-located on the same system as the Avocet HF Store, then localhost is
allowed. The default port number is 27000.
3. After entering the license file path, click OK to close the prompt.
Windows Powershell is displayed.
4. If you are prompted to install prerequisites, accept the request to continue with the installation.

65
 5. At the HFI Manager - Application ID prompt, enter the application ID (AppConfig_projectlayer.xml
file) that references the database you are using for the high frequency implementation, and click
OK.
Upon completion of the installation, the PowerShell window displays status messages and any
errors.
6. Exit Windows PowerShell by typing Exit at the directory prompt.
The installation routine results in the following:
• The HFILicensing service is installed and started.
• Licensing is automatically applied to the Apis components.
• Apis services ApisHive, ApisHoneyStore, and ApisOPCHDA are installed.
• Two security certificates are generated and installed in the trusted folder of the ApisHive instance:
one for the ApisHive (HF store) component and the other for the Avocet client.

7. Restart your system to complete the initialization.

The APIS services ApisHive, ApisHoneyStore, and ApisOPCHDA are started.
8. Refer to the remaining topics in this section for configuration and setup details.
If you have done an Avocet HF store upgrade and wish to apply the accompanying Apis security
settings, then see Manually apply security settings to Avocet HF store.
If you wish to apply a custom security implementation, instead of the out-of-the-box one, refer to
Appendix 4: Security guidelines and technologies for suggestions.

Manually apply security settings to Avocet HF store

You manually specify the security policy and message encryption for the ApisHive instance of the
Avocet HF store whenever you upgrade your existing Avocet HF store to the latest version through
the Avocet Installer.
This procedure assumes that you have just upgraded the Avocet HF store and have not yet installed
the HFI manager.

1. Launch the Apis Buddy Tool Utility, and choose the Tools > Configure OPC UA menu option.
2. In the Apis OPC UA Configuration dialog, select the ApisHive instance, and click Edit... .
The Endpoint Definition dialog is displayed with the Endpoint tab selected.
3. Verify and complete the following properties:

Endpoint URL A URL with the OPC.TPC protocol and a unique port number

Security policy De-select the None check box, and select the Basic 128 RSA 15 and Basic 256
check boxes.

Message encryption Select the Sign and Encrypt and Sign check boxes.

4. Click the Certificates tab, and verify the public key infrastructure (PKI) settings for the ApisHive
security certificate, as shown in the following screenshot:

66 Avocet High Frequency Infrastructure

5. Click Manage Certificates to view the certificates in the trusted folder of the ApisHive instance.
You should see two certificates:
• ApisHive@FullyQualifiedDomainName
The ApisHive certificate is for the Avocet HF store.
• Avocet
The Avocet certificate is for the Avocet client.

Populate the item link chain

You must populate the item link chain with data instances and assign the Avocet HF store instance
to a COMPANY item in the Avocet organization hierarchy. You can populate the data manually or
through a data loader.
Review the default item link template at installationDirectory\AvocetVM\Config\HFConfig_base.xml
file. Determine whether the default template suits your business needs, or customize it accordingly.
You must add the data instances to the organization hierarchy so that calculations and other updates
can complete when the AvocetHFSync process is run.

1. In the Navigation Tree, select Wells and Facilities and the item, such as completion, well, bore,
and so forth, and complete its Item Edit screen.
2. Proceed to Wells and Facilities > Organization, and complete the Item Edit screens for your
organizational units.
3. After adding the company or companies, in the Navigator list of the Company Item Edit screen,
select the company item to which the Avocet HF store instance is linked.
The corresponding Company Item Edit screen is displayed.
4. Select its Links tab
5. Locate the SCADA Organization Association link for the company item, and click New to display
the Select Item window for the data historian selections.
6. Select the Avocet HF store instance, and click OK to close the window and link the instance to the
SCADA Organization Association.

67
 7. Choose Home > Actions > Save to save the updated record.

Apis and Avocet security certificates

This topic presents of an overview of the Apis and Avocet security certificates and describes how they
are managed.
The Apis module instances generate their own X.509 security certificates and store them in the
respective instance's trusted folder. In addition, the Avocet HF store install routine generates the Avocet
client certificate and stores it in the trusted folder of the ApisHive instance or instances. The HFI
Manager install routine generates the Avocet Realtime Client certificate and stores it in the trusted
folder of the ApisHive instance.
You can view the Apis module and Avocet certificates through the Certificate Manager GUI of the Apis
Buddy Utility Tool.You navigate to the Certificate Manager GUI by following these steps on the system
where the Avocet HF store is installed:
1. Choose Tools > OPC UA Configure.
2. Select the ApisHive instance name, and click Edit... .
3. Click the Certificates tab.
4. Click Manage Certificates.

In this example, all certificates have check marks, meaning that they are in the trusted folder of the
selected ApisHive instance. The following security certificates are listed:
• ApisHive@FullyQualifiedDomainName for the Avocet HF store
• Avocet for the Avocet client
• Avocet Realtime Client for the HFI Manager
• CorporateHistorian for the Apis corporate historian (an ApisHive instance)

68 Avocet High Frequency Infrastructure

5. Select the certificate entry, and click View Certificate... to view the certificate details.
Each ApisHive instance has its own security certificate that is bound to the system for which it is
generated (instanceName@fullyQualifiedDomainName). For example, if you created an Apis corporate
historian instance, you would see a certificate entry such as the following in the Certificate Manager:

Each ApisHive instance has a security certificate file in the following format: instanceName.der. For
example, if you choose to implement the default ApisHive instance, a security certificate named
ApisHive.der is generated. If you registered an instance called CorporateHistorian1, its certificate
name would be CorporateHistorian1.der.

Note: The .der extension (Distinguished Encoding Rules) denotes a binary encoded certificate.

Once validated, these security certificates are stored in the respective trusted folders of the ApisHive
instances defined in this file path: C:\Program Files\APIS\Config\instanceName , as in this example:

The certificate files are stored in the trusted folder of the following directory path: C:\Program
Files\APIS\Config\instanceName\pki\trusted. For example, the following security certificates for the
Avocet HF store, the HFI Manager, the Avocet client, and the corporate historian or historians are
stored under the ApisHive instance for the Avocet HF store:

The ApisHive.der is for the Avocet HF store, the Avocet Realtime Client [nnn].der is for the HFI
Manager, the bfc nnn.der is for the Avocet client, and the CorporateHistorian n.der is for the historian
instance that is linked with the ApisHive instance.
Similarly, for a corporate historian instance called CorporateHistorian1, the following security certificates
are stored in its trusted folder:

69
 ApisHive.der is for the HF Store to which the historian connects, CorporateHistorian1.der is for the
data historian, and bfc nnn.der is for the Avocet client. The respective .der certificates should also
reside in the Schlumberger certs subfolder: for example,
C:\ProgramData\Schlumberger\CertificateStores\Client\Trusted Peers\certs.
In addition, a private key certificate (PEM or privacy enhanced mail) should be generated for the
corporate historian and stored in the private subfolder: for example, C:\Program
Files\APIS\Config\instanceName\pki\private\CorporateHistorian1.pem.
In production environments, the corporate historian typically resides on a separate system from that
of the Avocet HF store and HFI Manager. In this case, you copy the respective certificates to and from
the trusted folders of the two systems.
In the Apis Management Studio on the system where the Avocet HF store resides, you have to manually
enter the name of the corporate historian certificate in the ServerCertificatePath property of the
TF_Corporate Historian module of the Avocet HF store ApisHive instance, as in this example:

In addition, verify that the following TF_Corporate Historian module properties are populated:
Property Name Value

CertificateStorePath path of the certificates for the ApisHive instances:

C:\Program Files\APIS\Config\ApisHive\pki
CertificatePath The ApisHive instance .der certificate: ApisHive.der

PrivateKeyPath The ApisHive instance .pem certificate: ApisHive.pem

MessageSecurity the security for the connection string, such as Signed and
encrypted

SecurityPolicy the selected security policy, such as Basic128Rsa15

If you use a non-Apis corporate historian, do the following:

• Follow the vendor's guidelines for configuring it and for obtaining a security certificate.
• Store the certificate in the trusted folder of the particular corporate historian's instance.
• Enter the name of the certificate in the ServerCertificatePath property of the TF_Corporate Historian
module of the Avocet HF store ApisHive instance.
.
Manually generate an Avocet client certificate
In the event that the Avocet Installer does not generate a security certificate for the Avocet client, you
can manually generate one by launching the browse feature of the Connection Manager definition.
This topic provides a summary Connection Manager procedure. Refer to How to set up your OPC UA
data sources for high frequency implementations for detailed steps.

1. In the Avocet client, access the Connection Manager window by selecting Administration >
Interfaces > Measurement > Connection Manager in the Navigation Tree.
2. Define an OPC UA Connection Manager with the ApisHive instance of the Avocet HF store and,
optionally, a corporate historian instance.
3. Enter secure connection strings as your connection strings, as in this example for an ApisHive
instance of the Avocet HF store:
Data Source=opc.tcp://SystemName:4850/?0:Objects/
2:ApisHive:ApisHive;SecurityMode=SignAndEncrypt;
SecurityPolicy=Basic128Rsa15

70 Avocet High Frequency Infrastructure

4. Attempt to browse the node.
The initial browse attempt will fail, but the Avocet client certificate is generated and placed in the
rejected folder.
5. Manually copy the client certificate to the trusted folder of the ApisHive instance, or use the
Certificate Manager > Trust feature in the Apis Buddy Tool Utility to choose the Trust option.
The Avocet client certificates are stored in the trusted folders of all OPC UA instances defined in
the connection strings of Connection Manager definitions.

Install HFI Manager

You can install the High Frequency Infrastructure (HFI) manager, specify the Avocet application ID by
which it connects to the high frequency implementation, and automatically start the HFI manager's
AvocetHFSync service.
The initial synchronization process that is launched upon completion of the installation can automatically
populate specific security settings for your high frequency implementation. For a complete security
configuration to result from the initial synchronization, certain settings should be preconfigured. It is
recommended that you have
• installed Avocet, set up your database, and generated replication triggers
• configured an application ID that connects to the database that manages the high frequency
implementation
• installed the Avocet HF manager and, optionally, defined the corporate historian to which it connects
• created an OPC UA Connection Manager with an Avocet HF Manager instance and, optionally, a
corporate historian instance (refer to the Help topic How to set up your OPC UA data sources for
high frequency implementations)
You can install the HFI manager without the preconfigured settings. However, you will have to complete
the configuration manually later.
You can choose to overwrite an existing HFI manager deployment. If you choose this option, be sure
to save any customized files.

1. To install the HFIManager, do the following:

a) Select HFIManager.
b) Select the Terms & Conditions and safety acknowledgement check boxes.
c) Click Install.
A prompt is displayed, asking for the path to the Schlumberger License server or your license file.
2. Specify the port number, host name, and file path to the Schlumberger License server or to your
license file.
If the License server is co-located on the same system as the Avocet HF store, then localhost is
allowed. The default port number is 27000.
3. After entering the license file path, click OK to close the prompt.
Windows Powershell is displayed.
4. Follow the corresponding step for installing a new or upgrading an existing installation:

Option Action

New installation If you are prompted to install any prerequisites, accept the prompt and continue with the
installation.

Existing installation You receive a prompt asking whether you want to overwrite the existing installation. Click
OK to continue with the installation routine. Windows Powershell is displayed. You are
prompted to install any prerequisites.

71
 5. At the HFI Manager - Application ID prompt, enter the application ID of the
AppConfig_projectlayer.xml file that connects with the high frequency database, and click OK.
6. At the AvocetHFSync prompt, which asks whether you have defined a connection manager with
an Avocet HF store instance, make one of the following selections:
• Click Yes if you have defined the connection manager instance for the Avocet HF store.
• Click No if you have not defined the instance.
The AvocetHFSync service is installed.
7. When the installation completes, exit the PowerShell window.
The installation routine
• adds the specified application ID to the ApplicationId key of the HFIManager.exe.config file
and to the appId key of the HFILicensing.exe.config file.
• updates the relative path of the ConfigDir key to point to the AppConfig.xml file stored under
HFIManager\Config
• adds the specified license path to the <licenseFilePath> element of the
HFIManager\Config\AppConfig.xml file
• installs and starts the AvocetHFSync service. If you have configured an OPC UA corporate
historian instance and added it to a Connection Manager, the AvocetHFSync service populates
the following properties in the TF_Corporate Historian module of the Apis Management Studio:
CertificatePath, CertificateStorePath, MessageSecurity, and PkiType.

HFI Manager configuration guidelines

After installing the HFI manager, you should verify that the main configuration parameters have been
satisfied.
• The configuration files, including the AppConfig.xml and your AppConfig_ProjectLayer.xml, should
reside in the installDirectory\HFIManager\config subfolder. You may need to maintain duplicate
customized configuration files, especially your AppConfig_ProjectLayer.xml file, in both the
installDirectory\HFIManager\config subfolder and installDirectory\Avocet\config subfolder.
• The AppConfig.xml file that resides in the installDirectory\HFIManager\config subfolder should
contain the path and connecting port of the license server within the <licenseFilePath> element, as
in <licenseFilePath>[email protected] </licenseFilePath>.
• In the HFIManager.exe.config file, the ApplicationId key should point to the application ID that
references the database which the high frequency database uses.
• Verify in the HFIManager.exe.config file that the SystemUser key and the SystemPass key reflect
your application ID's login credentials.
• The HFIManager.exe.config file contains a relative or an absolute path that points to the location
of the installDirectory\HFIManager\config\AppConfig.xml file. You enter the relative path against
the ConfigDir key, or you enter the absolute path against the ManualConfigDir key.
• Verify that the plug-in assembly Slb.Avocet.HFNotificationPlugin.dll is located under the
installDirectory\HFIManager\HFIManagerPlugins folder.
Configure the HFIManager.exe.config file (manual guidelines)
You need to provide basic configuration parameters to launch the HFI manager's AvocetHFSync
service. You can customize other settings to satisfy business and performance requirements.

Note: The HFI manager installation automatically captures the application ID and modifies the
relative path value of the ConfigDir key.You must update other settings manually, such as buffer,
retry count, polling, and logging parameters.

The configuration files, including the AppConfig.xml and your AppConfig_ProjectLayer.xml, should
reside in the installDirectory\HFIManager\config subfolder. You may need to maintain duplicate

72 Avocet High Frequency Infrastructure

 customized configuration files in both the installDirectory\HFIManager\config subfolder and
installDirectory\Avocet\config subfolder.

1. Open the HFIManager.exe.config file.

2. At the ApplicationId key, specify or verify the application ID of the database your high frequency
implementation connects with.
<add key="ApplicationId" value="MyAvocetHFAppID" />

3. Verify that the installation routine populated a relative path to the AppConfig.xml file in the ConfigDir
key.
You can specify an absolute path to the AppConfig.xml file in the ManualConfigDir key. However,
a relative path entry is preferred.
Option Description
Relative path Enter the relative path value against the ConfigDir key.

Absolute path Enter an absolute path value against the ManualConfigDir key.

4. Review other settings and modify if necessary.

5. Save the changes.
6. Start or restart the AvocetHFSync service to initialize the changes.

High frequency infrastructure manager configuration file

The HFIManager.exe.config file serves as the configuration file for the high frequency infrastructure
manager service.
The configuration file contains properties for setting up and managing the behavior of the high frequency
infrastructure manager service.
To enable the high frequency infrastructure manager to communicate with your Avocet deployment,
you must provide the application ID of the database to which you are connecting together with the
path to the Config subfolder that holds your AppConfig.xml and other configuration files. The following
table summarizes the main configuration properties of the HFIManager.exe.config file:

Key Value

ApplicationId the name of the application ID that connects to the Avocet database for your high frequency
implementation

ConfigDir the relative file path to your deployment's Config folder where the AppConfig.xml file,
AppConfig_ProjectLayer.xml, and other configuration files reside. The default value
..\..\config\AppConfig.xml assumes that your working Config directory is
installDirectory\AvocetVM\config and that the HFIManager.exe.config file which
points to it is located under installDirectory\HFIManager.

If you are using a different path structure in your deployment folder, adjust the relative path
indicator accordingly. You can refer to this non-Schlumberger website for more information
about relative paths.

ManualConfigDir If not using the relative path, you can use the ManualConfigDir to specify the absolute path
to your project's Config subdirectory: for example,
c:\installDirectory\AvocetVM\Config.
HFStoreFilterKeys Applies to the Avocet HF store instance or instances that are defined in the database. It
contains a semi-colon delimited list of possible key values to verify against the Avocet HF

73
 Key Value

store connection string in the Connection Manager. This list can include a computer name,
an IP address, a load balancer domain name system (DNS) entry, and so forth.

The default values are localhost; 127.0.0.1. By default this key is commented out.

HFStoreFilterIncludeDns When set equal to true, which is the default value, this key appends the computer name
of the system where the HFI manager's AvocetHFSync service is executing to the filter list
of the HFStoreFilterKeys property.

HFStoreFilterIncludeIpAddresses When set equal to true, which is the default value, this key appends the IPv4 IP address
of the system where the HFI manager's AvocetHFSync service is executing to the filter list
of the HFStoreFilterKeys property.

LocalHostMode a Boolean True/False indicator. When set equal to True, it tells the HFI manager service to
replace the machine or domain name with the local host name in the Avocet HF store's
connection string in the Connection Manager instance.

The default value is True. Accept the default value when

• two or more Avocet HF store instances are defined

• the Connection Manager connection string points to a load balancer device that resides
in front of the multiple Avocet HF store instances

If LocalHostMode is set equal to False, then the high frequency infrastructure manager
service uses the connection string as-is.

SystemCulture denotes the culture (language) to use for displaying messages. Valid values include

• en-US
• en-GB
• es-CO
• es-EC
• es-MX
• es_VE
• ru_RU
• custom cultures

RunSyncOnConfigFileChange a Boolean True/False indicator. The default is true, meaning that the high frequency service
automatically performs a full synchronization whenever a configure change occurs to the
HFIManager.exe.config file. If the property is set equal to false, then synchronization does
not automatically occur.

SystemUser Avocet user account through which the high frequency infrastructure manager service logs
into the Avocet database

SystemPass Password associated with the Avocet user account

SyncRefreshRate The interval in minutes between full synchronizations of the high frequency infrastructure
service

You can enable logging by uncommenting the following entries under the <listeners> element in the
<system.diagnostics> section:
<listeners>
<!--<add name="logFilegGlobal" type="System.Diagnostics.
TextWriterTraceListener" initializeData="..\..\HFIManager.log"
traceOutputOptions="DateTime,Timestamp" />

74 Avocet High Frequency Infrastructure

 <add name="eventLogGlobal" type="System.Diagnostics.EventLogTraceListener"
initializeData="HFIManagerDiagnostics" />-->
........
</listeners>
The logFileGlobal attribute enables messages to be placed in a log file. The default log file is
HFIManager.log, specified by the initializeData attribute. The eventLogGlobal attribute enables
messages to be placed in the Windows event log.

How to implement a corporate historian in a high frequency setting

This topic contains guidelines for creating a secure OPC UA corporate historian instance. It describes
the corporate historian setup in a test and in a production environment.

The corporate historian in a test environment

The following flow charts outline the steps for setting up an Apis corporate historian in a test
environment.
This flow chart shows the steps for configuring an Apis corporate historian that is co-located on the
same system as the HF store and HFI manager:

75
 The following flow chart outlines the steps for configuring an Apis corporate historian when it is located
on a separate server:

76 Avocet High Frequency Infrastructure

The corporate historian in a production environment
The following flow chart depicts the steps in configuring a non-Apis corporate historian that resides
on a separate server from the system where the HF store and HFI manager reside.

77
 Add an Apis corporate historian instance to the local system
This task shows how to set up and register an APIS corporate historian instance on the same system
where you have installed Avocet, Avocet HF Store, and HFI Manager. This scenario describes a typical
test environment. In a production environment, the corporate historian is typically installed on a separate
server.
You must have administrator privilege to execute this task, specifically running the PostInstall.ps1
script.
Windows PowerShell 3.0 or later should be installed. (Windows Powershell 3.0 or later is required by
the Avocet Installer program, so it should already be installed.) The PostInstall.ps1 script runs under
Windows PowerShell.
The HFI Manager is installed. The HFI Manager is required because its subfolder ..HF\Apis contains
the PostInstall.ps1 script.
At the end of the Avocet HF store installation routine, the Avocet Installer applies security settings and
installs certificates for the HF Store and any existing corporate historian instances. If you add a corporate
historian after you have installed the Avocet HF store, you apply security settings and install certificates
by running the HFIManager\HF\Apis\PostInstall.ps1 script under Windows PowerShell.
Create a Connection Manager definition with the Avocet UA server and your Avocet HF store for the
application ID that connects to your high frequency implementation database. After you create the

78 Avocet High Frequency Infrastructure

APIS corporate historian instance, you can then include its URL and settings with the Connection
Manager definition. Refer to the Help topic How to set up your OPC UA data sources for high frequency
implementations.
Follow these steps to set up and register an APIS corporate historian on the local system:

1. Launch the APIS Buddy utility.

2. Choose Tools > Register New Instance… to open the Register New APIS Hive Instance dialog.

3. In the Enter name of new APIS Hive instance text box, enter and note the name of your corporate
historian.
If you intend to use the HF Player data simulator, it is preprogrammed to use the instance name
CorporateHistorian1.You can choose to enter CorporateHistorian1 as the name of your instance.
4. Select the Run As Service check box, and click OK.
A toolbar item with the name of your corporate historian instance is displayed in the APIS Buddy
GUI.
5. Choose Tools > Configure OPC UA to verify the URL entry in the Apis OPC UA Configuration
dialog.
a) If registering the corporate historian on the same system as the Avocet HF Store, specify a port
number other than 4850 (the Avocet HF Store default value) to avoid conflicts: for example,
4851.
The localhost designation is 0.0.0.0 for the opc:tcp endpoint.
b) Close the dialog.
6. Execute the installDirectory\HFIManager\HF\Apis\PostInstall.ps1 script to apply the security settings.
a) Go to installDirectory\HFIManager\HF\Apis\PostInstall.ps1, and right click PostInstall.ps1 to
display the flyout menu.
b) Choose Run with PowerShell.
If your system execution policy permits it, then the script automatically executes in a PowerShell
window where the output is displayed. If you receive an error, you will need to execute the
Get-ExecutionPolicy at the command line.
7. Verify the security settings in the Apis Buddy Tool.
a) Choose Tools > Configure OPC UA to open the Apis OPC UA Configuration dialog.
b) Verify the security settings:

79
 Security The security level is set automatically by the Avocet Installer or the execution of the PostInstall.ps1
script. The default settings are
• Basic 128 Rsa 15 (Sign or Sign and Encrypt)
• Basic 256 Rsa (Sign or Sign and Encrypt)

Certificates You should see the ApisHive and the two Avocet client certificates already assigned to the trusted
folder of the ApisHive HF Store instance. The ApisHive certificate is for the Avocet HF Store. The
Avocet certificate is for the Avocet client. The Avocet RealTime Client certificate is for the HFI
Manager component.
Select the ApisHive corporate historian instance, and verify that its certificate is installed and in the
trusted folder.

8. In the Avocet client, add the corporate historian to the secure Connection Manager definition for
the Avocet HF store defined in the application ID pointing to the database supporting the high
frequency implementation.
9. Browse the namespace of the corporate historian node.
An Avocet client certificate is generated for the corporate historian node.
10. In the Apis Buddy Tool Utility, verify that the Avocet client certificate is installed for the ApisHive
corporate historian instance.
11. Manually move the Avocet client certificate to the trusted folder of the ApisHive corporate historian.
12. In the APIS Buddy GUI, restart the ApisHive and corporate historian instances.
After the AvocetHFSync process is run, the following properties are populated in the TF_Corporate
Historian module of the Apis Management Studio:
• CertificatePath - name of ApisHive HF Store certificate (ApisHive.der for example)
• CertificateStorePath - path to the ApisHive HF Store certificate
• MessageSecurity - Signed and encrypted
• PkiType - OpenSSL

13. Open the Apis Management Studio on the system where the Avocet HF store resides, connect
with the Avocet HF Store to display the TF_CorporateHistorian module, and manually enter the file
path of the server certificate in the ServerCertificatePath property.

In the Data Flow screen, add the tag mapping entries linking items and transactions to the Avocet HF
store and corporate historian instances.
Execute Get-Execution Policy
Before running the Apis PostInstall.ps1 PowerShell script, you may need to execute and set the
execution policy. This requirement varies depending on your environment settings.
If you are unable to launch the PostInstall.ps1 PowerShell script from the flyout menu, you will need
to set your execution policy to RemoteSigned.

Note: Having an execution policy Unrestricted is not recommended because it possibly exposes
the system to malicious scripts.

1. Launch the Windows PowerShell in administrator mode.

2. Change directory (cd) to the directory path implementationFolder\HFIManager\HF\Apis .
If any of the folder names contain spaces, such as Deployment Folder, enclose the entire file path
in quotation marks: for example, cd "Deployment Folder\HFIManager\HF\Apis".
3. Enter Get-ExecutionPolicy at the directory prompt:
PS D:\AvocetDeployment\HFIManager\HF\Apis> Get-ExecutionPolicy
RemoteSigned

80 Avocet High Frequency Infrastructure

 If the message RemoteSigned is returned, then you can execute the postInstall.ps1 script by
choosing the Run with PowerShell option from the right-click flyout menu. If the message Restricted,
Unrestricted, or any message other than RemoteSigned is returned, then you need to change the
execution policy.
4. To change the execution policy, in the Windows PowerShell enter the Set-ExecutionPolicy
RemoteSigned command at the directory prompt:
PS D:\AvocetDeployment\HFIManager\HF\Apis>
Set-ExecutionPolicy RemoteSigned

Execution Policy Change

The execution policy helps protect you from scripts that you do not trust.
Changing the execution policy might expose you to the security risks
described in the about_Execution_Policies help topic at
http://go.microsoft.com/fwlink/?LinkID=135170.
Do you want to change the execution policy?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
PS D:\AvocetDeployment\HFIManager\HF\Apis>
A message displays that explains the consequences of the execution policy change.
5. Type Y at the prompt to accept the policy change.
You are returned to the directory prompt.

Install the Avocet client certificate to the trusted folder

In the Apis Buddy Utility Tool, you must manually install the Avocet client certificate to the trusted
folder.
You should have already defined the connection manager instance with the Avocet HF store and
corporate historian.

Note: You have to repeat this procedure for each Avocet HF store and corporate historian
instance that you add.

The Avocet client certificate does not display in the Certificate Manager of the Apis Buddy Utility Tool
until the specified node (HF store or corporate historian) has been browsed through a connection
manager link. When the Avocet client certificate first displays, it is marked as untrusted.
To install the Avocet client certificate to the trusted folder, follow these steps:

1. Launch the Apis Buddy Utility Tool, and choose Tools > Configure OPC UA.
2. In the Apis OPC UA Configuration dialog, select the ApisHive instance (HF store or corporate
historian) and click Edit... .
3. In the Endpoint Definition dialog, click the Certificates tab and choose Manage Certificates.
4. In the Manage Certificates dialog, select the Avocet client certificate, and click Trust.
The certificate is added to the trusted folder, and a green checkmark displays next to its name.
5. Close the Manager Certificates and Endpoint Definition dialogs to return to the Apis OPC UA
Configuration dialog.
6. In the Apis OPC UA Configuration dialog, choose the corporate historian instance, and click Edit...
.
7. Repeat steps 3 and 4 to add the Avocet client certificate to the trusted folder.
8. Follow this procedure to add the client certificate of each connected OPC UA client to the trusted
folder of the respective ApisHive instance.

81
 Add historian certificate to the ServerCertificatePath property
After creating a corporate historian and applying security settings to its configuration, you manually
enter the name of its server certificate in the ServerCertificatePath property of the TF_CorporateHistorian
module instance in the Apis Management Studio.
You perform this task on the system where the Avocet HF store and HFI Manager are installed.
The AvocetHFSync service should be running, as well as all Apis services.
If the corporate historian resides on a separate system, you must have already copied its server
certificate to the trusted folder on the local system.
Review the Apis Management Studio Help for additional details.
The ServerCertificatePath property references the server certificate for your data historian. You will
need to specify the server certificate name for each corporate historian instance in your implementation.

1. To view the server certificate for the corporate historian, do the following:
a) In the Apis Buddy Utility Tool, choose Tools > Configure OPC UA.
b) Select the corporate historian instance, and click Edit... .
c) Click the Certificates tab, and choose Manage Certificates to display the Certificate Manager
dialog.
d) Select the instanceName@FullyQualifiedDomainName entry, and click View Certificate... .
2. To verify the name of the server certificate for the corporate historian, go to the following file path:
C:\Program Files\APIS\Config\instanceName\pki\trusted.
The certificate name is instanceName.der.
3. Launch Apis Management Studio.
4. Connect to your HF Store (hive://hostName).
Its modules are displayed.
5. Open the TF_CorporateHistorian module, and locate the ServerCertificatePath property.

Note: A separate TF_CorporateHistorian module is generated for each corporate historian

instance.

6. Enter the name of the certificate in the ServerCertificatePath property, and click Apply.
The update is automatically synchronized.

Note: If the Avocet HF store and recently added corporate historian do not connect, in Apis
Management Studio, right click the TF_Corporate Historian module entry, choose Restart.

Add an Apis corporate historian instance to its own server

To add an Apis corporate historian instance to its own server, separate from the system where the
Avocet HF store and HFI manager reside, you must copy the Apis folder to the target system and
manually install Apis.
In a production environment, the corporate historian is usually installed on a separate server.
The default ApisHive instance is an OPC UA server and can function as the corporate historian when
linked with the Avocet HF store.
On the source system, you should have already installed and configured Avocet, Avocet HF store,
and HFI manager with secure settings.The Apis-related and AvocetHFSync services should be running.

82 Avocet High Frequency Infrastructure

On the source system, create a Connection Manager definition with the Avocet UA server and your
Avocet HF store for the application ID that connects to your high frequency implementation database.
After you create the Apis corporate historian instance, you can then include its URL and settings with
the Connection Manager definition. Refer to the Help topic Connection Manager, specifically How to
set up your OPC UA data sources for high frequency implementations.
The system on which the corporate historian is installed must be able to communicate with the system
where the Avocet HF store is installed.
You must have administrator privilege to execute this task.
The following diagram may be helpful to understanding the setup of a corporate historian residing on
a separate server:

With an Apis corporate historian on a separate system, you do not run the PostInstall.ps1 script to
apply security settings. Instead, you manually apply the security settings and copy the secure certificates
between the trusted folders of the two systems.

1. On the source system where you have already installed the components, locate the
Installer\Software\Apis subfolder and copy the Apis subfolder.
2. Paste the Apis folder to a local drive of the target system where you intend to set up your Apis
corporate historian.
3. Open the Apis folder and launch the APIS Foundation x64 Setup.exe executable to manually
install Apis.
4. Launch the APIS Buddy Utility Tool.
The default ApisHive instance is an OPC UA server and can function as the corporate historian
when linked with the Avocet HF store. You can use the default ApisHive instance as the corporate
historian. You do not need to register a new instance.
If you use the default ApisHive instance, it generates a security certificate named ApisHive.der.
5. Ensure that the ApisHive instance is running and the Apis services (ApisHive, ApisHoneyStore,
and ApisOPCHDA) have started.

83
 6. Choose Tools > Configure OPC UA to verify the URL entry in the Apis OPC UA Configuration
dialog.
a) Specify the URL of the system where the ApisHive corporate historian instance resides.
b) Specify the port number through which the ApisHive corporate historian instance will communicate
with the Avocet HF store that resides on the separate system.
c) Close the dialog.
7. Manually set the security settings of the ApisHive instance in the Apis Buddy Utility Tool.
a) Choose Tools > Configure OPC UA to open the Apis OPC UA Configuration dialog.
b) Specify these security settings:

Security • Basic 128 Rsa 15 (Sign or Sign and Encrypt)

• Basic 256 Rsa (Sign or Sign and Encrypt)

Certificates You should see the ApisHive certificate.

8. On the source system, add the corporate historian to the secure Connection Manager definition
for the Avocet HF store on the application ID pointing to the database supporting the high frequency
implementation.
Refer to the Help topic How to set up your OPC UA data sources for high frequency implementations.
9. Follow these guidelines to copy certificates between the two systems:

Note: If the certificates have the same name, for example ApisHive.der, you must first copy
the certificate to a temporary folder, rename it (ApisHive1.der for example), and then copy
it to the instanceName's trusted folder. Do NOT overwrite an existing certificate.

a) On the system where the corporate historian resides, export the corporate historian's secure
certificate and copy it to the system where the Avocet HF store resides in the following directory
path: C:\Program Files\APIS\Config\ApisHive\pki\trusted.
b) On the system where the Avocet HF store resides, copy the Avocet client and the ApisHive
certificates and paste them to the C:\Program
Files\APIS\Config\CorporateHistorianInstanceName\pki\trusted folder on the system where the
corporate historian resides.
10. Open the Apis Management Studio on the system where the Avocet HF store resides, add the
historian certificate to the ServerCertificatePath property:
a) Connect with the Avocet HF store to display the TF_CorporateHistorian module.
b) Open the corresponding TF_CorporateHistorian module, and locate the ServerCertificatePath
property.
c) Enter the name of the certificate (instanceName.der) in the ServerCertificatePath property, and
click Apply.
The update is automatically synchronized.

Note: If the Avocet HF store and recently added corporate historian do not connect, in Apis
Management Studio, right click the TF_Corporate Historian module entry, choose Restart.

After the AvocetHFSync process is run, the following properties are populated in the TF_Corporate
Historian module of the Apis Management Studio for the Apis corporate historian:
• CertificatePath
• CertificateStorePath
• MessageSecurity

84 Avocet High Frequency Infrastructure

 • PkiType

For the next major step, go to the Data Flow screen, and add the tag mapping entries linking items
and transactions to the Avocet HF store and corporate historian instances.

Set up a non-Apis corporate historian instance per your vendor's guidelines

Using the guidelines, commands, and utilities provided by your vendor, define your OPC UA corporate
historian instance after you have installed the Avocet HF store and the HFI Manager.
You must have administrator privilege to execute this task.
The Avocet HF store is installed and configured with its security settings.
The selected historian must be OPC UA compliant. If it is not, you can use a software wrapper to
encapsulate a non-compliant historian.
In a production environment, the non-Apis corporate historian is usually installed on a separate server.
On the system where your Avocet client resides, a connection manager instance is created with your
Avocet HF store for the application ID that connects to your high frequency implementation database.
To verify that the security settings have been applied to your Avocet HF store instance, launch the
Apis Buddy Utility Tool and choose the Tools > Configure OPC UA option. You should see the
following settings:

Endpoint URL A URL with the OPC.TPC protocol and a unique port number

Security policy Basic 128 RSA 15, Basic 256

Message encryption Sign and Encrypt, Sign

Certificates ApisHive, Avocet, and Avocet Realtime Client. The ApisHive certificate is for the Avocet
HF store. The Avocet certificate is for the Avocet client. The Avocet RealTime Client
certificate is for the HFI manager. (The Avocet client certificate is displayed only after the
connection manager instance is defined and browsed.)

You have to use your vendor's security guidelines for your historian.

1. Follow your vendor's procedure for defining the corporate historian instance and its endpoints.
2. Configure your historian's OPC UA settings for your connection endpoints and security settings.
3. Following the vendor's instructions, create secure certificates for your historian and install them in
the trusted folder.
4. On the system where your Avocet client resides, add your corporate historian instance to the secure
Connection Manager definition for the application ID that points to the database where the high
frequency implementation resides.
5. If your corporate historian resides on a different system from that of the Avocet HF store, follow
these guidelines to copy certificates between the two systems:

Note: If the certificates have the same name, for example ApisHive.der, you must first copy
the certificate to a temporary folder, rename it (ApisHive1.der for example), and then copy
it to the instanceName's trusted folder. Do NOT overwrite an existing certificate.

a) On the system where the corporate historian resides, export the corporate historian's secure
certificate and copy it to the system where the Avocet HF Store resides in the following directory
path: C:\Program Files\APIS\Config\ApisHive\pki\trusted.
b) On the system where the Avocet HF Store resides, copy the Avocet client and the ApisHive
certificates and paste them to the C:\Program

85
 Files\APIS\Config\CorporateHistorianInstanceName\pki\trusted folder on the system where the
corporate historian resides.
6. Open the Apis Management Studio on the system where the Avocet HF store resides, add the
historian certificate to the ServerCertificatePath property:
a) Connect with the Avocet HF store to display the TF_CorporateHistorian module.
b) Open the corresponding TF_CorporateHistorian module, and locate the ServerCertificatePath
property.
c) Enter the name of the certificate (instanceName.der) in the ServerCertificatePath property, and
click Apply.
The update is automatically synchronized.

Note: If for some reason the Avocet HF store and recently added corporate historian do not
connect, in Apis Management Studio, right click the TF_Corporate Historian module entry,
choose Restart.

After the AvocetHFSync process is run, the following properties are populated in the TF_Corporate
Historian module of the Apis Management Studio for the Apis corporate historian:
• CertificatePath
• CertificateStorePath
• MessageSecurity
• PkiType

In the Data Flow screen, add the tag mapping entries linking items and transactions to the new Avocet
HF Store and corporate historian instances.
Use the Windows Event Viewer to monitor and archive the event log for a few days.
Use the Apis Management Studio to verify that tags are being populated with data and that calculations
and alarms are functioning correctly.

Enable the event historian (Apis)

To enable the event historian, you edit specified variables in the
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Prediktor\Apis\ApisHiveInstance\Chronical registry
key in the Windows Registry Editor, where ApisHiveInstance is an HF store or a corporate historian
instance.
You must have administrator privilege to perform this task.
This procedure tells you how to do an initial setup of the event historian for your ApisHive instance.
For complete details, please refer to the topic Event Historian in the Apis Help that you launch from
the Apis Management Studio.

1. Launch the Windows Registry Editor using the regedit command.

2. Locate the
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Prediktor\Apis\ApisHiveInstance\Chronical
registry key.
3. Enter the following values for the initial configuration:
Variable Value

Enable Enter 1 to enable the event historian. The default is 0.

Horizon The number of days that events are stored in the historian
database. The default is 365.

86 Avocet High Frequency Infrastructure

 Variable Value

Path File path (relative or absolute) to the event historian database

for the ApisHive instance. The default folder name is
Chronical, with the ApisHive instance name appended to the
file path: for example, C:\Program
Files\Apis\Chronical\ApisHiveInstance.

LogLevel The level of detail in log messages. Valid values are

• 0 (Bugs)
• 1 (Errors)
• 2 (Warnings)
• 3 (Informational)
• 4 (Debug)
• 5 (Trace)

Cache_Flush_Sync Boolean indicator. The default value 0 indicates that the

historian flushes the cache file asynchronously at an interval
specified in the Cache_Flush_Interval variable. The value 1
indicates that the historian flushes the cache after each block
operation is finished, typically for synchronous tasks.

Cache_Flush_Interval Number of milliseconds between each asynchronous cache

flush. The range is 100 to 10000 milliseconds. If the
Cache_Flush_Sync is set equal to 1 (a synchronous flush),
then the Cache_Flush_Interval value is ignored.

4. Exit and close the Windows Registry Editor.

5. Restart the impacted ApisHive instance or instances.
When you navigate to the C:\Program Files\Apis file path, you should see a Chronical folder with
an ApisHive instance folder appended to it, as in this example screenshot:

6. For more advanced configuration options, refer to the Help topic Event Historian in the Apis
Management Studio Help.

Event historian (Apis)

Apis provides an event historian configuration for its ApisHive instances. The event historian stores
Apis events and alarms.
You manually enable the event historian by editing the Windows Registry Editor. Using an OPC UA
client, you can browse for alarms and event history. Be sure that you add the client certificate to the
trusted folder of the ApisHive instance that you are browsing.

Note: For a test client, you can download the UaExpert OPC UA client from this
non-Schlumberger website.

87
 In APIS Management Studio, you can search its Help for Event Historian to learn details about the
event historian and its configuration.

How to set up your OPC UA data sources for high frequency implementations
This section provides guidelines for configuring your Connection Manager definitions for high-frequency
and visualization. It assumes that you are familiar with the Connection Manager feature.
If you are using high frequency data collection, define the following three data sources:
• Avocet UA server
• Avocet HF store
• Corporate historian

Note: The Avocet UA server feature is deprecated in this release. However, its node is required
in the hierarchy when defining the high frequency implementation. The entry Avocet UA server
acts, in effect, as a placeholder.

The following diagram outlines the data flow in a high frequency implementation that includes the
Avocet HF store:

Before defining the data source connections, make sure that the corresponding components—ApisHive
(Avocet HF store) and corporate historian -- are running. The AvocetHFSync process does not have
to be running. If it is running, however, it actively monitors the connections once they are defined and
updates data if changes occur.
As a reminder, the following components are required for the Avocet high frequency connection
manager definition:
• Avocet UA server (as placeholder in node hierarchy)
• Avocet HF store
• corporate historian

88 Avocet High Frequency Infrastructure

Define the Avocet UA server
Although the feature is deprecated, you must still add the Avocet UA server node. It acts as a
placeholder in maintaining the high frequency node hierarchy.
Because it is acting as a placeholder in the current context, you cannot browse its endpoint in the
hierarchy.

1. Access the Connection Manager window through the Administration > Interfaces > Measurement
> Connection manager node.
2. In the ribbon toolbar, choose Home > Tools > New > Avocet UA Server to open a blank record.
3. Complete the following fields in the top section of the Connection Manager – Avocet UA Server
window:
Field Description

Name Name that you assign to this Connection Manager instance

Tag Mapping Color The color used to indicate which fields have been mapped to tag values

Data Source Level The data source value is Avocet (the Avocet database). Select Avocet from the
drop-down list if it is not already displayed.

Read by Disabled for Avocet UA Server. The Read by selection serves to link SCADA data
originating from a historian with Avocet items.

4. Select OPC UA as the data access type in the Historian Data Access Type field.
The actual value you select is irrelevant to the definition, but you must select an entry to maintain
the hierarchy.
5. Accept the default data connection string.
While the data connection string has no significance to the implementation, you must still make an
entry. You cannot leave the field blank.
6. Choose Home > Tools > Save.

Define the Avocet HF store

The Avocet HF store is derived from an ApisHive instance. This task shows how to define a secure
Avocet HF store Connection Manager instance.
Before you define the Avocet HF store, ensure that the Apis components are installed and configured
and that their corresponding services are running.
Ensure that the correct security settings and certificates have been assigned to the Avocet HF store.
The Avocet HF store is essential to the Avocet high frequency implementation.

1. In the Avocet client, access the Connection Manager window by selecting Administration >
Interfaces > Measurement > Connection Manager in the Navigation Tree.
2. In the ribbon toolbar, choose Home > Tools > New > Avocet HF Store to display a blank record.
3. Complete the following fields in the top section of the Connection Manager – Avocet HF Store
window:
Field Description

Name Name that you assign to this Connection Manager instance

Tag Mapping Color The color used to indicate which fields have been mapped to tag values

Data Source Level For the Avocet HF Store, the data source is itself, so select Avocet HF Store.

89
 Field Description

Read by Choose the placeholder node Avocet UA Server to maintain the data hierarchy.

4. Select OPC UA in the Historian Data Access Type field.

The default data connection string and a unique configuration URI are displayed:
The configuration URI is specific to Apis. As a general rule of thumb, do not modify the configuration
URI for your initial Avocet HF Store instance.
5. Specify the secure data connection string by which the historian client connects with the server.
Use the system name or IP address in this data connection string whether the Avocet HF store
resides on the local or a remote system. Do not use localhost or the fully qualified domain name
(FQDN) in the Avocet HF store connection string.

You obtain the secure data connection string by

• manually entering the data connection string with the security parameters, as in this example:
Data Source=opc.tcp://SystemName:4850/?0:Objects/
2:ApisHive;SecurityMode=SignAndEncrypt;
SecurityPolicy=Basic128Rsa15

• browsing the namespace of the Avocet HF store and connecting with a specific node

6. For the initial setup, accept the default values for the Tag List Source and Data loading options
fields.
7. In the ribbon toolbar, choose Home > Tools > Save.
The Avocet HF store's Connection Manager instance is created.

Caution: When you delete your Avocet HF store's Connection Manager instance, you also
delete its tag mapping definitions. You have to recreate the tag maps when you re-enter the
Avocet HF store's Connection Manager configuration.

Browse the OPC UA server namespace to connect with nodes

When setting up your connection manager instance, you can browse the namespace of the OPC UA
server (Avocet HF store or corporate historian) to view the node hierarchy and select a node object.
The Avocet HF store instance should be running.
The Browse feature can help you to determine if you have a valid connection. At a first-time browse
of the namespace, you may get an error if the Apis client and ApisHive security certificates are not in
the trusted folder. If you do get an error after an initial browse, launch the Apis Buddy Utility Tool, go
to Tools > Configure OPC UA, and select the instance to verify or update the status of the security
certificates.
After a first-time browse and verification of the security certificates, if you still do not see the Avocet
HF store entry when you browse the namespace, you should recheck your Apis installation and
configuration.

90 Avocet High Frequency Infrastructure

To browse the namespace of an OPC UA server, follow these steps:

1. Click the ellipsis (…) to display the OPC UA Browser window.

2. Specify the server name, port number, and any required authentication credentials (User Id and
Password) for accessing the Avocet HF Store. (This is the location where you installed the APIS
components.)
The default port number is 4850.
3. Click Browse to locate the top-level node for the Avocet HF store.
4. Click the unfold button to reveal the Avocet HF store security subnodes None, Sign, and
SignAndEncrypt.
5. Click the unfold button next to the SignAndEncrypt subnode.
6. Select the Objects subnode under SignAndEncrypt, and click OK.
The connection string should be similar to the following browse path in terms of its security
parameters:
Data Source=opc.tcp://SystemName:4850/?0:Objects/
2:ApisHive;SecurityMode=SignAndEncrypt;
SecurityPolicy=Basic128Rsa15

Define the corporate historian

The corporate historian can be any data historian that collects SCADA data. This task shows how to
define a secure corporate historian Connection Manager instance.
The corporate historian can use any connection protocol, except for the high frequency implementation.
In the high frequency implementation that includes the Avocet HF store, the connection protocol is
OPC UA.
The corporate historian must be installed and configured on the server (usually remote) before you
can define it in the Connection Manager window.
Ensure that the correct security settings and certificates have been assigned to the Avocet HF store
and the corporate historian instance.
Before starting this procedure, obtain the IP address or computer name of the system where the
corporate historian resides.

1. In the Avocet client, access the Connection Manager window by selecting Administration >
Interfaces > Measurement > Connection Manager in the Navigation Tree.
2. In the ribbon toolbar, choose Home > Tools > New > Corporate Historian to display a blank
record.
3. Complete the following fields in the top section of the Connection Manager – Corporate Historian
window:
Field Description

Name Name that you assign to this Connection Manager instance

Tag Mapping Color The color used to indicate which fields have been mapped to tag values

Data Source Level For the Corporate Historian, the data source is itself, so select Corporate Historian.

Read by Choose Avocet HF Store.

4. Select the data access type in the Historian Data Access Type field.
In a high-frequency implementation that includes the Avocet HF store, choose OPC UA.

91
 Other valid values depend on the type of connection. They include
• ODBC
• OleDb
• OPC HDA
• Oracle
• SQL Server

5. Specify the secure data connection string by which the historian client connects with the server.
Use the system name or IP address in this data connection string whether the corporate historian
resides on the local or a remote system. Do not use localhost or the fully qualified domain name
(FQDN) in the corporate historian connection string.
You obtain the secure data connection string by
• manually entering the data connection string with the security parameters, as in this example:
• Data Source=opc.tcp://systemName:4851/?0:Objects/
2:CorporateHistorian1;SecurityMode=SignAndEncrypt;
SecurityPolicy=Basic128Rsa15
browsing the namespace of the Avocet HF store and connecting with a specific node

6. For the initial setup, accept the default values for the Tag List Source and Data loading options
fields.
7. In the ribbon toolbar, choose Home > Tools > Save.
The corporate historian Connection Manager instance is created.

Caution: When you delete your corporate historian's Connection Manager instance, you
also delete its tag mapping definitions. You have to recreate the tag maps when you re-enter
the corporate historian's Connection Manager configuration.

Browse the OPC UA server namespace to connect with nodes

When setting up your connection manager instance, you can browse the namespace of the OPC UA
server (Avocet HF store or corporate historian) to view the node hierarchy and select a node object.
The corporate historian instance should be running.
The Browse feature can help you to determine if you have a valid connection. At a first-time browse
of the namespace, you may get an error if the Apis client and corporate historian certificates are not
in the trusted folder. If you do get an error after an initial browse, launch the Apis Buddy Utility Tool,
go to Tools > Configure OPC UA, and select the corporate historian instance to verify or update the
status of the security certificates.
After a first-time browse and verification of the security certificates, if you still do not see the Avocet
HF store entry when you browse the namespace, you should recheck your Apis installation and
configuration.
To browse the namespace of an OPC UA server, follow these steps:

1. Click the ellipsis (…) to display the OPC UA Browser window.

2. Specify the server name, port number, and any required authentication credentials (User Id and
Password) for accessing the corporate historian. (This is the server where you installed the corporate
historian.)

92 Avocet High Frequency Infrastructure

 If the corporate historian and Avocet HF store reside on the same system, they must connect
through different ports. If the corporate historian and Avocet HF store reside on separate systems,
then they can connect through the same port.
3. Click Browse to locate the top-level node for the corporate historian.
4. Click the unfold button to reveal the corporate historian security subnodes None, Sign, and
SignAndEncrypt.
5. Click the unfold button next to the SignAndEncrypt subnode.
6. Select the Objects subnode under SignAndEncrypt, and click OK.
The connection string should be similar to the following browse path in terms of its security
parameters:
Data Source=opc.tcp://systemName:4851/?0:Objects/
2:CorporateHistorian1;SecurityMode=SignAndEncrypt;
SecurityPolicy=Basic128Rsa15

Run script to grant non-administrative or standard user rights to Avocet HF store and
HFI manager
You can execute the HFIManager\HF\Apis\NonAdmin\ApisNonAdmin.ps1 script to grant a
non-administrative or standard user rights to run and configure the Avocet HF store, Apis corporate
historian, and HFI manager and its AvocetHFSync service.
You must have the HFIManager folder to gain access to the ApisNonAdmin.ps1 script. You must
have the administrative privilege to execute the script.
Create a new or select an existing non-administrative or standard user to which you want to grant
permission.
All Apis services and the AvocetHFSync service must be installed and working.
Windows Powershell 3.0, which is required for the Avocet Installer, should be installed.

1. Go to installDirectory\HFIManager\HF\Apis\NonAdmin to locate the ApisNonAdmin.ps1 script file.

2. Select the ApisNonAdmin.ps1 script file, right click to display the flyout menu, and choose Run
with Powershell.
If your system execution policy permits it, then the script automatically executes in a PowerShell
window where the output is displayed. If you receive an error, you will need to execute the
Get-ExecutionPolicy at the command line.
3. Review the on-screen instructions, and grant the target non-administrative or standard user Log
on as a service and Log on as a batch job rights as directed.
4. Press Enter to continue the script.
5. At the user credentials prompt, enter the name and password of the non-administrative or standard
user, and click OK.
The script stops any active APIS services and updates the Avocet HF store and Apis corporate
historian settings with the user credentials. It then prompts for the name of the synchronization
service, the default name being AvocetHFSync.
6. Accept the default AvocetHFSync, and click OK.
The script updates the AvocetHFSync service with the user credentials, and starts or restarts the
AvocetHFSync service.
7. Review the on-screen messages, press Enter to exit the PowerShell window, and restart your
system.

93
 8. Log in using the non-administrative user credentials to verify that the APIS and AvocetHFSync
services start under the updated non-administrative account.

Multiple HFI manager and Avocet HF store instances

A single HFI manager must reside on each system where an Avocet HF store instance or instances
reside.
The HFI manager determines which Avocet HF store instance or instances it manages by
• reading the three HFStoreFilter keys (HFStoreFilterKeys, HFStoreFilterIncludeDns, and
HFStoreFilterIncludeIpAddresses) defined in the HFIManager.exe.config file, and
• comparing their values with the host names defined in the data source connection strings for the
different Avocet HF store instances
The default values of the HFStoreFilter keys tells the HFI manager instance to accept the domain
names or IP addresses of the HF stores on the system where it resides.
In a simple scenario, two Avocet HF store instances are defined on a single system where an HFI
manager instance resides. In this example, the HFI manager reads the default values of the
HFStoreFilterKeys. The default values tell the HFI manager to accept the domain name of the HF
stores on the system where it resides. It compares the default values against the data source connection
strings where the domain name is defined, so it knows to manage them.

In the next scenario, three Avocet HF store instances are defined across two systems, each requiring
an HFI manager instance to monitor the respective Avocet HF store instances. In this example, each
HFI manager reads the default values of the HFStoreFilter keys. The default values tell each HFI
manager to accept the domain names of the HF stores on the system it resides on. When the Avocet
HF store data source connection string specifies the domain name (ACME or COYOTE in this example),
the HFI manager knows to manage the specified Avocet HF store instance.

94 Avocet High Frequency Infrastructure

The next example uses the IP address instead of the domain name as the filter value. Each HFI
manager instance reads the default values of the HFStoreFilter keys. The default values tell each HFI
manager instance to accept the IP addresses of the HF stores on the system it resides on. When the
Avocet HF store data source connection string specifies the IP address (167.188.75.89 and
167.188.75.90 in this example), the HFI manager knows to manage the specified Avocet HF store
instance.

The following example shows a domain name system load balancer defined in the HFStoreFilterKeys
property instead of its default value. The other HFStoreFile keys contain the default values, meaning
that the HFI manager instance can accept either a domain name or an IP address, if either is specified
in the HF store's data connection string. However, in this case, the domain name system load balancer
defined in the HFStoreFilterKeys property is specified.

95
 Because this is a load balancing scenario, the two HF store instances are managed as a single logical
instance. Consequently, in their respective Connection Manager definitions, each physical instance
is assigned the identical logical instance name.

Multiple Avocet HF store and corporate historian instances

The HFI manager implementation supports multiple Avocet HF store and corporate historian instances
on single or multiple machines.
The following schematic outlines a multiple HF store deployment on a single system:

The HFI manager service AvocetHFSync must be co-located on the same system as the Avocet HF
store instance or instances.
Each Avocet HF store instance must have a SCADA Organization Association link to a unique
COMPANY item.

96 Avocet High Frequency Infrastructure

In a typical configuration, a single HF store instance connects with a single corporate historian instance.

Note: A single HF store instance can be connected with one or more corporate historians.
However, a corporate historian instance cannot be shared by more than one HF store.

A unique Connection Manager definition (Avocet UA Server > Avocet HF Store > Corporate Historian)
must exist for each Avocet HF store instance.

Create multiple Avocet HF store instances

You can create multiple Avocet HF store instances to monitor different historians, to maintain backup
instances, or to adjust the high frequency workload.
An instance of the HFI manager service AvocetHFSync must be installed and running on each different
system where the Avocet HF store instance or instances are installed. A single HFI manager service
can support multiple Avocet HF store instances on the same system.
When adding additional instances, you should have a Connection Manager instance already defined
with the components Avocet UA server (placeholder), Avocet HF store, and Corporate Historian.
Ensure that your HFIManager.exe.config file points to the application ID referencing the database
where the Connection Manager instance and the target HF store instance or instances are defined.
Verify that your Avocet HF store instance or instances are assigned available ports, without any
conflicts.
PowerShell 3.0 or later should be installed to execute the PostInstall.ps1 script.
You will need to connect the new Avocet HF store instance to its unique corporate historian or historians
in the Connection Manager.

Note: Multiple Avocet HF store instances cannot connect to the same corporate historian.

97
 1. Launch the APIS Buddy Tool, and choose Tools > Register New Instance... .
The Register New Apis Hive Instance dialog is displayed.
2. Enter the name of the new instance of the Avocet HF store in the Enter name of new APIS Hive
Instance text field.
3. Ensure that the Run as Service check box is selected, and click OK.
4. Choose Tools > Configure OPC UA.
The APIS OPC UA configuration dialog is displayed.
5. Select the Avocet HF store instance you just registered, and click Edit.. .
The Endpoint Definition dialog is displayed.
6. Adjust the endpoint parameters as required.

Tab Description

Endpoint Ensure that the URL points to the correct system and the connecting port is available. Select
the security policies Basic 128 RSA 15 and Basic 256. Select the secure message modes
Sign and Sign and Encrypt.

Certificates The PostInstall.ps1 script will create and install the certificates.

Logging Set the logging options as desired.

7. In the Apis Buddy Took, click Close, start the new Avocet HF store instance, and restart all other
APIS instances. In the Services window, restart the AvocetHFSync service.
8. Execute the PostInstall.ps1 script to apply the security settings.
a) Go to installDirectory\HFIManager\HF\Apis\PostInstall.ps1, and right click PostInstall.ps1 to
display the flyout menu.
b) Choose Run with PowerShell.
If your system execution policy permits it, then the script automatically executes in a PowerShell
window where the output is displayed. If you receive an error, you will need to execute the
Get-ExecutionPolicy at the command line.
Upon completion of the script, a certificate is generated and installed for the new ApisHive instance
and the Avocet and Avocet Realtime Client certificates are duplicated in the Trust folder.

After completing this procedure, consider the following:

Link your Avocet HF store instance with a COMPANY item in the Avocet organization hierarchy.
Define the corporate historian that the Avocet HF store instance will monitor.
Apply security to the corporate historian instance.
Edit the Connection Manager by adding the new Avocet HF store and corporate historian instances.
In the Data Flow screen, add the tag mapping entries linking items and transactions to the new Avocet
HF store and corporate historian instances.

Add multiple Avocet HF store instances to a Connection Manager instance

You can add multiple Avocet HF store instances to your high frequency, OPC UA Connection Manager
definition.
You should have already defined the Avocet HF store instance and its properties through the APIS
Buddy Tool.
All APIS instances, including the one you are going to add, should be running together with the HFI
manager service AvocetHFSync.
Ensure that your HFIManager.exe.config file points to the application ID referencing the database
where the Connection Manager instance and the target HF store instance or instances are defined.

98 Avocet High Frequency Infrastructure

 Note: A single HF store instance can be connected with one or more corporate historians.
However, a corporate historian instance cannot be shared by more than one HF store.

1. Log into the application ID where your Connection Manager instance is defined.
2. In the Avocet client, access the Connection Manager window by selecting Administration >
Interfaces > Measurement > Connection Manager in the Navigation Tree.
3. In the ribbon toolbar, choose Home > Tools > New > Avocet HF Store to display an Avocet HF
store record.
4. Verify the following fields in the top section of the Connection Manager – Avocet HF Store window:
Field Description

Name Name that you assign to this HF store connection manager instance. For
convenience sake, this should be the same name you assigned to the instance
when you registered it in the APIS Buddy Tool.

Tag Mapping Color The color used to indicate which fields have been mapped to tag values

Data Source Level For the Avocet HF store, the data source is itself, so select Avocet HF Store.

Read by Choose the placeholder node Avocet UA Server to maintain the data hierarchy.

5. Select OPC UA in the Historian Data Access Type field.

6. Specify the data connection string, including its unique port number, by which the historian client
connects with the server.
Use the machine name or IP address in this data connection whether the Avocet HF store resides
on the local or a remote system. Do not use localhost or 127.0.0.1 in the Avocet HF store connection
string.
You obtain the data connection string when you browse the address space of the Avocet HF store.
a) Click the ellipsis (…) to display the OPC UA Browser window.
b) Specify the server name and any required authentication credentials (User Id and Password)
for accessing the Avocet HF store. (This is the location where you installed the Apis components.)
c) Click Browse to locate the historian node on the designated machine. The default instance runs
on port 4850. If you are installing the new instance on the same system, use a unique port
number.
d) Click the arrow to reveal the Avocet HF store subnodes.
e) Browse to the Objects node and select ApisHive for your path string.
f) Click OK.
The connection string should be similar to the following browse path in terms of its subnode
levels:
Data Source=opc.tcp://ComputerName:4852/?0:Objects/
2:NewAvocetHFStoreInstance

Note: The Browse feature can help you to determine if you have a valid connection. If
you do not see the Avocet HF store entry when you browse the address space, you should
recheck your Apis installation and configuration.

7. Modify the configuration URI entry by substituting the name of your registered Avocet HF store
instance.
The default Avocet HF store instance name is 1, as in
localhost:progid=Prediktor.ApisLoader.1

99
 Append the name of your new Avocet HF store instance after the ApisLoader. entry, as in
localhost:progid=Prediktor.ApisLoader.
NewAvocetHFStoreInstance

8. For the initial setup, accept the default values for the Tag List Source and Data loading options
fields.
9. In the ribbon toolbar, choose Home > Tools > Save.
The new Avocet HF store Connection Manager instance is created.

Add your corporate historian instance to the Connection Manager definition for this application ID.
In the Data Flow screen, add the tag mapping entries linking items and transactions to the new Avocet
HF store and corporate historian instances.

Add multiple corporate historian instances to a Connection Manager instance

You can add multiple corporate historian instances to the Connection Manager definition and assign
them to be read by a specified Avocet HF store.
You must have already defined the corporate historian instance and applied security settings to the
module in Apis Management Studio and in the OPC UA configuration of the historian. For example,
for an APIS historian, you can use the Apis Buddy Tool to set the OPC UA configuration settings.
You must have already added the Avocet HF store instance that will read the corporate historian in
the Connection Manager definition for your application ID.
All APIS instances, including the one you are going to add, should be running, together with the HFI
manager service AvocetHFSync.
Ensure that your HFIManager.exe.config file points to the application ID referencing the database
where the Connection Manager instance and the target HF store instance or instances are defined.

Note: A corporate historian instance or instances are read by a single HF store instance. You
cannot connect a single corporate historian instance to more than one HF store instance.

1. Log into the application ID where your Connection Manager instance is defined.
2. In the Avocet client, access the Connection Manager window by selecting Administration >
Interfaces > Measurement > Connection Manager in the Navigation Tree.
3. In the ribbon toolbar, choose Home > Tools > New > Corporate Historian to display a corporate
historian record.
4. Verify the following fields in the top section of the Connection Manager – Corporate Historian
window:
Field Description

Name Name that you assign to this corporate historian connection manager instance.
For convenience sake, this should be the same name you assigned to the instance
when you registered it in the APIS Buddy Tool.

Tag Mapping Color The color used to indicate which fields have been mapped to tag values

Data Source Level For the Corporate Historian, the data source is itself, so select Corporate Historian.

Read by Choose the Avocet HF store instance that it will connect with. This connection is
unique to the specified HF Store instance.

5. Select the data access type in the Historian Data Access Type field.
In a high frequency implementation that includes the Avocet HF store, choose OPC UA.

100 Avocet High Frequency Infrastructure

 6. Specify the data connection string, including the unique port number, by which the historian client
connects with the server.
Use the machine name or IP address in this data connection string whether the corporate historian
resides on the local or a remote system. Do not use localhost in the corporate historian connection
string.
You obtain the data connection string when you browse the address space of the corporate historian.
a) Click the ellipsis (…) to display the OPC UA Browser window.
b) Specify the server name and any required authentication credentials (User Id and Password)
for accessing the corporate historian.
c) Click Browse to locate the historian node on the designated machine.
If the corporate historian and Avocet HF store instances reside on separate systems, then they
can connect through the same port.
d) Click the arrow to reveal the corporate historian subnodes.
e) Browse to the Objects node and select the appropriate subnode for your path string. In this
APIS example it is CorporateHistorian2, but your namespace may be different depending on
your vendor's historian.
f) Click OK.
The connection string should be similar to the following browse path in terms of its subnode
levels:
Data Source=opc.tcp://163.188.75.139:4854/?0:Objects/2:CorporateHistorian2

Note: The Browse feature can help you to determine if you have a valid connection. If
you do not see the Corporate Historian entry when you browse the address space, you
should recheck your corporate historian installation and configuration.

If your corporate historian and Avocet HF store reside on the same system, ensure that they
do not share the same port number.

7. For the initial setup, accept the default values for the Tag List Source and Data loading options
fields.
8. In the ribbon toolbar, choose Home > Tools > Save.
The corporate historian Connection Manager instance is created.

In the Data Flow screen, add the tag mapping entries linking items and transactions to the new Avocet
HF store and corporate historian instances.

Apis backup and restore command line options

You can use the Apis command line options backup and restore to back up and restore configuration
settings, event and alarm history, and other data for the Apis components ApisHive and Honeystore.
The backup and restore commands are helpful in exporting and importing data and configuration
settings between instances of the Avocet HF store. For example, you can use the backup and restore
commands to copy data to multiple instances of the Avocet HF Store.

Note: The Avocet HF store is built on the ApisHive and Honeystore components.

Refer to the Apis Management Studio Help for specific information about these options.You can search
on the term "ApisBare," which is the name of the API. This topic provides summary descriptions and
guidelines for their use.

101
 The default backup and restore commands act on configuration settings, alarm and event data, historical
data files, UA certificates, and other data. The backup data includes the following files:

File extension Content

.cfg A JSON text file that contains general information about the backup, configuration entries defined in
the Windows Registry, and the content of the different configuration files that support Apis modules
and Honeystore databases

.chr a customized file format that contains event and alarm data. For example, the ApisHive.chr is the
backup for the event historian.

.bin Honeystore metadata stored in a SQLite3 database, which you can view with a SQLite3 browser. It
contains item, property, and attribute tables.

.bin.blockdata a customized file format containing raw data in a compressed format that is exported from the
Honeystore database. You can import this data into a target Honeystore database that contains the
same items as the source database. To do the import, you can use APIS Management Studio or the
Microsoft Management Console (MMC) for the Honeystore database.

certificates Private, trusted, and rejected certificates are stored in subdirectories under the backup directory.

The following command line options are available:

/Hive points the backup or restore option to the ApisHive component

/Honeystore points the backup or restore option to the Honeystore component

/Wait exits the completed backup or restore action only after you press a key on the keyboard

/ConfigOnly backs up or restores configuration settings only. This option applies to the ApisHive and the Honeystore.

/DataOnly backs up or restores data only. This option applies only to the Honeystore component.

/Yes restores all backup data and overrides existing data without a confirmation prompt. It applies only to
the restore option. If the /Yes option is omitted, the restore task behaves more interactively, printing
out attribute values that you can override.

/Incremental backs up configuration settings that have changed or event data that has been added since the last
backup. For configuration settings, each backup folder is incremented by one. For the restore action,
you specify the sequence number of the incremented backup folder you wish to restore.
For event and alarm data, a chronicle file (.chr) is used to store the events and alarms. Incremental
data is appended in data blocks to the existing chronicle .chr file. The .chr file is not numerically
incremented. The restore operation restores each data block one after the other.

When restoring an Apis configuration and data on a different system, the restore operation automatically
adjusts certain configuration parameters. (See the Apis Help topic for a list.) However, on the new
system you must generate new security certificates for the UA servers. In addition, you check all
service endpoints for any port conflicts. Also, you should verify the overridable values that are printed
out during an interactive restore session.

Back up ApisHive
You can back up the data and the configuration settings or only the configuration settings of the
ApisHive component. However, you cannot back up only the data of the ApisHive component.
Create a target backup folder where you intend to save the ApisHive data. You will need to be able
to run the Windows Command Prompt as administrator to perform this task.
Use the /Hive key in the command syntax to specify the ApisHive.

1. Open the Windows Command Prompt as administrator.

2. Change directory (cd) to the following path: C:\Program Files\APIS\Bin64.
3. To review the available backup options, type Bare Backup at the directory prompt, and press
Enter.

102 Avocet High Frequency Infrastructure

 The backup commands are displayed.

Note: The default backup operation saves both data and configuration settings.

4. Choose your backup options:

Option Description Syntax

/Hive points to the target component. When used by itself, it is the Bare Backup /Hive
default option. The default option backs up data and configuration "PathName\FileName.cfg"
settings. Be sure to user the forward slash (/) for the key hive
and include the .cfg suffix as the filename extension.

/Configonly This option restricts backup to the component's configuration Bare Backup /Hive /configonly
settings. "PathName\FileName.cfg"

/Incremental This option backs up only the data and configuration settings that Bare Backup /Hive /Incremental
have changed or have been added since the preceding backup. "PathName\FileName.cfg"
Backup .cfg files are numerically incremented. Backup .chr files
are appended.

/wait This option forces the backup script to wait for user input, such Bare Backup /Hive /Wait
as pressing a key, to exit. "PathName\FileName.cfg"

5. View the output in the Command Prompt to which file or files are being created.
6. Navigate to the file path where the backup files are being saved.
You should see the .cfg file that stores the configuration settings, a folder named ApisHive.Hive
that has a .pem file holding the certificate, files containing trusted certificates, a Logger.HS file,
and an ApisHive.chr file for the APIS event historian.

Back up Honeystore
You can back up the data only, the configuration settings only, or both data and configuration settings
of the Honeystore component.
Create a target backup folder where you intend to save the Honeystore data. You will need to be able
to run the Windows Command Prompt as administrator to perform this task.
Use the /honeystore key in the command syntax to specify the Honeystore.

1. Open the Windows Command Prompt as administrator.

2. Change directory (cd) to the following path: C:\Program Files\APIS\Bin64.
3. To review the available backup options, type Bare Backup at the directory prompt, and press
Enter.
The backup commands are displayed.

Note: The default backup operation saves both data and configuration settings.

4. Choose your backup options:

Option Description Syntax

/honeystore points to the target component. Used by itself, it is the default Bare Backup /honeystore
option. The default option backs up data and configuration "PathName\FileName.cfg"
settings. Be sure to user the forward slash (/) for the key
honeystore and include the .cfg suffix as the filename
extension.

/configonly This option restricts the backup to the component's Bare Backup /honeystore /configonly
configuration settings. "PathName\FileName.cfg"

103
 Option Description Syntax

/dataonly This option restricts the backup to the component's data files. Bare Backup /honeystore /dataonly
"PathName\FileName.cfg"

/Incremental This option backs up only the data and configuration settings Bare Backup /honeystore /Incremental
that have changed or have been added since the preceding "PathName\FileName.cfg"
backup. Backup .cfg files are numerically incremented. Backup
.chr files are appended.

/wait This option forces the backup script to wait for user input, Bare Backup /honeystore /Wait
such as pressing a key, to exit. "PathName\FileName.cfg"

5. View the output in the Command Prompt to which file or files are being created.
6. Navigate to the file path where the backup files are being saved.
You should see the .cfg file and one folder for each database that is backed up.

Restore ApisHive
You can restore the ApisHive configuration and data files that you backed up to the same or different
instance of the Avocet HF Store.
Before trying to restore your ApisHive instance on an existing installation, remove the Chronical folder
at C:\ProgramFiles\Apis\Chronical\ApisHiveInstance.
The configuration and data files that you restore override any existing data in the instance. By default,
a confirmation prompt asks whether you want to override the existing data. The data is copied to their
default Apis directories.

1. Open the Windows Command Prompt as administrator.

2. Change directory (cd) to the following path: C:\Program Files\APIS\Bin64.
3. Choose your restore options:

Option Description Syntax

/hive points to the target component. When used by itself, this Bare Restore /hive
is the default option. The default option restores data and "PathToBackupFolder\BackupFileName.cfg"
configuration settings. Be sure to use the forward slash (/)
for the key hive and include the full path to the backup file.

/configonly This option restores only the configuration settings to the Bare Restore /hive /configonly
Avocet HF Store. "PathToBackupFolder\BackupFileName.cfg"

/yes This option initiates the restore action without the Bare Restore /hive /yes
confirmation prompt. "PathToBackupFolder\BackupFileName.cfg"

/incremental This option restores the incremental or appended backup Bare Restore /hive /incremental
file that is specified in the command line. "PathtoBackupFolder\BackupFile"

4. If you do not use the /yes option, press Y at the prompt to restore the backed-up data, thereby
overriding any existing data in the Avocet HF store instance.
If the target instance is running, it is stopped.

Restore HoneyStore
You can restore the Honeystore data, the configuration settings, or both data and configuration settings
to the same or different instance of the Avocet HF store.
The configuration and data files that you restore override any existing data in the Avocet HF store
instance. By default, a confirmation prompt asks whether you want to override the existing data. The
data is copied to their default Apis directories.

104 Avocet High Frequency Infrastructure

 1. Open the Windows Command Prompt as administrator.
2. Change directory (cd) to the following path: C:\Program Files\APIS\Bin64.
3. Choose your restore options:

Option Description Syntax

/honeystore points to the target component. Used by itself, this is the Bare Restore /honeystore
default option. It restores data and configuration settings "PathToBackupFolder\BackupFileName"
to the Avocet HF store instance. Be sure to user the
forward slash (/) with the key honeystore and include the
full path to the backup file.

/configonly This option restores only the configuration settings to the Bare Restore /honeystore /configonly
Avocet HF store instance. "PathToBackupFolder\BackupFileName"

/dataonly This option restores only the data to the Avocet HF store Bare Restore /honeystore /dataonly
instance. "PathToBackupFolder\BackupFileName"

/yes This option initiates the restore action without the Bare Restore /honeystore /yes
confirmation prompt. "PathToBackupFolder\BackupFileName"

/incremental This option restores the incremental or appended backup Bare Restore /honeystore /incremental
file that is specified in the command line. "PathtoBackupFolder\BackupFile"

4. If you do not use the /yes option, press Y at the prompt to restore the backed-up data, thereby
overriding any existing data in the Avocet HF store instance.
If the target Avocet HF store instance is running, it is stopped.

Export and import data across multiple Avocet HF instances

Using the backup and restore commands for the ApisHive and Honeystore, you can back up the
configuration settings and data of one Avocet HF store instance and restore it to another Avocet HF
instance on a different system.

1. Identify the source Avocet HF store instance whose configuration and data you want to back up
and the target Avocet HF store instance that you want to import the information to.
2. Use the appropriate backup command options to back up the configuration and data of the source
Avocet HF store instance.
3. Using the appropriate restore options, restore the desired data and configuration settings to the
target Avocet HF store instance.

Appendix 1: Manual steps to apply security settings to your corporate historian

This appendix describes how to manually specify the certificate path, the certificate store path, the
message security level, and the public key infrastructure type for each corporate historian that you
add in its accompanying Avocet HF store module in APIS Management Studio.
Before adding the security settings, ensure that the high frequency infrastructure manager service has
completed its synchronization task against the corporate historian instance. Upon each startup, the
AvocetHFSync service performs a synchronization task.
These guidelines apply to any corporate historian instance. They are non-vendor specific.You manually
specify these settings in the Avocet HF store module definition within the Apis Management Studio.
They are the security credentials that the TF_Corporate Historian module for that Avocet HF store
uses to connect to your target historian.

Note: In APIS Management Studio, you can search its Help for the following terms:
• CertificatePath

105
 • CertificateStorePath
• MessageSecurity
• PkiType

1. Launch APIS Management Studio, and connect with your Avocet HF Store instance
(hive://hostName) to which the corporate historian is connected.
2. Display its modules, and select TF_Corporate Historian.
3. In the ApisOpcUa TF_Corporate Historian property list, make the following security entries:
Property Value
CertificatePath ApisHive.der
CertificateStorePath File path relative to the Apis configuration folder. The default is PKI.
MessageSecurity Signed or Signed and encrypted
PkiType OpenSSL

4. Optionally, save the configuration changes to an Apis configuration file (*.acf).

5. Launch the Buddy Tool, and restart the ApisHive and Corporate Historian instances.

Appendix 2: Manual steps to grant non-administrative or standard user rights to Avocet

HF store and HFI manager
You can enable a non-administrative or standard user with limited permissions so that she can configure
and administer the APIS services, including the HFI manager's AvocetHFSync service.
To successfully perform this process, you should be familiar with
• Windows user accounts and management
• Distributed Component Object Model (DCOM) security settings
• Windows registry
• Windows domain group policy
Depending on your implementation and security policies, you can define non-administrative users that
run in the context of:
• local system account
• non-domain member computer
• domain member computer
The following table outlines the workflow of the non-administrative user running on the local system
account:

1 Define a non-administrative user.

2 Apply DCOM security settings to the user.

3 Assign the non-administrative user Full Control to the Apis Configuration subfolder. (This is optional, depending
on whether you want the non-admin user to update APIS configuration settings.)

4 Grant the non-administrative user Full Control to the Apis registry entries.

The following table outlines the workflow of the non-administrative user running on a non-domain or
domain member computer:

1 Define a non-administrative user.

2 Apply DCOM security settings to the user.

106 Avocet High Frequency Infrastructure

3 Assign the non-administrative user Full Control to the Apis Dbs subfolder.

4 Grant the non-administrative user Full Control to the Apis registry entries.

5 Assign the non-administrative user account to the DCOM object APIS service.

6 Apply COM security permissions to Apis services.

If the non-administrative user runs under a domain member computer, then keep in mind that the
computer's security settings are controlled through domain controllers. Ensure that the domain policy
does not override the user settings. After you complete the configuration of the non-administrative
user who runs under a domain member computer, restart the computer. The restart prevents the
domain policy from overriding the user settings.

Define a non-administrative user for Apis services

You can define a non-administrative user account and grant it permission to run Apis-related services.
Because user account and group definitions are specific to a company's IT and security policies, a
generic procedure is presented that you can use as a guideline. The steps may differ from one Windows
version to another.
In this procedure, you define a standard user that you assign to the Users or similar non-administrative
group. Then you grant log-on permission for the standard user to the Apis-related services ApisHive,
ApisHoneyStore, and ApisOpcHda.

1. In the Control Panel, choose User Accounts > Give other users access to this computer to
launch the Advanced User Accounts Control Panel program.

Note: Depending on your access path, you may also need to select Manage User Accounts
to launch the panel.

The User Accounts dialog is displayed.

2. Click the Advanced tab in the User Accounts dialog.
3. Under the Advanced user management heading, click Advanced.
The Users and Groups window is displayed.
4. To add a new user, do the following:
a) Right-click the Users folder, and choose New User... .
The New User dialog is displayed.
b) Enter the user name and password information.

Note: If the user is assigned to a non-domain or domain member computer, select the
Password never expires check box.

c) Save and close New User dialog and the Users and Groups window.
d) To check the permission of the newly created user, in the User Accounts window select the
user name, click Properties, and click the Group Membership tab to verify that the Standard
user option is selected.

107
 5. Launch the Services window.
6. For the ApisHive, ApisHoneyStore, and ApisOpcHda services, grant log-on permission for the
standard user:
a) Right-click the service name to display the flyout menu, and choose Properties.
b) In the Properties dialog, choose the Log On tab.
c) Specify a log-on account type.
• If the services run on a local system account, select Local System account.
• If the services run on the non-administrative account, select This account, and choose Browse.
Next, in the Select User dialog, specify the non-administrative account, and click OK. Then
enter and confirm a password for the non-administrative account, and click OK.

Apply DCOM security settings to the non-administrative user

This task shows how to set your DCOM security settings for the non-administrative user or group in
the Component Services window.
In defining the DCOM security settings, you specify
• local and remote default access permissions to applications
• local and remote launch and activation permissions for applications that enforce their own permissions

1. Enter dcomcnfg.exe in the search field of the Windows Start menu to locate the dcomcnfg.exe
executable file.
2. Double-click dcomcnfg.exe to launch the Component Services window.
3. In the Component Services window, open the Component Services node to display the Computers
folder.
4. Open the Computers folder to display the My Computer icon.
5. Right-click the My Computer icon to display the flyout menu, and choose Properties.
6. Select the COM Security tab.

108 Avocet High Frequency Infrastructure

 The Access Permissions and Launch and Activation Permissions headings are displayed. You are
going to set the default and custom permissions for each.

Note: If the Edit Limits... button is grayed out, update your security policy, specifically the
DCOM: Machine Access Restriction in Security Descriptor Definition Language (SDDL)
syntax policy.

7. Click Edit Default... for Access and Launch and Activation Permissions, and make your
computer-wide default security settings for the non-administrative user or group.
Option Description
Access • If the Apis services are accessed from the local computer, select Local Access.
• If the Apis services are accessed from a remote computer by the non-administrative user or
group, select both Local Access and Remote Access.

Launch and Activation • If the Apis services are accessed from the local computer, select Local Launch and Local
Activation.
• If the Apis services are accessed from a remote computer by the non-administrative user or
group, select Local Launch, Remote Launch, Local Activation, and Remote Activation.

8. Click Edit Limits... for Access and Launch and Activation Permissions, and make your security
settings for the non-administrative user or group. These settings apply to applications that enforce
their own permissions.

109
 Option Description
Access • If the Apis services are accessed from the local computer, select Local Access.
• If the Apis services are accessed from a remote computer by the non-administrative user or
group, select both Local Access and Remote Access.

Launch and Activation • If the Apis services are accessed from the local computer, select Local Launch and Local
Activation.
• If the Apis services are accessed from a remote computer by the non-administrative user or
group, select Local Launch, Remote Launch, Local Activation, and Remote Activation.

9. In the COM Security tab, click Apply and OK to save the settings.

Define the permissions for DCOM objects

After establishing permissions for the group, you next define the permissions for the particular DCOM
objects. In this case, they are the ApisHive and your corporate historian.

1. Open the My Computer node to display the directory folders, and select the DCOM Config folder
to display the DCOM objects.
2. Right-click the ApisHive object and choose Properties from the flyout menu. The ApisHive
Properties dialog is displayed. Click the Security tab.

3. Click Edit.. for Launch and Activation Permissions to open the Launch and Activation Permission
dialog. Select the user group Everyone, and then choose the appropriate launch and activation
permissions. Click OK.
4. Click Edit.. for Access Permissions to open the Access Permission dialog. Select the user group
Everyone, and then choose the appropriate access permissions. Click OK.

110 Avocet High Frequency Infrastructure

5. Click Edit… for Configuration Permissions to open the Change Configuration Permission dialog.
Select the appropriate user group, such as Users, from the list, and then grant the group Full
Control permission. Click OK.
6. Click OK to close the ApisHive Properties dialog.
7. Right-click your corporate historian DCOM object, and choose Properties to display the <name
of corporate historian> dialog. Click the Security tab.

8. Repeat steps 3 through 6 and then click OK to close the <name of corporate historian> dialog.

Assign Full Control to Apis Configuration or Dbs subfolder

If the non-administrative user or group runs under the local system account and is allowed to make
configuration changes, then grant the user or group Full Control to the Apis Configuration subfolder.
If the non-administrative user or group runs on a non-domain or domain member computer, then grant
the user or group Full Control to the Apis Dbs subfolder.

1. Locate the Apis installation folder, and display the Configuration or Dbs subfolder: C:\Program
Files\APIS\Configuration or C:\Program Files\APIS\Dbs.
2. Right-click the Configuration or Dbs subfolder to display the flyout menu, and choose Properties
to display the Properties dialog.

111
 3. Click the Security tab, and then click Edit to display the Permissions dialog.
4. Click Add to display the Select Users, Computers, Service Accounts, or Groups dialog, specify the
non-administrative user or group, and click OK.
5. In the Permissions tab, select Full Control, click Apply, and click OK.
The user or group can access the Configuration or Dbs subfolder and make updates to the APIS
configuration files.

Grant Full Control to the Apis registry entries

You must give Full Control permission to the non-administrative user for the specified registry entries.

1. Execute regedit.exe to launch the Windows Registry Editor.

2. Locate the HKEY_LOCAL_MACHINE\SOFTWARE\Prediktor key.
3. Select the entry, right-click to display the flyout menu, and choose Permissions... .
The Permissions dialog is displayed.
4. In the Permissions dialog, select the non-administrative user or group from the list, and assign Full
Control to it.

Note: If you do not see the non-administrative user or group in the list, then click Add... to
open the Select Users, Computers, Service Accounts, or Groups dialog, locate the user
or group, and then click OK to add it.

5. Click Apply and then click OK.

6. Select the following entries, and assign Full Control to the non-administrative user or group in their
respective Permissions dialog:
• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application
• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\System

7. Close the Registry Editor.

Assign the user account to the Apis services

If you are implementing a domain or non-domain user account, instead of a local system account, you
must specify the account name for the Apis service, which is defined in the DCOM Config folder of
the Component Services window.

1. Enter dcomcnfg.exe in the search field of the Windows Start menu to locate the dcomcnfg.exe
executable file.
2. Double-click dcomcnfg.exe to launch the Component Services window.
3. In the Component Services window, open the Component Services node to display the Computers
folder.
4. Open the Computers folder to display the My Computer icon.
5. Unfold the DCOM Config subfolder, locate the ApisHive instance.
6. Select the ApisHive instance, right-click to display the flyout menu, and choose Properties.
The Properties dialog is displayed.
7. In the Properties dialog, change the user account selection from System account to This user.
8. Click Browse to open the Select User dialog, specify the non-administrative user, and click OK.
The user name is copied to the Properties dialog.
9. Enter and confirm the password for the non-administrative user, and click OK.
The specified non-administrative user account is assigned to the APIS service.

112 Avocet High Frequency Infrastructure

10. Repeat steps 6 through 9 for the ApisHoneystore and ApisOPCHDA instances located under the
DCOM Config subfolder.

Apply security permissions to Apis services

For domain or non-domain standard users, you define which launch and activation, access, and
configuration permissions that the users have on the Apis service.
The appropriate non-administrative user account must already be assigned to the Apis service before
you can specify permissions.
You can choose to apply computer-wide default or customized permissions for launch and activation,
access, and configuration. If you choose default permissions, the COM security default values are
applied to the service. In the Component Services console, you can view these values in the COM
Security tab of the My Computer Properties dialog. Refer to Adjust the DCOM security settings for
non-administrative user.

1. In the Component Services console, open the My Computer node to display the directory folders,
and select the DCOM Config folder to display the DCOM objects.
2. Right-click the ApisHive instance and choose Properties from the flyout menu. The ApisHive
Properties dialog is displayed. Click the Security tab.

3. Determine whether you want to apply custom or default permissions to the selected service.
Option Description
Custom Click Edit to launch the dialog for the selected permission.
Default The Edit button is greyed out. The default values are taken as defined on the COM Security
tab on the My Computer Properties dialog.

4. To apply custom settings, follow these steps:

113
 a) Click Edit next to the permission type: launch and activation, access, or configuration.
b) In the corresponding Permission dialog, select the non-administrative user or group.

Note: If you do not see the non-administrative user or group in the list, then click Add...
to open the Select Users, Computers, Service Accounts, or Groups dialog, locate the
user or group, and then click OK to add it.

c) Refer to the following table for guidelines on which permissions to allow:

Option Description

Launch and Activation • If the Apis services are accessed from the local computer, select Local Launch and Local
Activation.
• If the Apis services are accessed from a remote computer by the non-administrative user or
group, select Local Launch, Remote Launch, Local Activation, and Remote Activation.

Access • If the Apis services are accessed from the local computer, select Local Access.
• If the Apis services are accessed from a remote computer by the non-administrative user or
group, select both Local Access and Remote Access.

Configuration Your selection here depends on your company's IT and security policies. For special
permissions or advanced settings, click Advanced to display Advanced Security Settings for
Registry Value dialog. From this dialog, you can add users and edit permissions for each user
or user group.

5. Save and close the dialogs until you return to the DCOM Config subfolder of the Component
Services console.
6. Repeat steps 2 through 5 for the Apis service instances ApisHoneystore and ApisOPCHDA.
7. If your non-administrative user is running under a domain member computer and you have completed
all configuration procedures, restart the computer to prevent the domain group policy from overriding
your user settings.

Appendix 3: Install and uninstall Apis components (manual procedure)

This section describes the manual procedure for installing Apis. You typically perform this procedure
when you have copied the Apis folder to a target system where you want to set up an Apis corporate
historian to connect with the Avocet HF store residing on a separate source system.
The manual steps include
• launching the executable and completing the wizard
• starting services
• installing a license if needed
• uninstalling Apis
The APIS Foundation x64 Setup executable contains 32- and 64-bit versions of the ApisHive OPC
UA server. In all cases, the 64-bit versions of the components are installed on 64-bit operating systems.
Any custom assemblies are installed in the \bin subdirectory of the APIS installation folder.

Install the Apis components

This task shows how to install the Apis components manually.

1. Go to the APIS subfolder to locate the executable APIS Foundation x64 Setup.exe.
2. (Optional) Before launching the executable, review the documentation.
3. Double-click the APIS Foundation x64 Setup.exe executable file to start the installation wizard.

114 Avocet High Frequency Infrastructure

4. In the Select install directory screen, accept the default directory path or click Browse to choose
another folder. In most use cases, you accept the default directory path. Click Next.
5. In the Set ApisHive Service Startup Type screen, select the method for starting the ApisHive services
ApisOPCHDA, ApisHoneyStore, and ApisHive.
The Automatic option is the recommended selection.
6. Click Next. At the confirmation screen, click Confirm to launch the installation.
7. At the completion screen, click Done.
8. In the Set ApisHive Service Startup Type screen, accept the manual default startup option or choose
Automatic. Click Next.
9. Click Confirm to start the installation routine.
A screen is displayed with a progress bar that tracks the course of the installation. When the setup
is complete, a new screen opens.
10. Click Done to exit the installation routine.
After the installation completes successfully, the Apis services ApisHoneyStore. ApisOPCHDA,
ApisHive are installed as local services and started automatically.

Add the Apis software license manually

The APIS Foundation components look for the Schlumberger license file or licensing server. This task
shows how to add the Apis software license manually in the event the HFI Manager connection fails
to generate it.

1. In the search field of the Windows Start menu, enter Environment Variables to open the
Environment Variables dialog.
2. In the System variables pane, click New… to open the New System Variable dialog.
3. In the Variable name field, enter SLBSLS_LICENSE_FILE.
4. In the Variable value field, enter the port number and fully qualified domain name of your licensing
server. Alternatively, you can enter the full path to the licensing file.
5. Click OK to return to the Environment Variables dialog.
6. Click OK to close the Environment Variables dialog.

Uninstall APIS Foundation

This task shows how to uninstall the APIS Foundation. If the Apis instances are not completely removed,
this task also shows which registry key to delete.
Stop all running Apis services by opening the Windows Services window and locating the Apis services.

To stop the services manually, right-click the entry and choose Stop from the flyout menu.
Save all customized Apis configuration files and data.

115
 Whenever you upgrade your APIS Foundation installation, you must also upgrade and reinstall your
Avocet files. The APIS application has dependencies on certain Avocet files, which must be maintained
for the upgrade to succeed.

1. Open Windows Control Panel > Programs and Features, right-click the APIS Foundation x64
7.n entry, choose Uninstall.
The Uninstall wizard is launched.
2. Click Next.
3. At the Permanent removal of ApisHive instances screen, accept the default option (Keep all
instances) or choose Remove all instances.
If you are upgrading to a new version, choose the default Keep all instances option.
By removing all instances, you delete all entries related to the APIS Foundation installation.

Caution: Before deleting any configuration or historical data files, consider saving them to
a backup media device or different location on the local system.

4. Click Next.
5. At the confirmation screen, click Confirm to launch the uninstallation process.
If APIS instances are not completely removed, you can run the regedit.exe executable file to launch
the Registry Editor. Delete the following registry key:
• HKEY_LOCAL_MACHINE\SOFTWARE\Prediktor\Apis

Appendix 4: Security guidelines and technologies

As an alternative to the out-of-the-box security already packaged in the Apis deployment, you can
manually configure a security implementation for your high frequency components.
Before doing so, it is strongly recommended that you confer with your IT security administrator before
implementing a custom security configuration for the network nodes where your high frequency
components reside.
In your custom implementation, you would secure the nodes and the traffic between the following
high-frequency components:
• corporate historian and Avocet HF store
The following diagram presents a high-level overview of a security configuration. Each box represents
a node.

116 Avocet High Frequency Infrastructure

Using authentication methods and encryption, you configure your security settings on both the source
and destination targets so that inbound and outbound traffic is properly filtered.
Taking into account business and IT requirements, your IT security administrator can choose from
multiple data transmission encryption technologies.
These guidelines use the Internet Protocol Security (IPsec) technology as a basis for a walkthrough
example. IPsec is just one approach for implementing your security configuration. This walkthrough
example is not prescriptive. Your implementation will differ based on your IT security guidelines and
your choice of encryption technology.

Authentication and encryption

When defining your security policy, you set up the authentication method that controls the users or
systems that have access to the data.
The choices for authentication method are described in the following table:

Authentication method Description

Active Directory The Windows Active Directory domain service is the preferred method. It supports Lightweight
Directory Access Protocol (LDAP) and the Kerboros V5 protocol.

Public key certificates Certificates from a certificate authority are another option, but they are not recommended
because they have expiration dates, meaning they are valid only for a set period of time.
Constantly renewing certificates can become costly if you purchase them from a security vendor.
Performance sometimes drags because data encryption can be slow.

Preshared key The preshared key is shared among the different systems and is secret. It does not require the
Kerboros protocol or a public certificate. All users who use the preshared key must manually
configure their IPsec settings to support the preshared key. The preshared key can be encrypted
through a Diffie-Hellman key exchange.

You also encrypt the data using the preferred encryption tool (IPsec is used as an example). Your IT
administrator should approve both the authentication method and encryption tool.

Inbound and outbound firewall rules

When setting up your security configuration, you define a security policy and then assign firewall rules
that enforce the policy.
For the Avocet HF store, you specify an inbound firewall rule that blocks unsecured communication
originating from any external IP address that is destined for the server's IP address.

117
 On the client side, you specify an outbound rule that blocks unsecured communication originating from
the client's IP address and that is destined to the IP address of the server.

Establish the security policy

This procedure tells how to launch the New IP Security Policy Properties dialog.

1. Launch the Windows Local Security Policy window.

2. Right click IP Security Policies on Local Computer to display the flyout menu, and then choose
Create IP Security Policy... to launch the IP Security Policy Wizard.

118 Avocet High Frequency Infrastructure

3. Click Next, and enter a name and description for the policy. Then click Next again.
4. At the Requests for Secure Communication dialog, click Next without selecting the check box
because the default response rule does not apply.
The Completion dialog is displayed.
5. At the Completion dialog, verify that the Edit Properties check box is selected, and click Finish.
The New IP Security Policy Properties dialog is displayed.

119
 Note: Do not select the default rule because it only applies to earlier Windows versions.

Add security policy properties

This procedure tells how to set up the initial properties for the security policy.

1. In the New IP Security Policy Properties dialog, click Add... to launch the Security Rule Wizard,
and then click Next to display the Tunnel Endpoint dialog.

120 Avocet High Frequency Infrastructure

2. Select the option This rule does not specify a tunnel, and click Next to display the Network
Type dialog.

121
 3. Choose All network connections, and click Next to display the IP Filter List dialog.

122 Avocet High Frequency Infrastructure

4. If no appropriate filter list is displayed, click Add... launch the IP Filter Wizard. Otherwise, click
Next to display the Filter Action Wizard.

Add an IP filter
IP filters and filter actions are inclusive filters. That is, you filter for the specified property; you do not
filter out.

1. At the IP Filter Wizard , click Next to display the IP Filter Description and Mirrored property
dialog.

2. Enter a description of the filter, and choose the Mirrored check box. Then click Next to display the
IP Traffic Source dialog.
3. In the IP Traffic Source dialog, choose Any IP Address from the Source address drop-down list,
and click Next to display the IP Traffic Destination dialog.
4. In the IP Traffic Destination dialog, choose My IP Address from the Destination address
drop-down list, and click Next to display theIP Protocol Type dialog.
5. In the IP Protocol Type dialog, choose Any from the Select a protocol type drop-down list, and
click Next.
6. Click Finish to close the wizard and return to the IP Filter List dialog.

123
 7. Review the entries, and click OK to display the New IP Filter List entry.

8. Next, add the filter action to your IP filter list.

Add the filter action

This procedure tells how to add a filter action to your filter list.

1. In the IP Filter List dialog, click Next to display the Filter Action dialog, and then click Add to
launch the Filter Action Wizard.
2. In the Filter Action Wizard, click Next to display the Filter Action Name dialog.
3. In the Filter Action Name dialog, choose Negotiate Security, and then click Next to display the
Communicating with computers that do not support IPsec dialog.

124 Avocet High Frequency Infrastructure

4. Choose theDo not allow unsecured communication option, and click Next to display the IP
Traffic Security dialog.

125
 5. Choose the Integrity and encryption security method.
6. Click Next and then click Finish to complete the Filter Action Wizard.
You are returned to the Filter Action dialog, with the just created filter action listed.
7. Next, you specify an authentication method.

Choose the authentication method

This procedure tells how to select your authentication method.

1. In the Filter Action dialog, select the filter action entry you want to enable, and click Next to display
the Authentication Method dialog.

2. Choose your authentication method. Refer to Authentication and encryption.

3. Click Next to complete the Security Rule Wizard.
You are returned to the New IP Security Policy Properties dialog.
4. Click OK to save the policy settings.
5. Next, assign the security policy to the local computer.

Assign the IPSec policy

This procedure tells how to assign the IPSec policy to the local computer.

1. Launch the Local Security Policy window, and double-click the IP Security Policies on Local
Computer folder to display the available policy or policies, as shown in the following example:

126 Avocet High Frequency Infrastructure

2. In the list of security policies, right click the policy you want to assign. In the flyout menu, choose
Assign.
If an existing local policy is already assigned, then the new policy assignment takes precedence,
and the existing policy becomes unassigned.
If a policy is assigned at the domain or Active Directory level, then the domain or Active Directory
policy overrides the local security policy. You see a message similar to the following:

3. Next, you assign the inbound firewall rule.

Define inbound firewall rule

You define and apply an inbound firewall rule to control incoming traffic.

1. Launch the Local Security Policy window, open the Windows Firewall with Advanced Security
folder, and then expand the Windows Firewall with Advanced Security - Local Group Policy
Object.
The Inbound Rules entry is displayed.

127
 2. Right click Inbound Rules to display the flyout menu, and choose New Rule... to launch the Rule
Type dialog of the New Inbound Rule Wizard.

3. Select the rule type (in this example, Custom), and click Next to launch the Program dialog.

128 Avocet High Frequency Infrastructure

4. Choose All programs, and click Next to display the Action dialog.

5. Choose the Allow the connection if is secure action, and click Customize... .
The Customize Allow if Secure Settings popup dialog is displayed.

129
 6. Choose the Require the connections to be encrypted setting, but do not select the Allow the
computers to dynamically negotiate encryption. Then click OK to return to the Action dialog.
7. Click Next to display the Users dialog, but do not make any selections. In the Users dialog, click
Next to display the Computers dialog, but do not make any selections. Finally, click Next to display
the Profile dialog.

130 Avocet High Frequency Infrastructure

8. Select all three profiles (Domain, Private, and Public), and click Next to display the Name dialog.
9. Enter a unique name and corresponding description of the inbound rule. Then click Finish to add
the rule.
The rule name and its visible properties are displayed in the right-hand pane of the Local Security
Policy window. The following example rule shows a subset of its available properties.

131
 Note: You can select which properties (columns) of the rule to display by choosing View >
Add/Remove Columns... from the right-click flyout menu of Inbound Rules in the Local
Security Policy window.

You next verify that the firewall rule definition is complete.

Complete inbound firewall rule definition

This procedure tells how to complete the firewall rule definition and update any properties of the rule.

1. To complete the firewall rule, verify in the Local Security Policy window that the following properties
(columns) have the corresponding values assigned to them.

Property Value

Allowed Users Any

Allowed Computers Any

Interface Type All interface types

Edge Traversal Block edge traveral

2. To update a rule property, right click in the property column display the flyout menu, choose
Properties.
The Test Rule Properties dialog is displayed with the General tab selected.

132 Avocet High Frequency Infrastructure

3. Consider these updates:
Option Action
To authorize access to any user... Click the Users tab and ensure that the Authorized users and Exceptions
check boxes are deselected.
To authorize access to any computer... Click the Computers tab and ensure that the Authorized computers and
Exceptions check boxes are deselected.
To specify that the firewall rule applies Click the Advanced tab, and then
to all interface types...
1. in the Interface types panel, select Customize... to display the
Customize Interface Types pop-up dialog;
2. select All interface types, and click OK to close the pop-up dialog.

To block unsolicited inbound packets... Click the Advanced tab, and in the Edge traversal panel, choose Block
edge traversal from the drop-down menu.

4. After you have verified your changes, click Apply and then OK to close the Test Rule Properties
dialog.

133
 The new property values are displayed in the corresponding columns.

Implement IPsec on the client

On the client side, you define the IPsec policy and assign outbound firewall rules by following the
walkthrough example guidelines, but with two exceptions when adding an IP filter.
The exceptions are the client's Source address value and Destination address value.

1. Follow the guidelines as described from Establish the security policy to Assign the IPsec policy,
but note the following exceptions in Add an IP Filter:
a) Refer to the following example of an IP Filter Properties dialog that depicts values for the
client's source and destination addresses:

b) For the client's Source address, specify My IP Address instead of the server's Any ID Address.
c) For the client's Destination address, specify the actual IP address of the server. (The server
uses the value My IP address to point to its own location.)
2. In the Local Security Policy window, define and assign outbound firewall rules using the guidelines
in Define the inbound firewall rule and Complete the inbound firewall definition.
3. After defining the security policy and firewall rules on the server and client, test your security settings.

Test your security settings

You have multiple ways to verify your security settings. This topic provides a basic guideline.

134 Avocet High Frequency Infrastructure

 1. Check with the IT security administrator for your company's or organization's rules for security
compliance.
2. Try this basic test:
a) Connect to your configured, secure server from an unauthorized client system or an unauthorized
LDAP account.
An unauthorized error message should be returned: for example, an unauthorized LDAP account
typically returns a 401 unauthorized error.
b) If the unauthorized client or account can secure a connection, then you must review your security
configuration.
Always confer with your IT security administrator when verifying security settings.

Appendix 5: Install and launch the HF Player

The HF Player is a collection of data files that you execute manually through a batch process to simulate
real-time, high-frequency SCADA data. This task shows how to install and launch the HF Player.
During the execution of the batch file, modules and data are loaded into the corporate historian and
made available to the Avocet HF Store.

Note: The HF Player utility is reserved for use by the Avocet deployment team.

The HFPlayer is designed to run on the same system where your corporate historian is installed.
To see the results of the data load and simulation run, you should have access to and be familiar with
the Apis Management Studio feature.

1. Obtain the HFPlayer.zip from your deployment team.

2. Extract the file contents to your C:\ drive.
The folder structure is displayed as shown:

Folder/File Description

Data This folder contains the data files (CSV format) from different modules.

Player This folder contains the executable and APIS and OPC modules that are required to
launch the player and load the data.

Run.bat The batch file that loads the modules and starts the data run. Its script is as follows:

Tip: To ensure the batch file works correctly, maintain the folder structure exactly as packaged
in the zipped file.

3. (Optional) To modify the batch file Run.bat, review the following information.
The batch file Run.bat script is shown below:
@ECHO OFF
IF "%1"=="" GOTO USAGE
Player\HFPlayer.exe /create /dir:Data /frequency:15 /url:opcda://Prediktor.ApisOPCServer.%1
/progid:Prediktor.ApisLoader.%1

135
 GOTO EOF
:USAGE
ECHO Usage: Run.bat ^<InstanceName^>
ECHO Example: Run.bat CorporateHistorian1
PAUSE
:EOF
Use the following table as guidelines in determining which properties to edit.
Property Description

Frequency Determines the refresh rate, in seconds, in which the simulated data points are initiated

<InstanceName> The name that you assigned to your corporate historian

4. Before launching the batch file, verify that the following components are running:
• High frequency infrastructure manager service
• Avocet HF Store
• corporate historian

5. Execute the batch file from the command line.

a) Change directory path (cd) to the directory where the HF Player contents were extracted: for
example, cd c:\HFPlayer
b) Enter the batch file command with the name of your corporate historian: for example,
c:\HFPlayer>Run.bat CorporateHistorian1
Selected options: (use /? to view available)
Directory: Data
Frequency: 15
Create: True
Module: Worker
ProgID: Prediktor.ApisLoader.CorporateHistorian1
Connecting to opcda://Prediktor.ApisOPCServer.CorporateHistorian1...
The modules are loaded and the tag data is added to the corporate historian. The data simulation
run begins, as shown in the following extract from the Windows Command Prompt:

136 Avocet High Frequency Infrastructure

 If the display text ends with “Playing data. Press any key to exit… ,” then the data simulation is
successful.
To ensure the data values change dynamically, do not close the Windows Command Prompt
window during the session.

6. Because the simulated data only runs during the open session, execute the batch file for each
session you want to run the simulated data.

In addition to running the simulated data, the batch file creates modules and accompanying items,
both of which you can display in the Apis Management Studio, as shown in this extract from the Apis
Management Studio after the data has been loaded:

137
 Each item contains tag mapping definitions for different transaction properties, as seen in this Excel
excerpt of a CSV file for an item taken from the Data subfolder:

You can also open the same data file in Notepad and view its contents, as seen in this example:

138 Avocet High Frequency Infrastructure

 Aside from creating modules and items for the corporate historian, the HF Player batch file also creates
a historian database instance in the Apis Honeystore and an accompanying Apis logger module that
captures the tag values:

Appendix 6: Troubleshooting
Problems in the high frequency implementation can result from connectivity issues, sync issues,
licensing issues, and so forth.
You can check for connectivity issues by installing an OPC client like the UaExpert to check security
and browse the nodes of the Avocet HF store and the corporate historian. You can check connectivity
with the corporate historian through the Apis Management Studio.
You can monitor the synchronization process through the messages that the AvocetHFSync service
logs in the Windows Event Viewer console. You can monitor tag values dynamically through the Apis
Management Studio.

Access the Windows Event Viewer

Use the Windows Event Viewer to view informational, error, warning, and critical messages about
high frequency operations.
Event messages related to high frequency operations usually fall under the administrative and
application categories in the Event Viewer. The high frequency sources that log the events include
the following:
• ApisHive.TF_CorporateHistorian
• ApisHive
• HFIManagerDiagnostics
• AvocetHFSync
• HFPrepareSyncProcess
• nameOfCorporateHistorian. logger

139
 • ApisHive.Calcs
• Prediktor LicenseManager

1. To launch the Event Viewer, type event viewer in the Start menu’s search field and press Enter.
The Event Viewer console is launched, as shown in this screenshot example:

2. Scroll the event category, typically Administrative Events, until you find the event source and
message associated with the issue.

Schlumberger licensing server does not start

On single-machine installations that include the Avocet HF Store, you may encounter a licensing issue
in which the licensing server does not start. This task shows how to resolve that issue.
Follow these steps to work around this issue:

1. Remove the system variable SLBSLS_LICENSE_FILE.

2. Start the Schlumberger Licensing server.
3. Re-add the system variable.

The Avocet HF Store can then read the system variable and start up successfully.

Check the status of the AvocetHFSync service

This topic summarizes some troubleshooting tips for checking the status of the AvocetHFSync service.
You should monitor the AvocetHFSync service through the Event Viewer. A sampling of error messages
is listed below for when the AvocetHFSync service cannot be started:
• ... NoHFStoreDefined
• ... Either the license server is unreachable or there are no license features available
• ... Authentication failed for user userName
• ... Error 5: Access is denied

1. If you receive the error message that no Avocet HF store is defined, then try the following:
• Verify in your Connection Manager that you have an Avocet HF store instance with a valid
connection string.
• Browse the ApisHive node in the Connection Manager and/or in the UaExpert OPC client.
• Check whether the connection's security settings are compatible.

2. If you receive the error message regarding the license server, then try the following:

140 Avocet High Frequency Infrastructure

 • Verify that the license server is running.
• Check for any blocking issues, such as firewalls or antivirus software.
• In the HFIManager.exe.config file, ensure that the ConfigDir key points to the correct path of the
AppConfig.xml, where the license server path is defined under <licenseFilePath>.

3. If you receive the error message Authentication failed for user userName, then try the following:
• Open the HFIManager.exe.config file, and check whether the SystemUser and SystemPass keys
match the credentials used to log into the application ID.
• In the HFIManager.exe.config file, ensure that the ConfigDir key points to the correct path of the
AppConfig.xml.

4. If you receive the Error 5: Access is denied message, then try the following:
• Verify that the user account is defined on the system and has the proper privilege (typically
administrator privilege).
• In the HFIManager.exe.config file, verify that the correct ApplicationId key is defined and that the
ConfigDir key points to the correct Config path.
• Verify that the AppConfig_projectLayer.xml file resides in the Config directory specified by the
ConfigDir key.

Install the Unified Automation UaExpert client

After you have configured the Avocet HF store and HFI manager and successfully generated the trust
certificates, you can test your connectivity by running the UaExpert client. This task shows where to
download the package and get the installation instructions.
See the non-Schlumberger website for the download package and its installation instructions.

Verify OPC UA server connectivity in the Apis Management Studio

You can verify OPC UA server connectivity through the Apis Management Studio.

1. Launch the Apis Management Studio and connect with your ApisHive instance (Avocet HF Store).
2. Select the corresponding TF_CorporateHistorian module instance to display the list of items.
3. Locate the items TF_CorporateHistorianinstance.#Session-State# and
TF_CorporateHistorianinstance.#Subscription-State#.
4. Verify that their values read is_connected.

Monitor tag values in Apis Management Studio

You can monitor tag values in Apis Management Studio.

1. Launch the Apis Management Studio and connect with your ApisHive instance (Avocet HF Store).
2. Select the corresponding TF_CorporateHistorian module instance to display the list of items.
3. Locate the tag whose value you want to monitor.
It is displayed in the Adaptive Items List, as shown in this example screenshot:

141
 4. Monitor the value as it changes dynamically to note any unusual changes.

142 Avocet High Frequency Infrastructure

Working with data flow configuration and
alarms
This section shows how to work with the data flow configurations and alarms.

How to work with the Data Flow screen

This section shows a diagram of the hierarchy of how data is collected and read, explains the difference
between historical data and real-time data in the Avocet context, and discusses configuring the data
flow.
The Data Flow screen is designed to handle real-time and historical data collection in a scenario where
you have defined the following components:
• High frequency infrastructure manager service (HFIMS)
• Avocet OPC UA server (placeholder in node hierarchy)
• Avocet High Frequency (HF) Store
• A corporate historian that uses the OPC UA protocol
In this hierarchy, the data collected by the corporate historian is read by (or “mirrored” by) the Avocet
HF Store. The following diagram shows the relationships among components:

Data flow configuration applies to any Avocet item type that is subject to tag mapping. You can select
these item types from the Wells and Facilities node in the Navigation Tree. The item types that are

143
 subject to tag mapping extend to organizational units, geographical units, routes and stops, subsystems,
and desks.

Real-time and historical data in the Avocet context

In the Avocet context, real-time data can be considered high-frequency data transmitted by a corporate
historian with frequencies between one sample per one second and one sample per 15 minutes.
High-frequency data can be aggregated into lower frequencies at the Avocet HF Store level—for
example, hourly or daily intervals—and then passed to the Avocet database. Historical data refers to
data that is stored in a database, a data warehouse, or some kind of data store.

Configuration of data flow

The Data Flow screen is designed to pass real-time, raw data tags from a corporate historian to the
Avocet HF Store, which converts the raw data into an Avocet-compatible format. The data is typically
transmitted at a high frequency.
The decision to use the Data Flow screen hinges on whether you have chosen to implement the Avocet
HF Store.
Consider using the Avocet HF Store if
• you have a corporate historian that uses both the OPC Data Access specification for real-time data
and the OPC Historical Data Access (HDA) specification for historical data access
• you want to use the features of the HF Store, including real-time calculations, alarms, email
notifications, and data cleansing through clamping limits

Note: If you are loading SCADA data from an OPC UA source system other than a corporate
historian or if you are not interested in the Avocet HF Store features, then use the Tag Mapping
screen to define and load the tag maps that bind values to selected transactions and properties.
In the Navigation Tree, see Administration > Interfaces > Measurement > Tag Mapping.

Use the Data Flow screen to

• map corporate historian tags with specific Avocet items, transaction types, and properties
• specify data-loading options such as the aggregation method for the Avocet HF Store and the display
unit of measure for the tag values sent by the corporate historian
• set read or read/write access permission to tag map definitions

Before you begin

This topic summarizes what you need to do before configuring the data flow workflow.
Ensure that you have installed and configured
• High frequency manager infrastructure service (HFMIS)
• APIS Foundation components
• Your corporate historian
Refer to the Help topic High frequency infrastructure: components and implementation for more
information.
Follow the setup instructions for your corporate historian. Be sure that it contains the tag definitions
for mapping Avocet items and transactions with the values retrieved from the corresponding sensors.
You can load corporate historian tags into Avocet through the

144 Avocet High Frequency Infrastructure

 • Load to Avocet option in the Tag Mapping screen associated with the Connection Manager feature
(Administrator > Interfaces > Measurement > Tag mapping)
• Data Loader screen under Interfaces > Data Loader in the Avocet client
• Data Loader screen under Data Tools > Data Loader in the Avocet Configuration Tools utility
(ConfigTools.exe)

Note: Depending on your system’s processor (32-bit or 64-bit), you may need to run the 32-bit
version of the Avocet client (AvocetVM32.exe) or the Avocet Configuration Tools utility
(ConfigTools32.exe) to use the loader functions in the Avocet client or Avocet Configuration
Tools utility.

• Ensure that you have the proper privileges to run the synchronization process and other APIS-related
services. You must be logged into the Avocet client with administrator privilege. Alternatively, if you
do not have administrator privilege, adjust your DCOM security settings so that you can run
synchronization and other APIS-related services. See the High Frequency Infrastructure Manager
Service help topic for more information.
• Define the Avocet HF Store and the corporate historian in the Connection Manager of the Avocet
client. See the Connection Manager documentation.
• Verify that the Avocet HF Store, corporate historian, and the high frequency infrastructure manager
service (HFIMS) are running.

Access the Data Flow screen

This task shows how to access the Data Flow Configuration screen.
The Data Flow screen is a linked screen that you access from the ribbon toolbar of specific Item Editor
screens under Wells and Facilities in the Navigation Tree.

1. To access the Data Flow screen for an Avocet item, go to the Wells and Facilities node, select
the item to reveal its Item Edit screen.

Note: The Data Flow screen is not available to all items listed under the Wells and Facilities
node.

2. In the ribbon toolbar under Home > Linked Screens, select Data Flow.
The Data Flow screen for the item type is displayed.

Data Flow screen compared with Tag Mapping screen

The Data Flow screen is designed to serve a specific high frequency workflow that involves the Avocet
HF Store.
You cannot access the Data Flow screen from the Navigation Tree, only from certain Item Editor
screens that have items already defined in their Navigator list.
The Data Flow screen referred to here is distinct from the Tag Mapping screen associated with the
Connection Manager feature (Administration > Interfaces > Measurement > Tag mapping). Do not
confuse the two because they serve different purposes. The Navigation Tree node of the Tag Mapping
screen is shown below:

145
 Although they share similar features, the Data Flow screen addresses a specific high-frequency
workflow that uses the Avocet HF Store. If your data sources include a data historian or some other
OPC UA source, but you are not using the Avocet HF Store, you specify and load tag data in the
Administration > Interfaces > Measurement > Tag Mapping screen. See the Connection Manager
documentation.

Note: Tag mapping is not required if your data source is the Avocet database only.

Map historian tags to Avocet items

Tag mapping is the process of linking real-time or historical data points originating from a data source,
such as a data historian server, with specific Avocet items, transaction types, and transaction properties.
This section discusses various aspects of tag mapping.
In the Data Flow screen, you specify the transaction type and property from the Avocet database that
you want to bind to a tag value. When you make the transaction type and property selection, the Avocet
HF Store is automatically populated with a formatted tag that does not yet contain a value.You browse
the corporate historian tags that are available to the item, and select one to map to the transaction
type and property.
After you save the tag map, the real-time values from the corporate historian are stored in the
corresponding Avocet HF Store output tags after the AvocetHFSync process runs. The following
schematic, from the APIS Management Studio, shows the relation between the corporate historian
tag and the corresponding Avocet HF Store output tag:

The real-time values are then available to the database.

The following extract from the Data Flow screen shows the main components of a high-frequency tag
map. In this example multiple properties of the transaction type Meter Read for a multiphase meter
are mapped to tags from the corporate historian. Upon synchronization, their values are populated in
the corresponding Avocet HF Store tags.

146 Avocet High Frequency Infrastructure

 The following diagram illustrates the tag-mapping relationship among the components:

In this example, the tag map relation from physical data source (meter) to the database destination is
as follows:
Source real-time value   Corporate historian tag   Avocet HF Store tag   Database property

Check connectivity to the Avocet HF Store and corporate historian

Before you add tag maps, you should verify that you are connected with the Avocet HF Store and the
corporate historian.
To verify the connection, follow these steps:

1. Click Home > Tag Mapping Tools > Test Connection.

2. To view the results, select System > Status > View Status Pane.
The Status window is displayed.

Set up the Avocet item for data flow configuration

This task shows how to configure the items listed under the Wells and Facilities node in the Navigation
Tree of the Avocet client for high-frequency data collection.

147
 These items include the ones listed in the following screenshot:

1. In the Navigation Tree, under Wells and Facilities, select the Avocet item type whose transactions
and properties will be mapped to the corporate historian tag.
When you select Well and Facilities > <itemType>, the corresponding Item Edit screen is displayed.
In this example, a completion item is selected and its Item Edit screen is displayed.

148 Avocet High Frequency Infrastructure

2. Review the property descriptions of the listed items and make any changes. Click Home > Actions
> Save.
3. From the ribbon toolbar, click Home > Linked Screens > Data Flow to display the corresponding
Data Flow screen for the selected item type.

The Tag Mapping Tools tab in the ribbon toolbar contains the common menu options that apply
to the data flow configuration. The Linked Screens tab contains the link to the various Alarms
screens where you define alarm limits for selected transaction types and properties. The Templates
tab lets you apply existing .XML template files to the data flow configuration or save the current
configuration as its own template. .
You can click the Show details check box to display the full range of data columns, denoted by
check marks in the following extract:

149
How to map tags manually
This section shows how to map tags manually for high-frequency implementation without a data loader
and pre-existing tag mappings.
If you are entering new tag mappings for a high-frequency implementation, without a data loader and
pre-existing tag mappings, you typically enter the tag maps manually row by row.
Your workflow in the Data Flow screen looks similar to the one depicted in this following diagram:

If you want to create a high-frequency implementation for a corporate historian that uses the OPC UA
protocol and has its tag mappings already defined through the Administration > Interfaces >
Measurement > Tag Mapping interface, see How to add previously defined tag mappings to the Data
Flow Configuration screen.

Specify transaction and property in the Avocet database and populate HF Store tags
This task shows how to select the transaction and property in the Avocet database to map to a particular
corporate historian tag. The Avocet HF Store automatically generates a placeholder tag.

1. In the Navigator list, select the item to which the tag will be mapped.
2. In the ribbon toolbar, click Home > Tag Mapping Tools > New to open a blank row.
3. In the Transaction Type drop-down list, select the transaction type to which you are mapping the
corporate historian tag.
If a transaction type does not display, verify your database connection.
4. Select the specific transaction property of the transaction type for which the tag value is returned.
As soon as you specify a transaction property, the Name field for the Avocet HF Store is
automatically populated with a tag having the following format:
<targetItemName><transactionType>< transactionProperty>

150 Avocet High Frequency Infrastructure

 Upon synchronization, the Avocet HF Store tag stores the raw value of the corresponding corporate
historian tag in a format understandable to Avocet.

Map corporate historian tags with Avocet item and transaction properties
This task shows how to map a corporate historian tag with the Avocet item and transaction properties.

1. Under the Corporate Historian heading, click the Name field to display the Tag Browser window.
A summary view of the Tag Browser window is shown below. The top-level view presents the item
categories and corresponding browse node categories.

2. To view the available tags for an item, click the plus sign (+) next to the item category to reveal the
list of tags and associated browse nodes.
You can drill down into the nested categories of the individual tag definition to see its components
and their properties by clicking the remaining plus signs.You can use the Name and Node ID filters
to search for specific criteria.

151
 3. Select an appropriate tag for the item, transaction type, and transaction property. Ensure that it is
identified with the particular item whose transaction property to which you are mapping it. Click OK
to copy it to the Tag Name field under the Corporate Historian heading.
4. In the Unit Of Measure drop-down list, select the unit of measure that the corporate historian
records for the transaction property.
The listed units of measure should have corresponding Avocet storage units of measure. If an
Avocet storage unit of measure does not exist for the unit of measure recorded by the corporate
historian, then the Avocet administrator or deployment engineer should create one in the
implementation layer through the Type Editor in the Avocet Configuration Tools utility (Configuration
Editor Tools > Type Editor).
If no unit is selected from the display list, then a system default UOM is applied.
The Unit of Measure drop-down list is blank if the item’s transaction property does not have a unit
of measure code list associated with its property class. As a general reference, you can check the
property classes and their UOM lists in the Avocet Configuration Tools utility (Configuration Editor
Tools > UOM Editor options).
5. In the Tag Map Access drop-down column, choose Read or Read/Write.
The Tag Map Access selection indicates whether the specific tag mapping can be updated by the
setpoint API. A Read assignment means that the tag map cannot be modified, while a Read/Write
assignments means that the setpoint API can change the tag map. The default value is Read.
6. In the ribbon toolbar, you can click Home > Tools > Save to save the row, or if specifying additional
data-loading options, continue to the next topic.

152 Avocet High Frequency Infrastructure

Display additional data fields
When you select the Show Details check box, the Avocet HF Store and the corporate historian display
additional data fields.
When you select the Show Details check box, the Avocet HF Store displays the following fields:

• Node ID
• Time Offset
• Load to Avocet
• Tag Map Type
• Event Aggregation interval(s)
The corporate historian displays the following field: Node ID.

Complete detail data fields for Avocet HF Store and corporate historian
This task shows how to update the Time Offset field, use the Load to Avocet option, select the
aggregate computation method to apply, set how often the data from the HF Store is copied to the
Avocet database, and save the results.
The Node ID field refers to the node ID that stores the corresponding tag value from the corporate
historian. It is populated automatically after you select the corporate historian tag, save the record,
and the AvocetHFSync process is run. The node ID enables the Avocet HF Store to acquire the tag
data from the corporate historian.
The Node Id field for the corporate historian is populated automatically. The Node Id is written in the
format <namespace index>; <string identifier>: for example, ns=2;s=V|MPFM-2349.VX_Meter.VX_qo_lc.

1. In the Time Offset field, enter the time (in seconds) that you want to adjust the timestamps of the
incoming data from the corporate historian. The default value is zero.
To adjust the timestamp forwards, enter the positive numeric value without the sign. To adjust the
timestamp backwards, enter the numeric value with the negative sign (-).
To illustrate, if the data from the corporate historian originates in a different time zone, you can
enter an appropriate time offset value for loading it to the Avocet HF Store. For example, assume
your local time zone is US Central Standard Time and the corporate historian is located in a US
Mountain Time Zone. When preparing the incoming data for loading, you can enter the offset value
3600 to account for the time zone difference. Similarly, if the data originates from US Eastern
Standard Time, you would enter the offset value -3600 to account for the time zone difference.
2. Select the Load to Avocet option if you want to load the tag data received from the corporate
historian to the Avocet database.
3. You can specify an aggregation method to apply to the raw data received from the Avocet HF Store
over a period of time, usually to store it at a lower frequency in the Avocet database.
In the Tag Map Type drop-down list, select the aggregate computation method to apply to the
different values sent by the Avocet HF Store across multiple time intervals. The selected aggregation
method generates a single value from the multiple values that are loaded.

153
 Choose from among the following methods:
Tag Map Type Description

Average Data is weight averaged (it includes the standard deviation) as per the OPC 2.0 standards
from source frequency to the destination aggregation interval. For example, 60 records at 1
minute intervals would be aggregated to an hourly record using the weighted averaging method.

Copy Data is copied directly from the source at its sample frequency if the transaction type is an
event. All the tag values are copied, including the time stamp.

Note: When you choose Copy, leave the Event Aggregation Interval(s) field blank.

First The first data point encountered during data read in the aggregation interval is determined
and written as the destination value.

Last The last data point encountered during data read in the aggregation interval is determined
and written as the destination value.

Max Data is sampled at source frequency, and the maximum value during the interval is written
as the destination value. For example, the maximum value in 60 records would be the value
for the event aggregation per 1 hour.

Maximum Actual Time Data is sampled at source frequency, and the maximum value at the particular time is written
as the destination value.

Median Data is sampled at source frequency, and the median value is determined. The median is the
middle value of a set of data containing an odd number of values, or the average of the two
middle values of a set of data with an even number of values.

Min Data is sampled at source frequency, and the minimum value during the interval is written as
the destination value. For example, the minimum value in 60 records would be the value for
the event aggregation per 1 hour.

Minimum Actual Time Data is sampled at source frequency, and the minimum value at that particular time is written
as the destination value.

Value at Period End The value at the start of the aggregation interval is determined by interpolation and written as
the destination value. The difference between this and the First aggregation method is that
the final value depends on the sample value before the aggregation period begins and the
next sample value the application reads. In the case of the First method, it simply reads the
next sample value it encounters.

Value at Period Start The value at the end of the aggregation interval is determined by interpolation and written as
the destination value. The difference between this and the Last aggregation method is that
the final value depends on the next value after the aggregation ends and the last sample value
the application reads. In the case of the Last method, it simply reads the last sample value it
encounters.

4. In the Event Aggregation Interval(s) field, accept the default value (in seconds), or enter a different
interval value.
The Event Aggregation Interval(s) field indicates how often the data from the HF Store is copied
to the Avocet database.You can think of it as the destination frequency because it may be a different
value from the frequency at which the corporate historian transmits values.
It defaults to the value associated with the selected transaction type. For example, for the Daily
Meter Read transaction, it is 86,400 seconds (24 hours).
If you have chosen the Copy tag map type, leave this field blank.
5. Choose Home > Tag Mapping Tools > Save to save the record.

154 Avocet High Frequency Infrastructure

How to add previously defined tag mappings
If you have an existing corporate historian that uses the OPC UA protocol with tag mappings specified
in the Administration > Interfaces > Measurement > Tag Mapping screen, you can incorporate the
corporate historian into a high frequency implementation that uses the Avocet HF Store.
The procedure is essentially the same as the one described under How to map tags manually in the
Data Flow Configuration screen but with this exception: the Avocet HF Store’s tags are not automatically
populated.
To populate the Name field of the Avocet HF Store with its tag definitions, follow these steps:

1. In the Navigation Tree, select the item type under the Wells and Facilities node that has the tag
mappings from the corporate historian.
2. Access the Data Flow Configuration screen (Home > Linked Screens > Data Flow).
The tag mappings from the corporate historian should populate with their corresponding transaction
types and properties for the selected item. The Avocet HF Store tag Name column is blank.
3. To populate the Avocet HF Store Name column, choose Home > Tag Mapping Tools > Fill HF
Store.
The corresponding Avocet HF Store tags for the transaction types and properties should be filled
for every tag map entry of the item.
4. Choose Home > Tag Mapping Tools > Save.

Use templates to populate tag mapping entries

This section shows how to save an item's tag mapping entries as a template and how to apply an
item's tag mapping template to another item.
When making multiple tag mapping entries across several similar items on the Data Flow screen, you
can use the Home > Templates features to reduce repetitive data entry.
Use the Home > Templates > Save As Template menu option to save your current screen’s
Transaction Type, Transaction Property, and Avocet HF Store Tag Name entries for a selected
item. You save the data as an XML file (*.xml).
Use the Home > Templates > Apply Template menu option to copy the entries to a blank record for
an item of a similar type. You then only need to browse for and select the corresponding corporate
historian tags and specify any data loading options such as frequency and aggregation method.

Note: The XML markup that supports the template processing is in the
<implementationFolder>\AvocetVM\Config\HFConfig_base.xml file under the
<TransactionTemplateDefinition> node.

Save tag mapping entries as a template

This task shows how to save an item's tag mapping entries as a template.

1. In the Data Flow Configuration screen, open the item record containing the Transaction Type,
Transaction Property, and Avocet HF Store Tag Name entries that you want to save as a template.

155
 2. Choose Home > Templates > Save As Template to open the Save As dialog.
3. Specify a template name and directory location for the template, and click save it with the .xml
extension.

Apply a tag mapping template to another item

This task shows how to apply the tag mapping template of one item to the record of another item.

1. In the Navigation tree of the Data Flow screen, select the item that you wish to apply the existing
tag mapping entries to.
2. Click New to open a new record.
3. Choose Home > Templates > Apply Template to display the Open dialog.
4. Browse for and select the XML template that you want to apply, and click Open.
The relevant tag map entries are copied to the new record.
5. In the Data Flow screen, click Home > Tag Mapping Tools > Save to save the new record with
the template entries applied.

Mail settings, recipients, and groups

You can configure SMTP mail settings and specify mail recipients and mail groups to receive alarm
notifications.
A mail group is a container for the mail recipients. A mail recipient is a specific email address, Short
Message Service (SMS) gateway, or Multimedia Messaging Service (MMS) gateway. By defining
groups and notifications, you can assign alarm and other notifications to the responsible groups.
If implementing high-frequency alarms, you should specify mail recipients and groups who will receive
notifications when the alarm ranges have been exceeded. For example, if you have defined an alarm
range for the flow rate of a particular meter, and the rate falls outside the range, a notification can be
sent to the email address of an operator who belongs to the support group for the particular facility.

Note: The notification feature applies to high-frequency alarms. It is not enabled for alarms on
low-frequency or historical data.

One email or messaging recipient can belong to multiple groups. The relation between the groups and
the recipients is many-to-many.

156 Avocet High Frequency Infrastructure

 Before you define groups and recipients, define your SMTP mail settings for the notification destination.

Define your SMTP mail settings (include HFIManager.exe.config)

You must define an SMTP (Simple Mail Transfer Protocol) server in your Avocet environment to receive
email notifications.
For your high frequency implementation, do the following:
• specify the relative path of the AppConfig.xml file in the
installDirectory\HFIManager\HFIManager.exe.config file
• verify that the Slb.Avocet.HFNotificationPlugin.dll plug-in resides under the
installDirectory\HFIManager\HFIManagerPlugins subfolder
Generally, you receive email notifications for high frequency alarms or process executions.
These email notifications are sent to notification groups and specified recipients.
The SMTP server is a generic server. It has no dependencies on Avocet.
You specify the mail setting values in the <application> node of your
implementationFolder\AvocetVM\Config\appConfig_projectLayer.xml file.
So that the HFIMS can read the settings, you need to maintain a copy of the
appConfig_projectlayer.xml file in the implementationFolder\HFIManager\Config file path.
The XML <mailsettings> markup is shown below, with referenced websites and explanatory code
comments extrapolated from the websites:
<application id="yourProjectLayer">
<description>yourProjectLayer</description>
<buildTargets />
<database>
<driver>SQLSERVER</driver>
<sqlsyntax>SQLSERVER</sqlsyntax>
<connectString>Network Library=DBMSSOCN;Data Source=localhost,1433;
Initial Catalog=DbName;User ID=yourUserID;Password=yourPassword;
Application Name=AVM</connectString>

157
 <connectStringForSsas>[Connection string that allows SSAS to connect
to Avocet DB> </connectStringForSsas>
</database>
<mailSettings>
<!-- For details, see http://msdn.microsoft.com/en-us/library/ms164240(v=vs.110).aspx -->
<smtp from="[Specify the from address for outgoing e-mails]">
<network host="[Specify the hostname of the SMTP mail server to use for SMTP transactions]"
/>
<!-- Optional parameters, see: http://msdn.microsoft.com/en-us/library/ms164242(v=vs.110).aspx

defaultCredentials="Specifies whether the default user credentials should be used

to access the SMTP mail server for SMTP transactions. The default value is false."
enableSsl="Specifies whether SSL is used to access an SMTP mail server.
The default value is false."
password="Specifies the password to use for authentication to the SMTP mail server.
This attribute has no default value."
port="Specifies the port number to use to connect to the SMTP mail server.
The default value is 25."
targetName="Specifies the Service Provider Name (SPN) to use for authentication
when using extended protection for SMTP transactions.
This attribute has no default value."
userName="Specifies the user name to use for authentication to the SMTP mail server.
This attribute has no default value."
-->
</smtp>
</mailSettings>
You can refer to the code comments and review the websites to determine the best way to set up your
mail server.
To define your SMTP mail settings, follow these steps:

1. Open your appConfig_projectLayer.xml file in an editor.

Note: You update the <mailSettings> node in both locations of the

appConfig_projectLayer.xml file.

2. Locate the <mailSettings> node under the <application> node.

3. Enter your SMTP mail server settings, including any desired optional parameters.
A basic SMTP mail server example with an email address and SMTP host name follows:
<application id="yourProjectLayer">
...........
<mailSettings>
<smtp from="[email protected]">
<network host="gateway.mail.companyName.com" />
</smtp>
</mailSettings>
...........
</application>
You can contact your system administrator if you need additional help.
4. Save the updated appConfig_projectLayer.xml file.
5. Restart Avocet.

158 Avocet High Frequency Infrastructure

Define a mail recipient
This task shows how to define a mail recipient who receives alarm and other notifications through
email or messaging.

1. In the Navigation Tree, select Administration > Notifications > Mail Recipient to display the Mail
Recipient Item Edit screen.
2. Choose Home > Actions > New to open a new record.
3. Adjust the As Of Date, Start date, and End date values as needed.
These dates should correspond with the effective dates of the alarm settings and with any associated
mail group.
The dates in the Date Break column change accordingly.
4. Required. Enter a name for the recipient in the Name field under the Date Break column heading.
5. Required. Enter an email address or SMS or MMS gateway address in the Email address field
under the Date Break column heading.
The typical format for an SMS gateway address is Mobile-Number@ServiceProviderAddress. The
address may include the message format, such as SMS or MMS: for example,
[email protected] (MMS) for T-Mobile account.
You can search for and investigate several websites for a list of SMS gateway addresses.
6. Optional. Click View All Properties to display the Description field, and enter a unique description.
7. Click Home > Actions > Save to save the record.

Define a mail group

You specify and enable a mail group category to associate multiple email recipients, system roles,
and/or system users.

1. In the Navigation Tree, select Administration > Notifications > Mail Group to display the Mail
Group Item Editscreen.
2. Choose Home > Actions > New to open a new record.
3. Adjust the As Of Date, Start date, and End date values as needed.
These dates should correspond with the effective dates of the alarm settings and any target email
recipients.
4. Required. Enter a name for the group in the Name field under the Date Break column heading.
5. Required. Select the Enabled check box to enable the group.
You can leave it unselected if you are not ready to enable the group to receive email notifications.
6. Optional. Click View All Properties to display the Description and Rate Limit fields, and enter
an informative description of the new mail group.
7. Optional. In the Rate Limit field, enter the frequency in seconds that the group receives active
alarm notifications.
For example, if you specify 300, the group receives the current active alarm notifications every 5
minutes. Alarm notifications that occur during the time span, but are no longer active, are not sent.
If no alarms are active at the interval limit, then you do not receive alarms until they become active
again.
If you leave the field blank, the group receives active alarm notifications as they occur.
8. Choose Home >Actions > Save to save the record.

159
Link mail group with recipients
After you have defined your mail group, you can link it with individual mail recipients, system roles,
and/or system users.
To link a mail group with one or more recipients, follow these steps:

1. In the Mail Group Item Edit screen, select the mail group from the Navigator list.
2. Click the Links tab to open the Links pane.
3. If the message No active links is displayed, then click View linked only to display the Group-User
Link object. Otherwise, skip to step 4.
4. Click the Add Link icon to open the Select Item window.
5. In the Select Item window, select from among the following recipients to link with this group:
• specified mail or messaging recipients
• system roles such as field supervisor, field operator, read-only, and so forth
• system users who have been defined

6. Click OK. The selected recipient or recipients are added to the Links tab.
7. Click Home > Actions > Save to save the updated record.

Link mail recipients to mail groups

After you define your recipients and groups, you can link them together.
To link a mail recipient to one or more mail groups, follow these steps:

1. In the Mail Recipient Item Edit screen, select the mail recipient from the Navigator list.
2. Click the Links tab to open the Links pane.
3. If the message No active links is displayed, then click View linked only to display the Group-User
Link object. Otherwise, skip to step 4.
4. Click the Add Link icon to open the Select Item window.
5. In the Select Item window, select the mail group(s) that you want to link with this specific notification
group.
6. Click OK. The selected group or groups are added to the Links tab.
7. Click Home > Actions > Save to save the updated record.

Manage the Mail Queue Viewer

The Mail Queue Viewer grid report displays email notifications that have not yet been sent or whose
transmission has failed.
Email notifications that reside in the queue have the status of Wait, Failed, and so forth.
You have the option to
• send an alarm notification immediately
• cancel an alarm email transmission
• resend an alarm notification

Note: Email notifications that are transmitted immediately may display on the Mail Queue
Viewer viewer for a second or two.

160 Avocet High Frequency Infrastructure

 1. In the Navigation Tree, access Administration > Notifications > Mail Queue to display the Mail
Queue Viewer grid report.
2. In the list, select the email you wish to send.
3. Choose Home > Actions > Send Immediately.
The selected email is sent to its group and recipient.
4. To cancel a send action, choose Home > Actions > Cancel Sending.
5. To resend an email, choose Home > Actions > Repeat Sending.

Alarms
The corporate historian supports the OPC UA limit alarm type, watch dog alarm type, and off normal
alarm type.

Caution: The alarm settings are intended to be informative only. They are not for safety-critical
operations.

You can specify an alarm range to an item for each transaction type and property combination to which
you have mapped a tag.The data source or its frequency does not matter. However, only high-frequency
alarms are stored in the database.
For the OPC UA limit alarm type, the corporate historian supports the exclusive limit alarm. This limit
alarm can be in only one state at a time. That is, if the alarm exceeds the High High limit, then it is
classified in the High High state only, not also in the High state, which it has also exceeded.
The following example assumes a limit alarm type. The Data Flow Configuration screen shows the
rows containing the transaction types and their properties together with their respective tag maps for
the item MPFM-2349. You can assign an alarm range to each Transaction Type and Transaction
Property row.

161
 For the limit alarm, clamping restricts the values returned by the HF Store to a defined limit, thereby
excluding values that are outside of an acceptable range and might be deemed unreliable. You have
the option of clamping or restricting the alarm range to a specified high or low value, or to both high
and low values. Values that exceed the specified clamp high or low value are reset to the clamp value
and transmitted. For example, if you clamp the high value of a sensor’s alarm range at 3.00 and a
reading of 3.11 is received, that data point is reset to 3.00 and then transmitted.
Alarm and clamp values are in the same units of measure as the transaction values to which they are
mapped. Specified units of measure are not required for alarm and clamp values.
A watchdog alarm is triggered when a monitored value does not change over a specified time. For
example, if you are monitoring a flow meter that is measuring the flows from multiple links, you expect
the flow rate to change over time. If the flow rate does not change over a specified time, then it suggests
that an error has occurred--perhaps in the meter, in connectivity, or in another component. As with
other alarm types, you assign a notification group to receive the alert when the alarm is triggered.
An off normal alarm monitors an on/off or active/inactive condition or any change from a standard or
normal value. For example, you can set an off normal alarm to alert when a quantity, such as gas
volume, changes from a specified normal value. Like other alarm types, you assign a notification group
to receive the alert when the off normal alarm is triggered.

Alarm events and alarm thresholds

An alarm event is triggered whenever the value being monitored crosses the defined alarm threshold.
Alarm events are not continuous. An alarm event is triggered once for each time the value crosses
the defined alarm threshold. If the value remains in the alarm range for hours, only one alarm event
is triggered at the moment the value crosses the threshold.
An alarm event is triggered also when a value moves from an upper level alarm state to a lower level
alarm state. For example, in a limit alarm context, when a values moves down from a high high alarm
stage to a high alarm stage, an alarm event is triggered. No alarm event is triggered when a value
moves from an alarm stage to a normal range.
The following diagram outlines the relation between data points, alarm events, and alarm thresholds:

162 Avocet High Frequency Infrastructure

Before you begin
This topic describes what you need to do before setting up your alarms.
Be sure that you have completed the Data Flow Configuration entries for the particular item.
Prepare a notification group and a destination to receive the alarm messages (Administration >
Notifications in the Navigation Tree).

Verify the reference items for the VAL_ALM_LIMIT transaction

In the Type Editor, verify that the item to which you are assigning the limit alarm is entered as a
reference item against the VAL_ALM_LIMIT transaction.
See the following excerpt below:

163
 In this example, you can assign alarm limits to completions and multiphase meters. If necessary, you
(or the Avocet administrator) can add additional item references to the VAL_ALM_LIMIT transaction.

Access an alarm screen

This task shows describes how to access an alarm screen.
Ensure that you have
• defined the notification group or groups and destination recipients of the alarm event messages in
their respective Item Edit screens (see the Administration > Notifications node)
• defined the item (completion, meter, facility, and so forth) under the Wells and Facilities node to be
monitored for alarms
• launched the Data Flow screen to specify the item's transaction type and properties to be monitored
and map the corporate historian tags to the Avocet HF Store
• verified that the AvocetHFSync process has run

164 Avocet High Frequency Infrastructure

 All alarm screens are linked screens. The Linked Screens tab is available in the ribbon toolbar only
on certain types of screens. Typically, they are item editor screens for well and facilities (Wells and
Facilities > Item Edit in the Navigation Tree). After you have landed on an Item Edit screen, you can
also access the alarm screen from other linked screens listed in the toolbar, such as Data Flow and
other alarm screens.
After you have completed the prerequisite configuration, you can access an alarm screen and begin
to define your alarm definitions.

Configure the alarm limits for the Limit screen

This task shows how to set the alarm range and synchronize the alarms with the tag maps and
underlying calculations.

1. Click Home > Actions > New to display a blank record.

The DateTime value defaults to the As Of Date value in the Navigation panel of the ribbon toolbar.
2. Adjust the DateTime value as needed. Make sure that the time range corresponds to the effective
time range of the notification groups and destinations.
3. Specify the transaction type and corresponding property to which the alarm range applies.
The transaction type and property for the target item should already be tag mapped and synchronized
with the HF Store.
a) Select the transaction type from the Type Name drop-down menu.
b) Select the corresponding property in the Property Name drop-down menu.
For example, suppose you are setting an alarm range for the transaction type and property
highlighted by the arrow in the following screenshot:

You would select Meter Read from the Type Name drop-down list and Gas Volume Rate from
the Property Name drop-down list.

4. Based on industry guidelines and your knowledge of the current state of this transaction property,
use the following guidelines to set the alarm range:
Alarm setting Description

High High Setting for values that exceed a numeric level considered to be close to the maximum for the
transaction property that you are monitoring. If you set a high high alarm, you must also specify
a high alarm.

High Setting for values that exceed a numeric level considered normal for the transaction property
you are monitoring

Low Setting for values that fall short of a numeric level considered normal

165
 Alarm setting Description

Low Low Setting for values that fall short of a numerical level considered close to the minimum for the
transaction property you are monitoring. If you set a low low alarm, you must also specify a
low alarm.

Clamp Low The lower limit of returned values that are loaded or acknowledged. Values that fall short of
the Clamp Low value are ignored. Instead they are converted to the specified Clamp Low
value, transmitted, and loaded.

Clamp High The upper limit of returned values that are loaded or acknowledged. Values that exceed the
Clamp High value are ignored. Instead they are converted to the specified Clamp High value,
transmitted, and loaded.
For example, if the Clamp High setting is 101 and the data point is 110, then its instance is
converted to 101 and passed forward.

5. In the Notifications pane, click the ellipse in the Notification Group text box to open the Select Item
window for the Notification group.

6. Select the notification group, and click OK.

Remember that the alarm and clamp values are in the same units of measure as the transaction
values to which they are mapped.
7. In the ribbon toolbar, click Home > Tools > Save to save the alarm settings.

166 Avocet High Frequency Infrastructure

 When the AvocetHFSync process is run, it synchronizes the alarms with the tag map definitions
and underlying calculations.

Configure watchdog alarms

A watchdog alarm is triggered when a monitored value does not change over a specified time.

1. Access the Watchdog Alarm screen from your landing screen.

2. In the Navigator list, select the item to which you want to assign the discrete alarm.
3. Choose Actions > New to open a new record.
4. Specify a date and time when the alarm becomes effective in the Datetime field.
5. Choose a transaction type associated with the item from the Type Name drop-down field.
6. Choose a related transaction type property from the Property Name drop-down field.
7. In the Watch Period, specify the maximum number of periods that the property value can remain
static before a watchdog alarm is raised.
By default, a period is 500 milliseconds. The default period value is 5 or 2.5 seconds.
8. Select a notification group to receive the discrete alarm alerts from the Select Item list for the
Notification Group field.
9. Choose Actions > Save to save the discrete alarm record.
When the AvocetHFSync process is run, it synchronizes the alarms with the tag map definitions
and underlying calculations.
If the property value does not change over the specified watch period, a watchdog alarm alert is
sent to the designated notification group.

Configure off normal alarms

Use an off normal alarm to monitor an on/off or active/inactive condition or any change from a standard
or normal value.

1. Access the Off Normal screen from your landing screen.

2. In the Navigator list, select the item to which you want to assign the off normal alarm.
3. Choose Actions > New to open a new record.
4. Specify a date and time when the alarm becomes effective in the Datetime field.
5. Choose a transaction type associated with the item from the Type Name drop-down field.
6. Choose a related transaction type property from the Property Name drop-down field.
7. Specify a standard value from which the property should not deviate in the Normal State field.
8. Select a notification group to receive the off normal alarm alerts from the Select Item list for the
Notification Group field.
9. Choose Actions > Save to save the off normal alarm record.
When the AvocetHFSync process is run, it synchronizes the alarms with the tag map definitions
and underlying calculations.
If the specified normal value for the item's transaction type and property changes, an off normal
alarm alert is sent to the designated notification group.

Browse alarm and event history with an OPC UA client

APIS provides an event historian that you can browse for alarm and event history by using an OPC
UA client, such as UaExpert.

167
 You should already be familiar with APIS configuration, OPC UA clients, and SSL trust certificates.

1. If you do not already have an OPC UA client, download the UaExpert OPC UA client from the link
shown below:
https://www.unified-automation.com/products/development-tools/uaexpert.html
2. Follow the instructions in the APIS Management Studio Help topic Event Historian to define and
configure the historian in the Registry Editor.
3. Establish a secure connection between your OPC UA client and the APIS event historian.

Note: To enable the secure connection, verify that APIS has the client certificate of your
OPC UA client in its C:\Program Files\APIS\Config\ApisHive\pki\trusted folder.

4. View the alarms and events in the corresponding window of your OPC UA client.

Use templates to apply alarm settings

This section shows how to 1) use templates to save alarm settings as a template and 2) apply alarm
settings to another item.
To reduce repetitive data entry, in the Alarms screen you can use templates to apply alarm settings
to transaction type and property combinations across similar item types.
Use the Home > Templates > Save As Template menu option to save your current screen’s alarm
settings for the specified transaction type, transaction property, and notification group. You save the
data as an XML file, with the .xml file extension.
Use the Home > Templates > Apply Template menu option to copy the alarm settings and notification
group to a blank record for the transaction type and property of a similar item type.

Save alarm settings as a template

This task shows how to save your current screen's alarm settings as a template file with an .xml
extension.

1. In your alarms screen (Limit, Watchdog, or Off Normal), open the item record containing the
transaction type, transaction property, and alarm settings including the notification group, all of
which you want to save as a template.
The following example shows Limits alarm screen:

168 Avocet High Frequency Infrastructure

 2. Choose Home > Templates > Save As Template to open the Save As dialog.
3. Specify a template name and directory location for the template, and save the file with an .xml
extension.

Apply alarm settings to another item

This task shows how to apply the alarm settings for the transaction type and property of one item to
the alarm record of another similar item.

1. In the Navigator list of the specific screen (Limit, Watchdog, or Off Normal), select the item to which
you want to apply the alarm settings.
2. Choose Home > Templates > Apply Template to display the Open dialog.
3. Browse for and select the XML template that want to apply, and click Open.
The alarm setting entries are copied to the new record.
4. In the Alarms screen, click Home > Tag Mapping Tools > Save to save the new record with the
template entries applied.

How to load high-frequency alarm transactions and global tag maps

This section shows how to load high-frequency alarm transactions and global tag maps. You can use
the data loader mechanism to load high-frequency alarm transactions and global tag maps that apply
to high-frequency and historical data.

High-frequency alarm transactions

This topic discusses high-frequency alarm transactions and provides an example of XML markup
language for an alarm loader task to help create loader definitions for alarm transactions.
Before loading the high-frequency alarm transactions, ensure that the target item or items to which
the alarm transactions apply are specified as reference items for the VAL_ALM_LIMIT transaction.
You can verify the item references by checking the VAL_ALM_LIMIT transaction for your project layer
in the Type Editor.
You can use the following XML markup example of an alarm loader task to help create your loader
definitions for alarm transactions.
<task id='Alarms' sourceConnectionId='Data'>
<sourceSelect>
<![CDATA[
SELECT * FROM [ALARMS$]
</sourceSelect>
<row name='Alarms' typeClass='TRANSACTION' type='VAL_ALM_LIMIT'
allowInsert='True' >
<property name='ITEM_ID' type='DATA' colIndex='0'lookupType='COMPLETION'
lookupProperty='NAME' />
<property name='TYPE_NAME' type='DATA' colIndex='3' />
<property name='PROPERTY_NAME' type='DATA' colIndex='4'/>
<property name='LEVEL' type='DATA' colIndex='5' />
<property name='CLAMP_LOW' type='DATA' colIndex='6'/>
<property name='LOW_LOW' type='DATA' colIndex='7'/>
<property name='LOW' type='DATA' colIndex='8'/>
<property name='HIGH' type='DATA' colIndex='9'/>
<property name='HIGH_HIGH' type='DATA' colIndex='10'/>
<property name='CLAMP_HIGH' type='DATA' colIndex='11'/>

169
 <property name='UNIQUE_ID' type='FIXED' value='0' transformType='property'
transformClass='Slb.Avocet.DataAcess.Loader.Transform'
transformMethod='ColumnsToHash'
transformParam='$ITEM_ID,$TYPE_NAME,$PROPERTY_NAME'/>
<property name='START_DATETIME' type='FIXED' value='01/01/2012' />
<property name='END_DATETIME' type='FIXED' value='01/01/9000' />
</row>
</task>
The <row> element specifies the transaction type VAL_ALM_LIMIT. The <property> elements define
the item type (COMPLETION). They also define the alarm settings: CLAMP_LOW, LOW_LOW, and
so forth. Most important, they include the UNIQUE_ID property. Among other attributes, the UNIQUE_ID
property includes the following:

Attribute Description

transformMethod Use ColumnsToHash in all instances to retrieve the key values.

transformParam Use the variables $ITEM_ID, $TYPE_NAME, and $PROPERTY_NAME in all instances to point
to the columns ITEM_ID, TYPE_NAME, and PROPERTY_NAME in that order. These variables
are required to generate the unique ID for the alarm transaction.

Remember that an alarm setting is assigned to a combination of item type/transaction

type/transaction property type.

This example loader file connects with alarm transaction data in an Excel spreadsheet through the
OleDB interface:
<sourceConnections>
<sourceConnection id='Data' sourceType='oledb' connectionString=
'Provider=Microsoft.ACE.OLEDB.12.0;Data source=D:\FilePath to
Data.xls;Extended Properties="Excel 12.0 Xml;HDR=YES;IMEX=1";'>
</sourceConnection>
</sourceConnections>
The loader calls alarm transactions such as the ones in the following examples captured in an Excel
spreadsheet:

Note the Unique ID attributes of each row. They are in the following format:
Item.TransactionType.TransactionProperty.

Item Transaction Type Transaction Property

W497-ESP ESP_READ MOTOR_TEMP

W497-ESP ESP_READ CURRENT_LK_PRESS

W497-ESP WELL_READ TUBING_PRESS

You can load these alarm transactions through one of Avocet’s data loader interfaces using the OleDB
interface. For example, you can open the Avocet Configuration Tools utility and choose the Data Tools
> Data Loader node to open the Data Loader screen. Specify your XML loader file, and select the
tasks you want to import, as seen in the following excerpt:

170 Avocet High Frequency Infrastructure

Global tag maps
This topic discusses global tag maps and provides XML markup language that you can use for the
loader file.
When preparing the XML definition of a tag map, whether for high frequency or historical data, be sure
that you correctly specify its Name property. It must follow this format convention: ITEM_NAME.
TRANSACTION_TYPE.TRANSACTION_PROPERTY. For example, to define a tag map for a multiphase
meter with the following attributes
ITEM_NAME=MPFM 2349
TRANSACTION_TYPE=MPHASE_MTR_VX
TRANSACTION_PROPERTY=POS_12VDC
you would write it as follows:
MPFM 2349.MPHASE_MTR_VX.POS_12VDC
This tag map specifically refers to the following item, transaction type, and transaction property as
defined in the Type Editor:

When defining the XML markup for your loader file, you can use the following loader file as an example:
<?xml version="1.0" encoding="utf-8"?>
<task id='TagMappingImport' sourceConnectionId='Data'>
<sourceSelect>

171
 <![CDATA[
SELECT * FROM [TAG_MAPPING_IMPORT$]
</sourceSelect>
<row name='Tag Mapping' typeClass='TRANSACTION' type='TAG_MAP'
allowInsert='True' >
<property name='ITEM_ID' type='DATA' colIndex='0' lookupType='SCADA'
lookupProperty='NAME' />
<property name='TARGET_ID' type='DATA' colIndex='2'
lookupType='MPHASE_METER' lookupProperty='NAME' />
<property name='TRANS_TYPE' type='DATA' colIndex='3'/>
<property name='TRANS_PROPERTY' type='DATA' colIndex='4' />
<property name='NAME' type='FIXED' value='0' transformType='column'
transformClass='Slb.Avocet.DataAccess.Loader.Transform'
transformMethod='ColumnsAppendValues' transformParam='$2,$3,$4'/>
<property name='NODE_ID' type='DATA' colIndex='10'/>
<property name='TAG_ID' type='DATA' colIndex='11'/>
<property name='UOM' type='DATA' colIndex='12' />
<property name='START_DATETIME' type='FIXED' value='01-01-1994' />
<property name='END_DATETIME' type='FIXED' value='01/01/9000' />
<property name='ROW_STATUS' type='FIXED' value='RAW' />
</row>
</task>
Under the Name property, its transformParam attribute contains the variables $2, $3, and $4. They
refer to the ITEM_NAME, TRANSACTION_TYPE, and TRANSACTION_PROPERTY.
An example high-frequency tag map definition in Excel spreadsheet format is shown below.

Like the alarm transactions, you can load these tag maps, properly defined, through one of Avocet’s
data loader interfaces using the OleDB interface.
For example, you can open the Avocet Configuration Tools utility and choose the Data Tools > Data
Loader node to open the Data Loader screen. Specify your XML loader file, and select the tasks you
want to import, as seen in the following excerpt:

172 Avocet High Frequency Infrastructure

 Refer to the Connection Manager documentation for more information about the data loading process.

Appendix: Troubleshooting data flow configuration

This section presents basic guidelines on troubleshooting common issues encountered during data
flow configuration.
You can find a listing of high frequency error and status messages in the Resource Editor screen of
the Avocet Configuration Tools utility (Configuration Editor Tools > Resource Editor). An excerpt
is shown below:

You can relate the label text to error and status messages displayed in a screen’s status pane or in
the error details.

General guideline
This topic discusses what to check when experiencing connectivity problems.

173
 Connectivity problems can be the source of different types of issues. Always verify that the Avocet HF
Store and corporate historian are running.
In the Data Flow Configuration screen, you can choose Home > Tag Mapping Tools > Test
Connection to see the current status of the Avocet HF Store and your corporate historian. If the
components are live and connected, the Test Connection option return messages like the following:

Impact of synchronization on data source tags

This topic discusses how to troubleshoot synchronization issues.
To troubleshoot synchronization issues, you can review how tags from the data sources are processed
during synchronization and converted to output tags. These output tags are made available to the
different modules. You can view these relations schematically in the Connection View pane of the
APIS Management Studio console.
Note the syntax of the naming convention used by Avocet for tags. For data source tags, it is
ItemName.TransactionType.TransactionProperty. For the corresponding output tags, it is
ItemName.TransactionType.TransactionProperty.output.
The basic tag mapping relation takes a tag from a data source, corporate historian in this example,
and converts it to a corresponding output tag, as shown in this schematic.

Compare the model with the example from the APIS Management Studio:

A more elaborate tag mapping definition contains a unit of measure, which requires a calculation to
be performed. The unit of measure is assigned during the calculation phase, and the tag is passed
on to its output format.

In the example, the tag originating from the corporate historian does not show a unit of measure, but
Avocet automatically calculates one for it based on the transaction type and property.

174 Avocet High Frequency Infrastructure

 During synchronization, tag mappings for clamping calculations undergo multiple transforms. The tag
definitions include alarm transaction type and an alarm transaction type property, such as CLAMP_LOW
and CLAMP_HIGH. These tags are converted to their respective outputs, which are processed and
stored with the .CalculationClamping extension in the calculations module.

Compare with this example from the APIS Management Studio.

Other
This topic shows several diagrams that outline the basic aspects of the Apis Management Studio.

175
176 Avocet High Frequency Infrastructure
177
About calculations
The HFConfig_base.xml file supplies the basic configuration parameters for the Avocet high frequency
(HF) implementation.
It includes configuration data that supports the synchronization of the Avocet HF Store. The
synchronization process enables raw values from corporate historians to be stored in an Avocet-friendly
format in Avocet HF Store tags.
The HFConfig_base.xml file contains six main nodes:
• Historian configuration definition
• Synchronization validation timeout interval
• Calculation validation for custom calculation validations
• Item link chain for applying calculations to the Avocet HF Store
• Framework for and an example of a calculation definition
• Template definition
You can generally leave the historian configuration, item link chain, and template configuration sections
as they are. You would only need to modify these nodes if attempting a special implementation of the
high-frequency workflow or if your organization structure is different from the one specified in the item
link chain.
As an Avocet administrator or deployment engineer, your chief reason to access the HFConfig_base.xml
file is to supply the XML framework for customized calculation definitions.

About your HF configuration file

This topic discusses the HF configuration file, where it's located and its top-level nodes.
The HFConfig_base.xml file is located in your AvocetImplementation\AvocetVM\Config and in your
AvocetImplementation\HFIManager\Config subfolders. Its top-level nodes are
• <HistorianConfigurations>
• <SynchronizationValidation>
• <CalculationValildation>
• <ItemLinkChains>
• <Calculations>
• <TransactionTemplateDefinition>

Extensibility
This topic discusses how you can extend the HFConfig_base.xml file so that it is unique to your
implementation layer
Your implementation layer’s AppConfig_xxx.xml file references the HFConfig_base.xml file and its
out-of-the-box extension HFConfig_OG_STD.xml under an <HFConfig> node.
You can extend the HFConfig_base.xml file so that it is unique to your implementation layer: for
example, you can have an HFConfig_xxx.xml, where xxx denotes your unique implementation layer.

178 Avocet High Frequency Infrastructure

 Your AppConfig_xxx.xml for your implementation layer also contains an <HFConfig> element that
references your base and extended configuration files, as shown in this example:
<HFConfig>
<base>HFConfig_base.xml</base>
<extension>HFConfig_OG_STD.xml</extension>
<extension>HFConfig_xxx.xml</extension>
</HFConfig>
You can refer to the code comments within the HFConfig_base.xml file for helpful descriptions and
examples.
The main nodes of the HFConfig_base.xml are described in more detail below.

HistorianConfigurations
The <HistorianConfigurations> node contains configuration definitions of each supported historian
type in its unique XML stanza. Another stanza contains the actions, such as alarms and calculations,
that the historian's synchronization process supports. The last stanza in the node contains the filter
criteria for applying the appropriate SCADA items to the historian.
The <HistorianConfigurations> node contains the following stanzas:
• <HistorianConfiguration>
• <AssignedActions>
• <Filters>
The attributes of the default <HistorianConfiguration> are listed in the following table:
Attribute Description

Id Unique ID assigned to the configuration definition.

HFConfig_ApisHistorian_base is the ID in the default
configuration.

Type The type name of the historian. APIS is the default

configuration. Other historian types include OsiSoft PI,
Matrikon, and Rockwell, among others.

Assembly The .NET unit of deployment (.dll) for the historian. For this
default configuration, it is Slb.Avocet.HFApisHistorian .dll.

Class A grouping of variables, methods, and events that determines

the behavior of the APIS type, specifically its synchronization.
For this default configuration, it is
Slb.Avocet.HF.Apis.Management.ApisSynchronizationManager.

The <HistorianConfiguration> definition for APIS also contains custom module definitions defined in
a CDATA section. The custom module definitions are programmed outside the XML markup. Any
additional <HistorianConfiguration> definitions would also contain their unique custom module definitions
in their own CDATA sections.
The <AssignedActions> stanza specifies the items that the historian's synchronization process supports.
They include the following <string> elements:
• Tags
• Alarms
• Calculations
• Logging
The default APIS configuration supports all four items. The OsiSoft PI configuration supports only the
synchronization of tags.

179
 The <Filters> stanza defines a single item filter and a regular expression filter. The <SingleItems>
element contains the following subelements:

Subelement Description

ItemType the item to which the filter applies. It always applies to the SCADA item type.

LogicalOperator Options are AND or OR. The operator applies if multiple filter elements are defined under the
<SingleItems> element. For example, you can filter against multiple properties of the SCADA
item type.

Column denotes the item property to which the filter applies

Operator the operator specifying the relation between the property and the string value. Choices are
Equal, LessThan, GreaterThan, LessThanOrEqual, GreaterThanorEqual, In, IsNull, and
IsNotNull.

String denotes the filter value to apply to the specified item property

The regular expression filter <FilterRegex> is used to search for values of a specified item type
property. It can be used alone or in conjunction with the <SingleItems> filter. The regular expression
<FilterRegex> contains the following attributes:

Attributes Description

LogicalOperator Options are AND or OR. The operator applies if multiple <FilterRegex> entries are
defined.

Column denotes the item property to which the regular expression filter applies

Value denotes the regular expression value to be applied to the property

Validations
The HFConfig_base.xml file supports additional custom calculation validation definitions.
By default, the high-frequency implementation validates each calculation parameter and each calculation
name for uniqueness.You can add custom calculation validations. Custom calculation validations take
two forms:
• Static calculation validation
Static calculation validation is a global validation type. It is a single validation routine that applies to
multiple calculation instances regardless of item type. For example, this validation type can take the
form of an additional calculation parameter, such as one for status reporting, that must be satisfied
before all calculation definitions are validated. You specify a static calculation validation ID in the
HFConfig_base.xml file.
• Ad hoc calculation validation
Ad hoc calculation validation is a validation routine that is specific to an individual calculation class
for a specific item type. Ad hoc calculation validations are applied to calculations that have unique
constraints that must be satisfied. The ad hoc calculation validation is enabled by setting the
SupportsValidation attribute equal to "true" in the <CalculationReference> element.

Both custom calculation validation types share a timeout interval that specifies the duration within
which the validation must occur or otherwise be skipped.
The <SynchronizationValidation> element is provided so that you add a custom validation step before
the high-frequency synchronization occurs. The validation step considers tags, alarms, and calculations

180 Avocet High Frequency Infrastructure

 that might be impacted. The <SynchronizationValidation> attributes are described in the following
table:

Attribute Description

Timeout the interval in milliseconds for each custom validation to complete. If the validation does not
complete in the specified interval, then the validation is discarded, and the synchronization process
times out.
In the HFConfig_base.xml file, this value is set by default to Never times out. You can change it
to an appropriate interval in your project layer's HFConfig file for your custom calculation parameter.

Validation ID unique ID for the validation routine to be performed

Assembly the DLL file that supports the deployment of the custom calculation validations
(Slb.Avocet.HFCalculations.dll in the OOB deployment)

Class class where the validation is instantiated

The <CalculationValidation> element contains the definition for the static calculation validation. Its
attributes are described in the following table:

Attribute Description

Timeout the interval in milliseconds for each custom validation to complete. If the validation does not
complete in the specified interval, then the validation is discarded.
In the HFConfig_base.xml file, this value is set by default to Never times out. You can change
it to an appropriate interval in your project layer's HFConfig file for your custom calculation
parameter.

StaticCalculationValidation unique ID for the static calculation validation routine to be performed

ID

Assembly the DLL file that supports the deployment of the custom calculation validations
(Slb.Avocet.HFCalculations.dll in the OOB deployment)

Class class where the static calculation validation method is instantiated

Note: If you specify a custom calculation validation, you must reference it in the
<CalculationReference> element of your <Calculations> definition.

ItemLinkChains
This topic discusses the <ItemLinkChains> node that is defined to link the Avocet HF store with the
specified item types so that the calculations can be properly applied.
The default item link chain supports one or more Avocet HF store instances that are assigned to the
COMPANY item level in the specified Avocet organization hierarchy. If your Avocet HF store is assigned
to the COMPANY level in the same organization structure, you do not need to modify this stanza.
You would need to modify or create a new item link chain if
• your organization structure is different from the one specified in the default chain
• you want to assign the Avocet HF store to a different item level in the default chain
The default item link chain definition maps the Avocet item (MPHASE_METER or multiphase meter
in the example) with the SCADA item (the Avocet HF Store in this case) in the SCADA organizational
tree. The item link chain uses the ORG_ITEM link to traverse the Avocet organizational hierarchy
down to the COMPANY item. The SCADA_ORG link then links the COMPANY item with the SCADA

181
 item, as shown in this item link chain definition from the HFConfig_base.xml file (code comments
included):
<ItemLinkChain Id="HFConfig_ILC_base">
<LinkType SourceIdLocation="FROM" Id="BATTERY_ITEM" />
<!-- MPHASE_METER -> BATTERY-->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!-- BATTERY -> ORG_UNIT4 -->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!-- ORG_UNIT4 -> ORG_UNIT3 -->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!-- ORG_UNIT3 -> ORG_UNIT2 -->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!-- ORG_UNIT2 -> ORG_UNIT1 -->
<LinkType SourceIdLocation="FROM" Id="ORG_ITEM" />
<!-- ORG_UNIT1 -> COMPANY -->
<LinkType SourceIdLocation="TO" Id="SCADA_ORG" />
<!-- COMPANY -> SCADA -->
</ItemLinkChain>
The From and To links, which are designated by the SourceIdLocation attribute, for the ORG_ITEM
link are captured below in the following excerpt from the Type Editor in the Avocet Configuration Tools
utility:

The SCADA_ORG link that links the COMPANY item with the SCADA item is depicted below:

In the hierarchy, the chain path starts at the Avocet item type and then proceeds down the hierarchy
to the SCADA item, as shown in this illustration:

182 Avocet High Frequency Infrastructure

 The hierarchy determines how SCADA data is read during the synchronization process. The SCADA
data is linked with specific Avocet item types in the Avocet database. When creating your own links
between Avocet item types and the Avocet HF store, it is recommended that you follow this linking
structure to the COMPANY item, and then use the SCADA_ORG link to point to the Avocet HF store.

Calculations
See Working with calculations.

TransactionTemplateDefinition
This topic discusses the <TransactionTemplateDefinition> node that defines the import value for each
tag mapping or alarm settings field that is incorporated into the template definition.
The Avocet client supplies template definitions for saving tag map settings on the Data Flow
Configuration screen and for saving alarm settings on the Alarms screen. These settings are saved
for later reuse.
For the Data Flow Configuration screen, you can save the tag map definitions as stored in the Avocet
HF Store. This information includes the
• transaction type
• transaction property
• item type
• item name
• data loading options such as aggregation method, sampling interval (frequency), the Load to Avocet
check box

Note: Tag data from the corporate historian is not copied into the template definition.

For the Alarms screen, you can save the alarm setting definition, including the following information:
• item type
• item name
• transaction type
• property type

183
 • alarm values
• clamping values
• notification group type and name
The <TransactionTemplateDefinition> node defines the import value for each tag mapping or alarm
settings field that is incorporated into the template definition. It applies a series of tokens to the mapping
process. Each token represents a common Avocet data field that can be applied across items so that
the templates are applied consistently.

Working with calculations

Avocet provides default definitions for clamping and unit-of-measure calculations. This topic discusses
what you must provide if you want to create custom calculations.
If you wish to customize the clamping calculation, write a historical calculation, or create any other
calculation, you must provide
• custom XML framework for the interface
• underlying C# coding to execute the calculation

Background
This topic discusses a calculation definition that contains one or more input and one or more output
parameters.
Both the input and output parameters are defined in the XML markup framework of your
HFConfig_xxx.xml file, where xxx refers to your implementation layer. The relationship between inputs
and outputs is many-to-many. Depending on how you define the calculation, it can have
• multiple inputs and multiple outputs
• multiple inputs and a single output
• a single input and multiple outputs
Calculations are intrinsically bound with the tag mapping definitions contained in the Data Flow
Configuration screen. Generally speaking, inputs are the equivalent of tags originating from the corporate
historian. Outputs are the equivalent of tags associated with the Avocet HF store (for example,
tagName.output).
The following schematic shows the relation between the input tag, the corresponding output tag, and
the calculation module for a unit of measure calculation, which Avocet supports by default.

184 Avocet High Frequency Infrastructure

 Before calculations can run successfully, the tag maps need to be synchronized with the Avocet HF
store.

Distinguishing features
This topic discusses the distinguishing features of a calculation definition in the XML markup.
In the XML markup, the distinguishing features of a calculation definition are as follows:
• Each definition has a unique name and ID.
• Each definition can have one or more input and output calculations.
• Each input calculation processes historical or real-time data.
• Real-time data is current data. It is either raw, in which all input values are received as is; or it is
cleansed, meaning that the input values are restricted to a range through a clamping calculation.
• Historical data is either aggregated or un-aggregated (un-aggregated data is considered raw data).
• Input calculation parameters have a specified data source, which can be
• Avocet database
• Avocet HF Store
• corporate historian
• Each input or output calculation parameter is associated with either a
• specific Avocet item, transaction type, and transaction property; or
• specific Avocet item and item property (but only for real-time data originating from the Avocet
database data source)
• Support for custom calculation validation parameters is provided. In your project layer's HFConfig_
ProjectLayer .xmlfile, you can specify a timeout interval for synchronization if the validation does not
occur.

Data source and real-time or historical data

This topic shows which data sources can provide real-time or historical data in the Avocet
implementation.

Data source Real-time data? Historical data?

Avocet database Yes No

For calculations assigned to a specific

• Item|transaction type|transaction property

• Item|item property

Avocet HF Store Yes Yes

Corporate historian Yes Yes

Logging is automatically enabled.

When calculations are run

Calculations are run when input values change and when they are triggered by a timer setting.

185
Out-of-the-box versus custom calculations
The Avocet HF implementation supports clamping calculations and unit of measure calculations
out-of-the-box without the need to manually write XML markup or C# programming. This section
discusses both types of calculations.

Clamping calculation
This topic discusses clamping calculations, what they are, and how to apply clamping values on Alarm
screens.
A clamping calculation defines the
• maximum input value of an alarm
• minimum input value of an alarm
• the clamped input value, which programmatically restricts the input values that exceed the maximum
or minimum value to the specified alarm maximum or minimum
You apply the clamping values on the Alarms screen where you set the alarm range for the specified
transaction type and property.

In addition, you can define your own customized clamping calculation that overrides the out-of-the box
clamping calculation.

Unit of measure calculation

This topic discuses how the Avocet HF implementation supports an out-of-the-box unit of measure
(UOM) calculation.
This UOM calculation is automatically applied to UOMs assigned to incoming corporate historian tag
values that differ from the assigned Avocet storage unit value for the transaction type and property.
For example, suppose your Avocet storage unit of measure for gas volume is in 1,000 cubic feet (mcf),
as shown in this extract from the Storage UOM Editor screen (Configuration Editor Tools > UOM
Editor > Storage UOM Editor) of the Avocet Configuration Tools utility:

186 Avocet High Frequency Infrastructure

 3
But the UOM on the corporate historian tag value is 1,000 cubic meters (m ), as in this excerpt from
the Data Flow Configuration screen:

3
The UOM calculation automatically converts the volume from mcf to m during synchronization.

Real-time data
This topic discusses real-time data. Real-time data can originate from any data source. It is current
data.
From an end-user perspective it arrives “as is” from the data source. The following diagram outlines
the relation between the data source, the data tag, and the corresponding input parameter.

187
 In the XML markup of the input calculation, the value type of real-time data is not specified. The data
is assumed to be raw, unless it is a clamping calculation.

Historical data
This topic discusses historical data. Historical data originates from the Avocet HF store where the
historical data is stored per tag, or from the corporate historian, where logging is automatically enabled.
Historical data refers to a previous set of values, not the current values.
The value type of historical data is raw if the aggregation method is not specified. If the aggregation
method is specified, the value type is noted as historical.
Historical data contains the following unique parameters:
• Aggregation method (AggregationMethod)
• Aggregation resample Interval (AggregationResampleInterval)
• Time span (TimeSpan)
• Offset
• Maximum values to return (MaxValuesToReturn)
The following diagram outlines the relation between the data source and input calculations for historical
data:

These parameters share certain dependencies.You can choose from a range of aggregation methods
or choose none.The AggregationResampleInterval attribute applies only if you specify an aggregation
method. The other attributes apply no matter what the aggregation method is.
The AggregationResampleInterval (aggregation resampling interval) indicates the increments at
which data is retrieved. For example, if you specify a time span of 12 hours and an aggregation
resampling interval of 1 hour, then the calculation retrieves the last 12 hours of historical data in 1-hour
increments, as depicted in the following diagram:

188 Avocet High Frequency Infrastructure

A total of 12 data points is collected. If you set the aggregation resampling interval to 30 minutes, but
maintain the time span at 12 hours, then you would retrieve the last 12 hours of historical data in
half-hour increments: a total of 24 data points.
The Timespan (time span) denotes the time range for which data is retrieved. It is broken out
sequentially into days, hours, minutes, and seconds in this format: n.nn:nn:nn. For example, a time
span of 12 hours would be written as 0.12:00:00. The time span value is subtracted from the current
time (minus any offset value) to get the start time of the historical data retrieval.
The Offset (offset) indicates how far back from the current time to begin the data retrieval. It results
in offsetting the start time of the data retrieval. Assume the example of a 12-hour time span with 1-hour
resampling intervals. If the current time is 2:30 PM and you specify a 2-hour offset, then the data
retrieval would start 14 hours from the current time (12:30 AM) instead of 12 hours (2:30 AM). It would
then retrieve 12 hours of data (up to 12:30 PM instead of the current 2:30 PM time). The offset does
not affect the number of data points that are retrieved, only the start time.

The MaxValuesToReturn (maximum number of values to return) restricts the number of historical
data points that are retrieved. The example of a 12-hour time span with 1-hour resampling intervals
has 12 data points. If the maximum number of values to return is 6, then the calculation starts with the
original data point and proceeds chronologically from there. In our example, it retrieves the first
chronological data point sent 12 hours from the current time and then captures the next 5 data points,
ending at hour 6.

189
 The EnableLogging parameter applies to calculation output parameters only. By default it is set equal
to “False.” When set equal to “True,” the output tag is logged in the format
CalculationOutputs.TagName.Output in the Apis Management Studio.

Inputs and outputs

This topic discusses the calculation parameter output definition that is essentially an output tag whose
value varies depending on the input calculation.
The tag output consists mainly of a
• transaction property and type
• data type that describes how the calculated values are stored (optional)
When the calculation is run, the tag output value is stored in the Avocet HF store.
The following diagram shows the high-level relation between calculation inputs and outputs:

Calculation reference
The <CalculationReference> element identifies the assembly file that deploys the custom calculation
(Slb.Avocet.HFCalculations out of the box) and the class where the specific calculation is instantiated.

190 Avocet High Frequency Infrastructure

 You can extend the <CalculationReference> element to support custom calculation validations by
specifying the following attributes:

Attribute Description

StaticValidationId the unique identifier for the global static calculation validation routine. This is the same value as
denoted by the Id attribute of the <StaticCalculationValidation> element.
If specified, then the specified validation routine can be applied to multiple calculation instances.

SupportsValidation applies to ad hoc custom calculation validations. Its option is a Boolean true or false indicator that
tells whether the calculation invokes the validation interface for the specific calculation instance.
If both static calculation validations and ad hoc custom calculation validations are assigned to the
same calculation, then the static calculation validations are processed first.

Calculation definition attributes

This topic discusses the <CalculationDefinition> element that contains the attribute
HistoricalTimeInterval, which applies to raw and historical data.
For the HistoricalTimeInterval, you specify a value in seconds that determines an interval when
calculations are run against the inputs even if the inputs have not changed. In effect, you can use the
HistoricalTimeInterval attribute to generate simulation data when inputs have not changed.
To focus on a specific calculation parameter definition within a calculation, use the Supersede attribute
to specify the tag or parameter name (transaction and property). When the calculation is run, all the
calculation parameters are done, but only the latest value of the Supersede attribute is returned as
the output value for the respective tag in the Avocet HF Store.
You typically would apply the Supersede attribute to a clamping calculation that consists of the three
input parameters: low alarm limit, high alarm limit, and the value to be clamped. Specifically, you assign
the Supersede attribute to the input parameter containing the value to be clamped. However, if your
custom clamping calculation contains an output parameter for the value to be clamped, then you do
not use the Supersede attribute. You can also apply it to prioritize multiple calculations.

Filtering criteria
The filtering criteria under <Calculations> focus on the item that is the subject of the calculation. The
criteria are arranged from the specific to the general. Its descriptive elements begin with the name of
the item type, proceed to its subtypes, and then specify the type to which the calculation applies.

OPC HDA data types

This topic lists the supported data types. Data types are an optional attribute.
The following list includes the supported data types. Refer to a programming guide or website for more
detailed descriptions of each.

• Boolean • Sbyte

• Byte • Int16

• UInt16 • Int32

• UInt32 • Int64

• UInt64 • Float

191
 • Double • String

• DataTime • Number

• Integer • UInteger

• Duration

Aggregation methods
This topic describes the different aggregation methods.
The following table lists the OPC HDA and DA aggregation methods that historical calculations support.
For more information about these methods, see the OPC Historical Data Access Specification, Version
1.20, which you can download from the OPC Foundation website as well as other websites. The
descriptions herein are derived from the specifications.

Aggregation method Description

None No sampling is applied to the raw data from the historian. The as-is raw data is retrieved.

Interpolative zero order Samples an incoming value at given interval, holding the value until the next interval, at
(Zero-order hold interpolation) which time a new value sample is taken. Basically, one sample is taken per time interval.

Interpolative (First-order hold A linear interpolation method in which a sampling value is derived from the two nearest
interpolation) input samples (bounding values) over a specified interval

Average The sum of values over a given interval divided by the number of data points

Minimum The minimum raw value within the sampling interval, with the interval start time as the
timestamp

Time average Time-weighted average of raw values at the beginning and end of an interval

Maximum Actual Time Maximum raw value within the interval with that value’s timestamp

Maximum Maximum raw value within the interval, with the interval start time as the timestamp

Standard deviation Square root of the average of the squared differences of raw values from their average
values divided by the random sampling n-1: 1n(x-Avgx)2n-1

Range The difference between the raw maximum and raw minimum values in the interval. If only
value occurs during the interval, then the range is zero.

Count Count of the number of all raw values within an interval

Minimum actual time Minimum raw value within the interval with that value’s timestamp

Start Retrieves the first raw value within the interval with its timestamp

End Retrieves the last raw value within the interval with its timestamp

Variance Retrieves the square of the standard deviation

Median Retrieves the median of raw values within the interval. The median is the middle value in
the range of lowest to highest values. If there is an even number of values in the range,
then the median is the mean of the two middle values: m1 +m2/2.

192 Avocet High Frequency Infrastructure

 Aggregation method Description

Total The total aggregate is calculated by dividing the time-weighted average divided by the
interval length.

Percent Good The Percent Good calculation divides the Duration Good by the interval.

Percent Bad The Percent Bad calculation divides the Duration Bad by the interval.

Worst Quality Retrieves the worst quality OPC DA value in the interval

Sum Retrieves the sum of all raw values in the interval

Calculation examples
This section describes three example calculations: generic, clamping, and percent change.

Generic calculation example

This topic shows a generic example. You can find generic examples in the
<implementationFolder>\AvocetVM\Config\HFConfig_base.xml file.
<CalculationDefinition Id="SampleCalculation"
Name="SampleCalculation"
HistoricalTimeInterval="5"
Supersede="MPHASE_MTR_VX.NEG_12VDC">
<![CDATA[
This text will be passed on to the calculation upon instantiation
<CalculationReference Assembly="Slb.Avocet.HFCalculations"
TypeToInvoke="Slb.Avocet.HF.Calculations.TestCalc" />
<CalculationItemFilters>
<Types>
<string>MPHASE_METER</string>
</Types>
</CalculationItemFilters>
<CalculationParameters>
<CalculationParameter Name="MPHASE_MTR_VX.POS_12VDC"
SourceLevel="AVOCET_HF_STORE"
CalcType="Input"
Type="MPHASE_MTR_VX"
Property="POS_12VDC"
ValueType="Historical"
AggregationMethod="None"
AggregateResampleInterval="0.01:00:00"
TimeSpan="2.00:00:00"
Offset="0.00:00:00"
MaxValuesToReturn="5000" />
<CalculationParameter Name="MPHASE_MTR_VX.NEG_12VDC"
SourceLevel="CORP_HISTORIAN"
CalcType="Input"
Type="MPHASE_MTR_VX"
Property="NEG_12VDC" />
<CalculationParameter Name="MPHASE_MTR_VX.HART_24VDC"
CalcType="Output"
Type="MPHASE_MTR_VX"
Property="HART_24VDC" />
<CalculationParameter Name="MPHASE_MTR_VX.INPUT_24VDC"
CalcType="Output"

193
 Type="MPHASE_MTR_VX"
Property="INPUT_24VDC" />
</CalculationParameters>
</CalculationDefinition>
This section parses the XML markup of this sample calculation. It examines its elements and attributes.

CalculationDefinition
This topic defines the following elements: CalculationDefintion, HistoricalTimeInterval, and Supersede.
The CalculationDefinition element has its unique name and ID. Note that the name and ID can be
the same, but they must be unique to the definition.
The HistoricalTimeInterval attribute is set equal to 5, meaning that the calculation parameters are
automatically set to run every 5 seconds even if the values have not changed.
The Supersede attribute refers to the calculation parameter MPHASE_MTR_VX.NEG_12VDC. By
specifying the Supersede attribute, you ensure that the latest value of this specified parameter is
returned as the output value for the respective tag in the Avocet client.

CDATA
The CDATA section contains any string type character data not considered part of the XML markup.
It is passed to the calculation when it is instantiated.

Calculation Reference
The CalculationReference element points to the programming assembly (.dll) and class (.cs), both
of which implement the calculation in the C# code project of the calculation definition.

CalculationItemFilters
This topic discusses the CalculationItemFilters element that specifies the filtering level or levels
applied to the item that is the subject of the calculation.
In this example, the high-level filter <Types> is specified as MPHASE_METER. You could apply more
detailed filtering criteria, down to the actual name of the item.

CalculationParameters
In this example, the <CalculationParameters> element contains two input and two output calculation
parameters. One input is raw historical data and the other is raw real-time data.
• The first input, MPHASE_MTR_VX.POS_12VDC, applies to the property POS_12VDC for the
multiphase meter transaction MPHASE_MTR_VX, shown here in this excerpt from the Type Editor
screen:

Attributes Description

Name MPHASE_MTR_VX.POS_12VDC. The transaction type name (MPHASE_MTR_VX) and

transaction property (POS_12VDC)

SourceLevel AVOCET_HF_STORE. Source of the data

ValueType Historical. Indicates the value type

AggregationMethod None. Indicates that the historical data is not aggregated. It is raw historical data.

194 Avocet High Frequency Infrastructure

 The AggregationMethod attribute is set to None. Because it is set to None, the dependent attribute
AggregateResampleInterval does not apply. However, the attributes TimeSpan, Offset, and
MaxValuesToReturn do apply to non-aggregated data.
• The next input, MPHASE_MTR_VX.NEG_12VDC, is a raw, real-time data parameter from the
corporate historian data source. It applies to the property NEG_12VDC for the transaction
MPHASE_MTR_VX, as seen in this excerpt from the Type Editor screen:

Attributes Description

Name MPHASE_MTR_VX.NEG_12VDC. The transaction type name (MPHASE_MTR_VX) and

transaction property (NEG_12VDC)

SourceLevel CORP_HISTORIAN. Source of the data

• Two output calculation parameters are defined for two properties of the MPHASE_MTR_VX
transaction: MPHASE_MTR_VX.HART_24VDC and MPHASE_MTR_VX.INPUT_24VDC. When the
calculation is run, the output tag for each property is generated, and the current values are stored in
the Avocet HF Store.

Calculation parameter for item type and property

This topic discusses how to apply a calculation to an item and its property when the data source is
the Avocet database and when the data type is real-time data.
The previous generic example showed calculation parameters that apply to transactions and their
properties.
In the two examples in the following snippet, the item that is referenced by the PropertyType attribute
is the item name MPHASE_METER that is appended to the parameter name in this format:
ItemName.ItemProperty.
<CalculationParameter Name="MPHASE_METER.TOP_TVD"
SourceLevel="AVOCET"
PropertyType="Item" [The “Item” is MPHASE_METER.]
CalcType="Input"
Type="" [Transaction type is blank.]
Property="TOP_TVD" [This is the item property.]
DataChangeTrigger="StatusValue" />
<CalculationParameter Name="MPHASE_METER.TOP_MD"
SourceLevel="AVOCET"
PropertyType="Item"
CalcType="Input"
Type=""
Property="TOP_MD"
DataChangeTrigger="StatusValue" />
The first listed calculation applies to the TOP_TVD property of the item MPHASE_METER, and the
second calculation applies to the TOP_MD property of the same item. You can see the item and its
related properties in the Type Editor screen, as shown in this excerpt:

195
Custom clamping calculation: walkthrough
This walkthrough example of a real-time custom calculation looks at its customized XML markup and
its accompanying C# project and code content. It then describes the procedure for implementing the
calculation in Avocet after you have compiled the code.
The following chart outlines the main stages in the creation of a custom calculation:

The purpose of this calculation is to implement the following equation for vibration control:
|Vibration|=vibrationx2+ vibrationy2+vibrationz2. The values on the right side of the equation are the
inputs, and the value on the left side of the equation is the single output.

XML framework
The XML markup in this topic is an example of a real-time custom calculation definition. It has three
input parameters and a single output. You can formulate the XML markup before or after you have
created the C# project.
<Calculations>
<!-- Vibration Control Calculation -->
<CalculationDefinition Id="VibrationControl_Calculation_ABC"
Name="VibrationControl_Calculation_ABC" HistoricalTimeInterval="5" >
<![CDATA[
<CalculationReference Assembly="Slb.AvocetVM.ABCSharedInterfaces"
TypeToInvoke="Slb.AvocetVM.ABC.HF.Calculation.Cal_VibrationControl_ABC" />

196 Avocet High Frequency Infrastructure

<CalculationItemFilters>
<Types>
<string>COMPLETION</string>
</Types>
</CalculationItemFilters>
<CalculationParameters>
<CalculationParameter Name="ABN_READ.VIBRATION_X" SourceLevel=
"CORP_HISTORIAN" CalcType="Input" Type="ABN_READ" Property=
"VIBRATION_X"/>
<CalculationParameter Name="ABN_READ.VIBRATION_Y" SourceLevel=
"CORP_HISTORIAN" CalcType="Input" Type="ABN_READ"
Property="VIBRATION_Y" />
<CalculationParameter Name="ABN_READ.VIBRATION_Z" SourceLevel=
"CORP_HISTORIAN" CalcType="Input" Type="ABN_READ"
Property="VIBRATION_Z" />
<CalculationParameter Name="ABN_READ.VIBRATION_CON" CalcType="Output"
Type="ABN_READ" Property="VIBRATION_CON" />
</CalculationParameters>
</CalculationDefinition >
</Calculations>
The following table summarizes the main attribute and elements.

Element Attribute Description

CalculationDefinition ID Unique ID for this calculation. Each calculation definition must have
a unique ID. In this example the ID is
VibrationControl_Calculation_ABC.

Name Unique name for this calculation. Each calculation definition must
have a unique name. The ID and name can share the same value,
as they do in this example, but they must be unique to the definition.

Historical Time Functions as a timer that fires the input calculation at the successive
Interval interval (measured in seconds). As a result, the input calculation is
run even if its value has not changed.You can use the historical time
interval to generate simulated data. In this example, the interval is 5
seconds.

[CDATA] Passes character data to the calculation. No CDATA strings are is

provided in this example.

Calculation Reference Assembly Name of the DLL file that the calculation references. After you compile
the code, you will need to copy this particular DLL file to the following
subfolder:

implementationFolder\AvocetVM\HF\Apis\Calculations

TypeToInvoke Refers to the namespace and the public class that the calculation
invokes. In this example, the name of the public class is
Cal_VibrationControl_ABC.

CalculationItemFilters The filtering criteria contained in a series of nested elements. In this

example the criteria is general: only the item category COMPLETION
is specified. The filtering criteria can extend to the name of the item:
for example, COMPLETION_123.

CalculationParameter Name Name of the calculation parameter. The calculation parameter name
follows this convention: transactiontype.transactionproperty.

197
 Element Attribute Description

SourceLevel The source of the input data. In this example, it is real-time data from
the corporate historian. The options are

• AVOCET (the Avocet database)

• AVOCET HF STORE
• CORP_HISTORIAN

CalcType Indicates the type of calculation. The options are input or output.

Type The transaction type that the calculation is linked with

Note: If the SourceLevel=AVOCET (the Avocet database),

you can link the calculation with an item and an item property.
See Calculation parameter for item and propertyfor more
information.

Property The transaction type property that the calculation is linked with

Note: If the SourceLevel=AVOCET (the Avocet database),

this can be an item property.

The output parameter, ABN_READ.VIBRATION.COM, provides the value to the output tag in the
Avocet HF Store.

C# project
This topic discusses defining your custom project in Visual Studio when programming your calculation
in C#.
When programming your calculation in C#, you need to define your custom project in Visual Studio.
The folder structure of an example custom project is shown below:

The project folders contain class definitions that support the custom project. The high-frequency
calculation is contained in the HF folder. A summary description of the other folders follows:

Folder Description

Calculation Contains calculations that apply in contexts other than high frequency

Config Contains classes for various configuration rules, actions, and extensions

198 Avocet High Frequency Infrastructure

Folder Description

Data Class definitions for various data items and transactions

DomainDefs Class definitions for a specific domain. In this case, it is the well test transaction.

HF Class definitions for the high-frequency calculations are stored in this folder.

obj Contains debug information

Properties Contains identifying information for the assembly file. In this example, it is
Slb.AvocetVM.ABCSharedInterfaces.

This is the file that you will need to copy to the

implementationFolder\AvocetVM\HF\Apis\Calculations subfolder after you compile the
code.

Screens Class definitions for different screen properties

The sample C# class referenced in the XML markup (highlighted in the attribute
TypeToInvoke="Slb.AvocetVM.ABC.HF.Calculation.Cal_VibrationControl_ABC") is shown below:
using Slb.Avocet.HF.Interfaces;
using Slb.Avocet.HF.Configuration;
using Slb.Avocet.HF.Calculations;
namespace Slb.AvocetVM.ABN.HF.Calculation
{
public class Cal_VibrationControl : HighFrequencyCalculationBase
{
protected override ICalculationStatus OnCalculate(ICalculationInputs inputs, ICalculationOutputs
outputs)
{
var result = new CalculationResult { Success = true, Description = "Success" };
try
{
if (inputs.Inputs.Count < 1 || outputs.Outputs.Count < 1)
{
result.Success = false;
result.Description = "The cleansing calculation expects three inputs and one output.
The first being the tag to cleanse.
The second the Lo Clamping value.
The Third the Hi Clamping value.
The output will be the cleansed value.";
}
var index = 0;
ICalculationInput vibrationxValue = null;
ICalculationInput vibrationyValue = null;
ICalculationInput vibrationzValue = null;
// TODO: support IList on inputs
foreach (var input in inputs.Inputs.Values.ToList())
{
switch (index)
{
case 0:
vibrationxValue = input;
break;
case 1:
vibrationyValue = input;
break;
case 2:
vibrationzValue = input;

199
 break;
}
index++;
}
var vibrationx = Convert.ToDouble(vibrationxValue.Value);
var vibrationy = Convert.ToDouble(vibrationyValue.Value);
var vibrationz = Convert.ToDouble(vibrationzValue.Value);
var output = outputs.Outputs.First().Value;
output.Value = (Math.Sqrt(vibrationx * vibrationx) +
(vibrationy * vibrationy) + (vibrationz * vibrationz));
outputs.Outputs[outputs.Outputs.Keys.FirstOrDefault()] = output;
}
catch (Exception ex)
{
Logger.LogException(ex, "TestCalulation Failed", true);
result.Success = false;
result.Description = ex.Message;
}
return result;
}
}
}
As the code comments indicate, the input parameters reflect the three data points of a clamping
calculation.
• tag (transaction and property) whose value is the target of the clamping calculation
• low alarm limit
• high alarm limit
Whenever the clamp value exceeds either the low or high alarm limit, its value is calculated as the low
or high alarm limit value. So the clamped value equals the low alarm limit or high alarm limit, and the
respective data point is stored in the Avocet HF Store. This is the cleansed value that is captured by
the output calculation parameter.

Note: Because the output parameter is defined for the cleansed value, you do not specify a
Supersede attribute. In a clamping calculation consisting only of input parameters, the Supersede
attribute points to the input parameter whose transaction and property contain the value to be
clamped.

Consider also the following aspects of the code sample:

• The code uses the foreach statement to iterate through the list of input parameters.
• The equation is defined as the output value.
• Input values are converted to decimals through the Convert method.
• A method for catching and logging exceptions is defined.
After you compile the code, you are ready to add the custom calculation to your Avocet high-frequency
configuration.

Implementing the custom calculation in the Avocet high frequency deployment

This task shows how to implement your custom calculation in the Avocet high frequency deployment.
To implement the custom calculation, you first copy the assembly DLL that was generated during
compilation to the <implementationFolder>\HFIManager\HF\Apis\Calculations subfolder.
Apis-related custom modules and calculations are stored in the
<implementationFolder>\HFIManager\HF\Apis subdirectory. You use a Windows PowerShell script

200 Avocet High Frequency Infrastructure

to copy the custom calculations and modules to the appropriate subfolder in the APIS installation
directory and to register them.
You must have administrator privilege to execute the PowerShell scripts described in this procedure.
Follow these steps to run the post-install process that adds the custom calculation to the APIS
high-frequency configuration. You first configure the execution policy for the PowerShell script.

1. Open a Windows PowerShell command window.

You can type powershell in the search text box of the Start menu to locate the executable
PowerShell in the Start search entries.
You can launch the executable by clicking PowerShell in the Start menu. If you do not have
administrator privilege on the system, right-click PowerShell to open the flyout menu, and choose
Run as Administrator.
If you are running on Windows 8, see the accompanyingTroubleshooting note: Windows 8 .
2. Change directory (cd) to the directory path <implementationFolder>\HFIManager\HF\Apis
3. Enter the following command at the prompt:
Get-ExecutionPolicy
You should receive the message RemoteSigned.
You are done with the post-install configuration.
If the message Restricted is returned or any message other than RemoteSigned is returned, then
you need to change the execution policy.
To change the execution policy, enter the following command at the prompt:
a) Set-ExecutionPolicy RemoteSigned
b) At the message prompt, type Y or press Enter to accept the default.
c) Then re-enter the Get-ExecutionPolicy command. The message RemoteSigned should be
returned.
After configuring the execution policy, you then run the post-install script postinstall.ps1 in the
Windows PowerShell command window.

4. At the command prompt for the directory path <implementationFolder>\HFIManager\HF\Apis ,

enter postinstall.ps1.
The custom calculation should now be registered.

Troubleshooting note: Windows 8

This task shows how to modify the Windows PowerShell shortcut so it always runs with administrator
privileges.
On a Windows 8 system, when launching the PowerShell window you may get an error when running
the script. To run the script successfully, you have to select Run as Administrator even if you are
the administrator on the system. To avoid this extra step, you can modify the Windows PowerShell
shortcut so that it always runs with the administrator privilege.

1. Right-click the Windows PowerShell shortcut to display the flyout menu, and choose Properties.

201
 2. In the Shortcut tab of the Windows PowerShell Properties dialog, choose Advanced… .
3. In the Advanced Properties pop-up, select the Run as administrator check box.

4. Click OK to close the Advanced Properties pop-up.

5. Click Apply in the Windows PowerShell Properties dialog, and then click OK.

202 Avocet High Frequency Infrastructure

 Alternatively, you can disable User Account Control (UAC) in Windows 8. Open the User Account
Control Settings window, and change the setting to Never Notify. This method, however, is not
recommended.
Next, launch the Avocet client to access the Data Flow Configuration screen for the item type to
which you have applied the calculation definition. Select the individual item or items to which the
calculation applies, and click Home > HF Store > Synchronize for each entry.

Historical value calculation

This topic discusses historical value calculations. Historical calculations are run against historical data,
not current data.
Historical data consists of values that have occurred before the current time.
In most cases, you apply a historical value calculation to inputs from the Avocet HF Store and the
corporate historian for specified transaction types and properties.
Instead of receiving the raw input values, you can apply aggregation methods to calculate averages,
means, ranges, variances, and other views of the data points over a specified interval.
The following example shows the XML markup of a historical calculation definition for the WELL_READ
transaction.
<?xml version="1.0" encoding="utf-8"?>
<CalculationDefinition Id="HistoricalCalculation"
Name="HistoricalCalculation"
<![CDATA[
This text will be passed on to the calculation upon instantiation
<CalculationReference Assembly="Slb.Avocet.HFCalculations"
TypeToInvoke="Slb.Avocet.HF.Calculations.HistCalc" />
<CalculationItemFilters>
<Types>
<string>COMPLETION</string>
</Types>
</CalculationItemFilters>
<CalculationParameters>
<CalculationParameter Name="WELL_READ.CASING_PRESS1"
SourceLevel="AVOCET_HF_STORE"
CalcType="Input"
Type="WELL_READ"
Property="CASING_PRESS1"
ValueType="Historical"
AggregationMethod="Minimum"
AggregateResampleInterval="0.00:30:00"
TimeSpan="0.12:00:00"
Offset="0.00:00:00"
MaxValuesToReturn="22" />
<CalculationParameter Name="WELL_READ.CASING_PRESS2"
SourceLevel="AVOCET_HF_STORE"
CalcType="Input"
Type="WELL_READ"
Property="CASING_PRESS2" />
ValueType="Historical"
AggregationMethod="Maximum"
AggregateResampleInterval="0.00:30:00"
TimeSpan="0.12:00:00"
Offset="0.00:00:00"
MaxValuesToReturn="22" />
<CalculationParameter Name="WELL_READ.CASING_PRESS3"
CalcType="Output"

203
 Type="WELL_READ"
Property="CASING_PRESS3" />
</CalculationParameters>
</CalculationDefinition>
This calculation definition consists of two inputs, both aggregated, and a single output tag that captures
the calculated values.
The first input takes a casing pressure reading of the WELL_READ transaction of the COMPLETION
item type. It aggregates the data points over a sampling interval of 30 minutes, taking the minimum
raw value returned during the sampling interval and applying the interval start time as the time stamp
of the aggregated value. The calculations are applied for a period of 12 hours before the current time,
without an offset.
The MaxValuesToReturn attribute is specified. It caps the number of returned values at 22 within the
time span. The value count begins chronologically 12 hours before the current time and continues
through 22 data points, ending one hour before the current time.

The second input takes a second casing pressure reading from the WELL_READ transaction and
applies the maximum aggregation method over the same sampling interval and time span.The maximum
aggregation method returns the maximum raw value of the sampling interval, using the interval’s start
time as its time stamp.
The single tag output value in the Avocet HF Store depicts a third casing pressure value for the
WELL_READ transaction.

Custom percent change calculation

In this example, the percent change calculation is designed to show the percentage change (the delta)
in values of intake and discharge pressures. The output parameter is the delta, and the two input
parameters are the pressure readings.
To create a similar calculation, you can follow the guidelines described under Custom clamping
calculation: walkthrough.
Note that in the XML framework the output parameter has a data type value assigned to it (“double”
in this example). In some implementations, the data type is required so that the output value is visible.
<?xml version="1.0" encoding="utf-8" ?>
<HFConfig xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Calculations>
<CalculationDefinition Id="DeltaP_Calc" Name="DeltaP_Calc">
<CalculationReference Assembly="Slb.Avocet.ALMHFCalculations"
TypeToInvoke="Slb.Avocet.ALMHFCalculations.DeltaPCalc" />
<CalculationItemFilters>
<SingleItems />
<SubTypes />
<Types>

204 Avocet High Frequency Infrastructure

 <string>COMPLETION</string>
</Types>
</CalculationItemFilters>
<CalculationParameters>
<!--Input Parameters-->
<CalculationParameter Name="ESP_READ.PUMP_INTK_PRESS"
CalcType="Input"
Type="ESP_READ"
Property="PUMP_INTK_PRESS"
SourceLevel="AVOCET_HF_STORE"
ValueType="Raw" AggregationMethod="None"
AggregateResampleInterval="0.01:00:00"
TimeSpan="1.00:00:00" Offset="0.00:00:00"
MaxValuesToReturn="5000" />
<CalculationParameter Name="ESP_READ.PUMP_DISC_PRESS"
CalcType="Input"
Type="ESP_READ"
Property="PUMP_DISC_PRESS"
SourceLevel="AVOCET_HF_STORE"
ValueType="Raw" AggregationMethod="None"
AggregateResampleInterval="0.01:00:00" TimeSpan="1.00:00:00"
Offset="0.00:00:00" MaxValuesToReturn="5000" />
<!--Output Parameter-->
<CalculationParameter Name="ESP_READ.DELTA_P"
CalcType="Output"
Type="ESP_READ"
Property="DELTA_P" DataType="Double" />
</CalculationParameters>
</CalculationDefinition>
In the accompanying C# class definition, note that it follows a familiar pattern: input parameters, output
parameter, decimal conversion, and the calculation formula.
using System;
using Slb.Avocet.HF.Calculations;
using Slb.Avocet.HF.Configuration;
using Slb.Avocet.HF.Interfaces;
namespace Slb.Avocet.ALMHFCalculations
{
public class DeltaPCalc : HighFrequencyCalculationBase
{
protected override ICalculationStatus OnCalculate(ICalculationInputs
inputs, ICalculationOutputs outputs)
{
CalculationResult result = new CalculationResult { Success = true,
Description = "Success" };
try
{
//Input Parameter Validation:Intake Pressure
ICalculationInput intakePressure;
if (!inputs.Inputs.TryGetValue("ESP_READ.PUMP_INTK_PRESS", out
intakePressure))
{
result.Success = false;
result.Description = "No input for the intake pressure";
return result;
}
//Input Parameter Validation:Discharge Pressure
ICalculationInput dischargePressure;
if (!inputs.Inputs.TryGetValue("ESP_READ.PUMP_DISC_PRESS", out
dischargePressure))

205
 {
result.Success = false;
result.Description = "No input for the discharge pressure";
return result;
}
//Output Parameter Validation: Delta Pressure
ICalculationOutput output;
if (!outputs.Outputs.TryGetValue("ESP_READ.DELTA_P", out output))
{
result.Success = false;
result.Description = "No output for the delta p";
return result;
}
//Parameters to Decimal
decimal intakePressureValue =
Convert.ToDecimal(intakePressure.Value);
decimal dischargePressureValue =
Convert.ToDecimal(dischargePressure.Value);
//Calculation: DP=Discharge Pressure - Intake Pressure
output.Value = dischargePressureValue - intakePressureValue;
output.Quality = Quality.Good;
}
catch (Exception ex)
{
result.Success = false;
result.Description = ex.GetType().FullName + ": " + ex.Message;
}
return result;
}
}
}

Custom calculation validations

To implement custom calculation validations in C#, you define three interfaces. The public interface
and base class implementation definitions distinguish the
You define the following public interfaces in C# to support custom calculation validations:
• ISynchronizationValidation.Validate(ISynchronizationValidationParameter parameter)
• ICalculationValidation.ValidateCalculation(ICalculationValidationParameter parameter)
• ICalculationValidation.ModifyCalculationParameters(ICalculationValidationParameter parameter)
The following code example shows the method for returning synchronization validation results:
{

public ISynchronizationValidationResult Validate(ISynchronizationValidationParameter

parameter)
{

foreach (var pair in parameter.Queue().Keys)

{
if (pair.Historian.Level.Equals(DataSrcLevel.CorpHistorian))
{
var queue = parameter.GetQueue<ITag, string>(pair);
foreach (var tag in queue)
{
tag.Value.Data.Trigger = Opc.Ua.DataChangeTrigger.StatusValueTimestamp;
}
}

206 Avocet High Frequency Infrastructure

 }
return new SynchronizationValidationResult(true);
}
}

207
PI Historian configuration
You can configure the PI System historian to communicate with the Avocet HF store much as you
would other historians, except that it has its unique configuration file. After you complete the
configuration tasks, you can automatically populate the PI System historian with tags.
To configure the PI System historian, you edit the CDATA section in the implementationFolder
\HFIManager\Config\HFConfig_PIHistorian.xml file.
The following diagram depicts the data flow at the back end of a high-frequency implementation of the
PI historian:

You can refer to the topic High frequency infrastructure: components and implementation for details
about the component relationships.

HFConfig_PIHistorian.xml
The implementationFolder \HFIManager\Config\HFConfig_PIHistorian.xml file contains the configuration
information for your PI historian implementation. Its CDATA section contains the PI configuration data
that the corresponding C# assembly code implements.

Element Name Attributes Description

PISystem DefaultServer, Name, DefaultServer is a Boolean True/False indicator that says whether a
Host default PI system server is available. The default value is false. Name is
the name assigned to the PI system server. Host is the name of the
machine where the PI system server resides.

208 Avocet High Frequency Infrastructure

 Element Name Attributes Description

PIServer Name, Host, Force Name is the name of the PI server, the system that receives the data from
the PI historian. Host is the name of the machine where the PI system
server resides. Force is a Boolean True/False indicator that forces the
connection to the PI server.

Database Default, Name Default is a Boolean True/False indicator showing whether the default
database is used. Name is the name of the database instance.

TagManagement UseElements UseElements should be set equal to true. It identifies the PI system tag
naming format in the OPC UA address space: collective name, element,
delimiter, and element attribute (point). In Avocet, this syntax is equivalent
to Avocet HF Store, item, transaction, and property.

PointConfiguration ClassName, ClassName refers to a PI system server class. ArchivingDefault, when

ArchivingDefault, set equal to true, enables logging in the PI system. TagRegex specifies
TagRegex the regular expressions used to substitute the values in the text that makes
up the node ID of the tag definition.

Elements AutoCreateMissing When its value is set equal to true, AutoCreateMissingAttribute enables
Attributes the automatic creation of tags in the PI historian during synchronization.
You should keep the value as true to enable tag autocreation.

ElementTemplateMapping SourceType, Name SourceType identifies the Avocet item. Name refers to the name assigned
to the template.

Edit the HFConfig_PIHistorian.xml file

In the implementationFolder \HFIManager\Config\HFConfig_PIHistorian.xml file, you enter your PI
configuration data in the CDATA section. You can also assign additional synchronization actions to
run on the historian, provided you have implemented the corresponding code in your
PIHistorianSyncManager class in the PIHistorianSyncManager.cs file.

1. In the CDATA section, enter the PI configuration data for your implementation.
2. Save the file.

Define data tags

The tag definition is derived from your PI system implementation.You must structure your tag definitions
in a consistent way so that the tag synchronization process can automatically create them in the PI
historian.

1. Review the TagManagement node in theimplementationFolder

\HFIManager\Config\HFConfig_PIHistorian.xml file to determine the syntax of the tag in the OPC
UA address space.
The syntax has four components: collective name, element, delimiter, and element attribute.
2. In the PointConfiguration node, review the TagRegex attribute to uncover the regular expression
that determines the syntax pattern of the tag name.
A filled-in syntax pattern would look similar to this:
ns=7;s=i\\Avocet_HF_Store\MPFM-2349.VX_Meter.VX_12Volt.
The components that make up the node ID are described in the following table:

Component Description

209
 ns=7 namespace qualifier. The numeric value is unique

s=i address qualifier for the node ID. Values are s (string), i (integer), or g (GUID
identifier).

Avocet_HF_Store Collective in the node ID

MPFM-2349 Item in the node ID

Vx_Meter Transaction

VX_12Volt Property

Load data tags

You load the tags into the Avocet database to import their SCADA and hierarchical data and links.
The tag definitions must conform to the syntax specified in the HFConfig_PIHistorian.xml configuration
file that applies to the node IDs.
This procedure assumes that the tags and data have been entered into an Excel spreadsheet and
that a corresponding XML loader file which calls the Excel spreadsheet has been prepared.

1. Launch the Avocet Configuration Tools utility ConfigTools.exe.

2. Go to Data Tools > Data Loaderto open the Data Loaderscreen.
3. In the Import task file field, specify the XML loader file
The import tasks are listed.
4. Select the tasks you want to import.
5. Choose Tools > Load Selected Tasks.
The item, transaction, and other related data should load.

Autocreate PI historian tags

You autocreate PI historian tags after you have loaded the properly formatted tags to the Avocet
database.

1. In the Navigation Tree, choose the item for which you want to create tags in the PI historian.
2. In the ribbon toolbar, choose Home > Linked Screens > Data Flow to open the Data Flow
Configuration screen for the item.
3. Select the Show Details check box to display all the data columns.
4. In the Navigator list, select the item that you want to synchronize.
Its tags are displayed under the data columns.
5. Select the entries for which you want to create tags in the PI historian.
6. In the ribbon toolbar, choose Home > HF Store > Synchronize to populate the PI historian with
the properly formatted data tags you defined.

210 Avocet High Frequency Infrastructure

Avocet web services API
The Avocet web services API supports the deployment of web applications.
The Avocet web services API is addressed to deployment engineers who are already familiar with
• web services
• Swagger
• REST
• ASP.NET
• SignalR
This current version of the Avocet web services API is released "as-is." It does not include examples
of tested extensions.
The following table summarizes the main setup tasks. The task sequence is not prescriptive, but the
table lists a recommended order.

1 Determine how to share configuration files between the AvocetVM package and the AvocetWebService package.

2 Edit the Web.config file to point to the Config folder.

3 Add the license file path to the AppConfig.xml in the Config folder referenced by the Web.config file.

4 Define Active Directory users and roles, and enable pass-through authentication in the
AppConfig_ProjectLayer.xml file that resides in the Config folder referenced by the Web.config file.

5 Set up the IIS web server.

6 Launch the Swagger UI document to verify connectivity.

7 Add the <webApiServer> tag to the AppConfig_ProjectLayer.xml file in the Config folder referenced by the
Web.config file.

8 In the Avocet Configuration Tools utility, apply security constraints to user roles and HTTP request methods.

9 Configure the notification system.

10 Configure SignalR scale out parameters for high frequency alarm notifications and data support.

Share configuration files between AvocetVM and AvocetWebService projects

The AvocetWebService project contains a Web.config file that points to the Config folder that has the
requisite configuration files for the web service.
The Web.config file contains an <avocet.config> element. This element, in turn, has an appConfigPath
attribute where you specify the path to the Config folder that your AvocetWebService project uses.
The specific Config folder that you point to and how you maintain the folder depend on your AvocetVM
and AvocetWebService configuration. Three representative scenarios follow:
1. Scenario 1: The AvocetVM and AvocetWebService packages reside on the same system. AvocetVM
is only used to support AvocetWebService.
2. Scenario 2: The AvocetVM and AvocetWebService packages reside on the same system. However,
AvocetVM is also used for non-web purposes, such as allocations, reporting, Avocet Mobile, and
so forth.
3. Scenario 3: The AvocetVM and AvocetWebService packages reside on different systems.

211
 The following guidelines are descriptive, not prescriptive. However, each specifies a workable solution.

Note: It is important that you track your configuration changes to make sure that they are copied
to all relevant /Config subfolders in your project.

1. If you implement Scenario 1, then do the following:

a) Maintain the configuration files in the AvocetVM\Config subfolder.
b) Specify the path to the AvocetVM\Config subfolder in the Web.config file.
2. If you implement Scenario 2, then do the following:
a) Copy all the configuration files in the AvocetVM\Config subfolder to the
AvocetWebService\bin\Config subfolder.
b) Specify the path to the AvocetWebService\bin\Config subfolder in the Web.config file.
c) Maintain the updates in both subfolders by copying and pasting the relevant updates from one
Config subfolder to the other.
3. If you implement Scenario 3, then do the following:
a) Copy all the configuration files in the AvocetVM\Config subfolder to the
AvocetWebService\bin\Config subfolder.
b) Specify the path to the AvocetWebService\bin\Config subfolder in the Web.config file.
c) Maintain the updates in both subfolders by copying and pasting the relevant updates from one
Config subfolder to the other.

Edit the Web.config file and verify the license file path
Before installing Internet Information Services, in the Web.config file, specify the relative or absolute
path to the Config folder where your AppConfig.xml file, AppConfig_ProjectLayer.xml file, and all
other related configuration and layer files reside. In your AppConfig.xml file, specify the Avocet license
file path.

1. Open the ..\AvocetWebService\Web.config file in a text editor, and look for the <avocet.config>
element:<avocet.config appId="AvocetDev Passthru (MSSQL)" appConfigPath="..\..\config"/>.

Note: The default out-of-the-box appConfigPath attribute value contains relative path
indicators ..\..\.

Do not specify an application ID. You only need to point to the Config folder that contains the
AppConfig.xml file and the other configuration files that you intend to use, such as your
AppConfig_ProjectLayer.xml files and their dependent files.
2. Assuming your AppConfig.xml file resides under the installDirectory\AvocetWebService\bin\config
folder, for the appConfigPath attribute, remove the relative path indicators to point to the underlying
Config folder, as in this example:
<avocet.config appId="MyAppId"
appConfigPath="config"/>
If your Config folder resides at a different location, adjust the path definition accordingly. You can
use an absolute path, such as c:\installDirectory\AvocetVM\config.
3. Save the updated Web.config file.
4. In a text editor, open the AppConfig.xml file in the Config subfolder that your Web.config file
points to.
5. Locate the <licenseFilePath> element under the <Global> node.

212 Avocet High Frequency Infrastructure

 6. Enter the absolute path to your local license file or the port number and path to your license server.
In this example, the port number and path of a license server are entered:
<licenseFilePath>[email protected]
</licenseFilePath>

Note: Your license file or license server should contain all requisite licenses, including the
Avocet_Web license.

7. Save the AppConfig.xml file.

8. If you are maintaining the configuration files under the AvocetVM\Config and
AvocetWebService\bin\Config subfolders, maintain the updates in both locations.

Enable pass-through authentication

You must enable Windows pass-through authentication so that the user credentials (held by the Active
Directory pass-through server) can be authenticated on the Avocet non-mobile client (AvocetVM) and
the web service without requiring multiple logins.

Note: The Avocet Mobile client requires basic authentication (user name and password).
Nevertheless, in a Mobile deployment, the web services server requires Windows pass-through
authentication.

Ensure that the authenticated user account has been defined in the System User screen accessed
through the Administration > Users and Roles > System User node.
Before adding the XML markup to your AppConfig_ProjectLayer.xml file, you must define your Active
Directory users and roles. The procedure differs depending on whether you are defining separate
users or importing multiple users. If importing multiple users, you need to perform an Active Directory
synchronization after performing the initial configuration.

Note: For a detailed procedure describing how to set up pass-through authentication, see the
Security Help topic.

You add the pass-through XML markup to your project layer’s AppConfig_ProjectLayer.xml file. Ensure
that your project layer’s AppConfig_ProjectLayer.xml file containing the pass-through definition resides
in the Config folder specified in the Web.config file.
This topic provides summary guidelines for those already familiar with the steps.

1. In your AppConfig_ProjectLayer.xml file of your project layer, locate the <application id> node of
the database to which you are connected.
2. Under the <application id> node, enter the <authenticationType> definition at the same level as
the <description> and <database> entries. Assign the value passthru to the <authenticationType>
element.
<application id="MyAppID">
<description>MyAppID</description>
<authenticationType>passthru</authenticationType>
<database>
......

3. Verify that your <connectString> is appropriate for your database server authentication type.

213
 For example, if you connect to your MS SQL Server or Oracle database server using Window
authentication, the corresponding connection strings should display as in the following examples:
• MS SQL Server
<connectString>Network Library=DBMSSOCN;Data Source=DatabaseServer,1433;
Initial Catalog=DatabaseName;User ID=your_username; Password=your_password;
Application Name=AVM</connectString>
Do not use the Integrated Security keyword in the web service connection string.
• Oracle
<connectString>Data Source=MyOracleDB:1521;User Id=myUsername;
Password=myPassword;Integrated Security=no</connectString>

Note: Refer to the non-Schlumberger website for more information on connection strings.

4. As a safeguard, if you are maintaining an AvocetVM\Config subfolder and an

AvocetWebService\bin\Config subfolder, make sure the updated file resides in both locations.
5. To initialize this change, after you set up your IIS configuration, start the .NET v4.5 application pool:
a) In the Connections tree, select Application Pools under the server node to display the
Application Pools pane.
b) Right-click the .NET v4.5 entry in the list to display the flyout menu. and choose Stop if the pool
is running and then choose Start. Otherwise, choose Start.

Encrypt database connection strings

This task shows how to use the Encrypt text feature of the Avocet Configuration Tools utility to generate
an encrypted connection string.
Each connection string in the database node of the AppConfig_ProjectLayer.xml file has a
corresponding encryption node whereby you can obfuscate the database connection string.
A sample unencrypted excerpt from a database node of an AppConfig.xml file is shown below:
<application id="MyAppID">
<description>MyAppID</description>
<authenticationType>passthru</authenticationType>
<database>
<driver>SQLSERVER</driver>
<sqlsyntax>SQLSERVER</sqlsyntax>
<connectString>Network Library=DBMSSOCN;Data Source=ServerName;
Initial Catalog=DatabaseName;User ID=MyID;
Password=MyPassword;Application Name=AVM </connectString>
<connectStringForSsas>[Connection string that allows SSAS
to connect to Avocet DB]</connectStringForSsas>
</database>
The <connectString> node has an encrypted version called <cryptoConnectString>.
You can obtain the encrypted connection string through the Encrypt String feature of the Avocet
Configuration Tools utility (Security and Auditing Tools > Encrypt String).

214 Avocet High Frequency Infrastructure

To generate the encrypted connection string, you copy the unencrypted connection string, but not the
element name within the angle brackets, and paste it into the Text to Encrypt text field.

Tip: Copy and encrypt one connection string at a time.

Then click Encrypt to generate the encrypted text:

215
 In the AppConfig_ProjectLayer.xml file under the appropriate <database> node, enter the
<cryptoConnectString> element at the same level in the XML hierarchy as the original <ConnectString>
.
Copy the encrypted text from the Encrypted Text field to the corresponding element definition in the
AppConfig_ProjectLayer.xml file under the <database> node, as shown in the following example:
<database>
<driver>SQLSERVER</driver>
<sqlsyntax>SQLSERVER</sqlsyntax>
<cryptoConnectString>OiVYcCGovU952p11uCN
FawipR98pAYLEqMA42U5R36ZgoAjArZxzM3dl4EPg2CXWJYi/dtYT
24Pmlgr869RL9CToot3K0jboHMk4n4Ug+j38rBD2uUCxdlPx+EyqQN
z38j+Qwif4sWm</cryptoConnectString>

Restart the Avocet client to initialize any changes.

Note: The Decrypt function is not implemented.

Encrypt passwords in regular connection strings

You can encrypt the password you use in a regular, unencrypted database connection string and
assign it to a cryptoPassword attribute within the <connectionString> element of the application ID
definition.
You can use this encryption approach instead of encrypting the entire connection string.

1. In the Avocet Configuration Tools utility, access the Security and Auditing Tools > Encrypt String
node to display the Encrypt Stringpane.
2. In the Text to Encrypt panel, type or paste the unencrypted password of your database connection
string.
3. Click Encrypt.
The encrypted password is displayed in the Encrypted Test panel.

216 Avocet High Frequency Infrastructure

 4. Open your AppConfig_ProjectLayer.xml file, and locate the application ID whose connection string
you want to encrypt.
5. Within the <connectionString> element, replace the Password attribute with the cryptoPassword
attribute.
6. Copy the encrypted password and paste it as the cryptoPassword value in the connection string.
Refer to this MS SQL Server connection string example:
<connectString>Network Library=DBMSSOCN;
Data Source=localhost,1433;Initial Catalog=GridReport;
User ID=sa;Password=tPBuJ8ThsVxLqi5DpmP4y+Zr4s
KKiCKiWCQ7hFeFjQRs0n+fsdldA5wN4GHO2xVgRP88L7HaLZwX
2tgVeXLCuA==;Application Name=AVM</connectString>

7. Save the AppConfig_ProjectLayer.xml file, and start or restart Avocet to initialize the change. If
IIS is already active, then restart it as well.

Set up IIS 8.0 or 8.5 on Windows Server 2012 R2 (manual steps)

This section provides guidelines for doing a manual install and configuration of Internet Information
Services (IIS) 8.0 or 8.5 on Windows Server 2012 R2 within an Avocet application server context.
To define an HTTPS-enabled web services API to which external Avocet desktop clients can connect,
you must implement IIS on your server system. You can refer to the Microsoft IIS website for more
information.
Before proceeding with the IIS setup, you should verify that you have the following prerequisite runtime
and redistributable files:
• Microsoft .NET Framework 4.6.1 or later
• Visual C++ Redistributable for Visual Studio 2015
• Microsoft ReportViewer 2010 Redistributable
• Microsoft ReportViewer 2012 Redistributable
• Microsoft Visual C++ 2008 Runtime Libraries (x64)
• Microsoft Visual C++ 2008 Runtime Libraries (x86)
• Microsoft Visual C++ 2010 Runtime Libraries (x64)
• Microsoft Visual C++ 2010 Runtime Libraries (x86)
• Microsoft Visual C++ 2012 Runtime Libraries (x64)
• Microsoft Visual C++ 2012 Runtime Libraries (x86)

217
 • Microsoft Access Database Engine Redistributable 2010

Internet Information Services roles and features

The following table lists the recommended Internet Information Services (IIS) roles and features that
you should install and configure when setting up your IIS implementation.

Server role or Category Options

feature

Role Web Server (IIS)

Role Management IIS Management Console

Role Common HTTP Features

HTTP Errors
Static Content

Note: Be sure that you do not select WebDAV Publishing

because it conflicts with some of the web services API
features.

Role Health and Diagnostics HTTP Logging

Request Monitor

Role Performance Static Content Compression

Dynamic Content Compression

Role Security Request Filtering

Windows Authentication
Basic Authentication

Note: Enable Basic Authentication for both mobile and

non-mobile clients.

Role Application Development .NET Extensibility 3.5

.NET Extensibility 4.5
ASP.NET 3.5
ASP.NET 4.5
ISAPI Extensions
ISAPI Filters
WebSocket Protocol (for high frequency implementations only)

Feature .NET Framework 3.5 .NET Framework 3.5

Feature .NET Framework 4.5 .NET Framework 4.5

ASP.NET 4.5

Install IIS 8.0 or 8.5 on Windows Server 2012 R2

This task shows how to install IIS 8.0 or 8.5 on the Windows Server 2012 R2 system.

1. On your Windows Server 2012 R2 system, launch Server Manager through the Server Manager
icon.

218 Avocet High Frequency Infrastructure

 The Server Manager Dashboard is displayed.

2. In the Server Manager Dashboard, choose Add roles and features.

The Add Roles and Features Wizard is launched.
3. Select Installation Type, choose Role-based or feature-based installation, and click Next.

219
 4. In the Select destination server window, select the server that you want to configure for the web
services API.
In the majority of cases, it will be the host system on which you have deployed the web services
package.

220 Avocet High Frequency Infrastructure

5. Click Next to continue.
6. In the Select server roles window, select Web Server (IIS), and then display the following role
categories from which you are going to select options:
• Common HTTP Features
• Health and Diagnostics
• Performance
• Security
• Application Development
• Management Tools
You can refer to the Help topic "Internet Information Services roles and features" for a complete
list of selections, or you can scan the following screen shot:

221
 Note: Be sure that you do not select WebDAV Publishing because it conflicts with some of
the web services API features.

7. After making your selections, click Next.

The Select features window is displayed.
8. In the Select features window, select the following features to install on the server:
• .NET Framework 3.5
• .NET Framework 4.5
• ASP.NET 4.5
Refer to the Help topic "Internet Information Services roles and features" or the following screen
shot:

222 Avocet High Frequency Infrastructure

 9. Click Next.
The Confirm installation selections window is displayed.
10. Review the selections, select the Restart the destination server automatically if required check
box, and click Install.
If prompted, enable the automatic restart option.
11. Click Close when the installation is complete.

Test the IIS HTTP connection on Windows 2012 R2 Server

This task shows how to test the IIS HTTP connection on the Windows 2012 Server system.

1. In Server Manager, select IIS from the tree to display the Servers panel.
The newly defined IIS web server should display.

2. Right-click the IIS server entry in the Servers panel in the All servers list to display the flyout menu,
and select Internet Information Services (IIS) Manager.
The Internet Information Services (IIS) Manager window is displayed, listing the Internet Information
Services 8 Application Server Manager page. It initially opens to the Start Page. Its node is
highlighted in the Connections tree.

223
 3. In the Connections tree, select the Sites folder to display the default website’s status, and ensure
that the website’s HTTP binding is enabled.

4. In the Sites panel, right-click the Default Web Site entry to display the flyout menu, and choose
Manage Website > Browse *: <portNumber> (http) to check the status of the HTTP connection.
If the HTTP connection is successful, the IIS 8 launch page is displayed.

5. Proceed to set the HTTPS binding for the default website.

Configure HTTP response headers

To maintain the security of your web browser, you should add and configure HTTP response headers.
The HTTP response header fields constrain the content of the response messages in your HTTP and
HTTPS transactions.
You can define the HTTP response headers based on your web environment and security concerns.
This procedure recommends four parameters, but your configuration may differ.

1. In the IIS Manager console, select your Avocet web services application, and choose IIS > HTTP
Response Headers.
The HTTP Response Headers panel is displayed. By default, it might display an inherited header
called X-Powered-By.
2. In the Group by drop-down, choose Entry Type.
3. Under the Actions... panel, choose Add... .
The Add Custom HTTP Response Header dialog is displayed.
4. Add the following four response headers, repeating the add action and clicking OK for each entry.

224 Avocet High Frequency Infrastructure

 Header Description

Cache-Control indicates whether the caching mechanism can cache the

selected object. Enter no-cache, no-store.

X-Content-Type-Options restricts content sniffing of text files. Applies to Internet

Explorer and Google Chrome. Enter nosniff.

X-XSS-Protection filters for cross-scripting. Enter 1; mode=block.

Strict-Transport-Security guards against hijacking attempts and can restrict web

browser interaction to HTTPS connections for a specified
period. Enter max-age=16070400;includeSubDomains.

Your entries might appear as in the following example screenshot:

5. Refresh the default web site to initialize the change.

Enable HTTPS
This section shows how to enable the HTTPS service, which includes getting the SSL certificate.
To enable the HTTPS service, perform the following steps:
• Obtain an SSL (secure sockets layer) certificate with a trust level appropriate for your environment.
• Create the SSL bindings for the default website.
• Customize the SSL settings for your website.
• Verify the SSL connection to your website.

Obtain an SSL certificate

You can choose to create a certificate request in IIS for your HTTPS connection.
To create your certificate request, follow these guidelines:

1. Determine the type of SSL certificate you want to install.

2. Open the IIS Manager interface, and select the top-level server node in the Connections tree.
3. Double-click IIS > Server Certificates to reveal the list of current certificates (if any).
4. Under the Actions panel, select the command that creates the type of SSL certificate you want to
install (self-signing, domain, or any other types issued by a certificate authority), or choose Import...
to import a .pfx certificate file.

225
 5. Complete the corresponding wizard for the selected certificate type. Refer to the steps outlined in
the corresponding websites listed in the preceding table.
Your server certificate is listed in the Server Certificates pane.

Note: To manage your certificates, you may need to enable the Certificates plug-in in the
Microsoft Management Console.

SSL certificates
The following table lists the different types of SSL certificates that are available.

Certificate IIS Actions command Description

Self signed Create Self-Signed Certificate… useful in creating a secure, private channel between your
web server and a small group of known users, as in a test
environment. See the following non-Schlumberger websites
for more information:

Create a Self-Signed Server Certificate

Self-Signed Certificate

Domain Create Domain Certificate… used to protect a single domain (website). It does not
necessarily have to be issued by an external certification
authority (CA). See the following non-Schlumberger website
for the IIS procedure:

Create a Domain Server Certificate

Issued by external CA Create Certificate Request… Many types of digital certificates are issued by certificate
authorities: wildcard, full-authentication, extended validation,
and so forth. You can review various SSL websites for more
information.

See the following non-Schlumberger website for the IIS

procedure:

Installing an SSL Certificate

Enable the Certificates snap-in (optional)

The Certificates snap-in lets you browse the available certificates in your certificate stores. If you want
to browse for certificates to assign to the HTTPS protocol for IIS, you should consider enabling the
Certificates snap-in.
You install the Certificates snap-in from the Microsoft Management Console (mmc.exe).

1. Launch the Microsoft Management Console by entering mmc in the Run dialog.
The Console Root window is opened.
2. With the Console Root node selected in the tree, choose File > Add/Remove Snap-in... .

226 Avocet High Frequency Infrastructure

 The Add or Remove Snap-ins dialog is displayed.
3. Scroll the list of available snap-ins, select Certificates, and click Add.
The Certificates snap-in dialog is displayed, listing the accounts to which the certificate can apply.

4. Select the account, and click Finish.

The Certificates snap-in is displayed under the Selected snap-ins panel in the Add or Remove
Snap-ins dialog.
5. Open the Certificates snap-in in the Console window to browse the certificates across the different
folders.

Create the SSL bindings for the default website

This task shows how to create secure bindings to enable the HTTPS protocol for the default website.
After completing your certificate request and installation, follow these steps to create the secure
bindings:

1. In the Connections tree of IIS Manager, select the select Default Web Site under the Sites node.
If you created an application under the Default Web Site, then select Default Web Site.
2. Right-click to display the flyout menu, and choose Edit Bindings… to open the Site Bindings dialog.

227
 3. In the Site Bindings dialog, click Add to open the Add Site Binding dialog, and complete the following
steps:
a) Select https in the binding Type drop-down list.
b) Leave the IP address drop-down list as All Unassigned.
c) Specify the default secure port number 443 in the Port field.
You are restricted to port number 443 in the current implementation of the web services API.
d) In the SSL certificate drop-down list, select the SSL certificate you want to apply.

Note: If you do not have a certificate ready, you can choose to use the system's certificate.

e) Click OK.
4. Choose Default Web Site again, right-click to display the flyout menu, and choose Manage Web
Site > Advanced Settings... .
The Advanced Settings dialog is displayed.
5. For Enabled Protocols, specify HTTPS to restrict access only to secure HTTPS protocols.
6. Click OK to close the dialog.

Customize the SSL settings for the default website

You can specify the SSL settings for the default website so that only secure HTTPS connections are
allowed.
You can require that the HTTPS connections must be authenticated by certificate before website
access is granted. Your selections and choice of authentication depend on your environment and
requirements.
Avocet supports the following SSL configurations:

HTTP, HTTPS, or both Require SSL

HTTP No

HTTPS Yes

HTTP and HTTPS No

Because the Avocet web services API requires an HTTPS connection, SSL security is required.

1. In the Connections tree, select the Default Web Site.

2. In the IIS panel, double-click the SSL Settings icon to open the SSL Settings prompt.

228 Avocet High Frequency Infrastructure

 3. Click the Require SSL check box.
4. Indicate how you want to handle client certificates: Ignore, Accept, or Require.
5. To apply your selection, click Apply in the Actions pane on the right-hand side of the IIS Manager.
6. To verify the default website's HTTPS connection, select Default Web Site and choose Browse
Web Site > Browse *.portNumber (https) in the Actions panel.
The IIS 8 launch page is displayed.

Enable the .NET 4.5 application pool

Avocet web services runs under a .NET 4.5 framework. Consequently, your selection of application
pool should reflect the ASP .NET 4.5 runtime.
Ensure that you select the ASP.NET v4.5 feature when you select .NET Framework 4.5 during your
IIS installation.
Your web services instance must be filtered by the .NET 4.5 integrated application pool.

1. In the IIS Manager console, choose Application Pools in the Connections tree to display the
application pools. If .NET v4.5 (integrated mode) is not present, then do the following:
a) Select Actions > Add Application Pool... .
The Add Application Pool dialog is displayed.
b) Complete the following:

Name Enter .NET v4.5.

.NET CLR version Select .NET CLR Version v.4.30319.

Managed pipeline mode Select Integrated.

c) Click OK to close the dialog.

2. If required for your environment, modify the application pool settings.

Note: Avocet web services can run under the default application pool settings. However,
you may need to reset certain settings depending on which application pool your website is
using. For example, you may need to reset the Enable 32-bit applications property to False
to resolve certain issues.

3. Select the server node in the Connections tree, and choose IIS > ISAPI and CGI Restrictions.
The ISAPI and CGI Restrictions panel is displayed. The Restriction column for each ASP.NET
should read Allowed.
4. If necessary, change the Restriction setting to Allowed by selecting the ASP.NET entry and choosing
Actions > Allow.

Set the application pool identity

The application pool account that you choose depends on which options you select for your pass-through
authentication and connection string in the AppConfig_ProjectLayer.xml file.
In your AppConfig_ProjectLayer.xml file, the application ID node that contains the pass-through
authentication definition appears similar to the following:
application id="MyProjectApplicationID">
<description>MyProjectApplicationID</description>
<authenticationType>passthru</authenticationType>
<database>
<driver>SQLSERVER</driver>

229
 <sqlsyntax>SQLSERVER</sqlsyntax>
<connectString>Network Library=DBMSSOCN;
Data Source=localhost,1433;Initial Catalog=[DatabaseName];
User ID=userName;Password=yourDatabasePassword;;
Application Name=AVM</connectString>
<connectStringForSsas>[Connection string that allows SSAS to
connect to Avocet DB]</connectStringForSsas>
.........
</database>

1. Return to the Internet Information Services (IIS) Manager window, and choose Application Pools
in the Connection tree to display the Application Pools panel.
2. Select the .NET v4.5 entry, and choose Edit Application Pool > Advanced Settings... .
3. In the Advanced Settings dialog, choose Process Model > Generate Process Model Event Log
Entry > Identity ... to open the Application Pool Identity dialog.

4. From the Built-in account drop-down list, you can choose from the following account types:
Option Description
NetworkService Choose NetworkService if the Integration Security attribute is set equal to true,
SSPI, or yes.
ApplicationPoolIdentity Choose ApplicationPoolIdentity if the Integration Security attribute is set equal to
false or has been omitted from the string.

For Windows authentication in Avocet non-mobile clients, you can also define dedicated active
directory user accounts and configure the application pool to use them. The Avocet Mobile client
uses basic authentication, so active directory accounts do not apply.
5. Click OK on the open dialog boxes to return to the Application Pools panel with the updated Identity
value.

Register ASP.NET 4.5 with Internet Information Services

You may need to manually register ASP.NET 4.5 with IIS in the event the Avocet Installer is unable
to do so.
Ensure that you have enabled the ASP.NET 4.5 feature during your IIS setup.

230 Avocet High Frequency Infrastructure

 1. Open the Windows Command Prompt in administrator mode by selecting the Command Prompt
object and then right-click to display the flyout menu and choose Run as Administrator.
2. Enter the following directory path at the command prompt:
C:\Windows\Microsoft.NET\Framework64\v4.0.30319
3. Enter the following command: aspnet_regiis.exe -i.
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i
4. Press Enter.

Add the web services application under the default website

To enable the web services API, you add AvocetWebService node under the Default Web Site in the
Connections tree.
Ensure that you have
• deployed the AvocetWebService package with the AvocetVM folder contents pasted under the
\AvocetWebService\bin subfolder
• set up your IIS configuration with the recommended roles and features
• enabled HTTPS
• enabled the .NET v4.5 application pool
• unset the read-only permission on the AvocetWebService or the Avocet Mobile web service folder
if necessary

1. Right-click on the Default Web Site node to display the flyout menu, and choose Add Application…
.
2. In the Add Application dialog, complete the following fields:
Field Description

Alias Enter the display name of your Avocet web service instance. Do not include spaces in the display
name.

Application pool Select .NET v4.5 from the Select Application Pool drop-down list.

Physical path Browse the physical path to the AvocetWebService or to the Avocet Mobile web service folder:
for example, driveletter:\installationFolder\AvocetWebService.

Enable Preload Optional. This option sends a warm-up request to the Avocet web services. The IIS Application
Initialization module must be implemented to support the preload. Refer to this non-Schlumberger
website for more information.

3. Click OK.
In the Connections tree, the application node for the Avocet web services or the Avocet Mobile
web service should display:

Customize the compression setting of your web service node

In the IIS Manager console, you can modify the IIS role and feature settings of your web service node
depending on your environment and requirements.

1. In the Connections tree of the IIS Manager console, select the top-level server to display its Home
page.

231
 2. Choose IIS > Compression icon to display the Compression pane.

3. Optional. Increase the maximum amount of space (in MB) that the server uses when compressing
static content in the Per application pool disk space limit text field.
The value that you enter depends on your available resources and your requirements.
4. Go to the Actions panel in the right-hand side pane, and click Apply.

Browse the web service node to launch the Swagger UI

From IIS Manager, you browse the web service node to determine whether the Swagger UI document
displays.

1. From the Connections tree in IIS Manager, select the web service node.
2. Under the Actions panel, choose Manage Application > Browse Application > Browse
*:portNumber (https).
The URL of the web server address is displayed in the address bar of the browser. It points to the
web service node.
3. Add the resource name /Swagger to the end of the URL string in the address bar, and press Enter.
The Swagger UI document displays the controllers available to the web services API. Each controller
manages a data flow. The available controllers depend on whether you are implementing an Avocet
Mobile or a standard non-mobile deployment. A partial listing of the available controllers for the
non-mobile deployment is displayed in the following screen shot:

232 Avocet High Frequency Infrastructure

 Note: HostName refers to the fully qualified domain name of the system, which should be
the system name on the SSL certificate.

The Avocet Mobile deployment contains an additional set of controllers to support communication
with the mobile device. Some of the Avocet Mobile controllers are highlighted in the following
screenshot:

233
 Other Avocet Mobile controllers include OfflineSaving, RoutesAndStops, and UIConfigCache.
4. If, when attempting to link to the server, you get an exception such as Target not created
Slb.AvocetVM.Resources.ResourceCache, verify that the configuration files AppConfig.xml and
AppConfig_ProjectLayer.xml are in the directory path that the appConfigPath key points to in
the Web.config file.

Add the WebApiServer tag to your AppConfig_ProjectLayer file

To enable the Avocet client to apply security settings to the Avocet web services API, manually add
a <webApiServer> tag to your AppConfig_ProjectLayer.xml file.
This AppConfig_ProjectLayer.xml file is the one in which you have defined your pass-through
authentication.

1. Open the AppConfig_ProjectLayer.xml file in a text editor.

2. At the same hierarchical level as the <database> entry, insert the <webApiServer> tag with the
<url> subelement, as in this example:
<webApiServer>
<url> </url>
</webApiServer>

3. Enter the URL of your Avocet Web Service folder that you specified in IIS.

234 Avocet High Frequency Infrastructure

 It should contain the fully qualified domain name of the host system. This should be the same name
as specified in the SSL certificate.

Note: Do not leave any spaces between the URL string and the opening and closing <url>
tags.

<webApiServer>
<url>https://HostName.Domain1.Domain2.com/AvocetWebService</url>
</webApiServer>

4. Save the AppConfig_ProjectLayer.xml file.

5. Verify that the change is applied to the AppConfig_ProjectLayer.xml file in all relevant /Config
subfolders. (You can check the path value in the appConfigPath key of the Web.config file.)
6. Start or restart both Avocet and IIS to initialize the change.

Restart IIS after a configuration change in the Avocet web service configuration
In the Avocet web services deployment, whenever you make a change to any configuration file, such
as the AppConfig.xml or AppConfig_ProjectLayer.xml file, you must restart IIS to initialize the change.
This task shows how to restart IIS from the command line and from the Internet Information Services
Manager window.

Restart IIS from the command line

1. Launch the MS Command Prompt window.

2. Enter iisreset at the command prompt. This command stops and restarts IIS.

Restart IIS from the Internet Information Services Manager window

1. Select the website name in the Connections tree. If the application resides under the Default Web
Site node, select Default Web Site.
2. In the Actions panel on the right-hand side, select Manage Website > Restart.

Apply security constraints to user roles and HTTP request methods

Through the Security Editor interface of the Avocet Configuration Tools utility, you can assign an
Execute or a Read-only permission to each web API operation for each corresponding user role.
Add the webApiServer tag, with the <url> subelement, to your AppConfig_ProjectLayer.xml file where
you have enabled pass-through authentication.
The web API operations include the HTTP request methods GET, POST, PUT, and DELETE. The
Read-only permission limits the user role to view-only access to the specified operation.
The list of operations in the Security Editor is the same as the operations listed for each controller in
the Swagger user interface, as in this excerpt for the Alarm controller:

235
 By default, all user roles have execute permission for the operations.You must specify which operations
are disabled for each user role.

1. Launch the Avocet Configuration Tools utility (ConfigTools.exe), and navigate to the Security and
Auditing Tools > Security Editor node.
The Security Editor interface displays the available user roles, both default and customized, under
the securityRoot node.

Note: If you just added a role, you may need to select Sync Roles from the ribbon toolbar.

2. Unfold each role category to display the records available to each.

The webApiRoute collection is displayed.
3. Select webApiRoute to display the full list of web API operations.

236 Avocet High Frequency Infrastructure

 4. To change the permission from Execute to Read-only, clear the check box in the Read column.
5. Restart IIS to initialize the change.

Notifications
The web services API routes notifications for the high frequency infrastructure.
Avocet's native HFI manager and high frequency implementation is not dependent on web services.
However, the web services API, among other options, provides the resource to create a custom,
web-based notifications server that supports high frequency data. As a prerequisite to using the web
services API in a high frequency implementation, you have to install and configure the Avocet HF store
and HFI manager. Refer to the Help topic High Frequency Infrastructure Manager installation and
configuration.

Note:

To enable notifications in the high frequency infrastructure, you

• specify the relative path of the AppConfig.xml file in the
installDirectory\HFIManager\HFIManager.exe.config file
• verify that the Slb.Avocet.HFNotificationPlugin.dll plug-in resides under the
installDirectory\HFIManager\HFIManagerPlugins subfolder
• configure the <mailSettings> stanza in the AppConfig_ProjectLayer.xml
• define your mail notification groups and users
• configure a SignalR implementation

Edit the HFIManager.exe.config file and verify plug-in

The HFIManager.exe.config file contains configuration settings for the implementation of the high
frequency infrastructure.
The HFIManager.exe.config file enables high frequency notifications through a default, out-of-the-box
notifications plug-in, together with a relative path pointer to the AppConfig.xml file residing in the
AvocetWebService directory.
To enable high frequency notifications, follow these steps:

1. Open the installDirectory\ HFIManager\HFIManager.exe.config file in a text editor.

2. Locate the ApplicationId key: <add key="ApplicationId" value="MyAppID" />, and verify that the
application ID to which you are connecting is specified.
You enter this application ID as part of the HFI Manager installation routine. This application ID is
defined in the AppConfig_ProjectLayer.xml file in which you set up pass-through authentication.
3. Locate the ConfigDir key: <add key="ConfigDir" value="..\..\config\AppConfig.xml" />, and specify
the relative path to the AppConfig.xml file of your AvocetWebService deployment.
For example, if you pasted the contents of the AvocetVM\config folder to the AvocetWebService\bin
subfolder, then you should point to the AppConfig.xml file that resides at
installDirectory\AvocetWebService\bin\config\AppConfig.xml. Assuming that the
HFIManager.exe.config file resides under installDirectory\HFIManager, the value you would
assign in this example to the ConfigDir key is "..\AvocetWebService\bin\config".
4. Save the HFIManager.exe.config file.
5. In the Windows Services window, restart the AvocetHFSync service if it is running.

237
 6. Access the installDirectory\HFIManager\HFIManagerPlugins folder and verify that the plug-in
assembly Slb.Avocet.HFNotificationPlugin.dll is there.

Mail settings, recipients, and groups

You can configure SMTP mail settings and specify mail recipients and mail groups to receive alarm
notifications.
A mail group is a container for the mail recipients. A mail recipient is a specific email address, Short
Message Service (SMS) gateway, or Multimedia Messaging Service (MMS) gateway. By defining
groups and notifications, you can assign alarm and other notifications to the responsible groups.
If implementing high frequency alarms, you should specify mail recipients and groups who will receive
notifications when the alarm ranges have been exceeded. For example, if you have defined an alarm
range for the flow rate of a particular meter, and the rate falls outside the range, a notification can be
sent to the email address of an operator who belongs to the support group for the particular facility.

Note: The notification feature applies to high frequency alarms. It is not enabled for alarms on
low frequency or historical data.

One email or messaging recipient can belong to multiple groups. The relation between the groups and
the recipients is many-to-many.

Before you define groups and recipients, define your SMTP mail settings for the notification destination.

Define your SMTP mail settings

You must define an SMTP (Simple Mail Transfer Protocol) server in your Avocet environment to receive
email notifications for alarms.
You can receive email notifications for
These email notifications are sent to notification groups and specified recipients.
The SMTP server is a generic server. It has no dependencies on Avocet.

238 Avocet High Frequency Infrastructure

You specify the mail setting values in the <application> node of your
• implementationFolder\AvocetWebService\bin\Config\appConfig_projectLayer.xml file
The XML <mailsettings> markup is shown below, with referenced websites and explanatory code
comments extrapolated from the websites:
<application id="yourProjectLayer">
<description>yourProjectLayer</description>
<buildTargets />
<database>
<driver>SQLSERVER</driver>
<sqlsyntax>SQLSERVER</sqlsyntax>
<connectString>Network Library=DBMSSOCN;Data Source=localhost,1433;
Initial Catalog=DbName;User ID=yourUserID;Password=yourPassword;
Application Name=AVM</connectString>
<connectStringForSsas>[Connection string that allows SSAS to
connect to Avocet DB]</connectStringForSsas>
</database>
<mailSettings>
<!-- For details, see http://msdn.microsoft.com/en-us/library/
ms164240(v=vs.110).aspx -->
<smtp from="[Specify the from address for outgoing e-mails]">
<network host="[Specify the hostname of the SMTP mail server to use for SMTP transactions]" />
<!-- Optional parameters, see: http://msdn.microsoft.com/en-us/library/ms164242(v=vs.110).aspx
defaultCredentials="Specifies whether the default user credentials should be used
to access the SMTP mail server for SMTP transactions. The default value is false."
enableSsl="Specifies whether SSL is used to access an SMTP mail server.
The default value is false."
password="Specifies the password to use for authentication to the SMTP mail server.
This attribute has no default value."
port="Specifies the port number to use to connect to the SMTP mail server.
The default value is 25."
targetName="Specifies the Service Provider Name (SPN) to use for authentication
when using extended protection for SMTP transactions.
This attribute has no default value."
userName="Specifies the user name to use for authentication to the SMTP mail server.
This attribute has no default value."
-->
</smtp>
</mailSettings>
You can refer to the code comments and review the websites to determine the best way to set up your
mail server.
To define your SMTP mail settings, follow these steps:

1. Open your appConfig_projectLayer.xml file in an editor.

Note: You update the <mailSettings> node in both locations of the

appConfig_projectLayer.xml file.

2. Locate the <mailSettings> node under the <application> node.

3. Enter your SMTP mail server settings, including any desired optional parameters.
A basic SMTP mail server example with an email address and SMTP host name follows:
<application id="yourProjectLayer">
...........
<mailSettings>
<smtp from="[email protected]">

239
 <network host="gateway.mail.companyName.com" />
</smtp>
</mailSettings>
...........
</application>
You can contact your system administrator if you need additional help.
4. Save the updated appConfig_projectLayer.xml file in both locations if necessary.
5. Restart Avocet.

Define a mail recipient

This task shows how to define a mail recipient who receives alarm and other notifications through
email or messaging.

1. In the Navigation Tree, select Administration > Notifications > Mail Recipient to display the Mail
Recipient Item Edit screen.
2. Choose Home > Actions > New to open a new record.
3. Adjust the As Of Date, Start date, and End date values as needed.
These dates should correspond with the effective dates of the alarm settings and with any associated
mail group.
The dates in the Date Break column change accordingly.
4. Required. Enter a name for the recipient in the Name field under the Date Break column heading.
5. Required. Enter an email address or SMS or MMS gateway address in the Email address field
under the Date Break column heading.
The typical format for an SMS gateway address is Mobile-Number@ServiceProviderAddress. The
address may include the message format, such as SMS or MMS: for example,
[email protected] (MMS) for T-Mobile account.
You can refer to external websites for a list of SMS gateway addresses.
6. Optional. Click View All Properties to display the Description field, and enter a unique description.
7. Click Home > Actions > Save to save the record.

Define a mail group

You specify and enable a mail group category to associate multiple email recipients, system roles,
and/or system users.

1. In the Navigation Tree, select Administration > Notifications > Mail Group to display the Mail
Group Item Editscreen.
2. Choose Home > Actions > New to open a new record.
3. Adjust the As Of Date, Start date, and End date values as needed.
These dates should correspond with the effective dates of the alarm settings and any target email
recipients.
4. Required. Enter a name for the group in the Name field under the Date Break column heading.
5. Required. Select the Enabled check box to enable the group.
You can leave it unselected if you are not ready to enable the group to receive email notifications.
6. Optional. Click View All Properties to display the Description and Rate Limit fields, and enter
an informative description of the new mail group.

240 Avocet High Frequency Infrastructure

7. Optional. In the Rate Limit field, enter the frequency in seconds that the group receives active
alarm notifications.
For example, if you specify 300, the group receives the current active alarm notifications every 5
minutes. Alarm notifications that occur during the time span, but are no longer active, are not sent.
If no alarms are active at the interval limit, then you do not receive alarms until they become active
again.
If you leave the field blank, the group receives active alarm notifications as they occur.
8. Choose Home >Actions > Save to save the record.

Link mail group with recipients

After you have defined your mail group, you can link it with individual mail recipients, system roles,
and/or system users.
To link a mail group with one or more recipients, follow these steps:

1. In the Mail Group Item Edit screen, select the mail group from the Navigator list.
2. Click the Links tab to open the Links pane.
3. If the message No active links is displayed, then click View linked only to display the Group-User
Link object. Otherwise, skip to step 4.
4. Click the Add Link icon to open the Select Item window.
5. In the Select Item window, select from among the following recipients to link with this group:
• specified mail or messaging recipients
• system roles such as field supervisor, field operator, read-only, and so forth
• system users who have been defined

6. Click OK. The selected recipient or recipients are added to the Links tab.
7. Click Home > Actions > Save to save the updated record.

Link mail recipients to mail groups

After you define your recipients and groups, you can link them together.
To link a mail recipient to one or more mail groups, follow these steps:

1. In the Mail Recipient Item Edit screen, select the mail recipient from the Navigator list.
2. Click the Links tab to open the Links pane.
3. If the message No active links is displayed, then click View linked only to display the Group-User
Link object. Otherwise, skip to step 4.
4. Click the Add Link icon to open the Select Item window.
5. In the Select Item window, select the mail group(s) that you want to link with this specific notification
group.
6. Click OK. The selected group or groups are added to the Links tab.
7. Click Home > Actions > Save to save the updated record.

Manage the Mail Queue Viewer

The Mail Queue Viewer grid report displays email notifications that have not yet been sent or whose
transmission has failed.
Email notifications that reside in the queue have the status of Wait, Failed, and so forth.

241
 You have the option to
• send an alarm notification immediately
• cancel an alarm email transmission
• resend an alarm notification

Note: Email notifications that are transmitted immediately may display on the Mail Queue
Viewer viewer for a second or two.

1. In the Navigation Tree, access Administration > Notifications > Mail Queue to display the Mail
Queue Viewer grid report.
2. In the list, select the email you wish to send.
3. Choose Home > Actions > Send Immediately.
The selected email is sent to its group and recipient.
4. To cancel a send action, choose Home > Actions > Cancel Sending.
5. To resend an email, choose Home > Actions > Repeat Sending.

SignalR scale out configurations

To support the high frequency implementation and alarm notifications, the Avocet web service API
relies on the ASP.NET SignalR library for real-time web functionality.
To learn more about SignalR and its features, visit this non-Schlumberger website.
As a deployment engineer, you would create a web page that subscribes to a SignalR implementation.
You may have to consider how to scale the web application. SignalR supports a "scale out" capability
that allows you to add more servers to your web deployment. Refer to this explanation of SignalR's
scale out mechanism at the non-Schlumberger website.
The Avocet web service API supports all three SignalR scale out scenarios:
• Azure Service Bus
• Redis
• SQL Server
You enable each scale out configuration by updating the <signalR.webServer> element in the
Web.config file.

Note: In your IIS configuration, be sure that you have installed the WebSocket Protocol
application development feature. SignalR uses web sockets for communication. Refer to this
non-Schlumberger website for more information.

Enable Azure Service Bus scale out

This procedure describes the XML markup you need to add to the Web.config file to enable the Azure
Service Bus scale out.
Refer to this tutorial at the non-Schlumberger website for detailed information about the Azure Service
Bus scale out.

1. Open the AvocetWebService\Web.config in a text editor, and locate the <signalR.webserver> node.
2. Make the following changes:
a) Set the messageBusType attribute equal to "ServiceBus".
b) Create a <serviceBusScaleOut> subelement within the <signalR.webserver> element.
c) Include a connectionString attribute within the <serviceBusScaleOut> subelement.

242 Avocet High Frequency Infrastructure

 d) Point the connectionString attribute to the Azure service bus namespace.
e) Create a topicPrefix attribute and also include it within the <serviceBusScaleOut> subelement
after the connection string.
f) Set the topicPrefix attribute equal to the SignalR communication type.
The signalR.webServer stanza should display as in this example:
<signalR.webServer messageBusType=”ServiceBus”>
<serviceBusScaleOut connectionString=
”Endpoint=sb://xxxx.servicebus.windows.net/;
SharedSecretIssuer=owner;SharedSecretValue=XXXXXXXX”
topicPrefix=”AvocetRealtime” />
</signalR.webServer>

3. Restart IIS.

Enable Redis scale out

This procedure describes the XML markup you need to add to the Web.config file to enable the Redis
scale out.
Refer to this tutorial at the non-Schlumberger website for detailed information about the Redis scale
out.

1. Open the AvocetWebService\Web.config in a text editor, and locate the <signalR.webserver> node.
2. Make the following changes:
a) Set the messageBusType attribute equal to "Redis".
b) Create a <redisServerScaleOut> subelement within the <signalR.webserver> element.
c) Add a server attribute within the <redisServerScaleOut> subelement.
d) Set the server attribute equal to the Redis server name.
e) Create a port attribute within the <redisServerScaleOut> subelement, and set it equal to the
port number of the Redis server.
f) Within the <redisServerScaleOut> subelement, create a password attribute to contain the Redis
server password.
g) Also within the <redisServerScaleOut> subelement, create an appName attribute to point to the
SignalR communication type.
The signalR.webServer stanza should display as in this example:
<signalR.webServer messageBusType=”Redis”>
<redisServerScaleOut server=
”xxxx.redis.cloudapp.net” port=”6379”
password=”XXXXXXXX” appName=”AvocetRealtime” />
</signalR.webServer>

3. Restart IIS.

Enable SQL Server scale out

This procedure describes the XML markup you need to add to the Web.config file to enable the SQL
Server scale out.
Refer to this ASP.NET tutorial at the non-Schlumberger website for detailed information about the
SQL Server scale out.

1. Open the AvocetWebService\Web.config in a text editor, and locate the <signalR.webserver> node.
2. Make the following changes:
a) Set the messageBusType attribute equal to "SqlServer".

243
 b)Create a <sqlServerScaleOut> subelement within the <signalR.webserver> element.
c)Include a connectionString attribute within the <sqlServerScaleOut> subelement.
d)Point the connectionString attribute to the SQL Server database.
e)Include the Integrated Security property at the end of the connection string, and set it equal
to True.
The signalR.webServer stanza should display as in this example:
<signalR.webServer messageBusType=”SqlServer”>
<serviceBusScaleOut connectionString
Server=(localdb)\v11.0;Database=<YOUR-DATABASE>;
Integrated Security=True;” />
</signalR.webServer>

3. Restart IIS.

Avocet web services controllers and operations

This table summaries the purpose of each out-of-the-box controller and lists its HTTP request methods
for the high frequency implementation.

Controller Description HTTP request methods

Alarm Manages the high frequency limit, offnormal, and watchdog DELETE, GET, POST, PUT
alarms

Authentication Retrieves application IDs, gets authentication status, and GET

enables login and logout

Blob Retrieves blobs GET

CodeList Retrieves code lists GET

ConfigCache Retrieves cache data for mobile apps GET

Constants Retrieves constants and their values that are defined in the GET
controller

Historical Retrieves and adds data for historians GET, POST

Item Retrieves, adds, and uploads data for items, item types, GET, POST, PUT
and item IDs

ItemSubTypeDefCache Retrieves item subtype data GET

ItemTypeDefCache Retrieves and adds item type data GET, POST

Link Retrieves link data GET

Navigation Adds AXL table POST

Realtime (Deprecated) Retrieves and adds high frequency methods GET, POST

ResourceCache Retrieves and adds data for keys GET, POST

Scheduler Retrieves and adds data for the Avocet scheduling server GET, POST
service

SecurityCache Retrieves and adds security data GET, POST

SetPoint Retrieves and adds setpoint data GET, POST

Transaction Adds transaction data POST

Units Lists unit data GET

244 Avocet High Frequency Infrastructure

HTTP request methods and status codes
The controller is a software component that handles HTTP request methods between web client and
server. To fully engage with the web services API, you should be familiar with HTTP request methods
and HTTP response or status codes.
By default, the Avocet web services API supplies the following HTTP request methods for manipulating
JSON data through the Swagger interface:
• GET
• POST
• PUT
• DELETE
The GET method requests data from the server to read it only. It does not modify the data.
The POST method sends data, such as new properties and parameters, to a specified resource defined
by an Avocet item, type, model schema, and so forth. This data can extend or annotate the existing
resource.
The PUT method uploads data to update or replace properties of an existing resources identified by
Avocet item, type, model schema, and so forth. If no resource exists at the specified location, then the
PUT method can add the data.
The DELETE method deletes a resource at a specified Avocet item ID, transaction type, or other
identifier.
The distinctions between the methods may not be clear cut in some contexts. You can refer to this
basic overview at this non-Schlumberger website and then investigate further as desired.
Each HTTP request method results in an HTTP response code.You can refer to this non-Schlumberger
website for an overview of common HTTP response or status codes.

Log into the application ID

Using the GET request method, the Authentication controller lets you connect with the Avocet database
by logging into your application ID.
Launch the Swagger interface document from your IIS web server configuration.
The target application ID is the one for which you have enabled pass-through authentication in your
AppConfig_ProjectLayer.xml file.
You do not need to run the Avocet desktop to authenticate with the Avocet instance.

1. In the Swagger UI, expand the Authentication controller, and select the GET
/avocet/v1/Authetication/AppIds request.
The model schema is displayed.
2. Click Try it out!.
The response body retrieves a list of application IDs that it finds in the Config folder specified in
the Web.config file.
3. Scan the list to verify that your target application ID is listed and note its exact spelling and
capitalization.
4. Select the GET /avocet/v1/Authentication/Login request.
The model schema is displayed.
5. Under the Parameters heading, enter the application ID exactly as it is spelled and capitalized.
6. Click Try it out!.
If you authenticate successfully, you should receive the response code 200.

245