Monitoring sets

cspell.json

@@ -50,6 +50,10 @@
         ,"adrs"
         ,"puml"
         ,"rgba"
+        ,"MYSUBST"
+        ,"MYSUBSTN"
+        ,"EMSID"
+        ,"CIMMRID"
     ],
     "import": []
 }

docs/_config.yml

@@ -36,6 +36,9 @@ kramdown:
     block:
       line_numbers: true
 
+mermaid:
+  version: "11.3.0"
+
 callouts:
   announcement:
     color: green

docs/_data/components/parameters/monitoring-set-id.yaml

@@ -0,0 +1,14 @@
+name: id
+description: |
+
+  Identity of the associated
+  `monitoring-set`. The identifier for a `monitoring-set` is pre-coordinated,
+  but using the NERC id of the associated Ratings Provider is recommended.
+
+  This parameter also supports use of the special string "default", which 
+  indicates the logged-in user's default monitoring set.  
+
+in: path
+required: true
+schema:
+  $ref: ../schemas/generic-identifier.yaml

docs/_data/components/schemas/monitoring-set.yaml

@@ -0,0 +1,27 @@
+type: object
+description: |
+  See https://trolie.energy/concepts.html#monitoring-sets for info on the 
+  monitoring set concept in TROLIE.  
+
+  This representation is intended to be enough for consumers to read it and tell where 
+  the monitoring set came from, using metadata such as a source and an optional description.  
+  It also includes the list of resources included in the monitoring set, as well as all
+  their known aliases.  
+
+properties:
+  source:
+    $ref: ./data-provenance.yaml
+  id:
+    $ref: ./generic-identifier.yaml
+  description:
+    type: string
+    format: free-form
+    description: |
+      A freeform text description of this monitoring set
+    maxLength: 1000
+  power-system-resources:
+    $ref: ./array-max-monitored-elements.yaml#/named-power-system-resources
+required:
+- source
+- id
+- power-system-resources

docs/_data/components/schemas/name-type.yaml

@@ -0,0 +1,5 @@
+description: Type of the name being referenced.  Corresponds to the IEC CIM `NameType` concept.
+type: string
+maxLength: 20
+pattern: ^[A-Za-z0-9\-]{3,20}$
+example: EMSID

docs/_data/components/schemas/names.yaml

@@ -11,6 +11,8 @@ properties:
       properties:
         name:
           $ref: ./generic-identifier.yaml
+        type:
+          $ref: ./name-type.yaml
         authority:
           $ref: ./entity-id.yaml
         mrid:

docs/_data/openapi-split.yaml

@@ -170,6 +170,15 @@ tags:
       data feed could be down for some reason.  Therefore, this provides a
       placeholder set of numbers until the AAR data feed is repaired.
 
+  - name: Monitoring Sets
+    description: >      
+
+      Monitoring Sets are named sets of power system resources that may be used to
+      filter ratings and limits returned by queries against these APIs. How Monitoring
+      Sets are defined is beyond the scope of the TROLIE specification, and it is
+      assumed that the sender and receiver have predefined the appropriate Monitoring
+      Sets.  More on monitoring sets may be found at https://trolie.energy/concepts.html#monitoring-sets
+
   - name: limit-type
     description: <SchemaDefinition schemaRef="#/components/schemas/limit" />
     x-displayName: Limit Type
@@ -182,6 +191,7 @@ x-tagGroups:
     - Seasonal
     - Seasonal Overrides
     - Temporary AAR Exceptions
+    - Monitoring Sets
   - name: Common Schemas
     tags:
     - limit-type
@@ -211,6 +221,9 @@ paths:
     $ref: paths/temporary-aar-exceptions.yaml
   /temporary-aar-exceptions/{id}:
     $ref: paths/temporary-aar-exceptions_{id}.yaml
+
+  /monitoring-sets/{id}:
+    $ref: paths/monitoring-sets_{id}.yaml
 
 
 components:
