Scope
Sharing the Overall Sensor Corrosions, Forecasted Corrosion, Forecasted Wall Thickness, and Life of CML data with IMS from CARMA via Production API’s.
System Overview
CARMA is a Machine Learning/Data Science Driven application built on C3.AI platform using Azure Cloud Services. APIs built are user account and token-based accessible with no involvement of any third-party suite for communication.
Glossary
API = Application Programming Interface
CARMA = Corrosion And Risk Modelling Analytics
IMS = Integrity Management System
CML = Condition Monitoring Location
C3.AI = A platform on which the application is built
Requirements
| Number | Name | Description | Rationale |
|---|---|---|---|
CARMA API | |||
CARMA-IMS-001 | CARMA API | The CARMA application shall provide an API that allows IMS to access data | The CARMA application makes prediction on the status of piping and equipment that will be beneficial to optimize the Risk Based Inspection process that is housed in IMS. Direct access to the information on CARMA will streamline the use of its data. |
CARMA-IMS-001 | JSON Format | The CARMA API shall receive and send data in JSON format | JSON format is a standard for sending and receiving objective data. |
CARMA-IMS-002 | Production URL | https://shell-carma-prime.c3iot.ai/api/1/carma/prime | |
CARMA-IMS-003 | Sensor Field | The sensor associated with a CML shall be transmitted as a list of sensors | There can be more than one sensor at a CML, therefore the field shall always be treated as a list of sensors. |
CARMA-IMS-004 | Data Access Hierarchy | Data can be accessed by providing the data hierarchy in appendix A | We need a common hierarchy for finding asset data. |
CARMA-IMS-005 | CARMA Data Response | The response shall provide the data in appendix B | Reference: Appendix B |
CARMA-IMS-006 | Error Messages | The API shall provide clear error messages if an exception occurs | Providing what field is in error or missing will improve debugging. |
IMS API | |||
CARMA-IMS-101 | IMS API | IMS application shall provide an API that allows CARMA to access data | IMS contains asset information that CARMA uses for corrosion prediction. Direct access to the IMS application will automate data extraction. |
CARMA-IMS-101 | Test URL | https://ims-datalake-test.shell.com | |
CARMA-IMS-102 | Production URL | https://ims-datalake.shell.com | |
CARMA-IMS-103 | JSON Format | The IMS API shall receive and send data in JSON format | JSON format is a standard for sending and receiving objective data. |
CARMA-IMS-104 | Provide Static Information | The IMS API shall provide static design and process information | CARMA would like to extract this information directly from IMS instead of relying on SMEs to provide info. See Appendix C. |
CARMA-IMS-105 | Data Access Hierarchy | Data can be accessed by providing the data hierarchy in Appendix A | We need a common hierarchy for finding asset data. |
CARMA-IMS-106 | IMS Data Response | The response shall provide the data in appendix C | Reference: Appendix C |
CARMA-IMS-007 | Error Messages | The API shall provide clear error messages if an exception occurs | Providing that field is in error or missing will improve debugging. |
Asset Hierarchy
Both APIs will use the following hierarchy to search for data associated with a specific asset location:
Site / Production Unit / Unit / Equipment / Circuit / Subcircuit / CML
CARMA Response Data
The CARMA API will make the following data available:
Position – Operating Position of the Sensor in the CML
ShortTermCarmaCR – Average predicted short-term
LongTermCarmaCR – Average predicted corrosion rate long-term
CurrentCarmaCR – The latest/last Predicted Corrosion rate value
CustomCarmaCR – User Specified duration for average corrosion rate (Default – 2 Years)
CRUnit – Unit of the Corrosion Rate value
SpanOfCR – Duration for user-defined corrosion rate
SpanUnit – Unit of defined corrosion rate duration (Day, Month, Year)
IMS Response Data
The IMS API will make the following data available if it exists in the IMS system:
- Corrosion Loop
- Fluid
- Minimum allowable wall thickness
- Pipe diameter
- Pipe material
- Nominal pipe thickness
- Last measured thickness
- FLOC
- Nominal temperature
- Nominal pressure
Technical Overview
API action getCarmaCorrosions
API Scope
The scope is to Provide the Corrosion and other data to the IMS end users via the IMS Application UI.
API Details
API endpoint Name: CarmaPredictionApi
Action name: action=getCarmaCorrosions
API PROD URL: https://shell-carma-prime.c3iot.ai/api/1/carma/prime
Example FINAL URL: https://shell-carma-prime.c3iot.ai/api/1/carma/prime/CarmaPredictionApi?action=getCarmaCorrosions
API Method: POST
API Payload
- spec – contains the elements of the Payload
- equipment – equipment Id for the selected CML in IMS
- circuit – Circuit Id for the selected CML in IMS
- subCircuit – SubCircuit Id for the selected CML in IMS
- cml – ID for the selected CML in IMS
- start – Start Date from which the Predicted Corrosion Rates are to be averaged.
- end – End Date till which the Predicted Corrosion Rates are to be averaged.
- site – The site ID for the selected CML in IMS
- plant – The Plant ID for the selected CML in IMS
- Interval – The Interval the data needs to be fetched for the averaging.
API Response
- equipment – equipment ID for the selected CML in IMS
- circuit – Circuit ID for the selected CML in IMS
- subCircuit – SubCircuit ID for the selected CML in IMS
- cml – Condition Monitoring Location ID to which the response is populated.
- start – Start Date from which the Predicted Corrosion Rates are to be averaged.
- end – End Date till which the Predicted Corrosion Rates are to be averaged.
- site – The site ID for the selected CML in IMS
- plant – The Plant ID for the selected CML in IMS
- Interval – The Interval the data needs to be fetched for the averaging.
- sensors – Contains the list of Sensors that are tagged under the response CML.
- Sensor – Sensor ID tagged under the CML.
- Position – Operating Position of the Sensor in the CML
- Status – “Success”, “Error” describing if the CR fetch on the sensor was successful or failed letting the user know if is it good to use.
- CorrosionRates – The list of Corrosion Rates for the Tagged Sensor under the CML
- ShortTermCarmaCR – The Average Predicted Corrosion rate value of the Sensor for the tagged CML for the Predefined Specified duration (6 Months)
- LongTermCarmaCR – The Average Predicted Corrosion rate value of the Sensor for the tagged CML for the whole operating duration of sensor available in CARMA (2-5 Years)
- CurrentCarmaCR – The latest/last Predicted Corrosion rate value of the Sensor for the tagged CML ( 1 Day)
- CustomCarmaCR – The Average Predicted Corrosion rate value of the Sensor for the tagged CML for the User Specified duration. (Default – 2 Years)
- CRUnit – Unit of the Corrosion Rate value
- SpanOfCR – The Predefined or User-defined duration for which the Corrosion Rate is averaged out.
- SpanUnit – Unit of the duration (Day, Month, Year)
API Error
- errorMessage: The Reason for the Error is that the API is not giving the expected answer.
- equipment: The Equipment ID to which the Error is generated.
- circuit: The circuit ID to which the Error is generated.
- subCircuit: The subCircuit ID to which the Error is generated.
- cml: The cml ID to which the Error is generated.
API Access
IMS to raise or note any preparations to be done to access the API.
API action getAvailableCML
API Scope
The scope is to Provide the available Carma CML data to the IMS end users via the IMS Application UI.
API Details
API endpoint Name: CarmaPredictionApi
Action name: action=getAvailableCML
API PROD URL: https://shell-carma-prime.c3iot.ai/api/1/carma/prime
Example FINAL URL: https://shell-carma-prime.c3iot.ai/api/1/carma/prime/CarmaPredictionApi?action=getAvailableCML
API Method: POST
API Payload
- site – The site id for the selected CML in IMS
- limit – The limit of total data
- offset – The offset limit of total data
Request Example
Response Example
API Access
IMS picks up data and updates CMLs in IMS that has CARMA.