IHS FieldDIRECT API - FAQ

FieldDIRECT Data Services

FDDS is an OData web service designed to facilitate automated data delivery and retrieval to and from the FieldDIRECT system.

With FDDS, clients can upload and create records, download and view them, modify or replace them, and/or delete them. These operations can be completed one record at a time or on many records in a single batch operation.

• Clients can automate the delivery of SCADA data to FieldDIRECT for gas meter readings, tank gauges, and wellhead pressures
• Clients can create an application that will automatically synchronize FieldDIRECT with their systems for populating custom reports or other software packages
• FDDS contains logic to prevent incomplete or invalid records from being created in the system
• FDDS will auto-populate certain fields with default values when data is not provided, which helps to minimize the effort required from the client when interfacing with the services

FDDS currently supports Gas Meter Readings, Tank Gauges, and Wellhead Pressures.

IHS partners with ViaWest, a leading provider of hosting solutions, to deliver robust, reliable services. Our data centers meet various compliance standards: SOC2 and SOC3 (formerly SAS 70), US-EU Safe Harbor Privacy Framework, and ITAR among others.

No

Since FDDS is an OData service, the best way to consume FDDS is using an OData client toolkit. There are OData client toolkits available for many languages including Java, .NET and Javascript. For a full working .NET example, download the sample app from the FieldDIRECT User Administration (UA) site.

FDDS currently uses OData v3. For complete details about the OData v3 standard visit the OData Version 3.0 documentation page.

FDDS is coded with OData version 3 because it supports simple Date/Time formats, which is a more accurate representation of the FieldDIRECT system. OData version 4 requires GMT offset and is not supported. Hopefully OData version 5 will restore support for simple Date/Time in which case FieldDIRECT will consider upgrading to the latest version of OData.

https://apps.fielddirect.com/DataServices/OData/$metadata

FDDS supports the batch capabilities of OData to allow many records be uploaded or downloaded in a single operation.

Each record in the FieldDIRECT database has a primary key which uniquely identifies that record. The primary key begins with "DocID" and is suffixed by the corresponding table name. In order to retrieve, update or delete a specific record from FieldDIRECT using FDDS, the request must include the DocID.

FieldDIRECT generates and assigns new DocIDs automatically when a new record is created. This generated DocID will be returned by FDDS and should be stored for future interactions with the record.

Related entities are records that provide contextual information about data that is handled by FDDS. For instance, Gas Meter Readings are related to a Gas Meters database table that defines the meter that the readings apply to. The Gas Meters table is further related via a PropertyID key which ties the meter to the property that owns it. When submitting requests via FDDS, it is often imperative that related entities are present and configured correctly so that the data uploaded can be organized correctly within the FieldDIRECT database.

Default values are used for data items which are either not supplied or are supplied with a null value. System-supplied values are special data items such as time-stamps, source-of-data codes, input-by user IDs, etc. System-supplied values are generated and/or placed into records to track information that is used by FieldDIRECT to document reference values not related to actual field data.

Transmitted data is secured using strong encryption and compression. FDDS employs SSL (Secure Sockets Layer) encryption and all URLs are specified using https. In addition, FieldDIRECT database servers are located in secure data centers. For maximum security, we recommend the use of strong, lengthy passwords which combine upper case, lower case, and special characters. A long password using purely random characters is always a good idea. Finally, for maximum security, do not expose written passwords near client machines that access FieldDIRECT servers.

No, FDDS will only accept requests using HTTPS. Any request made using HTTP will result in a 403 (Forbidden) response.

Authentication is a process which confirms that "you are who you say you are." Authorization grants an authenticated user permissions to perform only approved actions only on data that the user has the right to work on.

User Configuration	Get	Add	Edit	Delete
User has "Add/Edit/Delete Data" and is assigned to the property	Yes	Yes	Yes	Yes
"User Type" is Pumper and user is assigned to the property	Yes	Yes	Yes	No
User is assigned to the property	Yes	No	No	No
User is in the corporation (not assigned to the property)	No	No	No	No

Yes, using User Administration (UA) and Builder, administrators can give each user access to specific data and also control what actions can be performed on those records.

FieldDIRECT allows administrators in customer corporations to set up multiple users with independent usernames and passwords. Tied to these credentials users may be given different permissions which restricts access and capabilities to only those records they are entitled to read, add, update, and/or delete. These permissions are honored when users employ FDDS. Users must log on using basic authentication by supplying their username and password. These credentials are both compressed and strongly encrypted before being transmitted through the Internet. Once this process is complete, a lengthy, random token is returned to the client. This token is then used for all further authentication and authorization.

A security token will expire after one continuous hour of inactivity. Rarely, other events can cause a session to expire sooner (such as scheduled maintenance usually during the FieldDIRECT maintenance window). When the security token expires, the user must be authenticated again to obtain a new security token before interacting with FDDS.

FDDS specifies date/time values using the format: "YYYY-MM-DDTHH:MM:SS". For example, 8 PM on January 1 of 2015 would be represented as "2015-01-01T20:00:00". Note that times are specified in 24-hour format (i.e., 0-23 hours).

