.. _scanmid:

=======
Scan
=======

    1. The Subarray node provides API for **Scan workflow**.
    2. **Input JSON** is as per schema detailed at :https://developer.skao.int/projects/ska-schemas/en/latest/schemas/tmc/ska-tmc-scan.html
    3. The Sub-array node **accepts the command** if :-

        A. **Admin mode** reported by each of the system - CSP,SDP subarray are in **ONLINE/ENGINEERING/RESERVED**
        B. Operational **state** of the Sub-array node is **ON/OFF/INIT/STANDBY/ALARM**

    4. The Sub-array Node **rejects the command** if :-

        A. **Admin mode** reported by each of the system - CSP,SDP Sub-array are in **OFFLINE** or **NOT FITTED**.
        B. Operational **state** of subarray node is **FAULT/UNKNOWN/DISABLE** .

    5. The **Input JSON** is **validated** as below, and Command is `'Rejected'` with **exception message if they are not met** :-

        A. JSON should not be **empty** or **malformed**
        B. **ska-tmc-cdm** is used to **validate the JSON**

    6. The following **state requirements** are applied for the **command execution**

        A. TMC Subarray is in `'observation state'` **READY** .
        B. :term:`isSubarrayAvailable` is checked to ensure the subsystems (CSP, SDP and Dish) are :term:`available`

    7. The **command execution** involves below **key operations** :-

        A. Below **updates** are done in each of the interface **before sending JSON** to each of the interface.

            - **CSP updates** :
                Sets **interface** field specified by the **CspScanInterfaceURL** property specified in helm chart of the TMC Subarray node

            - **SDP Updates** : 
                Sets **interface** field specified by the **SdpScanInterfaceURL** property specified in helm chart of the TMC Subarray node

            - **Dish Updates** :
                Only **Scan Id** will be sent to Dish leaf node when command is invoked. Other details in json will not be sent.

        B. The command is then **invoked** on the relevant TMC CSP, SDP, Dish leaf Nodes.

            - If leaf node **rejects configure command** , command failure is reported as **'RESULT_CODE - FAILED'** on Long Running Command Result attribute of the TMC Subarray node.Command will not be sent to remaining subsystems in this case if multiple subsystems are involved .
            - If **all** leaf node **accept command** , the TMC Subarry node will wait for command completion.

        C. **Scan timer** is **started** using the stored scan duration . The scan timer will later **trigger automatic termination** (EndScan) once timer is over.

    8. The Sub-array node **monitors the progress** of command via the Sub-array node **ObsState transitions** and the **long running command results**.

        A. Command is **successful** when **all** 3 leaf nodes send **'RESULT_CODE - OK'** on Long Running Command Result attribute of respective leaf nodes.This is reported as **'RESULT_CODE - OK'** on Long Running Command Result attribute of the Subarray node.
        B. Command **failure** is reported in any of the below cases as **'RESULT_CODE - FAILED'** on Long Running Command Result attribute of the Subarray node.
    
            - The CSP Leaf node/SDP Leaf node/Dish Leaf node reports **'RESULT_CODE - FAILED'** on its Long Running Command Result attribute
            - The command **times out** if TMC SubarrayNode **does not** get **'RESULT_CODE - OK'** from all 3 subsystems within the **timeout period** specified by `CommandTimeOutDefault` property specified in helm chart of the TMC Subarry Node .

    9. On **success** the system is **performing scanning observation**; on **failure** it may revert to **READY** or **FAULT** depending on severity.