IP21 Adaptor Features

The IP21 Adaptor provides access to read and write time series tag data to and from the Aspen InfoPlus.21® (IP21) data historians, and supports version 9 of Aspen InfoPlus.21.

IP21 Adaptor offers support for multiple custom mappings of record field names in the same instance of the datasource. This article describes how to map the field data, and the adaptor parameter settings.

Overview

In order to map field data from IP21 to P2 Server, and from P2 Server to IP21, you need to understand the InfoPlus.21 historian tag structure, as well as the P2 Server tag structure.

Note: If you do not define specific mappings in a configuration file, the default mappings will be used.

To configure the field mappings:

1. Create a Configuration File, and save it to the same path that you specified in the Configuration File for Variants property of the datasource.
2. Map the various fields where you want to override the defaults, using the following the guidelines.

IP21 Historian Tag Structure

Aspen InfoPlus.21 uses a distinctive structure of data definitions:

Definitions > Records > Fields

Field	The most basic data structure is a field. Each field has a name, a data type, and a value. The value can be static, historical, or time-aware.
Record	Fields can be grouped into records; a record's name is unique. A record can contain at most one instance of each field. Fields within a record are the fundamental data containers in IP21.
Definition	Each record is also associated with a definition record that indicates a class of a record object.

The combination of fields within a single record can be considered a tag; specific fields correspond to the tag name, the tag description, and the tag engineering unit, respectively, or to any other property as defined in the Historian.

To fetch the description and value of a specific tag, you need to provide the record name, as well as the names of all fields that correspond to the input value and description.

Internally, IP21 associates identifiers with all of its structures and through the API exposes the functions to convert names to identifiers, and identifiers to names, to retrieve values.

---

P2 Server IP21 Adaptor Tag Structure

IP21 Adaptor uses a general naming convention to identify which fields of a record represent the description, input value, input quality, and so on.

In addition to the general naming convention, field names can differ in the following ways:

• Custom names, that differ slightly from the standard names.
• Names can be missing, where not required.
• Existing names can be used for purposes other than what they are typically used for.

General or Standard IP21 Adaptor Field Definitions

By default, the following IP21 fields of a record are expected by the adaptor:

• #_OF_SELECTIONS
• 1st_SELECTION_VALUE
• IP_DESCRIPTION
• IP_ENG_UNITS
• IP_GRAPH_MAXIMUM
• IP_GRAPH_MINIMUM
• IP_INPUT_QUALITY
• IP_INPUT_TIME
• IP_INPUT_VALUE
• IP_TREND_QSTATUS
• IP_TREND_TIME
• IP_TREND_VALUE
• IP_VALUE_FORMAT
• QUALITY_LEVEL
• SELECT_DESCRIPTION

In addition, the adaptor may expect the following definition records associated with a record:

• ENG-UNITS
• QUALITY-STATUSES

Custom Field Definitions

When mapping configuration files, you may also use field names (or definition names) that are different from the default names, to retrieve specific types of information.

You may need to use alternative field names under the following circumstances:

• Where the spelling of a name varies slightly from its default spelling.
• Where you need to use separate fields (definition records) for a particular reason. For example, where limitations to a field’s data format exist.
• You can leave out a field name, where it is not required.

You can make the required changes in the configuration file, in the Mappings\Definition\TagGroup\Variation section.

Data Type Definition Records

In order to use the fetching method appropriate to the data type of a field, the adaptor needs to access the data format definition that is in accordance with the format provided by the IP_VALUE_FORMAT field of a record.

The adaptor is able to recognize values for one of three basic data types (integer, real, and timestamp) by comparing the definition of the record, which name corresponds to the format field, with definition records of the predefined data types.

Default names of the type definitions are shown below and can only be mapped globally, i.e. for all the tags. In contrast, the field names (and definition names) listed above can be mapped differently for every tag group.

Definition records with the following names are referenced globally:

IntegerFormatDef	Integer format definition record.
RealFormatDef	Real format definition record.
TimeStampFormDef	Time stamp format definition record.

Note: Default names of type definitions are referenced globally for all tags, whereas the standard and custom field definition names can be mapped differently for the various tag groups.

You may need to change the names of the data type definitions, used for identifying the fetching method.

You can override data type definitions (integer, real, and timestamp) in the configuration file in the Mappings\GlobalMapping section.

For example, if you have changed the data type in the Historian from IntegerFormatDef to CustomIntegerFormatDef, you will need to rename this in the configuration file as well, to ensure that the correct data type match can be made during tag discovery.

---

Configuration File

