Local Authorization List Management - CSMS Developer Guide

{
  "versionNumber": "integer (> 0)",       // REQUIRED - version to assign after update
  "updateType": "Full | Differential",    // REQUIRED - type of update
  "localAuthorizationList": [             // OPTIONAL - array of AuthorizationData
    {
      "idToken": {                        // REQUIRED - IdTokenType
        "idToken": "string (max 255)",    // REQUIRED - case insensitive identifier
        "type": "string (max 20)",        // REQUIRED - e.g. "ISO14443", "eMAID"
        "additionalInfo": [               // OPTIONAL
          {
            "additionalIdToken": "string (max 255)",  // REQUIRED
            "type": "string (max 50)"                 // REQUIRED
          }
        ]
      },
      "idTokenInfo": {                              // OPTIONAL - presence controls operation
        "status": "AuthorizationStatusEnumType",    // REQUIRED
        "cacheExpiryDateTime": "date-time",         // OPTIONAL
        "chargingPriority": "integer (-9..9)",      // OPTIONAL - default 0
        "groupIdToken": { ... },                    // OPTIONAL - IdTokenType
        "language1": "string (max 8)",              // OPTIONAL - RFC 5646
        "language2": "string (max 8)",              // OPTIONAL - must differ from language1
        "evseId": [1, 2],                           // OPTIONAL - restrict to specific EVSEs
        "personalMessage": {                        // OPTIONAL - MessageContentType
          "format": "ASCII|HTML|URI|UTF8|QRCODE",  // REQUIRED
          "content": "string (max 1024)",           // REQUIRED
          "language": "string (max 8)"              // OPTIONAL
        }
      }
    }
  ]
}

{
  "status": "Accepted | Failed | VersionMismatch",  // REQUIRED
  "statusInfo": {                                     // OPTIONAL
    "reasonCode": "string (max 20)",                  // REQUIRED
    "additionalInfo": "string (max 1024)"             // OPTIONAL
  }
}

{
  // No required fields - simple query request
  "customData": { ... }  // OPTIONAL - vendor-specific custom data
}

┌──────┐                                    ┌───────────────────┐
│ CSMS │                                    │ Charging Station  │
└──┬───┘                                    └────────┬──────────┘
   │                                                 │
   │  SendLocalListRequest(versionNumber,            │
   │    updateType, localAuthorizationList)           │
   │ ───────────────────────────────────────────────> │
   │                                                 │
   │         SendLocalListResponse(status)            │
   │ <─────────────────────────────────────────────── │
   │                                                 │

{
  "versionNumber": 9,
  "updateType": "Differential",
  "localAuthorizationList": [
    {
      "idToken": {
        "idToken": "NEWTOKEN02",
        "type": "eMAID"
      },
      "idTokenInfo": {
        "status": "Accepted",
        "evseId": [1, 2]
      }
    },
    {
      "idToken": {
        "idToken": "OLDTOKEN99",
        "type": "ISO14443"
      }
    }
  ]
}

Receive SendLocalListResponse:

├── status == "Accepted"
│   └── Update internal record: CS version = versionNumber from request
│       Done.
│
├── status == "Failed"
│   ├── Was updateType "Differential"?
│   │   ├── Yes → Retry with updateType "Full" (send complete list)
│   │   │         If list is too large for one message:
│   │   │           1. Send initial subset with updateType "Full"
│   │   │           2. Send remaining entries with updateType "Differential"
│   │   │              (incrementing version each time)
│   │   └── No (was already "Full") → Log error, alert operator, retry later
│   └── Done.
│
└── status == "VersionMismatch"
    ├── Was updateType "Differential"?
    │   ├── Yes → Send GetLocalListVersionRequest to get current version
    │   │         Then either:
    │   │           a) Resend differential with corrected versionNumber (> CS version)
    │   │           b) Send full list to force sync
    │   └── No → Should not normally occur for Full. Log and investigate.
    └── Done.

┌──────┐                                        ┌───────────────────┐
│ CSMS │                                        │ Charging Station  │
└──┬───┘                                        └────────┬──────────┘
   │                                                     │
   │       GetLocalListVersionRequest()                   │
   │ ───────────────────────────────────────────────────> │
   │                                                     │
   │     GetLocalListVersionResponse(versionNumber)       │
   │ <─────────────────────────────────────────────────── │
   │                                                     │

Receive GetLocalListVersionResponse:

├── versionNumber == 0
│   └── No list exists on the Charging Station.
│       Action: Send a Full list via SendLocalListRequest (versionNumber: 1).
│
├── versionNumber == CSMS's expected version
│   └── Lists are in sync. No action needed.
│
├── versionNumber < CSMS's expected version
│   └── Charging Station is behind (e.g. it was reset, or a previous update failed).
│       Action: Send a Full list to re-sync.
│
└── versionNumber > CSMS's expected version
    └── CSMS tracking is stale (should not normally happen since CSMS is sole sender).
        Action: Update internal tracking to match CS version.
        Consider sending a Full list to ensure correctness.

On Charging Station (re)connect or periodic sync:

1. Send GetLocalListVersionRequest
2. Receive GetLocalListVersionResponse(versionNumber)

3. IF versionNumber == 0:
     → CS has no list. Send Full list with versionNumber = CSMS_current_version

4. ELSE IF versionNumber == CSMS_current_version:
     → In sync. Nothing to do.

5. ELSE IF versionNumber < CSMS_current_version:
     → CS is behind.
     → Option A: Send Differential update (if delta is small)
                  Use versionNumber = CSMS_current_version (must be > CS version)
     → Option B: Send Full update (if delta is large or unknown)

6. ELSE (versionNumber > CSMS_current_version):
     → Unexpected. Log warning. Send Full list to force re-sync.

Given: total_entries = all entries to send
       max_per_msg = ItemsPerMessageSendLocalList from CS config
       version = starting version number

1. First message:
   - updateType: "Full"
   - localAuthorizationList: first chunk (up to max_per_msg entries)
   - versionNumber: version
   → This REPLACES the entire list with just this chunk

2. Subsequent messages (for remaining entries):
   - updateType: "Differential"
   - localAuthorizationList: next chunk (up to max_per_msg entries)
   - versionNumber: ++version  (must increment for each differential)
   → Each includes idTokenInfo for all entries (add operation)

3. Repeat step 2 until all entries are sent.

4. After final response, verify: CS version == last versionNumber sent.