What API do I use to create/update readings?
Purpose:
(If post) this API allows sending or integrating production readings such as well readings, tank readings, run tickets, downtimes, well tests, meter readings, etc to Joyn FDG to ensure proper volumes and other information are available for allocation processes.
Highlights:
Create, update readings to Joyn FDG in bulk or individually
API EndPoint:
v1/api/integration/reading
Method:
POST
Request Format
JSON compressed as gzip.
Maximum size of gzip file should be less than 6 MB
Getting Started
Need to generate x-api-key for the client to use the API
For carry forward and calculation to work. The trigger setup needs to be done as required.
For any other custom trigger, custom trigger needs to be turned on the for client.
For interdependent calculation flag needs to be turned on for the client
JSON structure
{
"authoritylevel": {
"id": 1013138
},
"calculationtype": {
"id": 1013145
},
"datainputmethod": {
"id": 1013164
},
"object": {
"id": 598493
},
"objecttype": {
"id": 1
},
"isdeleted": false,
"readingdate": "2024-06-13",
"readingentity": {
"id": 35846
},
"readingtime": "00:00",
"modifiedby": {
"id": 65981
},
"modifiedon": "2024-06-13 00:00:00.000",
"Comments": "Tester",
"CasingPressure": 122,
"TubingPressure": 322,
"SurfaceCasingPressure": 988,
"choke": 1
}Mandatory Fields
# | Field | Guidance |
|---|---|---|
1 | Calculation Type | Can be picklist id or name |
2 | Data Input Method | Can be picklist id or name |
3 | Object | Can be object id or object xid |
4 | Object Type | Can be object type id or object type name |
5 | Reading Date / Ticket Date | In format yyyy-mm-dd, without any timestamp |
6 | Reading Entity | Can be entity id or entity name |
7 | Reading Time / Ticket Time | In format, hh:mm, will be used to decide if reading already exists for the day or not |
8 | Modified On | In format, hh:mm, will be used to decide if reading already exists for the day or notIn ISO String format with UTC timestamp yyyy-mm-ddT00:00:00.000Z |
9 | Modified By | Can be user id, name or xid |
10 | Ticket Number | Required only if reading is a ticket |
11 | Other Attributes as Required | n/a |
Request Format
· List of jsons compressed as gzip.
· Maximum size should be less than 6 MB
Response Format
NOTE 1: For file size more than 10kb url will be provided which can be called to get the status
NOTE 2: If user is not able to determine the file size, 500 record limit can be taken as a conservative limit below which response should be returned immediately in most cases
{
"success": true,
"readingsCreated": 1,
"readingsUpdated": 0,
"invalidSchemaRecords": 0,
"invalidReadingsForObjectID": 0,
"invalidReadings": 0,
"triggerErrorRecords": 0,
"data": {
"processedItems": [
{
"IsDeleted": false,
"ReadingDate": "2024-06-13",
"ReadingTime": "00:00",
"ModifiedBy": 65981,
"ModifiedOn": "2024-06-13 00:00:00.000",
"Comments": "Tester",
"CasingPressure": 122,
"TubingPressure": 322,
"SurfaceCasingPressure": 988,
"Choke": 1,
"ReadingEntityID": 35846,
"ObjectTypeID": 1,
"ObjectID": 598493,
"ReadingNumber": 1,
"DataInputMethodID": 1013164,
"CalculationTypeID": 1013145,
"AuthorityLevelID": 1013138,
"Booleanattribute": "0",
"RecomendedBooleanattribute": "0",
"ID": 17781879550,
"CreatedBy": 65981,
"CreatedOn": "2024-06-13 00:00:00.000",
"CreatedTimestamp": "2024-06-14T09:28:27.706Z",
"ModifiedTimestamp": "2024-06-14T09:28:27.706Z",
"IsFinalized": false,
"FinalizedBy": null,
"assetId": "9ad5aba5-8b3f-4ae4-846b-5b529f2ececa",
"s_entityTypeDate": "35846#2024-06-13",
"tenantId": "3a5da7ba-94e7-4484-8a9c-9e2d00dec10d",
"TTL": 1781308800,
"UUID": "ac471a5b-ceac-4f07-b058-aed3f06b3c95",
"Downtime": null,
"DowntimeReason": null
}
],
"unProcessedItems": []
}
}Example response
{"message":"Readings processing started, please check status in the below URL","url":"/readingstatus/24f8f772-ed30-4341-93d4-a87aac6b8f21"}
Use url in above response to get the status of the reading API process.
Method: GET
Endpoint: v1/readingstatus/24f8f772-ed30-4341-93d4-a87aac6b8f21
{"invalidSchemaRecords":0,"readingsCreated":0,"success":true,"status":"Completed","triggerErrorRecords":0,"invalidReadings":3695,"invalidReadingsForObjectID":0,"responseUrl":"s3 url link to download","readingsUpdated":305,"requestId":"4ffba186-26f5-4fe7-b22f-78039eb3e10b"}
Use responseUrl to download the response in gzip format.
Error Handling
Our API uses standard HTTP status codes to indicate the success or failure of a request. **Common Error Codes:** -
Code | Description |
|---|---|
400 Bad Request | The request was invalid. |
401 Unauthorized | Authentication failed. |
404 Not Found | The requested resource was not found. |
500 Internal Server Error | An error occurred on the server. |
Error Response:
{"success":false,"message":"Some error message"}
Common Reasons for API Failure
Potential Issue | Resolution |
|---|---|
if createdOn has proper iso format
| format should be |
If you are not providing ticketdate and tickettime in case of ticket reading ticket | ticket should have ticketdate and tickettime |
Improper readingentity | Provide proper proper readingentity |
Checks / Validations
# | Validation |
|---|---|
1 | All picklists/metadata ids or names will be checked |
2 | All user emails, xids will be checked |
3 | All objects id or xids will be checked |
4 | All entity names or xids will be checked |
5 | All form attributes will be checked against data type of value provided |
6 | Authority level will be checked, lower authority level cannot update higher authority level reading |
7 | Duplicate readings check |
8 | Reading Number is generated using reading time, for single reading per day it is always 1. For multiple reading per day, if same reading time is provided, that reading will be updated. If another reading time is provided new reading number will be given to reading and new reading will be created. |
Current Limitations
# | Limitation |
|---|---|
1 | In a single API payload only one kind of entity should be present. |
2 | Independent readings should be entered first wherever possible. For example, first tickets should be entered, then dual phase readings should be entered. |
3 | Attribute min. max, etc. are not supported. |
4 | Validation formula is not supported. |
5 | For now readings update is possible for readings having reading date less than the TTL date defined in reading entity type. |
Setup Requirements
# | Requirement |
|---|---|
1 | Need to generate x-api-key for the client to use the API |
2 | For carry forward and calculation to work. The trigger setup needs to be done as required. |
3 | For any other custom trigger, custom trigger needs to be turned on the for client |
4 | For interdependent calculation flag needs to be turned on for the client |