Gas Analysis Write File Service

Overview

The Gas Analysis Write File Service is a Windows Service application that manages delimited files created by customers or labs and generates GC Write requests from these files to be sent to field devices. The service is configured such that the customer’s specific file contents can be read by the service with minimal configuration work. This document will discuss how to configure the service for use with a file.

Service Configuration  

Configuration is done using the ACM ACM Monitor Properties page. The Gas Analysis Write File Service section has the following configurable parameters:

• ImportFolder  The location the service will use to look for new files to process. The service checks for new files every 10 seconds. The files found are processed one at a time in alphabetical order by file name.

• ArchiveFailedFolder  The location the service will use to move files that failed to process.

• ArchiveCompletedFolder  The location the service will use to move files that processed successfully.

  When Is A File Considered Successful?

  In order for a file to be considered successful, at least one request in that file must have resulted in a valid request entry to be processed (In other words it was entered in the database). Therefore, it is possible for multiple requests from a file to fail as valid request entries but have the file archived as successful. A failed file is one for which no requests resulted in valid request entries.

• ValidationTolerance  This value is used when the mole components are totaled up and allow a tolerance window to be valid for processing. 100 would let any sum validate. 0 would require a perfect 100%. Example: A value of 10 would result in a range tolerance of 90% to 110% for the final total of all mole components.

• MeterResolutionMode  This value is used to determine how the Gas Analysis Write File Service resolves the meter associated with data in the file. A value of RecordField indicates that a column in the delimited file contains the metername/number that corresponds to a meter configuration object present in the ACM configuration data base. Each file line is evaluated as a separate request with the value present in this column. A value of FileName indicates that the name of the file (what precedes the file extension) contains the metername/number that corresponds to a meter configuration object present in the ACM configuration data base. Each file line is evaluated as a separate request but the filename will be used to resolve the metername/number for all lines in the file. If your files contain data to be sent to multiple meters and devices, then it is recommended to use the RecordField mode. For more information, please refer to the section on Meter Mapping Between Systems below.

• FieldMapping  This value stores the column mapping scheme used by the service to determine the meaning of data in each column of the file. Please refer to the section on Field Mapping for more information on how to configure this setting.

• FieldDelimiter  This value is used to indicate what character is expected to delimit files imported by the service. The default is a comma. The valid delimiters are comma ",", tab "\t", pipe "|", and semicolon ";".

• HasColumnHeaders  This value is used to signal the service to skip any attempt to process the first row of the file as a request record if the file contains the column headers or descriptions on the first row of the file.

Field Mapping

Field mapping is the process by which the service is able to determine which columns of the delimited file equal the related field in a GC Request. If a file column contains data that does not relate to a GC Request field, it can be skipped over during the reading process by applying the SKIP keyword. This allows lab files to be used as is, without having to alter the file before processing. 

The FieldMapping configuration parameter stores a comma separated list of keywords to use as the map for reading each line of a file. Each keyword maps a column in the file. The number of keywords in the map should equal the number of columns in the file. Valid keywords are:

SKIP

GCIDENTIFIER

EXTERNALREQUESTID

ARGON

CO

CO2

ETHANE

H2

H2O

H2S

HELIUM

IBUTANE

IPENTANE

METHANE

N2

NBUTANE

NDECANE

NEOPENTANE

NHEPTANE

NHEXANE

NNONANE

NOCTANE

NPENTANE

O2

PROPANE

HEATINGVALUE

SPECIFICGRAVITY

USERDEFINEDSTRING1

USERDEFINEDSTRING2

USERDEFINEDDOUBLE1

USERDEFINEDDOUBLE2

REQUESTEDTIME

Mapping Example

A customer file has the following eight columns with column header descriptions and uses a comma to separate values. Each line could be a different meter.

 The configuration would be:

FieldMapping = GCIDENTIFIER, SKIP,ARGON,CO2,H2,HEATINGVALUE,SPECIFICGRAVITY,SKIP

MeterResolutionMode = RecordField

FieldDelimiter = “,”

HasColumnHeaders = true 

In this example the WellCode column is mapped as the GCIDENTIFIER. This indicates the service to use the value in this column to map to a meter in ACM. REQUESTEDTIME is not mapped, so the service will fill this value in at the time the request is created. This file has column headers on the first line, so the HasColumnHeaders configuration parameter is set to true so the service will know to skip the first line for processing.

Meter Mapping Between Systems

In order for a request to be successfully created, it must be mapped in the ACM configuration. When RecordField or FileName values are assigned to the GCIDENTIFIER field of a request, they must map to a meter object in ACM by one of these two methods:

1. The meter object name in ACM matches the value of the mapped GCIDENTIFIER column.  

2. The External GC property of a device meter object matches the value of the mapped GCIDENTIFIER column.  

Validation Tolerance

Mole sum validation is used to validate the sum of the mole components of a request record before it is submitted to ACM. The tolerance is a +/- value range the sum must fall between to be considered valid. To disable validation, the tolerance can be set to a value of 100 which allows a wide range. If the file mole component values are a percentage of 100, then apply a tolerance to compliment. If the values are decimal number of 1 (such as .95), then use a tolerance value with a decimal.