# Virtual Inkspot Handling (VIH)

!!! info "From SMT Template version 3.1.0 onwards, the GetVirtualInkspotHandlingData service relies on the _SMTUnitsExcluded_ attribute"

## Overview

When replying to a BoardGateKeeper request, IoT should reply what boards should be assembled. These boards are previously marked (At SPI process, for example).  

### Concept

When a board arrives at pick & place, BoardGateKeeper will send a BoardRequest to IoT.
Then, the automation workflow `doVIHOnBoardRequest` will read the configuration at IoTMetadataDefinition to find the configured service (`GetVirtualInkspotHandlingData`) and invoke it, sending the Material and Resource.

This service returns a `GetVirtualInkspotHandlingDataOutput` object to IoT with the VIH information, containing the Boards and information if their components should be placed or not. This data is then included in the IoT BoardRequestResponse to the BoardGateKeeper. The panel boards marked for no placement will have their property `Placed` as False.

The service will also return the `BoardPath` info to IoT, which will also be sent to BoardGateKeeper together with the boards list. This data is required by ASM and contains the full ASM path for this material.

??? note "GetVirtualInkspotHandlingData service signature"

    The table below describes the input parameters for the service (object of Type `GetVirtualInkspotHandlingDataInput`)

    | Name         | Type   | Description                                                               |
    | :----------- | :----- | :------------------------------------------------------------------------ |
    | MaterialName | string | Material name to be Evaluated                                             |
    | ResourceName | string | Resource name                                                             |
    | BarcodeSide  | string | Signals the board's side to be returned (to be supplied by Customization) |

    The table below describes the output parameters for the service (object of Type `GetVirtualInkspotHandlingDataOutput`)

    | Name      | Type    | Description                                                                         |
    | :-------- | :------ | :---------------------------------------------------------------------------------- |
    | VIHResult | VIHData | Boards information array                                                            |
    | BoardPath | string  | The complete path where the board is in Siplace Pro(Only used for OIB Integrations) |
    
    `VIHData` object format:
    ```
    [  
        {  
            PanelName : string (EquipmentBoardId),  
            Place : bool (True if board is to be assembled, False if not),  
            Reason : string (optional)  
        },  
        { 
            ...  
        }  
    ]
    ```

### GetVirtualInkspotHandlingData service details

This service will first resolve the Smart Table [SMTConventionContext](../artifacts/tables.md#smtconventioncontext) to get the convention used by the resource. It then verifies that the panel’s `Form` is present in the [SMTPanelForms](../artifacts/tables.md#smtpanelforms) Lookup Table; if not, skips the logic and returns. Next, it resolves the Smart Table [SMTMapBoardIDContext](../artifacts/tables.md#smtmapboardidcontext) to get the `EquipmentBoardID` and `MESPositionID` for each board. To resolve this table, two regex configs are used:

- `SMT/VirtualInkspotHandling/EquipmentBoardIDTopRegex`: Holds the Regex needed to identify the equipment's EquipmentBoardID top side board.
- `SMT/VirtualInkspotHandling/EquipmentBoardIDBottomRegex`: Holds the Regex needed to identify the equipment's EquipmentBoardID top side board.  

Only the entries from [SMTMapBoardIDContext](../artifacts/tables.md#smtmapboardidcontext) that match the selected side (via `BarcodeSide`) will be returned.

These regexes are applied according to the `BarcodeSide` input. The service will create a `VIHResult` board list for that side, using the *EquipmentBoardID* as `PanelName` and setting `Place` based on whether the corresponding `MESPositionID` is excluded.

The service aggregates all panel data resolved from the **Smart Table** [SMTMapBoardIDContext](../artifacts/tables.md#smtmapboardidcontext), fetching all `EquipmentBoardID` and `MESPositionID` applicable to the panel, then checks the panel’s `SMTUnitsExcluded` attribute to determine which `MESPositionIDs` are excluded from placement. If a `MESPositionID` is present in `SMTUnitsExcluded`, then `Place = false`; otherwise, `Place = true`.

### Customization

To keep track of the correct side, a DEE and a Pre ActionGroup should be added, so the value `BarcodeSide` can be determined before calling the Service. That can be accomplished by evaluating the material barcode, flow, step, etc, depending on each project customization.  

#### DEE Input

Type: Dictionary containing a key named `GetVirtualInkspotHandlingDataInput` of type `GetVirtualInkspotHandlingDataInput`  

| Member       | Type   | Description                   |
| :----------- | :----- | :---------------------------- |
| MaterialName | string | Material name to be evaluated |
| ResourceName | string | Resource Name                 |

#### DEE Output

Same as Input.  
  
!!! info "Customization notes"
    In case of receiving an invalid `BarcodeSide` parameter (other than `Top` or `Bottom`), the service will search for the first valid MES Config containing the side info, following this sequence:

    1. A config at `SMT/VirtualInkspotHandling/DefaultSide/<Resource>`, where Resource is the received parameter.  
    2. A config at `SMT/VirtualInkspotHandling/DefaultSide`.  

    To resolve `ProductNamePrefix` value, the service will search for the first valid MES Config following this sequence:

    1. A config at `SMT/VirtualInkspotHandling/ProductNamePrefix/<Area>`, where `<Area>` is the Resource Area.  
    2. A Config at `SMT/VirtualInkspotHandling/ProductNamePrefix`.  
    

    To resolve `EquipmentBoardIDTopRegex` value, the service will search for the first valid MES Config following this sequence:

    1. A config at `SMT/VirtualInkspotHandling/EquipmentBoardIDTopRegex/<Area>`, where `<Area>` is the Resource Area.
    2. A config at `SMT/VirtualInkspotHandling/EquipmentBoardIDTopRegex`.  

    To resolve `EquipmentBoardIDBottomRegex`, follow the same process above.  

    In case of missing or invalid config `SMT/VirtualInkspotHandling/ProductNamePrefix`, the service will return only the material product name at `BoardPath`.

## Example

![IoTMetadataDefinition](images/vih/vih-iotmetadatadefinition.png)

![Configs](images/vih/vih-configs.png)

![SMTConventionContext](images/vih/vih-smtconventioncontext.png)

![SMTMapBoardIDContextContext](images/vih/vih-smtmapboardidcontext.png)

Full returned service object:  

![VIHResults](images/vih/vih-serviceoutput.png)

VIHResult property service object (let's assume that the second board of the panel was terminated):  

![VIHOutput](images/vih/vih-vihdata.png)

!!! note "Notes"
    - Note the second Sub-Material is marked as defective (on Panel's attribute `SMTUnitsExcluded`) and is also marked to not be placed at service output.
    - The config `SMT/VirtualInkspotHandling/ProductNamePrefix` is appended to the material product name by the service, to create the `BoardPath` output and sent to Siplace Pro.

!!! info "Preconditions"
    Materials have sub-materials with MESPositionID attribute already set.