What API do I use to create/update Readings API

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

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

5. Picklist n

Example of JSON

 [{"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

Response Format

{"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":[]}}

NOTE

1. For file size more than 10kb url will be provided which can be called to get the status

2. If user is not able to determine the file size, 500 record limit can be taken as the limit below which response will be returned immediately.

 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:** -
`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 Reason for API failure

Checks / Validations

1. All picklists/metadata ids or names will be checked

2. All user ids, emails, xids will be checked

3. All objects id or xids will be checked

4. All entity ids or names 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

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.

6. Stop total calculations happen only for the last 60 days.

Instructions:

URL: https://90iqppj8qf.execute-api.us-west-2.amazonaws.com/v1/api/integration/reading

x-api-key : vcFZxH75ed6uoFYjYaSGc4JF6JCW0Eo5OAAqAZ84

→ User has to send the Compressed(gzip) JSON file for creating the readings.

→ User has to send the attribute names with small letters as tubingpressure instead of TubingPressure.

→ The compressed file should be less than 10kb.

→ If the Compressed file is having greater than 10kb, then the readings will be created from backend and get below message.

{
    "message": "Readings processing started, please check status in the below URL",
    "url": "/readingstatus/9ee38d14-ac17-4130-885d-83912b8f61b5"
}

→ To get the details of readings which are created with file more than 10 kb should be followed to check the status using with GET call of ReadingStatus.

a. https://90iqppj8qf.execute-api.us-west-2.amazonaws.com/v1/api/integration/readingstatus/9ee38d14-ac17-4130-885d-83912b8f61b5

b. The response should be as followed.

c.

{
    "readingsCreated": 682,
    "success": true,
    "status": "Completed",
    "invalidReadings": 432,
    "responseUrl": "https://joyn-fdg-data-api-readings-qa.s3.us-west-2.amazonaws.com/b5e234d6-02f0-42f6-aed7-4a39c83988c7/2024-06-26/balanjanreddy007%252Bqa%2540gmail.com/9ee38d14-ac17-4130-885d-83912b8f61b5-response.json.gz?AWSAccessKeyId=ASIA3QU64AZG33OUYSWU&Expires=1719390871&Signature=8xWjH7QkTrdZk9TlaBDI4jTdiw4%3D&X-Amzn-Trace-Id=Root%3D1-667bc467-46f6f8ad43da0e3d6f60ac86%3BParent%3D497152875a13a853%3BSampled%3D0%3BLineage%3D375ae52f%3A0&x-amz-security-token=IQoJb3JpZ2luX2VjECgaCXVzLXdlc3QtMiJIMEYCIQCTXNF2mlAgfwcRPR%2Fw1LBQiAUr88hOFdL5SASpXIA%2FgwIhAPV4FaI6Fe7YVSNm0ctDVyh4pTiMsqwiHjYftorfUtmuKpgDCNH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQBBoMNzkxNjgwOTEwOTI1IgzwgMZncynhYjDyN8gq7AL1PlbAtUaJp7nqwJITz%2BOQgzChEN9qUBCPwoh8XLToSchN5OkwV4LvsYFBAxH6rtmfcZJYdNfdynVx5btVYYkam%2FHfqI81N%2FoEGdTzqo6I5p5A9BhjtoBNGO2EO%2FECf3zcszw279O3rbKVLFP3xV9vF1mqhmpK3zVLu0yj%2FyE8fUihiRIItKRVbHavzlfVzWsIEf5R3u9Bzf7dTWzP26arMx%2B5yrmtJOduBCIp12Cs5apxEE%2FizgFloryYsJQa%2F5ClWEte9goW9KQKvQlGbwMx8wHGDULeGYYq4HkTDUcfGZOjZleFrrPWPix27vPEsfN4drIkO5kgOhuWuOKQQXAPIuMMchKb3712muOCRBkPxhFC0ictiMj9GlDZD8zdprDbzwJjWgBqj6Zu1jE1nS2M1HSrZu%2FtMffsaNPD5%2FdEZ6PClaSbDZSC%2Fg2KJSPTNv2s1gxLOyGSk5ympQPyaIQM%2BD9ClLD9Q8ZLHODRMOSI77MGOpwBY%2FdOewjEDPII1BANmIGQ%2B5PcJUQx29n8fjdivIJAIpeGzU2T%2FemGDRaXUDf4vwGQxj3As0P464E3ZIDmiLcI8WrxCT%2F6ziZpvDytIgodiFtV9d2BtPVnDzhXcYTQyt3zale%2FxNFL%2B50iLnBw2PdCvOJB0rfNDImwEO923oqMla4b%2B3n%2F%2F6jI9ZDYUSgfFNtqumCT%2BnD1b8vjSNC0",
    "readingsUpdated": 792,
    "requestId": "9ee38d14-ac17-4130-885d-83912b8f61b5"
}

→ The readings creation with readings API should be less than 2 years.

→ User should send only one entity type in one payload with multiple different object IDs and should not with different Entity ID’s.

→ Make sure user is sending less than 500 records in one file to get response immediately.

Please find the mandatory fields:

1. User is able to create the readings through Readings API.

2. User is able to create the readings with picklist ID or name through readings API.

3. User is able to create the readings with all attribute types through readings API.

4. User is able to create the readings through readings API with calculation type ID or Name.

5. User is able to create the readings through readings API with Input Method ID or Name.

6. User is able to create the readings through readings API with Object ID or XID.

7. User is able to create the readings through readings API with Object Type ID or Name.

8. User is able to create the readings through readings API with Reading Date/ Ticket date (if it is tankrunticket) and the format should be yyyy-mm-dd, without any timestamp.

9. User is able to create the readings through readings API with Reading Entity ID or Name.

10. User is able to create the readings through readings API with Reading Time / Ticket Time and the format should be hh:mm:ss.

11. User is able to create the readings through readings API with Modified On and format should be UTC format yyyy-mm-ddT00:00:00.000Z.

12. User is able to create the readings through readings API with Modified By, Name or XID.

13. User is able to create the readings through readings API and Ticket Number is mandatory when reading is a ticket.

14. User is able to create the readings through readings API and Modified By is user email.

15. Pumper is not able to create the reading with readings API when that reading is created by Admin Authority level.

16. User is able to create multiple readings per with different time.

17. Carry forward is happening only on Auto carry forward attributes when the Carry forward triggers is on.

18. Calculation is happening on calculated attributes when calculation trigger is on.

Note: Will test Interdependent calculation on JOYN OG Stage.