On a date/time value, if time is not specified, the time defaults to midnight (i.e. morning of the specified date). Acceptable times are 00:00:00 through 23:59:59 (1 second before midnight).

Typically, a range includes two data items: a start date and an end date. These dates are inclusive. For instance, "StartDate":"2015-01-01" and "EndDate":"2015-01-01T23:59:59" is a date/time range that includes the entire day of January 1, 2015.

FDDS uses standard HTTP response codes and messages to inform the user about basic success or failure of the operation. In addition, FDDS often returns an "Inner Error" which further clarifies what went wrong with any action that fails. Please refer to the ErrorResponse documentation for more details.

The most common cause of an "Unknown Error" response from the IHS FieldDIRECT API is a duplicate record. When attempting to create or update records, check to make sure that no other records already exist in the target table with the same doc date and equipment id (MeterPtID, ProductionPtID, TankID). If the issue persists after verifying that no other records exist with the same doc date and equipment id, contact Customer Care for further assistance.

There are a few things to check if no data is being returned from the FieldDIRECT system:

1. Does the user have sufficient permissions to retrieve the records from the FieldDIRECT system? GET operations will only return data for properties the current user has permissions to view.
2. Has the corresponding related entity been deleted from the FieldDIRECT system? FDDS will only return records for Active and Inactive entities.
3. Does the request contain a query filter ($filter query string parameter)? If so, check the filter for correctness.

FDDS responses for GET operations are limited to 20000 records per request in most tables. Due to size limitations, some tables will have lower limits. In the event that a user is authorized to retrieve more records, multiple GET commands should be issued subsequently using the "odata.nextlink" in previous response to retrieve all of the data. For example: { ..., odata.nextlink: "https://apps.fielddirect.com/DataServices/OData/DocWellHeadPressures?$skip=20000"}

FDDS OData batch submissions are limited to 2000 requests per batch.

In the event that a client which submits a batch request times out, the FieldDIRECT system will continue to process the batch request as normal. The best course of corrective action is to query the FieldDIRECT system at a later time to see if the batch operations were completed successfully.

The most common cause of a HTTP 500 (Internal Server Error) when sending a batch request is exceeding the maximum number of records allowed in a single batch. This limit for FDDS is 2000 requests in a single batch, so if this error is encountered check the request to ensure that the maximum was not exceeded. If this issue persists, contact Customer Care for further assistance.

All batch operations are completed inside the scope of a single transaction. If any of the requests fail, the entire batch request is rolled back and the database is returned to its original state. The response returned contains information regarding what failed and allows you to fix the problem and resubmit the batch.

For DocGasMeterReadings, you must either submit:

1. A "MeterPtID", a "docDate", and a "Volume" or:
2. A "MeterPtID", a "docDate", and sufficient other inputs to calculate a volume given the type of meter involved

FDDS will only recalculate the volume for DocGasMeterReadings when a NULL volume is provided. Otherwise, the provided Non-NULL volume will be used.

Volumes for DocTankGauges are always recalculated whenever a record is created or modified.

No

A web service is any piece of software that makes itself available over the Internet and uses a standardized messaging system to allow two machines to communicate. Many web services have a public interface, defined using a well-understood, common grammar. The interface describes all the methods available to clients and specifies the signature (how to make requests and the expected responses) for each method.

The Open Data Protocol (OData) is an open protocol begun by Microsoft which allows the implementation of queryable and interoperable Application Programming Interfaces (APIs) in a simple and standard way. This protocol enables use of RESTful APIs, which allow resources, defined in a data model and identified using Universal Resource Locators (URLs), to be created and edited by Web clients using simple Hypertext Transfer Protocol (HTTP) messages. FDDS uses OData version 3 because it supports simple Date/Time formats and does not require GMT (Greenwich Mean Time) offset. OData version 4 requires GMT offset and is not supported. In the future OData version 5 will restore support for simple Date/Time data elements. Complete documentation covering OData v3 can be found at OData Version 3.0.

JSON is strongly recommended when using FDDS. The only time XML is acceptable for use with FDDS is when using the Atom Publishing protocol for viewing data as a web feed.

Metadata specifies the data types and formats of the data items exchanged between a client and a server. The FDDS metadata specifically outlines the data items understood by the FieldDIRECT system.

A web service client is an any application (software) which builds HTTP (Hypertext Transfer Protocol) messages which create, read, update, or delete information from a remote computer system called a server. Often a server will contain a relational database that stores information of interest.

SCADA (Supervisory Control and Data Acquisition) systems operate using coded signals over communication channels to control remote equipment. These control systems are often combined with data acquisition functions which autonomously acquire information about the status of the remote equipment. FDDS is ideal for quickly and regularly updating FieldDIRECT databases with SCADA data. Before SCADA data is submitted via FDDS, users must translate the SCADA identifiers to FieldDIRECT identifiers for the records being transmitted.