The mapping configuration file is an XML file, based on the schema document distributed with the adaptor (Schema.xsd).

Elements of the Configuration File

The configuration file contains a list of definition groups (Mappings\Definition) which contain tag groups (Mappings\Definition\TagGroup). A record is used for tags within a tag group if its name matches the regular expression pattern of a TagGroup node and its definition matches the pattern of a Definition parent node.

Each tag group contains a list of variations (Mappings\Definition\TagGroup\Variation), distinguished by the suffix of a tag. A variation is a collection of field name mappings. Each mapping is a pair consisting of name and mapping text strings that correspond to a default name and the replacement mapping name.

Multiple variations used with the same record represent multiple tags, each with a name consisting of:

• A record name
• A separator
• A suffix which relates to the variation

How the Adaptor Detects New Tags

When the adaptor detects new tags, it fetches the list of records from the IP21 historian and for each record executes the following procedure:

1. Identifies the first definition group and a tag group by matching the record name and its definition name against the patterns defined in the configuration file.
2. Iterates over the variations in that tag group and returns new tag names consisting of a record name, a separator, and the variation suffix.

Note: If the suffix is an empty string, a separator is not included.

How the Adaptor Returns Tag Data

When the adaptor receives a request to return data for a tag with a specified name, it executes the following procedure:

1. Searches for the separator and splits the name to retrieve a record name and a suffix.
2. Finds the definition of a record and identifies the first definition group and tag group by matching a record's name and its definition name against the patterns defined in the configuration file.
3. Finds the variation corresponding to the suffix.
4. Based on field name, it returns a mapping name for the field that must be accessed to retrieve the data (or just the requested field name itself, if there is no mapping).
5. Accesses the record field to fetch and return the data.

Tag Discovery

A separator character can be specified in the mapping file (Mappings[@separator]); by default, a double dash character sequence (--) is used.

As some tags might not have the corresponding engineering unit, it is possible to disable unit retrieval for specific tag groups. You can disable the relevant tag groups in Mappings\Definition\TagGroup\Variation[@useEngineeringUnit]. In such a case, an empty string will be used for that engineering unit.

• A Definition with an empty pattern string is considered a default definition group and is used if the name of a record's definition does not match any other pattern.
• A TagGroup with an empty pattern string is considered a default tag group and is used if the name of a record does not match any other pattern in the definition group.
• A Variation with a missing suffix is considered to be a default variation and is used with a tag without a suffix.

If a tag group contains at least one non-default variation, the tag discovery process will not return a tag name containing just an original record name in the result list, unless a default variation is explicitly specified and contains at least one mapping. Sometimes it might be required to override a field name with the same name used in mapping, in order to provide at least one mapping entry.

Example of Tag Discovery

The following example demonstrates how tag ABC0123456 is discovered:

---

Example Configuration File

Here are some examples that illustrate different configurations that can be managed through the use of an IP21 Adaptor configuration file. Note that any combination of these configurations can be used. For a formal specification, please see the Schema.xsd that is included in the adaptor’s installation directory.

Example 1: Global Mapping Modified Only

<?xml version="1.0" encoding="utf-8"?>
<Mappings>
  <GlobalMapping name="IntegerFormatDef" mapping="CustomIntFormatDef"/>
</Mappings>

Example 2: Extra Fields Applied for a Tag Folder

<?xml version="1.0" encoding="utf-8"?>
<Mappings>
   <Definition pattern="^IP_DiscreteDef$">
      <TagGroup> <Variation/>
         <TagProfile name="DiscreteProfile">
            <Field>DISCRETE_FIELD_ONE</Field>
            <Field>DISCRETE_FIELD_TWO</Field>
         </TagProfile>
      </TagGroup>
   </Definition>
</Mappings>


Example 3: Using Variations to Create Multiple P2 Server Entities per Record