@@ -435,6 +448,7 @@ components:
         clientCredentials:
           tokenUrl: https://no-server/oauth2
           scopes:
+            read:monitoring-sets: Read monitoring sets
             read:forecast-proposals: Read Forecast rating proposals
             read:realtime-proposals: Read real-time rating proposals
             read:seasonal-proposals: Read seasonal rating proposals

docs/_data/paths/monitoring-sets_{id}.yaml

@@ -0,0 +1,41 @@
+get:
+  operationId: getMonitoringSet
+  description: &get_desc Obtain a specific monitoring set by identifier.  
+  summary: *get_desc
+  tags: 
+    - Monitoring Sets
+  parameters:
+    - $ref: ../components/parameters/monitoring-set-id.yaml
+  responses:
+    '200':
+      description: OK
+      content:
+        application/vnd.trolie.monitoring-set.v1+json:
+          schema:
+            $ref: ../components/schemas/monitoring-set.yaml
+          example:
+            $ref: ../../example-narratives/examples/monitoring-set-get.json
+      headers:
+        $ref: '../openapi-split.yaml#/components/responses/204/headers'
+
+    '304':
+      $ref: '../openapi-split.yaml#/components/responses/304'
+    '400': 
+      $ref: '../openapi-split.yaml#/components/responses/400-problem'
+    '401': 
+      $ref: '../openapi-split.yaml#/components/responses/401-empty'
+    '403': 
+      $ref: '../openapi-split.yaml#/components/responses/403-empty'
+    '404': 
+      $ref: '../openapi-split.yaml#/components/responses/404-empty'
+    '406': 
+      $ref: '../openapi-split.yaml#/components/responses/406-empty'
+    '429': 
+      $ref: '../openapi-split.yaml#/components/responses/429-empty'
+    '500': &unexpected-error-empty
+      $ref: '../openapi-split.yaml#/components/responses/500-empty'
+    default: *unexpected-error-empty
+
+  security:
+    - oauth2-primary-flow:
+        - read:monitoring-sets

docs/articles/examples/RC-A-monitoring-set.json

@@ -0,0 +1,25 @@
+{
+  "source": {
+    "last-updated": "2025-10-01T12:00:00.044267100-07:00",
+    "provider": "RC-A",
+    "origin-id": "efa3f807-9a5c-4448-8e63-273fb173d183"
+  },  
+  "id":"RC-B",
+  "description": "RC B's Tier 1 facilities",
+  "power-system-resources": [
+    { "resource-id": "e300d2c2-45bb-49f6-a3bc-a3e5d5a30ce6",
+      "alternate-identifiers": [
+        {
+          "name": "MYSUBSTN.LN.12345", 
+          "type": "EMSID",
+          "authority":"RC-A"
+        },
+        {
+          "name": "DLR_OUT_LINE_5742_NORM",
+          "type": "ICCP-NORM-MVA-OUT",
+          "authority": "RC-A"
+        }
+      ]
+    }
+  ]
+}

docs/articles/examples/RC-B-monitoring-set.json

@@ -0,0 +1,25 @@
+{
+  "source": {
+    "last-updated": "2024-10-06T19:23:18-07:00",
+    "provider": "RC-B",
+    "origin-id": "27a6b9ac-db4d-4340-a5ea-080271f7b072"
+  },  
+  "id":"RC-A",
+  "description": "RC A's Tier 1 facilities",
+  "power-system-resources": [
+    { "resource-id": "MYSUBST-LINE-5742",
+      "alternate-identifiers": [
+        {
+          "name": "a276c684-aa68-4799-8c00-44913c61e77a", 
+          "type": "CIMMRID",
+          "authority": "RC-B"
+        },
+        {
+          "name": "DLR_OUT_LINE_5742_NORM",
+          "type": "ICCP-NORM-MVA-OUT",
+          "authority": "RC-A"
+        }
+      ]
+    }
+  ]
+}

docs/articles/peer-monitoring-sets.md

