eLynx API

• Updated 11/12/2021 to include information on retrieving Attributes assigned to Device and Well objects.

Getting an API Key

API Keys can be generated in the eLynx application. Once logged in click on your user name and select "User Profile and Settings."

Click on the "API Management" tab, if you've already signed up your API keys will be displayed, if not, simply click on the "Request API Access" button and your keys will be generated and displayed.

Key Expiration and Renewal

API keys are valid for six months after they are issued, the expiration date is shown directly below the key. We suggest you set a reminder on your calendar a few days before this date to renew your key before it expires. If you let your key expire you will need to setup a new key and update any applications or scripts with the new key.

Renewing your key is done via the same API Management tab of your User Profile. Next to both the Primary and Secondary keys are four Action Buttons which can be used to perform the following tasks:

Copy Key: Copies the key to your clipboard.

Regenerate: Revokes your existing key and generates a new key. You should do this if you feel security of the old key has been compromised.

Renew: Extends the expiration date of the key to six months from today. 

Revoke: Removes the key from the system and prevents any data access using that key.

Automating Key Renewal

Renew and Regenerate key operations CAN BE automated using the API calls RenewAPIKey and RegenerateAPIKey as long as your current key is still valid.  For this reason we STRONGLY recommend that when you are developing your interface to our API that you call the RenewAPIKey once per month for both your Primary and Secondary API keys.  This will insure that your scripts run for as long the user account the API key is assigned to is a valid user in the eLynx system.

Concepts

Having a basic understanding of the following concepts will aid you in creating an application that interfaces with the eLynx API.

Functional Overview

The API allows for data retrieval (any report configured within the eLynx application can be accessed via the RunDataReport method) Accessing Attachments, Memo's, Alarms, Run Tickets, Dynacards, Diagnostic Events, Tag Data, and Production Targets.

Online Documentation

This help file contains general information that will be useful when interacting with the eLynx API, but does not go into detail (or show samples) for each of the calls.

Full documentation for each of the API calls including code samples in various languages is available online at https://portal.api.elynxtech.com. Or via this button on the API Management tab in your User Profile.

Object Types

• Organization - For customers where multiple operating areas are using the application organizations can be created to represent these different areas. If organizations are in use for your account then it is a requirement that an Organization GUID (see GUID's below) be passed with the query.
• Device - All polled / hosted devices are represented within the application as devices.
• Well - An object that contains production, target, and variance data for a well. In addition a subset of tags from the devices that make up the well will also be shown on the well. Well features are only available within certain Tiers in the application so queries to read/write data associated with wells may fail if your site does not have wells on it.
• Memo - A simple text only document that is linked to one of the main objects. These often contain, but are not limited to, field notes from routine maintenance of the device/well.
• Event - A structured item that contains diagnostic information from the Rules Engine about times when a rule violation occured.
• Run Tickets - A structured item that contains information for liquid hauls from a tank.
• Dynacards - A structured item that contains load/position data from a dynamometer on a rod pump. Each card represents either the direct load/position informatoin from the sensor as measured at the point of connection between the rod and the pump, or, if supported by the controller a downhole card showing the estimated weight of the liquid in the pump.
• Production Targets - Gas/Oil/Water targets for a well that estimate expected production from the well.
• Tag Data - Data values over time (whether polled, calculated, or imported) for a given set of tags over a given time range.
• Attachments - Various data files (pictures, diagrams etc.) can be attached to either a well or a device object. The API includes queries for both retrieving and adding attachments to the system.
• Attributes - User defined properties that can be applied to Objects. These properties can be used for Dynamic Grouping, tracking basic information (date of first flow, lift controller etc.) and other helpful information.

GUID's

Organizations, Devices, and Wells all have a GUID (Globally Unique IDentifier) in the eLynx system. Many of the individual functions available in the API require you to pass one or more of these identifiers when calling the API.

For each of these types of objects there is an API call (GetOrganizations, GetDevices, GetWells) that will retrieve a list of objects of that type with their Name, their GUID, and other attributes, you can use the returned data to build a dictionary mapping names to GUIDS for use elsewhere in your program.

Queries

All queries for data in the API are made via REST API HTTPS requests, all data is returned in JSON formatted text responses.

For Memo's, Run Tickets, Attachments, Events and Production Targets there are both Get and Save calls in the system so you can examine existing data, or add new information. There is also a Delete function specific to Production Targets, this function is limited however to only being able to delete data that was added via the API, any target data entered directly into the eLynx application can only be modified from within the application.

Running reports

Extracting tag data from the eLynx API can be done by running any report that is setup within the eLynx application via the RunDataReport API call, the data is then returned to you from the API in JSON formatted arrays. If a report has multiple sections defined then an array of sections, each containing an array of data is returned.

You can query the API with the GetDataReportList call to retrieve a list of available reports that can be run via the API.

Query Tag Data

The GetTagValues query may also be used to query the system for data.  The GetTagValues query has the ability to return raw, daily or hourly averages, over a time period or the current value (LastKnownValue) for a given set of tags.  You can use the GetTags query to retrieve the GUIDS for the tags you wish to query.

When calling GetTagValues you have to specify an ObjectType in the query, it will either be "Device" or "Well". You can determine this by which call "GetDevices" or "GetWells" you used to get the ID's. 

Query Attributes

The GetAttributeSchemas query may be used to query the system for a list of defined Attributes that can be applied to objects. The schema includes information on the type of values that an attribute can contain (i.e. numeric, date/time, freeform text, picklist etc.) these definitions will include (where appropriate) information on acceptable values.

The GetAttributes query may be used to query the system for the attributes applied to an object or set of objects.  The return will include the schema and the assigned values for the object list. This query will paginate as necessary as the amount of data returned can be quite large.

In addition the GetDevice and GetWell functions have been updated to optionally return the Attributes assigned to the devices.