<?xml version="1.0" encoding="utf-8"?>
<Mappings separator="--"> <!-- Overrides default, see section above -->
   <Definition pattern="^CustomerSpecificDef$">
      <TagGroup pattern="^A.*$"> <!-- All records starting with A-->
         <Variation> <!-- Entity Name = RecordName -->
            <TagMapping name="IP_TREND_QSTATUS" mapping="TempQuality" />
            <TagMapping name="IP_TREND_VALUE" mapping="TempValue" />
            <TagMapping name="IP_TREND_TIME" mapping="TempTime" />
            <TagMapping name="IP_INPUT_VALUE" mapping="TempCurrentValue" />
            <TagMapping name="IP_INPUT_TIME" mapping="TempCurrentTime" />
            <TagMapping name="IP_INPUT_QUALITY" mapping="TempCurrentQuality" />
            <TagMapping name="IP_DESCRIPTION" mapping="TempDescription" />
            <TagMapping name="IP_ENG_UNITS" mapping="TempUnits" />
        </Variation>
        <Variation suffix="S"> <!-- Entity Name = RecordName_S -->
           <TagMapping name="IP_TREND_QSTATUS" mapping="PressureQuality" />
          <TagMapping name="IP_TREND_VALUE" mapping="PressureValue" />
          <TagMapping name="IP_TREND_TIME" mapping="PressureTime" />
          <TagMapping name="IP_INPUT_VALUE" mapping="CurrentPressure" />
          <TagMapping name="IP_INPUT_TIME" mapping="CurrPressTime" />
          <TagMapping name="IP_INPUT_QUALITY" mapping="CurrPressQuality" />
          <TagMapping name="IP_DESCRIPTION" mapping="PressDescription" />
          <TagMapping name="IP_ENG_UNITS" mapping="PressUnits" />
        </Variation>
        <TagGroup> <!-- Matches all tags that don’t start with A -->
           <Variation/> <!-- Use default field names. -->
        </TagGroup>
   </Definition>
</Mappings>

---

IP21 Adaptor Settings

The following tables list the adaptor's parameters, along with the name and type to be used in the Import/Export spreadsheet.

Parameter	Description	Name	Type
Server	The hostname of the machine on which the IP21 historian is running.	Server	String
User ID	The user name to use to connect to the historian.	UserID	String
Password	The password for the user name used to connect to the historian.	Password	EncryptedString
Use Point Cache	The cache retains the tag metadata used to look up recorded values from IP21. Enabling this cache may save time when fetching data for a tag that has been previously fetched by the same adaptor instance. Note that enabling this caching will increase the potential memory consumption of each adaptor instance for this datasource. Options: True, False.	UsePointCache	Boolean
Configuration File for Variants	The path to a configuration file that specifies mappings for standard IP21 fields and records. If the specified file does not exist or a name is empty, default mapping names are used.	ConfigFilePath	String
Log Level	The level of logging to use for this datasource. Options: Verbose, Debug, Informational, Warning, Error, Fatal.	LogLevel	String
Tag Folders	Extra tag folders to search for tags in the IP21 server. To separate multiple folders, use the | character.	TagFolders	String
Use Standard Tag Folders	Whether to use the standard tag folders (IP_AnalogDef and IP_DiscreteDef). Options: True, False.	UseStandardTagFolders	Boolean
Raw History Mode	The IP21 Best Fit algorithm to use when doing Raw fetches. Options: Get Actuals, Get Best Fit.	RawHistoryMode	String
Linear Interpolate History Mode	The IP21 Best Fit algorithm to use when doing Linear Interpolate fetches. Options: Get Times, Get Best Fit.	LinearInterpolateHistoryMode	String
Minimum Quality Level	The minimum confidence to be returned from Best Fit fetches.	MinimumQualityLevel	Integer
Best Fit Buckets	The static number of buckets to be used in a Best Fit fetch. If not specified or set to 0, the Interval parameter is used to specify the size of a bucket.	BestFitBuckets	Integer
Occurrences per Bucket	The maximum expected number of occurrences to be returned per bucket. Defaults to 5.	OccurrencesPerBucket	Integer
Single Point Average Time Weight	The value of the TimeWeight parameter (RHIS21AGGREG) to use in single point average fetches. Defaults to '3'. Statistics are calculated using the best fit method. All time periods are calculated, even those past the latest value. Options: ActualValues, BestFit, BestFitWithLatestValue, BestFitWithAllTimePeriods, ActualValuesWithAllTimePeriods, ActualValuesWithLatestValue.	FetchAverageModeSingle	String
History Average Time Weight	The value of the TimeWeight parameter (RHIS21AGGREG) to use in history average fetches. Defaults to '2'. Statistics are calculated using the best fit method. The time period containing the latest value is calculated, but none past this period are calculated. Options: ActualValues, BestFit, BestFitWithLatestValue, BestFitWithAllTimePeriods, ActualValuesWithAllTimePeriods, ActualValuesWithLatestValue.	FetchAverageModeHistory	String
"Quality Not Available" Confidence	The confidence value to use for data points where IP21 does not report a quality level. This value will be clamped to the range 0-100.	QualityNotAvailableConfidence	Integer

Release History

• IP21 Adaptor Features 4.9.7
  • Added "Quality Not Available" Confidence
• IP21 Adaptor Features 4.5.0
  • Initial version