Getting an API Key
An API Key is required to access the eLynx API . API Keys are generated in the eLynx application as follows:
- Log in to the eLynx application.
- Click on your user name (upper right corner of page) and select the User Profile and Settings menu option from the dropdown menu.
- Click the API Management tab.
- Click the Request API Access button to generate an API key.
NOTE: Any/all API keys that you generate will be listed on this page for future reference.
This help file contains general information for interacting with the eLynx API, but does not go into detail or show samples for the various calls. Additional eLynx API documentation, API command references, and code samples in various languages can be accessed online at https://portal.api.elynxtech.com/ or by clicking the Developer Portal button on the API Management tab in User Profile & Settings.
The eLynx API allows for data retrieval of any report configured within the eLynx application via the RunDataReport method. Common examples include:
- Accessing Attachments
- Alarms (Setpoints)
- Run Tickets
- Diagnostic Events
- Production Targets
Having a basic understanding of the following concepts will aid you in creating an application that interfaces with the eLynx API.
- Attachments - Various data files (e.g., 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.
- Device - All polled / hosted devices are represented within the application as Devices.
- Dynacards - A structured item that contains load/position data from a dynamometer on a rod pump. Each card represents either the direct load/position information 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.
- Event - A structured item that contains diagnostic information from the Rules Engine about times when a rule violation occurred.
- Memo - A simple text document that is linked to one of the main objects. Memos often contain field notes from routine maintenance of the Device or Well.
- Organization - Customers with multiple operating areas may configure Organizations to represent each of those different areas in the eLynx application. If Organizations are in use for your account then you must include the specific Organization GUID as part of your API query. Please see the GUIDs section below for more information.
- Production Targets - Gas/Oil/Water targets for a well that estimate expected production from the well.
- Run Tickets - A structured item that contains information for liquid hauls from a tank.
- Tag Data - Data values captured (i.e., polled, calculated, or imported) for a given set of Tags over a given time range.
- Well - An object that contains production, target, and variance data for a Well. Additionally, a subset of data tags from the Devices related to the Well will also be shown on the Well. Note that 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.
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 one or more of these identifiers as parameters when calling the API.
For each of these types of objects there is an API call (i.e., GetOrganizations, GetDevices, GetWells) that will retrieve a list of objects of that type with their Name, GUID, and other attributes. This returned data may be used to build a dictionary mapping of names to GUIDs for use elsewhere in your program.
All queries for data in the API are made via REST API HTTPS requests. All data is returned in JSON formatted text responses.
For Memos, Run Tickets, Attachments, Events and Production Targets there are both Get and Save calls in the system to examine existing data or add new information.
For Production Targets, there is also a Delete function although it is limited to data that was added via the API. Any target data entered directly into the eLynx application can only be modified or deleted from within the application.
Extracting tag data from the eLynx API is done by running any report that is setup within the eLynx application via the RunDataReport API call. The data is returned from the API in JSON formatted arrays. If a report has multiple sections defined then the data will be returned as an array of sections each containing an array of data.
The GetDataReportList call may be used to query the API to retrieve a list of available reports that can be run via the API.