Integrate mRounds with AVEVA PI
mRounds can receive PI event frames, acknowledge them in PI, and write round readings back to PI attributes.
Four separate actions
| Action | Who calls whom | Topic |
|---|---|---|
| Innovapptive polls PI for event frames | Innovapptive calls your PI Web API on a schedule | Poll AVEVA PI for Event Frames |
| A customer connector pushes event frames to Innovapptive | Your system calls the Innovapptive webhook | Receive AVEVA PI Event Frames by Webhook |
| Innovapptive acknowledges receipt in PI | Innovapptive writes the acknowledgement attribute | Write Acknowledgements and Round Readings to AVEVA PI |
| Innovapptive writes an operator's round reading to PI | Innovapptive writes the measurement attribute mapped to the round task | Write Acknowledgements and Round Readings to AVEVA PI |
Polling and the webhook are alternatives for receiving event frames; most customers use one of them. Both use the event-frame WebId as the unique ID, so a frame delivered twice does not create a second event. The acknowledgement and the round-reading write are separate writes, each to its own attribute.
Four kinds of WebId
PI Web API generates a WebId for every object. These four are not interchangeable:
| WebId | Identifies | Example | Used for |
|---|---|---|---|
| AF database WebId | The AF database that holds the event frames | F1RDbgZy4oKQ9kiBiZJTW7eugwvgV_Y00G | Scoping the polling search |
| Event-frame WebId | One event frame | F1FmbgZy4oKQ9kiBiZJTW7eugwqF… | The unique event ID (externalId, item.WebId) |
| Element WebId | An AF element, such as Pump-01 | F1EmbgZy4oKQ9kiBiZJTW7eugwPV… | Polled frames return it in RefElementWebIds |
| Attribute (stream) WebId | One attribute, such as Acknowledged or BearingTemp | F1AbEAI8QAAAAAAAAAAAAAAAAAAAAAAATTRTMP01 | The target of each write. Element and event-frame WebIds cannot be used here. |
WebIds in this guide are examples. Your PI Web API generates your own.
Prerequisites
Collect these from the team that owns the PI AF system.
| Item | Polling | Webhook | Writeback |
|---|---|---|---|
PI Web API base URL, for example https://pi.example-customer.com/piwebapi | Required | Required | |
| AF asset server and AF database that hold the event frames, and the database WebId | Required | ||
| Account that can search event frames and read their attributes and values in that database | Required | ||
| Account that can write the acknowledgement attribute and every measurement attribute a round can update | Required | ||
| WebId of the acknowledgement attribute, and the WebId of each measurement attribute a round can update | Required | ||
| HTTPS access from Innovapptive to the PI Web API | Required | Required | |
| How the customer system authenticates when calling Innovapptive | Required | ||
| How Innovapptive authenticates when calling the PI Web API | Required | Required |
The read account and the write account can be the same if your security policy allows it. The credentials your system uses to call Innovapptive are separate from both.
Innovapptive configures the database WebId, polling interval, lookback, acknowledgement attribute and PI credentials for the tenant during onboarding. Send them to your Innovapptive implementation team.
Authentication
The two directions do not share credentials.
Your system to Innovapptive (webhook only). Innovapptive issues the secret during onboarding. Choose one method:
| Method | What you send |
|---|---|
| API key | Header x-api-key: {key we issue} |
| HMAC | Header x-signature: {HMAC-SHA256 hex of the raw request body}, using the shared secret Innovapptive issues |
| OAuth | Request a token first, then send Authorization: Bearer {token} |
OAuth token request, only if you choose OAuth:
POST https://{innovapptive-host}/esis/auth/{yourTenantId}/pi_af
Content-Type: application/json
{
"clientId": "{client id we issue}",
"clientSecret": "{client secret we issue}"
}Innovapptive to your PI Web API (polling reads and both writes).
| Call | Sign-in |
|---|---|
| Polling reads | HTTP Basic |
| Acknowledgement write and round-reading write | Basic, API key, or none. Both writes use the same choice. |
| Method | What you give Innovapptive | Header Innovapptive sends |
|---|---|---|
| Basic | Username and password | Authorization: Basic {base64(username:password)} |
| API key | The key, and the header name if it is not x-api-key | That header. Writes only. |
| None | Confirmation that the PI Web API allows the call with no credential on your network | No credential header. Writes only. |
Basic is the usual choice for reads and writes. This is not Windows integrated authentication (Kerberos or NTLM). A Windows account works only if the PI Web API accepts it as a Basic username and password; it does not have to be the account the PI services run under. Reads and writes also send Accept: application/json.
PI Web API paths to allow
Allow HTTPS from Innovapptive to these paths and grant the matching permission.
| Method | Path | When | Permission |
|---|---|---|---|
| GET | /piwebapi/eventframes/search | Every poll | Read event frames in the AF database |
| GET | /piwebapi/eventframes/{eventFrameWebId}/attributes | Once per frame found | Read event-frame attributes |
| GET | /piwebapi/streamsets/{eventFrameWebId}/value | Once per frame found | Read attribute values |
| POST | /piwebapi/streams/{attributeWebId}/value | Each acknowledgement and each round reading | Write the designated attributes |