@@ -0,0 +1,152 @@
+---
+title: Monitoring Sets and Peer TROLIEs
+parent: Articles
+---
+
+# Peer TROLIEs
+
+In TROLIE's simplest usage, rating providers send rating proposals to Transmission Providers
+using the workflow described in [Forecast Submittal](../example-narratives/submitting-forecasts.md).  
+
+However, two neighboring Transmission Providers, each running independent clearinghouses, will also
+have to share ratings.  Each TROLIE server must be able to act as a client to achieve this coordination, 
+with each reaching out to one another.  
+
+This article specifically covers coordination of resource models on the seam between reliability 
+coordinators, or really any two TROLIE implementations that can act as peers.  It uses each RC's 
+default monitoring sets as a foundation for discovery of mapped models.  
+
+This article defines a design pattern recommended as a best practice, as it ultimately must 
+be implemented within TROLIE servers and is only supported by the TROLIE communications specification 
+rather than mandated by it.  
+
+# Coordinating Models and Identifiers
+The data exchange specified by TROLIE implies that any two parties must both agree on identifiers for 
+[Power System Resources](../concepts.md#power-system-resource-or-simply-resource).  This is required for 
+the exchange to function.  
+
+However, this creates a significant burden on modelers to maintain.  Each reliability coordinator will
+almost always have different identifiers for the resources within their footprint across different 
+systems.  Modelers will have to maintain some alias identifiers for resources so that they may be 
+mapped to the external RC's system.  Some of this complexity is unavoidable.
+
+# Peers and Monitoring Sets
+
+TROLIE servers can mitigate some of this complexity by introspecting monitoring 
+sets.  The Venn diagram below illustrates two [monitoring sets](../concepts.md#monitoring-sets) owned 
+by RCs (A and B), one in each of the other's TROLIE servers.  Each RC must coordinate creation of 
+monitoring sets in the other's TROLIE in order to monitor ratings, as described in the operations 
+[getLimitsForecastSnapshot](../spec#tag/Forecasting/operation/getLimitsForecastSnapshot) and
+[getRealTimeLimits](../spec#tag/Real-Time/operation/getRealTimeLimits).
+
+![Peers](../images/Seam.excalidraw.png)
+
+As indicated by the diagram, the actual seam between the RCs can be derived where the two monitoring sets
+overlap.  For these resources, both RCs are producing a rating.  
+
+# Monitoring Set Reconciliation Process
+
+Consider the perspective of RC A given the above diagram.  RC A must be aware of both its own monitoring set
+in RC B's TROLIE, which will be referred to as monitoring set `B-in` in the following examples.   In addition,
+The RC A TROLIE can gain insight by specifically being aware of the monitoring set in its own database that 
+RC B is using to monitor RC A's footprint.  This will be referred to as `B-out` in the following examples.  
+
+Visibility into the monitoring set itself in either system is exposed via the 
+[getMonitoringSet](../spec#tag/Monitoring-Sets/operation/getMonitoringSet) operation.  Given this capability, 
+TROLIE for RC A may do the following:
+
+* Automatically determine the overlapping aliases between models. 
+* Automatically derive the actively configured seam between RCs, to use for debugging and monitoring.
+
+This automation should be triggered by an update to either the `B-in` or `B-out` monitoring 
+sets.  The process to update `B-out` is an implementation internal.  Updates to `B-in` are 
+facilitated by an independent polling mechanism in the RC A TROLIE, using the 
+[conditional GET](./conditional-GET.md) pattern against `getMonitoringSet`.  When 
+`getMonitoringSet` returns a 200 status (as opposed to 304), indicating a new version, then this triggers 
+reconciliation.  This is illustrated in the data flow below.  Note that "Monitoring Set"
+is abbreviated to "MS" for readability.    
+
+```mermaid
+
+flowchart
+
+  rcb[RC B TROLIE]  
+  msp[[MS Poller]]
+  bin[(B-in MS)]
+  bout[(B-out MS)]
+  msr[[MS Reconciler]]
+  mappedIds[(RC B Mapped Ids)]
+  seam[(Seam MS)]
+
+  msp -- Poll for new version of B-In --> rcb
+  rcb -- Return new version --> msp
+  msp ---> bin
+
+  bin -- new version --> msr
+  bout -- new version --> msr
+
+  msr -- update --> mappedIds
+  msr -- update --> seam
+
+```
+
+The above diagram illustrates two outputs of a reconciliation process, both of which should be
+stored in the TROLIE server's database:
+
+* Mappings of remote identifiers (the identifiers expected by RC B in this case)
+* The seam monitoring set
+
+# Automatic Resource Alias Mapping
+In practice, most Transmission Providers have at least the following identifiers for each resource:
+
+* An identity for the resource in a modeling system and/or asset registration system.  Since many modeling tools are CIM-based, this is typically a master resource identifier (MrID) in the form of a UUID.  
+* An identity for the resource in an EMS system.  These may be the same as the modeling system identities, but since most EMS technologies pre-date CIM modeling practices, they typically do not.  Instead, they often follow some convention established by the specific EMS technology in combination with company-specific naming conventions and modeling practices.  
+
+As discussed above, typically none of these identifiers are the same across grid operators.  Also, each 
+RC could decide to use either as their "primary" value for `resource-id` in TROLIE operations.  
+
+Naively, each RC could track the primary `resource-id`s used by the other.  So, for example, 
+RC A could track RC B's EMS IDs in its database mapped to it own internal ones, and then ensure that
+those EMS IDs are explicitly used (and expected back) whenever it interacts with RC B's 
+TROLIE.  RC A would have to do something similar for all other neighbors.  
+
+This approach is functional and perfectly valid.  However, it presents some challenges:
+
+* If both RC A and RC B were to use this approach, then each would have to manually maintain copies of one another's IDs.  
+* RC A would have to either hard-code or manually configure each peer so that they know which set of IDs apply to that peer.  
+
+Using monitoring set reconciliation however, any unique identifier may be shared.  This could mean only 
+one of the RCs maintaining an alias.  Alternatively, RCs that are using ICCP for real-time 
+communications must already coordinate point names for sending the ratings.  Using the point name as one of 
+the aliases allows it to be reused to map resources.  Consider the following example contents for monitoring sets
+as returned by [getMonitoringSet](../spec#tag/Monitoring-Sets/operation/getMonitoringSet) for `B-in` and `B-out` 
+respectively.  Note these examples are oversimplified for readability, as they both only contain a single resource:
+
+**`B-in`**:
+
+```json
+{% include_relative examples/RC-B-monitoring-set.json %}
+```
+
+**`B-out`**
+
+```json
+{% include_relative examples/RC-A-monitoring-set.json %}
+```
+
+The IDs used by RC A and B are very different.  The MRIDs are of course different.  The EMS IDs also use different
+naming conventions.  Also, RC B has chosen to use CIM MRIDs as their `resource-id`, whereas RC A has chosen to 
+use EMS IDs as their `resource-id`.  
+
+However, when querying a new version of `B-in`, monitoring set reconciler function in the RC A TROLIE can see that 
+one of the aliases, specifically the ICCP point name "DLR_OUT_LINE_5742_NORM" matches another alias it has in its 
+database, with the matching name type and authority.  The reconciler function can then determine that the resource 
+RC-A refers to as "e300d2c2-45bb-49f6-a3bc-a3e5d5a30ce6" may be referred to as "MYSUBST-LINE-5742" whenever it 
+interacts with RC B's TROLIE.  It should store this mapping and assume it on all future calls.  
+
+# Seam Monitoring Sets 
+The seam monitoring set, as described above, would be derived by finding the overlap between `B-in` and 
+`B-out`.  This monitoring set has various uses in monitoring system behavior:
+
+* If the TROLIE implementation pre-configures the expected seam, then this configuration may be checked against the seam modeling set for differences, therefore spotting modeling errors.  
+* In future articles, we will show how the seam monitoring set may be used to monitor reconciliation of ratings across RCs.