C8Y Mapper Operation Handling

!!ATTENTION!! We support only c8y_SoftwareUpdate in the release 0.3. Ignore c8y_DeviceProfile for now.

In this page, we focus on the contract between C8Y Mapper and C8Y Cloud. If you want to know the mapping rules, please refer to Thin Edge JSON Mapping to/from C8Y.

Flow at SM Agent Startup

sequenceDiagram
    participant SM Agent
    participant C8Y Mapper
    participant C8Y Cloud

    alt If SM Agent reports failure of last SoftwareUpdateOperation on a startup
      SM Agent ->> C8Y Mapper: Operation status FAILED + current SoftwareList
      C8Y Mapper ->> C8Y Cloud: SmartREST 502: Update operation status to FAILED
      C8Y Mapper ->> C8Y Cloud: SmartREST 116: Send current c8y_SoftwareList
    end

    SM Agent ->> C8Y Mapper: Declare SoftwareUpdate and SoftwareList capability
    C8Y Mapper ->> C8Y Cloud: SmartREST 114: Send c8y_SoftwareUpdate as SupportedOperations
    
    alt If receiving both SoftwareUpdate and SoftwareList capabilities
      C8Y Mapper ->> SM Agent: Software List Request
      SM Agent -->> C8Y Mapper: Software List
      C8Y Mapper ->> C8Y Cloud: SmartREST 116: Send current c8y_SoftwareList
      
      C8Y Mapper ->> C8Y Cloud: SmartREST 500: Get PENDING operations
      C8Y Cloud -->> C8Y Mapper: SmartREST 528: SoftwareUpdate operation and others
      Note right of C8Y Mapper: the following flow is the same as the flow in runtime
    end

This flow is consists of 4 parts.

1. Report operation failed to C8Y Cloud.
2. Receive device capabilities from SM Agent and translate as C8Y_SupportedOperatons and report them to C8Y Cloud.
3. Trigger a Set Software List request to SM Agent as a response of receiving Software List capability.
4. Trigger a Get PENDING operations request to C8Y Cloud as a response of receiving Software Update capability.

Both "SM Agent is up but C8Y Mapper is down" and "SM Agent is down but C8Y Mapper is up" cases must be considered here. Namely, the device capabilities must be delivered to C8Y Mapper in any case.

Other notes:

• Collecting all device's capabilities (e.g. SoftwareUpdate, Restart, etc.) are required so that the mapper sends SmartREST 114 with all necessary supported operations.
• SM Agent might publish more capabilities than C8Y cloud supports. In this case, the mapper doesn't need to subscribe the unsupported capability topics.
• c8y_SoftwareUpdate is supported in c8y version 10.7 and onwards.
• C8Y mapper can consider that the SM Agent is ready for a new operation after the agent publishes device's capabilities.
• SmartREST 500 returns all the operations in the status PENDING.
• SmartREST 500 may return not only 528.

Flow in runtime phase for c8y_SoftwareUpdate operation

sequenceDiagram
    participant SM Agent
    participant C8Y Mapper
    participant C8Y Cloud
    
    C8Y Cloud ->> C8Y Mapper: SmartREST 528: SoftwareUpdate operation and others
    C8Y Mapper ->> C8Y Mapper: Put operations to FIFO queue
    C8Y Mapper ->> C8Y Mapper: Wait until the SM Agent completes processing the last SoftwareUpdate operation(if any)
    C8Y Mapper ->> C8Y Mapper: Pick up the oldest c8y_SoftwareUpdate operation

    C8Y Mapper ->> SM Agent: Software Update Request
    
    SM Agent ->> C8Y Mapper: Operation status EXECUTING
    C8Y Mapper ->> C8Y Cloud: SmartREST 501: Update operation status to EXECUTING
        
    alt software update successful
        SM Agent ->> C8Y Mapper: Operation status SUCCESSFUL + current SoftwareList
        alt the size of software list is small enough
            C8Y Mapper ->> C8Y Cloud: SmartREST 116: Send current c8y_SoftwareList
            C8Y Mapper ->> C8Y Cloud: SmartREST 503: Update operation status to SUCCESSFUL
        else the size of software list is above the threshold 
            C8Y Mapper ->> C8Y Cloud: SmartREST 502: Update operation status to FAILED
        end
    else software update failed
        SM Agent ->> C8Y Mapper: Operation status FAILED + current SoftwareList
        C8Y Mapper ->> C8Y Cloud: SmartREST 116: Send current c8y_SoftwareList
        C8Y Mapper ->> C8Y Cloud: SmartREST 502: Update operation status to FAILED
    end

Note:

• C8Y cloud might publish c8y_SoftwareUpdate(528) and also other operations.
• The mapper has responsibility to keep all received PENDING operations in FIFO queue.
• The mapper considers that SM Agent is ready for receiving a new operation either when it receives Operation status SUCCESSFUL/FAILED + current SoftwareList or when it receives device capability (at agent startup only).
• SM Agent can process only one Software Update operation at one time. Therefore, c8y Mapper should pick up the oldest c8y_SoftwareUpdate operation.
• C8Y UI blocks to create more than one c8y_SoftwareUpdate operation at the same time. However, still user can create more than one operation from REST API.
• If one operation includes a couple of packages updates, and if one of those package failed, we have to send FAILED.